Context-Driven Architecture Drift

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.

Solution

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.

When to use

• 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.