Context-Driven Architecture Drift

also known as Tacit-Convention Violation, Brownfield Architecture Drift

Anti-pattern: let a coding agent change a brownfield codebase guided only by the files it can see, so it silently violates the architecture conventions that live in nobody's machine-readable form.

Context

A coding agent is set loose on an existing codebase that already has a shape: layers it is supposed to respect, places where certain logic belongs, naming and dependency rules that the team enforces by habit and code review. Most of those rules were never written down for a machine. They live in senior engineers' heads, in the implicit pattern of how the existing files are arranged, and in the unstated reasons a previous author put a thing where it is. The agent reads the few files it is shown and infers a local shape from them.

Problem

The agent builds what it is shown, not what the team means. From a handful of visible files it infers a plausible but wrong picture of where logic belongs, then puts a database call in a controller, duplicates a helper that already exists one layer up, or wires a dependency that the architecture forbids. Each change looks reasonable on its own and passes the tests, so it merges. Over many such changes the codebase drifts away from its intended architecture, and because every individual diff was defensible, nobody catches the slide until the layering is already tangled and a feature that should have been local now touches everything.

Forces

The architecture's real rules are tacit — in heads, review habits, and the arrangement of existing files — so the agent cannot read what it must obey.
What the agent can see is a small, possibly unrepresentative slice of the codebase, and it generalises a global convention from a local sample.
A change that respects the visible files but violates the unseen convention still compiles and passes the existing tests, so the usual gates do not catch it.
Each violating diff is small and locally defensible, so reviewers approve them one at a time and the drift only becomes visible in aggregate.

When to watch for it

A coding agent is given write access to an existing codebase whose architecture conventions are mostly tacit and not written down for a machine.
Plausible, test-passing agent diffs are merging quickly and nobody is checking them against the intended layering or module boundaries.
The team notices, after the fact, that logic is landing in the wrong layers or that helpers and abstractions are being duplicated.

When it is not a concern

The codebase is greenfield with no established conventions yet for the agent to violate.
The architecture conventions are already encoded as machine-readable specs and enforced by an in-loop drift check (that is agentic-golden-path, not this anti-pattern).
The agent only proposes diffs that a human architect reviews against the conventions before any merge.

Example

A team asks a coding agent to add a discount rule to an order service. The agent reads the order controller and the request handler it is shown, sees other small bits of logic there, and writes the discount calculation straight into the controller. It also adds its own currency-rounding helper, not knowing the team already has one in the shared money module. Tests pass and the diff merges. Over a quarter, dozens of such diffs put business logic in controllers and scatter duplicate helpers, until a change that should touch one file touches twenty.

Diagram

flowchart TD T[Tacit architecture conventions\nin heads and review habits] -. not encoded .-> A[Agent sees only local files] A --> I[Infers wrong global shape] I --> D[Plausible diff: wrong layer / duplicate helper] D --> P{Tests pass?} P -- yes --> M[Merged] M --> R[Repeat over many diffs] R --> DR[Codebase drifts off its architecture]

Solution

Therefore:

Treat the absence of a machine-readable architecture spec as the defect. Encode the tacit conventions the team enforces by habit — allowed layer dependencies, where each kind of logic belongs, naming and module boundaries — as artifacts the agent reads and that a check can enforce: an agent guidance file, architecture decision records, dependency and structural lint rules, reference examples of the right shape. Give the agent enough of the codebase as context to see the real conventions rather than a local sample, and run a drift check in the loop so a layer violation is rejected while the agent is editing, not discovered after a dozen such diffs have merged. The remedy is the positive pattern agentic-golden-path; this entry names the failure that results when that spec and harness are missing.

What this pattern forbids. No useful constraint; the missing constraint is a machine-readable architecture spec plus an in-loop drift check that rejects layer and dependency violations before the diff merges, rather than after.

The patterns that counter or replace it —

alternative-toAgentic Golden Path★— Constrain an agent to the platform's curated golden path of living, machine-readable standards and check for drift as it works, so its output is compliant by construction rather than corrected later.
complementsRepo Map★— Give the agent a compact, ranked map of the codebase's symbols and their dependencies so it orients on what matters before reading any files.
complementsAutomating a Broken Process✕— Anti-pattern: deploy agents on top of a workflow that is already dysfunctional, so the dysfunction is amplified at machine speed instead of resolved.
complementsAgentic Skill Atrophy✕— Anti-pattern: let agents take over routine architectural and debugging decisions in code until developers no longer form the implicit knowledge that lets them review the agent's output or recover when it fails.