Spec drift is the gap that opens between a written spec and the actual behavior of the code: the spec says one thing, the system does another, because the spec wasn't updated when the implementation or the decision changed.

How is spec drift different from decision drift?

Spec drift is code diverging from a written spec; you can see it by comparing the two. Decision drift is work diverging from what the team decided, and the decision was often never written anywhere. Spec drift is the visible symptom; decision drift is usually the cause.

Why does spec drift get worse with AI coding agents?

Agents read specs as ground truth and can't ask a hallway question to check. A stale spec that would mislead one engineer now misleads every agent session that loads it, at machine speed, and the code they generate widens the gap further.

Spec Drift

Spec drift is when code and its written spec stop agreeing: the spec says one thing, shipped behavior does another, because nobody updated the spec.

Spec drift is when the code and the written spec stop agreeing. The spec says the endpoint returns amounts in dollars; the code switched to cents in March; the spec still says dollars. Nobody lied: someone made a good decision and the document never heard about it.

How it happens

A spec is written once, at the start, when the team knows the least. Then implementation teaches everyone things, decisions change in review and in Slack, and updating the document is the step that always loses to shipping. The drift is invisible day to day because everyone who made the change remembers it. The spec is only wrong for the next reader.

Why agents make it compound

The next reader is now an AI agent, and agents are worse at stale specs than humans in two specific ways. First, an agent treats the document as ground truth; it won't get the hallway correction a human would. It builds against dollars, confidently, and the output even looks right. Second, agents multiply the reads: the same stale line misleads every session that loads it, across every repo that references it. One outdated sentence used to cost a question; now it costs a batch of wrong pull requests.

And agents generate more code against more documents, so the surface area for drift grows exactly as the tolerance for it shrinks.

Spec drift vs decision drift

Spec drift is code versus a written spec, detectable in principle by comparing the two. Decision drift is broader: work diverging from what the team decided, whether or not anyone wrote it down. Most spec drift starts as decision drift: the decision changed, the document didn't. The same failure eats ADRs and PRDs alike.

Catching it

The cheap place to catch drift is the pull request, before it merges. Lockstep keeps an approved record of decisions and checks PRs against it, warning on conflicts by default and blocking only if you opt in. See how it works.