Architecture Drift in AI-Assisted Codebases
AI agents need architectural rules enforced at build time, not just in prompts.
Sponsored by Graphide

Architecture drift in AI-assisted codebases happens when changes that work on their own break the boundaries, layering rules, and dependency constraints that make up the system’s design. Better prompts alone cannot stop it when agents have no access to that design and their output is not checked against it. Architectural intent must be made machine-readable, each change checked against it, and violations blocked before they become the foundation for further generation.
Why AI agents produce locally correct but globally incoherent code
A staff engineer’s agent-assisted PR adds an endpoint that writes directly to the customer table, bypassing the internal customer service API. The code is clean, tests pass, and the reviewer approves. Two weeks later, entries are missing from the audit-log. The audit hooks live in the API that the endpoint bypassed. An Architecture Decision Record banning direct database access existed, but it had been written two years earlier and sat in a directory the workflow never touched.
The failure stems from a gap in organizational memory. Human developers internalize conventions through repeated work in a codebase, while agents start sessions without accumulated organizational memory. When architectural rules are absent from their context, agents draw on training-data patterns and whatever code they can see. A direct database write can therefore look reasonable for the immediate task while contradicting the system’s intended design. A better model given the same incomplete prompt would still have no access to the decision it should follow.
Kashif et al. (2026) found that AI IDE-generated large-scale projects had high functional correctness but also had over a thousand design issues across those projects, with an average in the hundreds per project. The issues included duplication, high complexity, framework best-practice violations, and violations of Single Responsibility, Separation of Concerns, and DRY. These issues show how code can execute successfully yet fail to hold together as a design.
How drift accumulates across an agent-assisted codebase over time
Session amnesia turns that gap into a recurring process. Each session may make different assumptions about where behavior belongs or which dependencies are acceptable. Those assumptions turn into code that later sessions see without the decisions that should guide it. A shortcut import or misplaced class can then appear to be an established convention. The existing code becomes guidance, even when it already departs from the intended architecture.
A faulty helper can spread across services, end up in a shared library, or become boilerplate for code generated later. Duplicate logic in a second service adds another place where behavior must be kept up to date, while direct imports across layers add dependencies that the design was meant to keep out. Each change may remain defensible in isolation. Together, the changes create coupling that becomes increasingly difficult to unwind.
Hartwig Grabowski’s 2026 Spec Growth Engine identifies “silent spec-code drift” as a related structural failure. The agent changes code, the specification remains untouched, tests pass, and nothing flags the divergence. The specification becomes a historical artifact rather than a living contract, while context explosion makes reasoning across the repository harder as context fills. Helpful intent does not prevent this degradation. Its visible signals are rising cross-module dependencies, repeated logic, and small edits that require increasingly broad knowledge of the codebase.
Why the speed of agent output makes review an insufficient check on drift
Steve Yegge claimed in January 2026 to produce 12,000 lines of code daily with AI agents. That individual practitioner’s claim illustrates the volume that review may be asked to absorb, though its scope limits its use as a general productivity benchmark. The bottleneck is sustained attention to large diffs. Reviewers must assess whether changes meet the stated requirements, while architectural integrity depends on relationships extending beyond the files under review. Passing functional tests does not settle that broader question.
When the same model family generates and reviews code, its blind spots can be correlated. The reviewing agent may accept a pattern introduced by the generating agent as conventional rather than question whether it belongs in the architecture. Kashif et al. state that the design issues they found “require careful review by experienced developers.” That requirement becomes harder to satisfy as generated output grows.
Human review remains valuable for judgment and design discussion. It cannot, however, be the main way to keep architecture in check at agent speed, because reviewers see structural decisions only after they have taken shape across many files. A diff shows textual changes rather than the full arrangement of dependencies those changes produce. Enforcement must therefore move earlier and become structural, rather than depend on someone noticing every boundary crossing.
What architectural fitness functions do and why they are model-independent
An architectural fitness function is an objective, automatable test of whether a system still satisfies a desired architectural characteristic. Wired into the build, it turns an architectural rule into a continuously checked property. It checks the structure that exists on disk. The author could be a human, a capable model, or a less capable model without changing the criterion used to accept the result.
That model-independence is the essential difference from generation-time guidance. A better agent may follow rules better, but the rules can be enforced without waiting for that improvement. A structural check applies the same declared constraint to every change, regardless of how persuasive or locally correct the implementation looks. In the customer-table case, an enforced prohibition on direct access would have made the boundary violation a build failure. The missing organizational memory would no longer depend on a reviewer recalling the ADR.
Grabowski formalizes this principle as a “drift gate” that makes spec-code divergence a blocking merge condition. His framework ties established ideas including information hiding, ADRs, Reflexion Models, and Fitness Functions to the code. The distinction from an ADR is precise. An ADR records what was decided and why, while a fitness function tests whether the code satisfies that decision. When used at merge time, the fitness function stops a structural choice that breaks the rules from becoming a pattern for later work.
Three layers where architectural enforcement must actually live
Layer one is agent context. Architectural rules must reach the agent before generation so that its task begins with the relevant boundaries. Grabowski’s Spine context assembler scopes that context to an ownership path, including only the relevant module and the contracts of its declared dependencies. This reduces the context burden and discourages global fixes outside the requested scope. Context remains guidance, however. An agent can ignore a rule or apply it inconsistently as requirements accumulate.
Layer two is static structural analysis on every change. This layer validates dependencies, layer placement, and module relationships in the implementation rather than assuming the agent followed its instructions. Kashif et al. used CodeScene and SonarQube to surface design issues that functional tests missed. Complexity, duplication, and dependency violations provide measurable signals of structural erosion. This is not merely style checking, because the relevant comparison is between the declared architecture and the relationships present in code. Context cannot substitute for inspecting the result.
Layer three is a blocking CI gate. Structural analysis can identify a violation without preventing it from entering the codebase, so the pipeline must make failure consequential. The check exits non-zero and blocks the merge when the implementation violates declared constraints. To make that comparison meaningful, the graph or specification must live in the repository and version with the code. The CI gate is the non-negotiable backstop before a violation reaches main.
What a codebase needs before enforcement can be meaningful
Module boundaries, allowed dependencies, layering rules, and their rationale must exist somewhere the toolchain can read, including when they are already recorded in documentation for people. ADRs provide a useful starting point because they preserve both the decision and its reason. The next step is translating their enforceable content into constraints.
The customer-access rule makes that translation concrete. Its rationale explains why writes must pass through the internal customer service API, while its checkable constraint prohibits the direct database access that bypasses that API. Grabowski also distinguishes a module’s contract from its design, meaning what it exposes versus how it is internally structured. Both belong in the spec graph. Agents need that distinction to generate conformant code, and enforcement needs it to distinguish an allowed relationship from a boundary violation.
The specification must then evolve with the implementation. The framework requires code and specification to change in the same commit so divergence becomes visible immediately, before the design record goes stale. For an existing codebase, enforcement can begin with new code while leaving existing code in place. Blocking fresh violations stops structural debt from compounding while the team continues shipping.
How living architecture graphs change what developers can actually verify
A live architecture graph makes structural relationships directly inspectable. By mapping modules, files, classes, functions, and call relationships as agents write code, it lets developers navigate the system represented by those scattered edits. A new cross-module dependency is visible as a structural change even when its import line sits within otherwise reasonable implementation. That gives developers and agents a shared model for discussing what was built.
The graph must distinguish description from architectural intent. A map of the implementation shows what exists, while declared boundaries and dependency constraints establish what is allowed. Comparing the two makes divergence detectable rather than leaving the engineer to infer the rule from the picture. The graph therefore needs to version with the code and reflect current decisions. A diagram detached from the repository cannot provide that current comparison to CI.
The team practices that make structural enforcement hold under agent-speed development
Teams adopting this workflow should treat the architecture graph as a first-class artifact. Every structural decision needs a corresponding update in the same commit as the code that requires it. That includes new module boundaries and changes to dependency rules. Consistency gives the constraint system its authority. Once new-code enforcement is established, continuing to apply it prevents ongoing agent development from expanding the debt that the team still needs to address.
Work ordering also helps that discipline hold. Grabowski’s vertical-slice growth protocol puts the most architecturally complex or risky slices first, when the specification is receiving close attention, rather than deferring them until the codebase is tangled. The goal is not to slow agents down. A graph-enforced workflow lets teams work at that speed while keeping architectural decisions clear, open to inspection, and binding on what reaches production.
Putting architectural checks in CI
Choose an architecture-test or dependency-rule tool that supports your language and the constraints you can explicitly encode. Commit its rules with the code, run the documented command in CI, and make the resulting check required where those rules should prevent a merge. Test the gate with an intentionally forbidden dependency before relying on it. Such checks enforce the rules you specify; they do not establish that every aspect of the architecture or runtime behavior is correct.
Updated November 5, 2026: obsolete CLI examples removed. Use the selected tool’s current installation and command documentation.


