Specification Drift
Specification drift is a growing mismatch between a software specification and the code it describes, caused by one changing without the other. Either the code evolves while the spec stays frozen, or the spec is updated while the code keeps the old behavior. Because the spec still reads as correct, people and AI coding agents that trust it end up building on behavior the software no longer has.
How Specification Drift Happens
Drift runs in two directions.
The code moves, the spec does not. A later request changes a behavior. The developer or agent edits the code without opening the spec, then updates the tests to match the new code, so the suite still passes. Nothing reports that the spec now describes something that no longer exists.
The spec moves, the code does not. A product decision changes, for example an account recovery window shrinks from 30 days to 14. The requirement is edited, but the tickets, code and tests built against the old version are never revisited.
Tests catch drift only for what they check. Once a test's expectation is rewritten to match changed code, the drift becomes invisible to the test suite.
AI coding agents raise the stakes. An agent treats the spec as input, not background reading. A human might notice that a document looks old; the model gets no such signal unless the context says so. A stale spec therefore does not just sit unread, it actively steers the next round of generated code in the wrong direction.
Why Specification Drift Matters
A drifted spec can be worse than no spec, because it is trusted. New team members onboard from it, agents generate from it, support answers questions from it and reviewers approve changes against it. Each of those decisions inherits the error.
Common defenses are simple but need discipline: change the spec and the code in the same pull request; have the reviewer check both against what the team intended, not just against each other; keep requirements-to-code traceability so it is clear which code and tests depend on which requirement; and run a periodic requirement alignment audit on the areas that change most. Approaches such as spec-driven development make the spec the primary artifact, which raises the cost of letting it go stale.
Specification Drift Example
The account settings spec says deleted accounts are recoverable for 30 days. A developer asks an agent to "simplify deletion." The agent switches to an immediate hard delete and updates the related test so it passes. The spec is untouched.
Three months later, a support agent tells a customer their account can still be restored, quoting the spec. It cannot. The next time an agent works on account features, it reads the same spec and builds a "restore account" button for data that no longer exists.
For how drift accumulates in AI-built codebases and how teams track requirements to prevent it, see how to prevent context drift in AI-generated codebases.
Specification Drift vs. Context Drift
The two are closely related and often appear together. Context drift describes the gradual gap between approved product behavior and implemented behavior that builds up as agents work across many tasks with incomplete or stale context. Specification drift is narrower and more concrete: the written spec and the code disagree. Context drift is often a cause, since an agent that never saw the spec cannot keep it current. But specification drift also happens without any AI involved, whenever documentation is not updated alongside code.