Graph Diffing Your Intended Architecture Against What AI Agents Actually Built

Architecture drift in AI-generated codebases occurs when generated code changes module boundaries, dependencies, or domain separation without a deliberate design decision. Detecting it requires comparing the as-built dependency graph against a versioned graph of the intended architecture. Graph diffing makes that divergence a reproducible build artifact that can block a merge, rather than a structural failure discovered months later.

Why AI agents are making architectural decisions without anyone noticing

In a single interaction, an AI coding agent can select a framework, wire a database, establish authentication boundaries, and shape deployment topology. These are architectural decisions, even when they arrive as implementation details buried across generated files. The code appears before the reasoning is recorded. Deliberations that would take a team days can happen in seconds, without an architecture decision record, design document, or audit trail explaining the choices.

Konrad, Adam, Terrenzi, and Ayvaz, from the Centre for Industrial Software at the University of Southern Denmark, name this pattern “vibe architecting.” Their paper, accepted at the SAGAI Workshop at IEEE ICSA 2026, describes architecture shaped by prompts. The concern is that an agent made several interlocking decisions before a reviewer could examine their combined effect.

Grabowski’s October 2026 work describes two related ways that structure can break down, context explosion and silent spec-code drift. The former arises as the agent reasons over an entire repository, while the latter develops as code evolves without corresponding changes to its specification. Neither means agents automatically create technical debt. The risk emerges because generating a change becomes much cheaper while understanding its architectural consequences does not.

What uncontrolled agent output actually does to a codebase at production scale

Abenhaim at AI Sovereign Labs documented an AI coding agent dismantling a core architectural invariant across 189 files in a large production codebase in 2026. The case had no test oracle, no human code review, and no signal until the damage was done. The invariant was therefore an unenforced assumption.

The Konrad et al. case study shows how little input change can produce substantial structural expansion. A single sentence change in the prompt produced 5.9× growth in lines of code, from 141 to 827 LoC, and a 3× increase in file count, while the agent and model remained constant. In that setting, the prompt functions as an architectural artifact because it dictates complexity and attack surface.

Veracode’s Spring 2026 GenAI Code Security Update found that only a bare majority of AI code-generation tasks produce secure code out of the box. That result has barely moved in two years, even as syntax correctness has reached a high level. The GitClear study found that AI-generated code is copied, changed soon after it is written, and maintained less consistently than human-written code. Its churn measure concerns lines modified or deleted within two weeks of being written.

These findings cover different kinds of quality. Agents can scaffold systems in minutes. Teams still need hours or days to audit the result, creating a speed-review gap that grows as agents get faster.

Why line-by-line diff review cannot close the speed-review gap

A line diff remains useful for reviewing implementation, and linters and static analysis catch syntax and type-level violations. Those checks perform necessary but different work. A unified diff shows a new import, but does not itself identify architecturally significant relationships, such as whether that import crosses a forbidden layer boundary or couples domains that were deliberately separate.

Across a 40-file, multi-thousand-line change, a reviewer must reconstruct those relationships while reading the patch. One seemingly reasonable abstraction may change the meaning of several other edits. More careful reading does not change the representation. Ordinary syntax and type checks also have no declared intent to tell them which layer may call which, or which abstraction must stay separate. Encoding and checking those rules requires an architectural instrument.

What a graph diff is and why structural divergence is a catchable artifact

The as-intended graph sets out the architecture before the agent runs, with module boundaries, allowed dependencies, and layering rules. The as-built graph represents dependencies extracted from the code after generation. A graph diff compares those two structures. Its findings concern forbidden new edges, required relationships that are absent, misplaced modules, and abstractions that have become coupled despite a declared separation.

This comparison needs more than two rendered diagrams. Lucidchart supports manually maintained diagrams, Structurizr supports models-as-code, and Mermaid supports diagrams-as-code, while dependency extractors derive relationships from implementation. Graph diffing makes it possible for a machine to compare the extracted structure with the declared design despite their different forms. The design must express constraints in a form the comparison can evaluate. A picture of boxes and arrows is not automatically an enforceable model.

SAGE, the Structured Agentic Graph Editing for Software Diagrams system, illustrates the underlying separation. It treats a diagram as an editable graph, translates requests into structured changes, and validates changes against that representation before accepting them. Its principle is to “use language models for interpretation, but constrain accepted changes through editable representations, deterministic logic, and validation guards.” Architectural verification applies that principle to coding-agent output.

Reproducibility makes the result suitable for automation. Given the same codebase, the same graph extractor produces the same graph, so structural divergence can become a repeatable CI check. That does not make the intended graph correct by definition. A stale baseline simply formalizes an obsolete design. The intended graph must therefore live in the repository, version with the code, and change deliberately when architectural decisions change.

How the three-layer governance framework makes graph diffing enforceable

The first layer declares instructions and constraints before generation, giving the agent architectural boundaries and supplying the as-intended graph. The second layer enforces fitness functions during the build, comparing the extracted dependencies against those constraints and failing on violations. The third layer captures architectural decisions from agent reasoning traces as ADRs, preserving the rationale for deliberate updates to the model.

Enforcement is the decisive distinction in practice. A report that identifies a forbidden dependency still leaves acceptance to a later human intervention. A check that exits non-zero and blocks the merge makes the boundary operational. Legitimate refactors are still possible because the intended graph can change when someone makes an explicit architectural decision, keeping it from being silently rewritten to match whatever the agent produced.

Additional constraints also have a real cost. Adding architectural rule files to every agent context window raises the cost of each call and can lead agents to work around legitimate refactors. No published benchmark yet quantifies that cost-benefit tradeoff at scale. CI-level graph comparison avoids adding its verification work to the context window because it runs after generation. That is why graph diffing belongs in the fitness-function layer, rather than being treated as a problem solved by making prompts longer.

GitHub’s Security Validation for Third-Party Coding Agents, announced June 9, 2026, gives teams a way to enforce checks on agent-generated code. Anthropic’s agentic quality control findings also support keeping generation separate from the decision to accept the code. Neither establishes that a security check is an architecture check. They support the broader operating pattern in which automated validation governs agent output, with architectural divergence enforced at the CI merge gate.

The toolchain that implements graph diffing in CI today

CppDepend 2026.2 provides multi-language baseline comparison, allowing a current build to be compared with a historical baseline such as the last release or main branch. It distinguishes newly introduced issues from legacy debt. That distinction is useful when existing violations should not obscure new ones. A historical baseline shows what changed since an earlier build, but the result may still differ from an architectural intention declared on its own.

codegraph, from optave/ops-codegraph-tool, provides function-level dependency graphs across a wide range of languages. It has architecture boundary enforcement, CI quality gates, git diff impact with co-change analysis, and a 34-tool MCP server for AI agents. Agent workflows are explicitly within its scope. Its fit therefore differs from baseline-oriented analysis, particularly where the verification process needs function-level relationships and agent-facing access to the graph.

Model Discovery / Dependency Graph Extraction, described in arXiv:2506.11176, is another way to build the model. This emerging class mines distributed traces, logs, and metrics to synthesize an explicit architectural model, with extraction positioned after the build stage to keep the model current on every commit. The choice of extraction method determines which relationships become visible to comparison.

These tool families do not remove the modeling work. None was designed around the specific problem of verifying agent output against an intended architectural graph, and teams must translate their intent into rule files. Their findings also do not supply a structural view of the whole codebase. The enforceable baseline still needs to reside in the repository and version with the code. Tool selection follows from the relationships that must be checked.

How do you detect when AI-generated code diverges from your intended architecture?

Forbidden edges are new import or call relationships that cross declared boundaries. For example, a generated UI module might import directly from a data-access module when the intended layering forbids that path. The individual import may compile without difficulty. The violation lies in the relationship it establishes, which the graph diff can compare against the allowed dependency direction.

Missing edges express the opposite kind of breach. An intended adapter might be required to mediate two domains, yet the generated implementation could omit that relationship. A missing connection can be easy to overlook in a line diff. Detection depends on declaring the relationship as required, rather than merely maintaining a list of forbidden imports.

New nodes in the wrong domains reveal misplaced responsibility. An agent might create a module that appears to belong to one domain but imports the dependencies of another because it inlined logic that should have been delegated. Its name alone would not settle the question. The graph exposes its placement through dependency relationships, making the mismatch between declared responsibility and actual coupling visible.

Collapsed abstractions occur when modules meant to remain separate become directly coupled or share a dependency that breaches their declared separation. For example, an agent might introduce a common abstraction that joins domains the design intentionally isolates. Shared dependencies are not inherently architectural violations. The finding becomes meaningful only when the intended graph defines the separation that this particular dependency defeats.

Repeated review comments, misplaced logic, and forbidden imports are early signals of architecture drift. Complexity thresholds can also trigger review when structural growth exceeds a baseline, extending the Konrad et al. case study’s concern about uncontrolled scaffolding beyond line counts. These signals still require a precise scope. Graph diffing complements test suites because it does not detect runtime behavioral regressions, performance characteristics, or business logic errors.

The developer's role when the graph is the source of truth

The developer’s architectural task shifts from reconstructing intent from generated code to maintaining the model that generated code must satisfy. This is not a reduction in responsibility. A machine-enforceable design must express which dependencies are allowed, which relationships are required, and which domains must stay separate. That calls for judgment about structure before generation, with less left to a reviewer to catch afterward.

The distinction also changes how agents can be used. Bounded execution can proceed aggressively when the boundaries are explicit and instrumented, while open-ended ideation requires greater caution. The graph supplies instrumentation for structure. Developers still decide whether a flagged divergence is an error or a legitimate architectural change, and decision capture preserves the reason for updating the baseline.

The practical workflow begins by declaring the intended graph in the repository before the agent runs. After generation, the CI gate extracts the as-built graph and compares it with the declared constraints. Architectural review then focuses on the structural divergences instead of reconstructing the whole design from the line diff. When a legitimate refactor changes the architecture, the developer updates the graph deliberately, so the next generation runs against the new design.