What Is Spec Drift? Why AI-Built Software Stops Matching the Plan

Spec drift is when your product spec splits into competing versions and the code stops matching the plan. Feature specs pile onto a core doc no one reads, old copies multiply, and every team or AI agent builds from a different version.

Here is the uncomfortable part: your agents are not ignoring the spec, they are following one, just not the one you approved last Tuesday. When code ships faster than people can update documents, the gap between what you decided and what you built grows every day. Most teams only notice when a customer finds it first.

What is spec drift?

Spec drift is a cousin of older ideas like requirements drift and documentation drift. The difference is speed and scale. With AI agents writing code, a stale spec does not sit on a shelf: it gets read, trusted, and turned into working software within minutes.

You can think of it as the distance between three things. There is what the team decided, what the documents say, and what the code does. In a healthy system those match, and in a drifting one they quietly pull apart.

Spec drift is not the same as a bad spec. A great spec can still drift if no one owns where it lives, how it changes, and which copy counts. It is a process problem first and a writing problem second.

How does spec drift happen?

No one sets out to create spec drift. It builds from small, reasonable choices that each save a few minutes. Here are the five patterns we see most often.

• Feature specs get appended: Every new feature adds a section to the core spec. After a year it can run 40 pages, and no human reads it end to end.
• Copies multiply: Someone pastes the spec into a wiki, a ticket, a prompt file, and a slide deck. Each copy starts aging the moment it is made.
• Each team or agent pulls a different version: The mobile team reads the wiki, the backend agent reads a markdown file, and design works from last quarter's deck. They are all following the spec, just different ones.
• Chats become requirements: A decision gets made in a Slack thread or an AI chat and never reaches the spec. The code follows the chat, and the spec now describes a product that does not exist.
• Agents write faster than people update docs: An agent can open several pull requests an hour. A person updates the spec when they find the time, which is often never.

That last point is new. Back in 2003, a study in IEEE Software by Lethbridge, Singer, and Forward found engineers usually updated documents several weeks after code changes. Weeks of lag was tolerable when humans wrote the code, but it is not tolerable when agents write it in an afternoon.

Why long specs make it worse

Appending feature specs creates one giant document. That feels thorough, but it works against both people and models. Long documents get skimmed by humans and misread by machines, which we cover in the cost section below.

What are the signs your team has spec drift?

Spec drift rarely announces itself. It shows up as friction that people blame on something else. Run through this checklist with your team.

• Two people quote different specs: Someone says "the spec says X" and someone else pulls up a doc that says Y.
• No one knows which copy is current: Files are named final, final-v2, or new-spec-USE-THIS.
• Agents rebuild things that already exist: The code has duplicate classes, endpoints, or components that do the same job.
• Review comments say "that's not what we agreed": Reviewers catch mismatches late, after the work is done.
• Decisions live in chat history: You search Slack, not the spec, to learn why something works the way it does.
• The spec is too long to read in one sitting: If no one has read it end to end this quarter, no one knows what it says.
• QA tests against a different version than engineering: Bugs get filed for behavior that someone, somewhere, approved.

If three or more of these sound familiar, you have spec drift. The good news is that every one of them traces back to a fixable process choice.

What does spec drift cost?

The cost shows up in three places: stale documents, confused models, and overloaded reviewers. Each one is measured in real research. None of them is a guess.

Stale documents are the default

In the Lethbridge, Singer, and Forward survey, 44% of engineers somewhat agreed and 24% strongly agreed that documentation is always outdated relative to the system. That is 68% of respondents. The same study found engineers often do not maintain documentation at all unless it is tied to the change request process.

Late discovery is expensive. A NIST summary of its 2002 report estimated that inadequate software testing infrastructure cost the U.S. economy $59.5 billion a year. It also noted that over half of software bugs are not found until downstream in the development process.

Long, messy context confuses agents

Agents read your spec as context, and context has limits. In "Lost in the Middle" by Liu et al. (2023), models did best when the key fact sat at the start or end of the input. When it sat in the middle of 20 documents, GPT-3.5-Turbo scored lower than it did with no documents at all.

Newer models show the same pattern. Chroma's Context Rot study tested 18 models in 2025 and found performance grows more unreliable as input length grows. Distracting, similar-looking text made it worse, which is exactly what a pile of near-duplicate spec copies looks like.

“finding the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome”

Reviewers drown

When the spec is unclear, review becomes the last line of defense. Faros AI's 2025 report studied more than 10,000 developers and found high AI adoption teams merged 98% more pull requests. Review time rose 91%, and AI adoption was associated with a 154% increase in average PR size.

Why doesn't AI code match requirements?

Most of the time, AI code does not match requirements because the requirements it read were not the ones you meant. The agent did its job on the wrong input. That is spec drift showing up as a code problem.

Even with a clear spec, agents slip. In her review of spec-driven tools on martinfowler.com, Thoughtworks' Birgitta Böckeler saw an agent ignore notes about existing classes and regenerate them as duplicates. She also saw different output when generating code multiple times from the same spec.

“I frequently saw the agent ultimately not follow all the instructions.”

Böckeler also noted that most tools are spec-first, not spec-anchored. The spec guides one task, then gets left behind, and how it is maintained over time is often left vague. That gap is where drift lives.

Volume compounds the problem. Faros AI's 2026 AI Engineering Report tracked 22,000 developers and found code churn up 861% and incidents per PR up 242.7% for high AI adoption teams. More code built on unstable intent means more rework.

How do you fix spec drift?

You fix spec drift by treating the spec like code. It needs one home, a change process, and a history. Here are the seven practices that keep specs in sync with code.

• One source of truth in Git: Keep the spec in the same version control system as the code. Agents and people read from one place.
• Every change is a pull request: No edits in chat, no silent rewrites. A change is proposed, reviewed, and merged, or it does not count.
• Size limits on every change: Small changes get read, and long ones get skimmed. A word cap keeps each proposal reviewable in one sitting.
• A required reason: Every change states who it is for and why. That turns a spec edit into a decision someone can defend later.
• Timed review cycles: Short, focused review blocks beat marathon sessions. Reviewers catch more when they are fresh.
• Append-only history: Never overwrite who decided what. An audit trail answers "why does it work this way?" without a Slack search.
• Deprecate old copies: Delete or clearly mark every wiki page, prompt file, and deck that duplicates the spec. Point them all at the one source.

This is what people mean by a living specification. It changes as often as the product does, but every change is visible, sized, and explained. For more on writing the changes themselves, see our guide on how to write a PRD for AI coding agents.

Spec drift symptoms, causes, and fixes

What does a single source of truth for specs look like?

A single source of truth means there is exactly one place where the spec is allowed to change. Everything else either reads from it or gets retired. That includes prompt files, agent instructions, and the wiki.

It also means sizing each change for a human. A tidy repo is not enough if every pull request is 9,000 words, because reviewers will skim and approve. Small, explained changes are the ones people actually read.

Crema is one way to run this practice. Crema Spec keeps the spec in a GitHub monorepo, makes every revision a pull request, and caps each one at 2,000 words with a required who and why. If you want to start for free, Crema PRD is an MIT-licensed skill for writing specs and spec changes for AI coding agents.

This matters more as more of the company writes code. Our posts on software factories and AI-native companies where everyone codes show why the spec becomes the main control point. And if you are new to the approach, start with what spec-driven development is.

How do you stop spec drift this quarter?

You do not need a big migration to start. Work through these steps in order, one per week if you like.

1. Find every copy of your spec, including wikis, tickets, prompt files, decks, and agent instruction files.
2. Pick one home in Git and move the current, agreed version there.
3. Mark every other copy as deprecated and link it to the new home.
4. Point every agent's context at the one source, and remove pasted copies from prompts.
5. Require a pull request for every spec change, with a stated audience and reason.
6. Set a word limit for each change so a reviewer can read it in one sitting.
7. Log every merged change with who drafted it, who approved it, and why, and record bigger calls as decision records.

Run the signs checklist again in a month. If fewer people are quoting different specs, it is working.

If your team started with quick prototypes, read vibe coding vs. spec-driven development for a simple path from prototype to a governed spec.