Layered Architecture Violations Caused by AI Agents

Architecture drift in AI-generated codebases happens when agents write code that works but breaks the design constraints that keep layers apart. The resulting violations can pass review and standard CI because functional correctness does not establish architectural correctness. Detecting and preventing this drift requires checking the codebase’s actual dependency graph against explicit boundaries and blocking changes that violate them.

Why layered architecture breaks down differently when agents write the code

An agent receives a prompt, touches dozens of files, and produces a large diff. The code compiles, tests pass, and nothing in the normal workflow flags that three layer boundaries were crossed. The requested behavior is present, so the change appears complete. Yet the implementation has altered relationships that the task never authorized it to change.

Layered architecture depends on permitted relationships between parts of a system. Human developers learn those relationships from conventions, earlier decisions, and explanations of why the boundaries are there. Agents generate code from the context available for the immediate task, which may describe the desired behavior without supplying the constraints governing its implementation.

This mismatch makes agent-caused violations different from isolated developer mistakes. Without enforcement, the same missing constraint can affect task after task, and the more changes agents make, the more chances there are for drift. With that many changes, careful review alone cannot fill in every missing design decision. Esposito et al.’s survey on GenAI for software architecture identifies architectural coherence as an open challenge, with rigorous testing of outputs typically missing and evaluation frameworks still inadequate. The gap is between the ability to generate code and the ability to establish that its structure remains acceptable.

How agents bypass layer boundaries: the three structural mechanisms

Context blindness occurs when an agent cannot retain and apply the conventions relevant to its changes. Consider an agent that duplicates a utility across modules because the shared implementation and its intended use are absent from the working context. Each copy may work correctly. The architectural failure is the missed convention about where that responsibility belongs. Hartwig Grabowski’s August 2026 Hochschule Offenburg paper, “The Spec Growth Engine,” names “context explosion” as a structural failure mode in which growing repository context undermines the agent’s ability to reason coherently.

Boundary-skipping happens when the shortest way to finish a task crosses a prohibited dependency. A controller can query a database directly and return the expected result without using the application’s intended intermediary. The test can still pass. Unless architectural constraints enter the task’s acceptance conditions, successful behavior does not penalize the shortcut. The agent has satisfied the local request while weakening the separation the surrounding system depends on.

Silent spec-code drift occurs when implementation changes but its governing specification does not. For example, documentation may still require database access through a designated layer after direct access has entered the code. Subsequent tasks then encounter conflicting evidence about the intended design. The same paper identifies this divergence as a second structural failure mode. Agent-generated change volume makes reconciliation harder because implementation can move faster than people maintain its specification.

Missing context hides the rule, the shortcut supplies a working implementation, and stale specifications leave the discrepancy unresolved. Tools that map topology, including Graphide, give reviewers a navigable graph of modules, boundaries, and cross-layer edges. Cross-layer edges become visible directly, while unapplied conventions and spec-code drift become visible when that topology is compared with explicit intent.

Why standard diffs and CI pipelines cannot see these violations

A diff shows changed text. A direct database call in a controller may occupy one line, while understanding its significance requires knowing the responsibilities and permitted dependencies of several modules. That information may be missing from the surrounding patch. As agents expand a change across many files, reviewers must reconstruct more of the system’s topology from fragments.

Cloudflare’s AI review system illustrates this limit within a sophisticated implementation. Its review sees the diff but not the design intent behind it, and it cannot verify that downstream API consumers have updated when a contract changes. A relationship can extend beyond both the changed lines and the material available to the reviewer.

Standard CI has a different but related blind spot. Compilation checks whether code is valid, tests check specified behavior, and linting checks encoded rules. None inherently establishes permitted layer topology. A controller that directly queries a database can satisfy all three unless an architectural rule explicitly forbids that dependency.

The Layered Attack Surface Model survey establishes a non-transferability theorem for security controls, under which a control at one layer has zero detection power against an attack localized at another. The relevant engineering analogy is narrower, because a check cannot establish a property it does not examine. Graph-level enforcement, as used by Graphide, checks the code’s actual structure against constraints, so a clean diff and passing behavioral tests alone do not count as architectural approval.

What accumulating violations actually do to a codebase over time

An undetected violation becomes part of the implementation that later agents encounter. A controller with direct database access is no longer just an exception in a pending patch. It is now an available precedent. An agent completing a similar task can follow that pattern without recognizing that it contradicts the intended architecture. Repetition gives the shortcut the appearance of a convention even when no developer approved it as one.

Boundaries described as stable in documentation can cease to describe the code, while responsibilities become distributed across places that were intended to remain separate. Repair then requires distinguishing intended relationships from inherited exceptions. NimoNova’s example of many hundreds of warnings gives this accumulation a concrete scale. Such a backlog makes drift visible as a structural condition.

Natural-language instructions can drift along with the implementation. AGENTS.md files describe project conventions, but a test-framework migration that leaves those files unchanged instructs agents to keep generating code for the old framework. The guidance itself becomes a source of divergence. In multi-agent workflows, guardrail propagation across delegation boundaries remains an open problem, so instructions supplied at one level cannot simply be assumed to govern downstream work.

This is why supplying more context is not equivalent to enforcing architecture. Context can be incomplete, stale, or inconsistently propagated. A live topology map such as Graphide’s addresses the visibility side of this problem by exposing the structure produced as agent work accumulates. Establishing whether that structure is permitted still requires maintained constraints.

Why adding more AI to the review process does not solve the structural problem

AI review can find issues that need fixing without reliably enforcing binary rules. Whether a controller may depend directly on a data-access implementation is not a question that needs a fresh probabilistic judgment for every patch. The permitted relationship should already be defined. Asking another model to infer and apply that relationship substitutes another interpretation step for an enforceable constraint.

Cloudflare separates these responsibilities in its review system. It uses conventional static analysis and linters for deterministic requirements while reserving AI review for rules that need contextual understanding. That distinction leaves a substantial role for AI. Its system caught nearly 16,000 violations that caused approval to be withheld because they referred to MUST statements on enforced RFCs. The result demonstrates the value of AI review without establishing that it can replace hard boundary checks.

The practical comparison is between advisory coverage and a gate. Practitioners evaluating architecture tests, agent reviews, and documentation or skills chose architecture tests because a violated rule prevents the build from passing. An AI reviewer can suggest a correction. A deterministic test can make compliance with an encoded constraint a condition of acceptance. That guarantee applies only to the rules the tests actually express.

The LASM survey identifies the governance layer as among the least-studied and highest-severity threat zones, including exposure to adversarial manipulation of documents agents consume. Architectural instructions are therefore not safe by default merely because they are written down. The engineering response is to keep contextual review additive while assigning hard dependency rules to checks whose outcome does not depend on a model accepting or interpreting those instructions correctly.

What deterministic architectural enforcement in CI actually requires

Deterministic enforcement needs both an up-to-date view of the codebase’s relationships and explicit constraints to check against that view. The graph establishes what exists. The constraints establish what is allowed. CI then blocks a proposed change when its resulting structure violates an encoded boundary, rather than waiting for someone to recognize the problem in review.

The graph must reflect current implementation. Mapping modules, files, classes, functions, and call relationships makes cross-layer dependencies available for machine checking. Architectural intent must be supplied separately because the code may already have violations. Deriving permitted relationships solely from current topology would risk converting those violations into policy. The useful comparison is between a maintained model of intent and an up-to-date model of implementation.

Graphide implements this graph-based approach by making codebase topology navigable and architectural constraints enforceable in CI. It is a concrete option within the broader category of architecture tests and graph-based enforcement. For the controller example, the relevant check concerns the prohibited dependency rather than whether the database query returns the correct result.

Atlan’s four-layer AI platform model supplies a related principle, in which a control plane depends on a governed context layer beneath it. Architectural enforcement has the same dependency on current structural context. In practice, the graph needs to live in the repository, version with the code, and provide a constraint surface that CI can evaluate. This makes the proposed structure reviewable together with the implementation that produces it.

The blocking condition must also be explicit. A warning found after merge gives less protection than an architecture test that fails before the change is accepted. Deterministic checks can enforce encoded rules as changes grow without a human checking every dependency the agents create. They prevent known, prohibited relationships from becoming accepted precedent.

How the developer role changes when architectural enforcement is automated

Developers still decide which responsibilities belong together, which dependencies are allowed, and when an exception is a design change made on purpose. Their judgment defines the rules. Instead of repeatedly reconstructing those rules from large diffs, they maintain the constraints that govern what agents may introduce.

This shift makes the work on the system around the agent more important. Some 2026 engineering literature calls that work “harness engineering,” including the design of tools, context, state, runtime loops, sandboxes, guardrails, and human approval gates. Layer-boundary enforcement belongs within that system because it limits acceptable output independently of how the agent reached it. The agent can choose how to write the code, but finishing the requested feature does not make a prohibited dependency acceptable.

AGENTS.md files and constraint registries become living specifications in this arrangement. Their maintenance must accompany changes to the code and its intended architecture. The graph records the relationships in the code, while explicit constraints keep track of decisions that would otherwise stay in experienced developers’ heads. Versioning both makes a boundary change a visible engineering decision rather than an unnoticed side effect of generated code.

Gartner’s February 2026 projection places the broader governance risk in context. By 2030, roughly half of AI agent deployment failures are projected to trace back to insufficient governance enforcement. That forward-looking claim about agent deployment reinforces the need to distinguish written guidance from enforced rules. For engineering teams, the next steps are concrete. Define the architectural constraints, put them in CI, and keep the graph current.