How to Prevent Architecture Drift in Agent-Assisted Changes
Architecture drift, named in 1992, and a working answer: rules kept as files and checked on every change. A Kubernetes example and an eight-question checklist.

In short
Architecture drift is the slow loss of a codebase's intended structure, one reasonable change at a time. Perry and Wolf named it in 1992 and traced it to "insensitivity about the architecture". A change written with an AI coding agent is exposed to drift in a specific way: the agent works from the task, the files and the instructions in its context, and an architecture that lives only in people's heads appears in none of them. The practice shown here comes from a public repository. Each architectural rule is stated in a file a tool can evaluate. The check runs on every change. An edit to a rule is itself a reviewed change, with its reason written beside it. A passing check shows the change kept the stated rules, and a named person still decides whether to accept it.
What architecture drift is
Perry and Wolf's founding paper on software architecture separates two ways a system loses its shape. "Architectural erosion is due to violations of the architecture", they wrote, and "Architectural drift is due to insensitivity about the architecture." Drift is the quieter of the two. In their words: "This insensitivity leads more to inadaptability than to disasters and results in a lack of coherence and clarity of form, which in turn makes it much easier to violate the architecture that has now become more obscured" (ACM SIGSOFT Software Engineering Notes, October 1992, page 43).
Three years later Murphy, Notkin and Sullivan gave the comparison a vocabulary. An engineer states a high-level model, a tool extracts a second model from the source, and the two are laid over each other. Where they agree, the result is a convergence. A divergence is a place "where the source model includes arcs not predicted by the high-level model" (Software Reflexion Models, 1995). Applied to a restructuring tool with a layered design, the comparison "highlighted, as divergences, a few cases where modules in the source code did not adhere to the layering principles".
Architecture conformance checking is that comparison run as routine. Li and colleagues, who studied how practitioners discuss erosion, describe it as "the type of conformance between the implemented architecture and the intended architecture", and add that "The detection happens by identifying architectural violations in the implementation" (ICPC 2021). Their sample is small: 80 community posts and 13 practitioners. One developer they quote marks how far review by eye can carry the job: "when the team is small enough, using code reviews will be effective enough to prevent architectural erosion".
Why an agent-assisted change needs the rule written down
A person who has worked in a codebase for a year carries its layering as habit. An AI coding agent starts each task from what its context holds: the task, the files it opened, and any instruction file the repository provides. The open AGENTS.md format describes that file as "a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project" (agents.md).
Teams already use such files for architecture. A study of 2,303 agent context files from 1,925 repositories hand-coded a sample of 332 English-language files and found architecture instructions in 68.1% of that sample (Chatlatanagulchai and colleagues, arXiv preprint, version 2). The category covers text that describes "the high-level structure, design principles, or key components" of a system. The figure counts descriptions, and whether changes then follow them is outside what the study measured.
A description informs whoever writes the change. The reviewer needs something more: evidence that the finished change stayed inside the structure described. In our reading, this is where the engineering bottleneck moves when agents write more of the code: from producing changes to trusting them. Rebuilding the architecture from memory for every diff is slow work, and diffs now arrive quickly. Each rule therefore gets a second form, one a machine evaluates before the reviewer starts.
A conformance example from a public repository
Kubernetes keeps its dependency rules inside the repository and checks them in a CI job that runs on pull requests. The tool is import-boss. Its README states the purpose: "This is useful to manage the dependency graph within a large repository" (cmd/import-boss/README.md). Rules live in YAML files named .import-restrictions, each placed in the directory it governs. The tool reads the rule file beside a package and those in each parent directory, closest first. The README gives the test: "An import is allowed if it matches at least one allowed prefix and does not match any forbidden prefixes."
At the commit we read on November 18, 2026, the tree held 64 of these files, plus 7 that are the tool's own test fixtures. Some are short. The file for the apiserver library is five lines: the comment "prevent import of k8s.io/kubernetes", and one rule that forbids every import path matching that name. The repository's AGENTS.md tells agents the same thing in prose, in a line that bans importing k8s.io/kubernetes from the staging libraries. For that library the boundary exists twice: a sentence an agent reads, and a rule a tool evaluates.
Nobody has to remember to run the check. A presubmit job named pull-kubernetes-verify is configured with always_run: true, and release branches have their own copies of the job. Through a wrapper script it calls make verify, which runs the repository's verification scripts apart from a short exclusion list. The import check is outside that list, so it runs.

Two merged pull requests show the rule files in ordinary use.
Pull request 141415, merged on August 27, 2026, added a rule file for the scheduler package. Its description gives the reason in one sentence: "This PR prevents silently expanding the k8s.io/kubernetes dependencies in scheduler package." It also states a direction: "We will want the import allowlist to gradually shrink". The file listed nine permitted dependencies when it merged, and six at the commit we read. One entry left through pull request 141463, which replaced an import with a local constant and deleted the matching line of the allowlist.
Pull request 142453, merged on September 29, 2026, moved three signal-handling functions into a small package, so that the kubelet and a Windows service helper no longer link the generic API server. The same change added two rule files. The one for the kubelet opens with its reason: "Importing the generic API server, directly or transitively, pulls admission and etcd storage into the kubelet." The description carries the disclosure the project asks of every contributor: "YES. AI tooling helped map the import chains, apply the change, and draft this description. The author reviewed and verified all of it."
That pull request shows the practice at small scale. A person used AI tooling to trace a dependency, removed it, and added a rule with the reason attached, and the verify job passed on the final commit. A later change that pulls the generic server back into the kubelet or kube-proxy, whoever or whatever writes it, now has two ways through: drop the import, or edit the rule file in front of a reviewer.
A conformance checklist for agent-assisted changes
The checklist is written for a change produced with an agent, and nothing in it depends on the tool. It pairs with the review checklist for agent-written changes and the provenance checklist.
| Question | Where the answer should already be |
|---|---|
| Is the intended architecture stated in a form a tool can evaluate? | Rule files in the repository, next to the code they govern |
| Does the author's context include the rules? | The agent instruction file or the contributor guide, naming each boundary and the command that checks it |
| Did the conformance check run on this exact change? | The CI record of the pull request, from a job that runs on every change |
| Did the change edit a rule file? | The diff. An edited rule is a design decision, with its reason in a comment or in the description |
| Does the change add a dependency the rules do not cover yet? | The reviewer's reading of the import changes, and a new rule in the same pull request where the boundary matters |
| Was an exception granted? | An allowlist entry with an owner and a linked issue for removing it |
| Was tool use disclosed? | The description, in the form the project's policy asks for |
| Who accepted the change? | The approval on the pull request, from a named person with authority over that part of the code |
Checkers of this kind exist beyond Go. ArchUnit presents itself as "a free, simple and extensible library for checking the architecture of your Java code using any plain Java unit test framework" (archunit.org), and for Python the documentation of Import Linter says it "allows you to impose constraints on the imports between your Python modules" (Import Linter).
What a passing check leaves open
A conformance check answers one narrow question: whether the change kept the dependencies the rules allow. Rules cover only the boundaries someone wrote down. Li and colleagues report that "alongside technical factors, architecture erosion is caused to a large extent by non-technical factors", and no rule file reaches those. An allowlist can grow one approved entry at a time, which is why the checklist treats every rule edit as a design decision. Last, a change can respect every boundary and still fail to do what was asked.
The Kubernetes contributor guide keeps that last judgment with people. "Do not leave the first review of AI generated changes to the reviewers", it says, and it warns that "if you cannot explain why a change was made, the PR will be closed" (AI Guidance).
The check takes the mechanical comparison off the reviewer and leaves a record that it ran. In software whose failure has consequences, that record belongs with the rest of the evidence for the change, in an assurance case. Our article on agentic engineering explains why the decision to accept is now the scarce step.
Where Kealu Vector fits
The Agentic Engineering Assurance Layer is the proposed category for the layer that governs how agentic engineering work is performed and evidenced, so that humans can trust and accept the resulting work. Our white paper AI Has Moved the Bottleneck sets out the problem it answers, and the questions raised here hold whatever tools a team uses to answer them. Kealu Vector, currently designated Vector Assurance Assist, is our early-access implementation of that category.
FAQ
What is architecture drift?
Architecture drift is the gradual loss of a system's intended structure through changes that each look reasonable. Perry and Wolf, who introduced the term in 1992, attributed it to "insensitivity about the architecture" and set it beside architectural erosion, which comes from outright violations. Drift leaves a system harder to adapt and its design less clear, which makes later violations easier.
What is architecture conformance checking?
Architecture conformance checking compares the structure the code actually has with the structure the team intended, and reports the differences. In practice the intended structure is written as rules, for example which packages may import which, and a tool evaluates every change against them in CI. Examples are import-boss in the Kubernetes repository, ArchUnit for Java and Import Linter for Python.
How do you prevent AI coding agent mistakes that break the architecture?
Write the architectural rules down twice. Put them in the instruction file the agent reads, so the author of the change knows the boundaries, and encode them as rule files that a check evaluates on every pull request. Treat any edit to a rule file as a design decision with a stated reason. Keep acceptance with a named person. The same practice works for changes written by hand.
Is an AGENTS.md file enough to keep an agent inside the architecture?
An AGENTS.md file tells the agent what the architecture is, and one study found architecture instructions in 68.1% of a hand-coded sample of 332 English-language agent context files. The file informs the author of the change. Evidence that a finished change followed it comes from a conformance check that runs on the change, with the result kept in the pull request record.
On Google
Add Kealu as a preferred source: our articles get highlighted in Top Stories, AI Mode and AI Overviews.
Talk to our team.
Questions about this article, or about using Kealu Vector in your organization? Send us a message.
Talk to our team.

