Why do specifications go out of date so quickly?

Because nothing breaks when they are wrong. Code forces a fix, since it stops working when it disagrees with reality, while a document can contradict the running system for months without anyone noticing, so the growing gap is invisible until a new person builds something based on a page that has been wrong since spring.

How do you make a spec that stays accurate?

Make the part that matters executable, so disagreement between the document and the system shows up as a failing build rather than a discovery. Then require the spec to change in the same pull request as the code it describes, since any process that puts the update afterwards is a process where the update never happens.

What does it mean to make a spec executable?

It means the rules the software must guarantee are written as automated checks derived from the specification rather than from the implementation. When behaviour changes without the rule changing, the check fails, which converts the invisible problem of documentation slowly becoming wrong into a visible problem that blocks a merge.

Why should tests be written from the spec rather than the code?

Because a suite generated by reading the implementation asserts that the code does what it does, passes automatically because of how it was made, and proves nothing while showing every test as passing. Checks derived from the specification can disagree with the implementation, and that ability to disagree is the entire value of having them.

What should a spec contain that most specs leave out?

The decisions that were rejected and why. Recording that partial refunds are unsupported because reconciliation would have to change stays useful for years, while a bare statement that the system supports refunds tells a future reader nothing about the boundary or the reasoning behind it.

How long should a specification be?

Short enough that all of it is current. Forty pages where eight are accurate is worse than eight accurate pages, because a reader cannot tell which is which and eventually stops trusting the whole document, so deleting out-of-date sections is a maintenance activity rather than a loss.

Who should own keeping the spec current?

The person making the change, in the same change, rather than a separate task afterwards. Assigning ownership to a single documentation owner creates a queue and a slow step, and it separates the knowledge from the person who has it at the exact moment they have it.

Does a spec matter more when AI writes the code?

Yes, because it becomes the only artifact stating what the software is supposed to do as distinct from what it happens to do. When a model produced the implementation there is no author who knows the reasoning, so a reviewer with no specification is left working out the requirement backwards from the code they are meant to be checking.

What is the difference between a spec and documentation?

A spec states what the software must guarantee and is written before or independently of the implementation, while documentation describes how the current system behaves. Both are useful, and only the first can be used to judge whether the implementation is correct.

What is a specification decision log?

A short running record of what was decided, when, and what was ruled out, kept next to the spec rather than in a chat thread. It answers the question that costs the most time later, which is why the system works this way, and it prevents a future team from arguing again about a decision whose reasoning was never recorded.

How do you know whether a spec is still trusted?

Watch whether engineers check it before making a change or ask a colleague instead. When people skip the document and go to a person, the document has already failed, and the useful response is to find out which sections were wrong the last time somebody trusted them.

How to keep a spec alive after the build: Reveneau

Q: How do you fix a spec that is already out of date?

Do not rewrite the whole thing. Take the highest-risk area, verify what the system actually does today, write that down with the date, add automated checks for those rules, and delete everything else that nobody can confirm. A small current document is more useful than a large uncertain one.

Every specification we have ever seen is accurate on exactly one day: the day it is approved. By the end of the quarter it has become a historical document that new joiners read, half-believe, and then quietly stop consulting once they discover the third thing in it that is no longer true.

The usual explanation is discipline. Nobody updated the doc. That is accurate as a description and useless as a diagnosis, because it suggests the fix is reminding people, and reminding people has never worked at any company anywhere.

The real cause is simpler. Nothing breaks when the spec is wrong.

Code forces you to fix it. It stops working, loudly, in front of customers. A document has no such property. It can contradict the running system for six months and the only cost is paid later, by somebody who was not involved, in the form of a feature based on a paragraph that stopped being true in March.

This matters more than it used to. When a model writes the implementation, the spec is the only artifact that says what the software is supposed to do, as opposed to what it happens to do. Without it, the only definition of what the system should do is whatever it does today.

Four things keep a spec alive, meaning accurate and trusted after the build.

1. Make the part that matters executable

The single most valuable step is to stop relying on anyone reading the document.

Take the rules the software must actually guarantee: who can see what, what happens when a payment fails halfway, what must never be deleted, which fields are required at which stage. Write those as automated checks, derived from the specification rather than from the implementation.

Now disagreement between the document and the system is a failing build instead of a discovery. The invisible problem became a visible one, which is the whole point.

The direction of derivation is the part people get wrong, and it is worth being blunt about. A test suite generated by reading the code asserts that the code does what it does. It passes automatically, because of how it was made. It proves nothing and it shows every test passing, which makes it worse than having no suite at all. Checks written from the spec have the ability to disagree with the implementation, and that ability is the whole reason they exist. The method is set out in writing specs an agent can verify.

Not everything can be made executable. "The onboarding flow should feel calm" is a real requirement and no check can test it. Fine. Executable checks cover the rules with consequences, and prose covers the rest, and knowing which is which is most of the skill.

2. Change the spec in the same pull request as the code

Not afterwards. Afterwards means never, and everybody in the process knows it means never.

If a change alters what the software guarantees, the change that alters the guarantee also alters the sentence describing it. Same commit, same review, same approval. It costs a couple of minutes while the reasoning is still in the author's head, which is the only moment it is cheap.

This works because it puts the update into the code review, which already forces people to look. A reviewer looking at a behaviour change with no corresponding spec change has an obvious question to ask, and asking it takes one comment.

The predictable objection is that it slows things down. It slows the individual change by minutes and saves weeks of confusion over the quarter, and we would rather argue about that trade than about why the document is wrong again.

3. Delete more than you add

A forty-page spec where eight pages are current is strictly worse than an eight-page spec, because no reader can tell which eight.

That is how documents stop being trusted. Not one wrong statement. The impossibility of knowing which statements to trust, at which point a rational reader stops trusting all of them and asks a colleague instead.

So treat deletion as maintenance. If a section describes a feature that no longer exists, remove it. If nobody can confirm whether a paragraph is still true, remove it and note that it was removed. A shorter document that is entirely current is a working tool. A long one full of uncertainty is an archive that nobody has admitted is an archive.

The sign to watch: when engineers check the spec before making a change, it is still trusted. When they message a colleague instead, it has already failed, and the useful follow-up is to find out which part was wrong the last time somebody trusted it.

4. Record what you decided against

This is the section most specs are missing, and it is the one that saves the most time later.

"The system supports refunds" tells a future reader almost nothing. "We support full refunds and not partial ones, because partial refunds would require the reconciliation process to change and we chose to defer that" tells them the boundary, the reason, and the condition under which the decision should be revisited.

Records of rejected options stay useful longer than records of chosen ones. The chosen option is visible in the code. The rejected option exists nowhere except in the memory of people who may have left, and its absence is why teams argue again about the same decision every eighteen months, usually reaching the same conclusion after a fortnight of discussion.

Keep it as a short running log next to the spec: what was decided, when, what was ruled out. Three lines per entry. The characteristics of a document that does this well are in what a good technical spec looks like.

Why this got more important, specifically

Two reasons, both practical.

The first is that a reviewer with no specification is doing an impossible job. When a model produced the diff, there is no author who knows the reasoning, so the reviewer has to work out the requirement backwards from the implementation they are supposed to be checking. That reverses the purpose of the review. A current spec is what makes review a comparison rather than a guess, and the wider version of that argument is in how to review AI-generated code.

The second is trust in the output. Stack Overflow's 2025 developer survey found 46 percent of developers actively distrust the accuracy of AI tools against 33 percent who trust them, and 66 percent naming "almost right, but not quite" as their biggest frustration. Almost-right is precisely the category a specification catches and a reviewer's intuition does not. Code that is subtly wrong looks fine. Code that is subtly wrong against a written requirement is visibly wrong.

Fixing one that is already out of date

Do not rewrite it. Rewriting an out-of-date forty-page spec is a month of work that produces a document which will be out of date again by Christmas.

Take the highest-risk area instead: whatever moves money, handles permissions, or writes customer data. Verify what the system actually does there today, by reading the code and checking the behaviour rather than by asking. Write that down, with the date. Add automated checks for those rules. Then delete everything nobody can confirm.

You will end up with a much smaller document that is true, which is a starting point. Everything you deleted was already not helping. The approach to adding verification to a system that has none is covered in adding evals to an existing codebase.

What we do on our own builds

The spec is written before the code and is the source the checks are derived from. It changes in the same pull request as the behaviour it describes. It carries a decision log with the rejected options. And it is deliberately short, because a document that is read is worth more than a document that is complete.

None of that requires anyone to be diligent on a Thursday afternoon, which is the point. Processes that need sustained goodwill fail at the first busy week.

Thanks to the teams who let us read the specs that nobody had updated, and were honest about when they had stopped believing them. The answer was usually about four months, and nobody had marked the day.

A specification is the standard you check the build against. On the day it can no longer disagree with the code, it has stopped being a specification.

Related guide: Writing software requirements.

Sources

Stack Overflow 2025 Developer Survey, AI section: 46 percent of developers actively distrust the accuracy of AI tools against 33 percent who trust them; 66 percent name "almost right, but not quite" as their biggest frustration.

How to keep a spec alive after the build