What is spec drift?
Spec drift is the gap that opens between what a specification says and what was built, planned or agreed from it. It starts the day after the spec is written: the code moves, a ticket is changed, a client agrees to something on a call — and the spec still says what it said. With AI coding agents it matters more, because an agent reads the stale spec and builds from it with confidence.
Spec drift runs in three directions
| Direction | What happens | Example |
|---|---|---|
| The code moves | The implementation changes; the spec does not | A field is renamed during the build; the spec still names the old one |
| The spec moves | The spec changes; what was built from it is not told | A rule is tightened; the task, the test and two older specs still follow the old rule |
| The agreement moves | The spec changes after someone signed it off; the sign-off still points at “the spec” | The client approved one version; the team is building a later one |
Most writing about drift covers only the first direction. The other two are where teams lose days, and where agencies lose money.
Spec drift vs documentation drift
Documentation drift is the gap between documentation and code: a README that describes last year’s API. Spec drift is about intent — what the software is supposed to do, who agreed to it, and what was built against which version of it.
The difference decides the fix. Documentation can often be regenerated from the code. A spec cannot: the code shows what was built, not what was meant or agreed. The term is sometimes written “specification drift”. It is not the same as “requirements drift”, which usually means the requirements themselves keep changing.
Why specs get out of sync
- The spec lives in more than one place. A markdown file, the tickets copied from it, the document the client saw, a decision in a chat. Each copy is right on the day it is written, and each drifts on its own.
- Changes are made in the code. Implementation finds edge cases, and they are fixed where they are found. The spec is updated later, or never.
- One change touches several specs. A new feature quietly changes what earlier specs promised, and nothing points from the new spec to the old ones.
- The update step is the first one skipped. “Update the spec” sits at the end of the definition of done, behind the deadline.
- Agents change code without touching the spec. On the day Kiro launched, the author of a guide in its own documentation wrote that the agent “can make code changes without updating the specs at all” (Hacker News, July 2025).
How do you adress spec drift? A new feature can easily affect 2 or 3 specs. Do you update them manually?
— Hacker News, February 2026
Why spec drift matters more with AI coding agents
A person who reads a stale spec usually notices that it no longer matches what they see. An agent does not: it treats the text as true and builds from it.
Then we refactored a couple of modules, changed our deploy flow, and nobody updated the file. Claude kept confidently working off rules that stopped being true weeks ago.
— a five-person team, r/ClaudeAI, July 2026
Among developers using spec-driven development tools, it is one of the three complaints we found most often — see what 20,000 comments say. One put it bluntly: “In my experience, spec drift is the main reason why none of these tools work” (Hacker News, September 2026).
Specs in git: why version control does not stop drift
Keeping specs in the repository is a good start. They are versioned, reviewed in pull requests, and sit next to the code. But git records when the spec’s text changed — not whether anything that depends on it has moved. A Kiro user put it in a heading: “Why committing specs to git isn’t enough” (kirodotdev/Kiro #9435).
Files in git also multiply. The most-supported request on Spec Kit’s tracker, with 115 reactions, says updating an existing spec means “creating new branches and redundant specification artifacts” (github/spec-kit #1191) — more copies, each free to drift. And the people who have to agree with the spec, if they do not use git, cannot read it there at all. More in requirements in git.
How to detect spec drift
| Method | What it catches | What it misses |
|---|---|---|
| Record the basis. Store the commit or version a spec describes; flag the spec when the files it names change after it | Code that moved under a spec | Changes of meaning made in other files |
| Pin work to versions. Every task records the spec version it was built from | Tasks built from a spec that has changed since | Specs nobody turned into tasks |
| Turn acceptance criteria into tests (Given / When / Then) | Behaviour that no longer matches a testable statement | Intent that cannot be tested; criteria nobody wrote |
| Review the spec in every pull request, by a person or an AI | Mismatches in the files that changed | Everything outside the change; it reports, it does not decide |
| Look for copies. Search for any requirement written in more than one place | The copies that will drift next | — |
Detection tells you drift happened. It does not tell you which side is right — the code or the spec — and someone with the authority to decide still has to.
How to stop spec drift instead of chasing it
- Write each statement once. One requirement, one place. Documents, tickets and reviews refer to it; they do not copy it.
- Version the spec instead of editing it. Keep every version under one stable name, so “which version did we build?” always has an answer.
- Make a change mark what it touches. Before a change is accepted, list every requirement, test and task that depends on what it changes.
- Point every agreement at a version. A sign-off names the exact version it approved, and that version stays readable after the spec moves on — this requirements sign-off template does it. The approved version is the requirements baseline.
- Change the spec first. When implementation finds something, the spec changes in the same piece of work — not after it.
A five-question check
- Is every requirement written in exactly one place?
- Can you tell which version of the spec each task was built from?
- When a requirement changes, do you get a list of what it affects — or do you search for it?
- Does the client’s sign-off point at a version, or at “the document”?
- Can someone who does not use git read and comment on the current spec?
Every “no” is a place where drift is already happening.
Where Specroot fits
Those five rules are the problem Specroot works on: one specification instead of copies, changes that show what they affect, and work that knows which version it was built from. Specroot for teams using AI coding agents.
For what developers and agencies say about drift in their own words, read We went through 20,000 comments about specs.
Read next
- Requirements in git: what version control does not track — Keeping specs and requirements in git gives you history, diffs and review. What it does not give you, and how to make requirements in GitHub or GitLab work.
- Requirements baseline: what it is, with an example — A requirements baseline is the agreed version of the requirements every later change is measured against. Definition, example, scope baseline, re-baselining.
- We went through 20,000 comments about specs. Here is what breaks. — Developers say their specs drift from the code; agencies say the client's sign-off does not hold. What 20,000 comments and issues from 2025–2026 show.