Blog · AI SDLC series

How to Preserve Architecture When Coding Agents Write the Code

Keep architecture intact with AI agents: encode boundaries as CI checks, give agents your conventions as context, and track rework across every PR.

Elad Zalait
Elad ZalaitOctober 13, 20268 min read
A road with guardrails built into it, representing engineering standards that keep fast AI-written code on course

You preserve architecture under AI-driven development by moving your standards out of people's heads and into the path every change travels: boundaries become automated checks, conventions become context that every agent receives, and quality signals are tracked across all PRs so erosion shows up early. Done well, this costs agents almost no speed, and it is what keeps a quarter of fast delivery from turning into a year of rework.

This is part 2 of 5 in our series on the AI SDLC. Part 1 covered measurement: knowing how much of your code is human-touched and where agents are doing the work. This part is about what happens to the system itself once they are.

What is architecture preservation in AI-assisted development?

It is not a code freeze, a manual architecture review board or a ban on agents. It is the opposite: making the standards cheap enough to apply on every change that you can let agents move fast without worrying about what they leave behind.

Why do coding agents erode architecture?

A coding agent optimizes locally. Its goal is the task in front of it: make the failing test pass, implement the ticket, close the loop. Within that frame it is often excellent. What it lacks is everything outside the frame.

  • It does not know your team retired the callback-based retry helper two years ago, because the old helper is still in the repo and still compiles.
  • It does not know that the checkout service must never call the ledger directly, because nothing in the code says so; a senior engineer simply rejects it in review.
  • It does not know the module it just copied is scheduled for deletion next quarter.
  • It does not know that "we already have a currency conversion utility" unless it happens to search for it.

Humans carry this knowledge from incident reviews, hallway conversations and years of context. Agents start every session fresh. The more of your code they write, the more your architecture depends on knowledge they never receive.

How do small AI shortcuts compound into rework?

Take the running example from this series: a multi-currency change to checkout. An agent needs exchange rates, finds no obvious helper, and writes a small conversion function inline. It needs to record the transaction, sees that the ledger has a clean internal method, and calls it directly instead of going through the payments API. Both changes pass tests. Both look reasonable in a 400-line diff that a reviewer skims between meetings.

Now repeat that across fifty PRs a week. Three months later you have three currency conversion paths with slightly different rounding, four services that write to the ledger directly, and a deprecated pattern that has quietly doubled its footprint because agents learn from what they see in the repo. No single PR was the mistake. The mistake was that nothing in the system could tell the difference.

Each shortcut looks harmless in review. Together they compound into duplicated logic, leaky boundaries and three ways of doing the same thing.

The cost arrives later and elsewhere: a rounding bug that has to be fixed in three places, a ledger schema change that breaks four callers, a refactor that nobody can scope. Velocity looks great for a quarter, then rework eats the gains and nobody can explain why the system feels brittle.

How do you encode architecture boundaries as automated checks?

Any rule that is enforced only by a reviewer remembering it will fail at agent volume. The fix is to write it down in a form CI can execute. Most teams already have the tools; they just never encoded the rules that mattered most.

  • Dependency rules. Declare which modules and services may depend on which. "Checkout may call payments; only payments may call the ledger." A dependency or import check fails the build when that is violated.
  • Forbidden calls. List specific functions, clients or endpoints that must not be used from certain places, such as direct ledger writes outside the payments service or raw SQL outside the data layer.
  • Deprecation lists. Mark retired patterns and modules as banned for new code. Existing usages are grandfathered; new ones fail.
  • Ownership boundaries. Changes that cross into another team's service require that team's review, automatically.

Start with the rules you would be most embarrassed to see broken. Five sharp rules that run on every PR beat fifty aspirational ones in a wiki page. Each rule should carry a short explanation and a pointer to the preferred alternative, because the failure message is also guidance, both to the person and to the agent that will retry.

How do you give coding agents your conventions as context?

Checks catch violations after the fact. Context prevents them. If agents start every session fresh, the job is to make sure every session starts with the right material.

  • Context files at the repo and service level: what this service owns, what it must never do, which patterns are preferred and which are retired.
  • Skills for recurring tasks, such as "add an endpoint" or "add a currency", that walk the agent through your way of doing it, including which shared utilities to use.
  • Examples of the preferred pattern. One canonical, well-commented example of each pattern is worth more than a page of prose. Agents imitate; give them the right thing to imitate.
  • Deprecation lists in context, not only in CI, so the agent avoids the retired helper before it writes it rather than after the build fails.

Treat this context like code. Version it, review changes to it, and keep it short enough that it actually gets read. When a check fails repeatedly for the same reason, that is a signal the context is missing something.

How do you measure code quality across AI-written and human PRs?

Preservation needs feedback, and the feedback has to come from outcomes, not opinions. Four signals do most of the work, and they should be tracked across every PR, AI-heavy or not:

  • Duplication: new code that repeats logic already present elsewhere in the repo.
  • Churn: lines that are rewritten or deleted shortly after they merge.
  • Rework: follow-up PRs that fix, adjust or redo recent work in the same area.
  • Reverts: changes rolled back entirely, the bluntest signal of all.

Tracking all PRs matters for two reasons. First, humans erode architecture too, and you want one standard. Second, you cannot judge AI-heavy work without a baseline. Compare fairly: same repo, same period, similar change size and change type. An agent-heavy PR that touches a fragile legacy module will churn more than a human PR in a clean new service, and that tells you about the module, not the agent.

For example, if the ledger service went from 61% human-touched in March to 31% today, the question is not whether that is good or bad. The question is whether churn, duplication and reverts in the ledger moved with it.

Gates that fail the change, not the person

Gates only work if people trust them, and people only trust gates that are fast, explainable and blameless. A failed boundary check should read like a compiler error: what rule, where, why it exists and what to do instead. It should never read like a performance note, and the data should never be used to rank engineers by how often their agent tripped a check.

Speed matters as much as tone. A check that reports in two minutes gets fixed in the same session, often by the agent itself. A check that reports in the next morning's review gets argued with.

How do you roll this out without slowing teams down?

  1. Pick one critical boundary. Choose the rule whose violation hurts most, such as direct ledger access, and write it as a check.
  2. Run in report-only mode first. Collect violations for two to four weeks without failing builds, and fix the false positives.
  3. Grandfather existing debt. Fail only new violations, so teams are not blocked by history they did not write.
  4. Ship the matching context. For every rule, add the context file entry and preferred example that would have prevented the violation.
  5. Baseline the quality signals. Measure duplication, churn, rework and reverts per service before you change anything.
  6. Turn on enforcement, then add the next rule. Review the rule set quarterly and delete rules nobody breaks.

Most teams find that enforcement adds seconds to CI and saves hours in review, because reviewers stop policing conventions and start reviewing design.

Throughput that comes back as rework was never throughput

The accounting most teams skip is simple. When you report AI-driven throughput, subtract the work that came back. If a team merged 40% more PRs this quarter but a third of the extra changes were followed by rework or reverts within 30 days, the real gain is much smaller than the headline, and the debt it created is still on the books.

I would rather see a team report 25% more throughput with flat rework than 60% more with rework climbing. The first is acceleration. The second is a loan.

Where Sparkey fits

Sparkey links agent sessions to the PRs they produce, so you know which changes were human-touched and which were agent-generated. It tracks duplication, churn, rework and reverts across all PRs, AI-written or not, per repo, team and service, and evaluates PRs against your standards. Our agentic SDLC workflows place gates between stages and ship your conventions to agents as versioned skills, so the rules and the context stay in sync.

Preservation tells you whether your standards are holding today. The next part of the series is about seeing the slope before the cliff: "Thresholds tell you when it's too late. Trends tell you while you can still act."

Frequently asked questions

Do coding agents produce lower-quality code than humans?

Not inherently. Agents often write clean, well-tested code for the task they are given. The risk is that they lack institutional knowledge, so they may duplicate existing logic or cross boundaries nobody wrote down. Measure outcomes across all PRs rather than assuming either way.

What is the first architecture rule we should automate?

The boundary whose violation would hurt most, such as a service calling the ledger or the database directly. Encode it as a dependency or forbidden-call check, run it in report-only mode first, then enforce it on new violations only.

How do we compare AI-heavy PRs with human PRs fairly?

Compare within the same repo and period, and control for change size and type. Track the same signals (duplication, churn, rework, reverts) for both groups. Differences in a fragile module usually say more about the module than about who wrote the code.

Will automated gates slow our developers down?

Well-designed gates add seconds to CI and usually save review time, because reviewers stop policing conventions. Keep checks fast, explain each failure with a fix, and grandfather existing debt so teams are not blocked by history.

What should go into an agent context file?

What the service owns, what it must never do, the preferred patterns with one canonical example each, and a list of deprecated modules and helpers. Keep it short, version it with the code and update it whenever the same check keeps failing.

Elad Zalait
Elad Zalait
CTO, Sparkey AI
Follow on LinkedIn
All articles

See your own AI SDLC, measured

Sparkey shows how AI coding tools and agents are changing your teams, your code and your costs.

Book a DemoCalculate Your ROI