Specs drift because the real decisions leave the document. A spec is written once, and then the work happens somewhere else: a Slack thread, a call, a review comment, a fix an agent made overnight. Almost none of it travels back, because updating a static file always loses to the next task. So the spec slips out of date a little at a time until it describes a plan that no longer exists.
A spec starts life accurate. It is written at the one moment when someone has the whole plan in their head, and on that day it matches what everyone intends to build. Then the build begins, and the plan stops being a plan and becomes a series of small decisions made under pressure. Each of those decisions lands in the code. Very few of them land back in the spec. Nobody decides to let the document rot. It rots because keeping it true is continuous work that competes with shipping, and shipping wins every time.
What is spec drift?
Spec drift is the widening gap between what a spec says and what the system actually does. The document on file describes one product; the running code is a different one. The two were identical the day the spec was written, and they have been separating ever since, quietly, without any single event that marks the moment they came apart.
It goes by a few names. Documentation drift, documentation rot, spec rot: all of them point at the same thing, a written artefact that was true once and is trusted as if it still is. The danger is not that the spec is wrong. The danger is that it still looks authoritative. It is well formatted, it sounds confident, and it is read by the next person as the current state of the system when it is actually a photograph of an intention from weeks ago.
What causes specs to drift from the code?
The single cause underneath all the others is that the decisions move and the document does not. Trace where the work actually gets decided and almost none of it is in the spec:
- A constraint shows up in the data that nobody knew about at planning time, and the build quietly routes around it.
- A design changes in a call, and the new shape lives in three people's memory and a Slack message.
- A reviewer asks for something different, it gets done, and the comment thread is the only record.
- An agent takes a shortcut overnight, ships something that runs, and no human even saw the divergence happen.
Each of these is a correct, sensible decision. The problem is purely that the spec is not where they land. Updating the document is more effort than the moment allows, so it is deferred, and deferred again, and the backlog of un-recorded decisions becomes the drift.
Why doesn't keeping the spec updated work?
Because it is invisible work that has to be done forever, by hand, against the pull of everything more urgent. Writing the feature is visible and rewarded. Going back to reconcile the document afterwards is neither, so it is the first thing dropped on a busy day, and most days are busy.
There is also a quieter reason. Even someone willing to do the work often cannot, because they do not have the full list of what changed. The decisions were scattered across tools and conversations, and no single person saw all of them. Reconciling the spec would mean reconstructing a week of small choices from memory, so starting the next spec fresh feels easier than repairing the last one. The document is abandoned not out of laziness but because catching it up has become genuinely hard.
Does AI make spec drift worse?
Considerably. An agent executes faster than any human reviewer can track, and it makes more decisions per hour, each one a potential divergence that no one approved. The faster the agent, the more ground it covers between the points where a person might have noticed the document and the build pulling apart. Speed that should be an advantage turns into drift accumulating quicker than anyone can read it.
It compounds in the other direction too. When the spec is already stale, the agent reads a document that no longer matches the system and builds against the wrong picture, widening the gap it was supposed to close. A drifted spec does not just fail to help the agent. It actively misleads it.
What does spec drift cost?
The cost is delayed, which is what makes it expensive. Nothing breaks at the moment of drift. The code runs, the feature ships, and the gap sits there silently until someone relies on the document and is wrong. Usually that someone is the next person in, reading the spec to understand the system and unable to tell which parts are still true and which were overridden weeks ago. They make a decision on a false picture, and the cost of the drift finally lands, far from where it was created.
This is the wall the builders we work with keep hitting. The strongest of them write genuinely good specs and still watch them rot, because the document was never connected to the work it described. It could only ever record a plan, never track a build, and a record that cannot keep up with reality stops being a record at all. The spec is right on the day it is written and a little more wrong every day after, and nothing in a static file was ever going to change that.
| As the build moves | A spec in a doc (Obsidian, Notion, Confluence, Word) | A Canery spec |
|---|---|---|
| Stays current as decisions move? | It falls behind | Yes |
| Records what got built differently, and why? | The gap lives in memory | Yes |
| Can be trusted by the next person in? | Looks current, often isn't | Yes |
| Tells you when plan and build separate? | You find out later | It surfaces |
A spec only stops drifting when it is connected to the work instead of sitting beside it. Canery is built for that. It holds the spec against the codebase it describes, the work as it changes, and the team building from it, so a divergence is recorded as it happens rather than discovered weeks later, and the spec stays an honest account of both what was intended and what was actually built. The document stops being a snapshot that ages and becomes the thing the build is held to as it moves.
If this is how you want to work
If you want a spec that stays true as the build moves, records what actually shipped, and surfaces a divergence the moment it happens instead of weeks later, Canery is being built for exactly that. Join the waitlist at canery.ai and be among the first to use it.