Keeping an AI Agent Oriented as Your Codebase Changes Beneath It

An interactive codebase graph for AI agent steering gives developers and agents a map they can share that shows the modules, dependencies, and architectural boundaries as they are now. Keeping an agent oriented requires that map to be queryable, inspectable, and enforceable in CI. Better prompts alone cannot solve structural disorientation.

Why agents lose structural coherence when codebases evolve

In the VS Code layered-architecture example, an agent places a path utility in the workbench layer because that is where its caller lives. The placement makes local sense but violates the architectural constraint that such utilities belong in the base layer. The structural error can occur even when the agent understands the requested function.

That distinction explains why an agent can become less reliable as a repository changes even when it is still just as good at coding. It learns that a team uses a particular pattern, but not necessarily why the pattern exists or which conditions make it valid. When other work changes those conditions, the agent can continue applying the old pattern with confidence. Its knowledge and the repository have diverged. More detailed reasoning over that stale model does not restore the missing relationship.

Aristidis Vasilopoulos’s Codified Context: Infrastructure for AI Agents in a Complex Codebase describes agents losing coherence across sessions, forgetting project conventions, and repeating known mistakes. Architectural knowledge does not reliably persist just because an agent encountered it once. A previous correction can disappear from the next session’s working context, while a convention that does persist can outlive the structure that justified it.

How architectural drift compounds across long-horizon and multi-file work

An agent satisfies an immediate requirement, then proceeds using the resulting code as the basis for its next decision. If the first change weakened a boundary, later changes can build on that weakened structure. Each step can remain locally coherent. The task progresses while the architecture drifts away from the constraints that were supposed to govern it.

SlopCodeBench found structural erosion in 77% of trajectories, and no agent fully solved any of its long-horizon problems. A requirement visible in the current task can displace an architectural invariant that the agent cannot see. Adding more work therefore creates more opportunities for this mismatch, rather than simply asking the agent to repeat an isolated coding operation.

Monorepos make the mismatch especially clear because a one-line change to a shared type definition can break multiple downstream packages. An agent looking only at its own changes does not see the package relationships through which the effect propagates. More context helps only if it shows how those packages relate to each other. A larger window filled with nearby code is not equivalent to a view of downstream dependencies.

Parallel agents introduce another source of divergence because each can operate from a different structural model of the same repository. Their outputs may be individually coherent yet mutually inconsistent. Saebo et al.’s 2026 paper, Asymmetric Goal Drift in Coding Agents Under Value Conflict, also reports that violations cluster around constraints that conflict with strongly held model priors. Drift is therefore not evenly distributed. Some architectural decisions face more pressure than others.

Why the diff is the wrong interface for catching what agents have changed

A diff shows which lines changed. A reviewer can see an added import without seeing the boundary it crosses or every package affected by the new dependency. The missing relationship must be reconstructed from elsewhere. As agents produce more code, review becomes harder to rely on when it depends on piecing those relationships together.

This is an interface limitation. In the shared-type example, the change is small enough to inspect closely, but the defect can live in the package graph beyond it. The reviewer needs the relationship between the changed definition and the rest of the system, including code that the patch leaves untouched.

A larger context window can expose more text without identifying the dependencies or invariants the change must satisfy. More suggestions on style and best practices also leave the missing architectural signal out of view. For a change to be correct, it must fit the system as well as follow familiar code patterns.

Diff review still has a role in understanding implementation details. It is not, however, an adequate primary interface for detecting changes to global structure. Asking reviewers to inspect more carefully leaves the central task unchanged, which is to reconstruct a system-level model from a line-level representation. The missing signal is not in the diff at all.

What teams have tried with context files and manifest specifications

AGENTS.md gives teams a standard place in the repository to put governance instructions. The specification was formalized in August 2025 and donated to the Linux Foundation’s Agentic AI Foundation in December 2025. It puts conventions where agents can find them, so developers no longer have to keep them all in their heads. That is a genuine engineering improvement. A precise instruction can prevent an agent from having to infer a rule from scattered examples.

Vasilopoulos’s study reports that most Claude Code projects by far set out their application architecture in manifest files. It also reports an association between the presence of AGENTS.md files and meaningful reductions in agent runtime and output token usage. Specificity is the useful distinction. Agents followed specific instructions reliably, while repository overviews did not help them reach relevant code more efficiently. A constraint does more work than a general description.

The same study addresses the scale limit of a single prompt through tiered context documentation for a 108,000-line codebase. This approach treats context as maintained infrastructure. It deserves that distinction. However, even extensive documentation describes the structure as it was when the documentation was written. A moved module boundary, a new package, or a parallel agent’s change can create a gap between the document and the repository.

ContextCov advances this approach by synthesizing enforcement checks from natural-language constraints through static AST analysis, runtime shell shims, and architectural validators. It turns written guidance into something executable. Yet the constraints still originate in a developer’s description at a point in time. A file-based description is a snapshot of a changing system. Maintaining it requires continual reconciliation with the code.

What a live architectural model actually provides that static context cannot

A live architectural model makes the repository’s relationships available as current, queryable structure. It maps modules, files, classes, functions, and call relationships rather than asking an agent to reconstruct all of them from prose. Humans can inspect the same model that agents query. CI can evaluate constraints against it. These are different uses of one shared structural reference.

The essential distinction is between informational and relational orientation. Informational context tells an agent facts about the codebase, such as where a module lives or what a function does. Relational context shows how that module or function connects to parts of the system outside the immediate task. Both are useful, but they answer different questions. Knowing the edited code is not the same as knowing the consequences of editing it.

A static instruction says that utilities belong in the base layer. A current graph exposes the base layer’s contents and boundaries, allowing the placement decision to be evaluated against the repository as it exists. The rule still expresses design intent. The graph supplies the structural evidence needed to apply it, including relationships that may have changed since the instruction was written.

Meta’s ARCTIC self-review system shows the value of accurate signals over more material to read. The system processed a vast volume of API requests and achieved a high attestation-to-land rate with zero attributed defects since launch. Its relevant mechanism was giving developers signals about intent alignment and structural risk. This supports the narrower principle that orientation improves when review exposes the relationships that determine risk.

The structure as it stands cannot tell a team which relationships it should allow. Once that intent is explicit, however, the model makes compliance computable against the code instead of dependent on an agent’s interpretation of a document.

Enforcing architectural constraints in CI rather than relying on agent self-regulation

The engineering response is to enforce computable architectural constraints in CI. An agent under local optimization pressure may not correct a violation merely by reflecting on its work, because the immediate task still rewards the decision it made. Another reminder leaves that pressure intact. A pipeline gate instead evaluates whether the proposed structure satisfies the policy before the change can land.

ContextCov demonstrates one version of this approach by extracting constraints from AGENTS.md and synthesizing checks. The important shift is from instructions the agent should follow to conditions the repository requires. CI becomes a policy enforcement layer. In the practitioner pattern described by the notes, strict reviewer mode treats the architectural specification as policy and produces hard failures that block merges.

Graph-based enforcement can also check cases beyond those named in the rules. A boundary rule can apply to a newly introduced import path even when that particular path was not anticipated in the written examples. The relationship is what the check evaluates. A stated boundary can govern new combinations of code without requiring a separate rule for each combination.

An encoded constraint can fire on a one-line change with broad downstream effects regardless of how modest the patch appears or how much attention a reviewer has available. People still need to use their judgment to define the design and judge changes to it. For an enforceable invariant, however, a check that exits non-zero and blocks a merge is more valuable than post-hoc review because it acts before the violation lands.

How can developers give an AI agent a real-time map of the codebase?

A structural map becomes useful for agent steering when developers can navigate it, direct work through it, and evaluate the result against it. The practical criteria are current relationships, agent query access, human inspection, repository versioning, and CI enforcement. A diagram on its own falls short of those needs. A fresh index can make source text easier to find while still leaving architectural policy undefined.

With those capabilities in place, a developer can identify which modules an agent should touch, which boundaries it must respect, and which invariants are non-negotiable. The agent can receive structural context that is current at the moment of the prompt. In the utility example, that means showing where the new function belongs before implementation begins. This gives the agent the architectural knowledge it lacks, while enforcement catches violations that still occur with that context in place.

Vasilopoulos’s framework uses documents to help agents find their way in each session, with help from specialized domain-expert agents and an on-demand knowledge base of specification documents. It makes the knowledge agents need available across many sessions. Its continuing dependency is synchronization between those documents and the codebase. A live graph removes the need to manually restate the structural relationships it represents, while leaving developers responsible for expressing the intended constraints.

When the model lives in the repository, versions with the code, and is enforced in CI, it becomes a shared reference for agent work, human review, and onboarding. Agent speed then operates within explicit boundaries. The developer’s role shifts toward less diff scrolling and more architectural steering, with confidence grounded in an enforced design.