Spec drift: your spec says one thing, the code another
The spec was right on the day you wrote it. Ten agent sessions later it describes a product you no longer have, and nobody can say which of the two is correct.
How we know
Quotes are verbatim from two public Hacker News threads: the March 2026 discussion of the Kotlin creator's spec language and the September 2026 OpenSpec launch thread. The script on this page was run on a test repository before publishing; it is plain Python with no dependencies. Product claims are what the code does: suspect requirements in models/links.py and api/routes/requirements.py, the status ladder in models/requirement.py. We have not measured how fast specs drift, in our projects or anyone else's, so there is no rate on this page.
What it looks like
- A requirement in the spec has no code behind it, and nobody remembers whether it was dropped on purpose or forgotten.
- The code does something no requirement asks for: a field, a rule, a fallback the agent added in one session and kept in every session after.
- A story was reworded last week, and the requirements written from the old wording were never looked at again.
- The agent starts a new session, reads the spec, and "fixes" code that was right, because the spec is the stale side.
Why it happens with coding agents
Drift is not new. Agents make it faster, for three reasons. Every session starts from zero, so the only memory of a decision is whatever was written down. The agent changes code in minutes, while the spec changes only when someone remembers to change it. And the spec is a document in the repository with nothing tying a sentence in it to the lines of code that implement it, so neither side notices when the other moves.
I found it works very well in once-off scenarios, but the specs often drift from the implementation. Even if you let the model update the spec at the end, the next few work items will make parts of it obsolete.
the_duke, Hacker News, March 2026
Asking the agent to update the spec at the end of every task helps for exactly one task. The next one edits code the spec describes, in a session that did not write that part of the spec, and the update it makes is to the part it was asked about.
In my experience, spec drift is the main reason why none of these tools work. Maybe they work for one shot greenfield feature generation but in a large, multi developer long lived code bases, specs rot and end up being more pain than they are worth.
twen_ty, Hacker News, September 2026
the real problem
A spec drifts when nothing connects a requirement to the code that implements it. Writing it down was never the hard part; noticing when one side moved is.
What helps, even without new tools
- Give every requirement a stable id, such as
REQ-12, and never reuse one. Without ids there is nothing to check. - Make the agent cite the id: in
CLAUDE.md,AGENTS.mdor Cursor rules, ask for the requirement id in the test name or a comment next to the code, and in the commit message. - Change the spec first. When a requirement changes, edit it in its own commit before the code, so the review sees the decision and not only its effect.
- Check the links in CI. The script below lists requirements nothing cites and ids the code cites that the spec no longer has, and fails the build on either.
- Review the spec against the code, not only the diff. One team on Hacker News does this with an AI review in every pull request, quoted below.
import os, re, subprocess, sys
# python3 spec_drift.py specs/ ["\bREQ-\d+\b"] (run from the repository root)
spec_dir = os.path.normpath(sys.argv[1]) + os.sep
ids = re.compile(sys.argv[2] if len(sys.argv) > 2 else r"\bREQ-\d+\b")
files = subprocess.run(["git", "ls-files", "-z"], capture_output=True,
text=True, check=True).stdout.split("\0")
in_spec, in_code = set(), set()
for path in filter(None, files):
try:
found = set(ids.findall(open(path, errors="ignore").read()))
except (IsADirectoryError, FileNotFoundError):
continue
(in_spec if path.startswith(spec_dir) else in_code).update(found)
for label, missing in (("in the spec, cited nowhere in code or tests", in_spec - in_code),
("cited in code or tests, gone from the spec", in_code - in_spec)):
for rid in sorted(missing):
print(f"{rid}: {label}")
sys.exit(1 if in_spec ^ in_code else 0)Run it from the repository root with the folder your spec lives in, for example python3 spec_drift.py specs/, and pass a second argument if your ids look different. A requirement cited nowhere is not always drift: it may simply not be built yet. That is still worth a line in the output, because it is the list a new session should see before it starts.
My team has an AI review that matches the existing specs against the current implementation. This is very useful and keeps both in sync. If there are any conflicts they are noted in the pull request review and can be fixed.
p_kuni, Hacker News, September 2026
These catch drift after it happened. What they cannot do is tell you which side is right: the id check knows a link is missing, not whether the code or the spec moved. For that you need to know what changed, when, and what was built on it.
How Entalpa handles it
Entalpa keeps the spec outside the repository as structured data: stakeholders, user stories and requirements with acceptance criteria, each with a stable id, and each requirement linked to the stories it came from. Your agent reads it over MCP at the start of a session instead of a markdown file that may be months old.
- Edit a story and every requirement written from it is marked suspect. Your agent can list the suspect requirements, then either rewrite them or confirm they still hold, which clears the flag without touching the wording.
- Agents write back what they built: each requirement moves along a status ladder from draft to implemented and verified, with code and test references, so the spec records where its requirements live in the code.
- Every change, yours or the agent's, lands in the project history. You can compare two versions of the spec and undo, so "which side moved" has an answer.
- Lock a requirement and Entalpa's AI never rewrites it to match the code. More on that on the page about agents changing requirements.
None of this stops drift by itself: if nobody records status, the spec cannot know what was built. What it changes is that the connection between a story, its requirements and the code is data the agent can read and update, not a convention it has to remember. Setup takes one command for Claude Code, Cursor, Codex and other agents.
Questions this raises
What is spec drift?
Spec drift is the specification and the code growing apart over time: requirements nobody implemented or removed on purpose, and code doing things no requirement asks for. With AI coding agents it happens faster, because code changes in minutes and the spec only when someone remembers to update it.
How do I detect spec drift?
Give each requirement a stable id, have the agent cite it in tests and code, and run a check in CI that lists ids the spec has and the code never cites, and ids the code cites that the spec no longer has. An AI review that compares the spec against the implementation in every pull request catches the drift a missing id does not show.
Should the agent update the spec after every task?
It helps, but it does not hold. The agent updates the part of the spec it was asked about, and the next task changes code that other parts of the spec describe. Change the spec first, in its own commit, and check the links between requirements and code automatically.
Is spec drift the same as an agent changing the requirements?
Related, not the same. Drift is the two sides slowly growing apart. An agent changing the requirements is the spec being bent to match the code, in one edit. The cure for both is one source of truth the agent reads, cites and reports back to, but does not own.
Entalpa gives your agent one locked source of truth
Structured, traceable requirements your agent reads over MCP — so it works from a curated spec instead of reconstructing your project every session. Free to start, no card, and reading or writing your project over MCP never spends credits.