Spec Drift

Spec drift is the silent killer of AI projects. When the written specification and the actual code quietly drift apart, every downstream decision — testing, debugging, adding features, handing off to another team — becomes guesswork. By mastering this concept, you will be able to detect drift early, understand why it happens, and know how to keep your documentation honest. This unlocks the next stage of your learning: Requirements Traceability, where you will learn to build the links that make drift impossible to hide. From there, you will move on to Acceptance Criteria and Review Gates, turning 'is the code right?' from a feeling into a testable, checkable process.

Imagine you are following a recipe to bake a cake. The recipe says 'add 200g of flour, then 2 eggs, then bake for 30 minutes.' But halfway through, you decide to add an extra egg because the mixture looks dry. Then you bake it for 40 minutes because the oven seems slow. The cake turns out fine — but if you bake it again next week, you will follow the recipe exactly as written, not as you actually made it. The second cake might be dry or too eggy. The recipe no longer describes what you actually do. That is spec drift: the written document (the recipe) and the actual implementation (your baking) slowly diverge. Each small deviation feels harmless — an extra egg, a few extra minutes — but together they mean the document has stopped telling the truth. And the danger is that everyone trusts the document. If someone new reads the recipe, they will follow it exactly, and get a different result than you did. In software, spec drift is the same: a requirement states 'the search should return results in under 2 seconds.' The developer optimises one query, but then adds a feature that makes it 3 seconds. Then another developer, seeing the spec, assumes 2 seconds is still the target and spends days debugging a problem that no longer exists. The document is trusted, but it is wrong. Drift is invisible because nothing crashes — the system still works, just differently than specified. The tragedy is that by the time you notice, the gap is so large that fixing it means rewriting either the code or the spec, and both are expensive. In AI systems, where models are retrained, prompts are tweaked, and data pipelines change constantly, drift happens even faster. A prompt that says 'classify this email as spam or not spam' might drift as the model is fine-tuned, or as the data distribution shifts. The spec says one thing; the system does another. The longer you ignore the gap, the harder it is to close. The fix is not to avoid all change — change is inevitable and often good — but to make drift detectable. You need a way to compare the spec against the implementation regularly, like checking the recipe against the cake you actually made.

Think of a city's official map and its actual streets. The map is the specification — it describes the roads, their names, their one-way directions. When the city builds a new road, or changes a street to one-way, someone updates the map. But if the map is not updated, a driver following it will hit a dead end, or drive the wrong way down a one-way street. Now, the map is not just unhelpful — it is dangerous, because the driver trusts it. Spec drift is the gap between the map and the streets. At first, the difference is tiny: a new roundabout, a renamed street. Nobody notices because the old road still exists, just slightly differently. But then the city builds a bypass, and the old road becomes a cul-de-sac. The map still shows it as a through-road, and a driver following the map ends up stuck. The cost of a wrong map is not just one wrong turn — it is every driver who trusts it, and every journey that is planned around it. The same happens in software. A specification says 'the login endpoint accepts email and password.' The developer changes it to accept a token instead, but does not update the spec. Now every test, every review, every new developer reading the spec is planning around the old design. The system works, but the map is wrong. Where does the analogy break down? In a city, the map is a physical object that exists separately from the streets. If it is wrong, you can throw it away and draw a new one. In software, the specification and the code are intertwined — the code is the implementation of the spec, and the spec is the explanation of the code. Correcting a wrong map is easy; correcting a wrong spec requires deciding which one is the source of truth, and that is a hard, political decision. Also, in a city, streets change slowly. In software, the code changes every day, every commit. Drift is not a rare event — it is the default. The map is always slightly out of date. That is why you need a process, not just goodwill, to keep them aligned.

Spec drift is the gradual, often unnoticed divergence between a written specification and the actual implemented system, so that the document stops accurately describing what the code does.

You have not studied anything yet, so this is your starting point. But know that spec drift is the reason the entire practice of Spec-Driven Development exists. The spec-to-code pipeline, acceptance criteria, and review gates are all defensive measures against drift. When you get to Requirements Traceability, you will learn the tool that makes drift visible: a traceability matrix that links each requirement to the tasks, tests, and code that implement it. That is the practical answer to the problem this concept describes. For now, understand the disease before you learn the cure.