What Is Architectural Drift?
Architectural drift is the gradual divergence between the architecture a team intends and the one the code actually has, as individual changes add dependencies, shortcuts and couplings that the design never allowed.
How it happens
No single change causes it. A deadline justifies one import across a layer boundary; a copied module brings its dependencies along; a feature routes around an interface because calling the implementation directly was faster. Each change is reasonable in isolation, and each makes the next shortcut look normal.
AI coding agents accelerate the pattern. An agent optimises for the change in front of it and cannot respect a boundary it cannot see, so generated code tends to take the most direct dependency path available.
How to detect it
Compare the intended structure with the real dependency graph. Signs of drift include imports that cross a layer the design says is one-way, hubs that did not exist in the original design, and cycles between modules that were meant to be independent.
The graph has to be read from the code as it stands today. An architecture diagram in a wiki records the intent, not the drift.
Common questions
What is architectural drift?
The gradual divergence between the architecture a team intends and the one the code actually has, built up one reasonable-looking shortcut at a time.
What is the difference between architectural drift and architectural erosion?
The terms are often used together. Drift usually means the structure moving away from the design without breaking an explicit rule; erosion means changes that violate the design's rules outright. Both are found the same way: by reading the real dependency graph.
How do you stop AI agents from breaking architecture dependencies?
Make the structure visible before the agent edits: give it a way to query what depends on a file and what a change affects, and review generated changes against the dependency graph rather than the diff alone.
Related
- Code dependency mapping — See your codebase as a live dependency graph. Mapnostics maps every file, import and route, highlights the high-blast-radius hubs, and layers ownership, schema and performance patterns over the same canvas.
- Change impact analysis tool — Map the exact blast radius of any code change before you ship. Plain-English change impact analysis, traced through your real dependency graph. Try it free.
- AI code sprawl
- Legacy modernization
- Dependency graph — glossary
- Codebase context for AI agents — glossary
- Blast radius (in code) — glossary
See it in your own codebase.
Analyze my codebase →No credit card required · Free tier available