The spec is the artifact of record now
For thirty years the code was the only document guaranteed to be true. That guarantee rested on a fact that no longer holds, which is that a person decided every line of it and could tell you why.
“The code is the documentation” was never really an argument about documentation. It was an argument about trust. Documents drift and code cannot, because the code is what runs. If you want to know what the system does, read the thing that does it.
That was correct, and I defended it for years. It rested on an assumption that has quietly stopped being true: that behind every line there was a person who chose it, and that person or their colleague could reconstruct why.
My position is that the spec has replaced the code as the artifact of record. Not as the description of behaviour, the code still wins that outright. As the record of intent, which is a different question and now the harder one.
The code tells you what, and has never told you why
Read a function that retries three times with exponential backoff and a 30 second cap. The code tells you exactly that. It does not tell you whether 30 seconds was chosen because the upstream provider’s documented timeout is 28, or because someone picked a round number on a Friday.
Those two situations demand opposite behaviour from the next person to touch it. In the first, changing it breaks a contract. In the second, changing it is free. The code is identical either way.
We survived this gap because the why lived in people. You asked. Somebody remembered, or remembered who to ask, or found the pull request where it was argued out.
With roughly 41 percent of production code AI-generated by early 2026, that recovery path degrades in a specific way. The person who merged it can tell you it looked reasonable and the tests passed. They cannot tell you why 30 and not 45, because they did not choose 30. Nobody chose 30. It was produced, reviewed for plausibility, and accepted.
Artifact of record is a real status with real obligations
I am not using the phrase loosely. In any discipline that has one, an artifact of record carries four obligations, and applying them to specs is the whole practical content of this argument.
It is versioned. Not overwritten. You can see what the criteria said at the moment the work was accepted, not just what they say now. A spec you can silently edit after the fact records nothing.
It is reviewed. Somebody other than the author read it before it became binding. We do this for diffs without question and almost never for the criteria that produced them, which is backwards once the criteria are the human contribution.
It is retained. For a defined period, deliberately, rather than living in a ticket that a tracker migration will flatten in two years.
It is linked to the thing it governs. A spec floating in a wiki is not a record. A spec bound to the change that implemented it is.
Most organisations have none of the four for acceptance criteria, while having all four for code. That asymmetry was defensible when the code carried the intent. It is not defensible now.
The regulatory direction points the same way, and I want to be careful here
EU AI Act enforcement began on 2 August 2026. Article 12 requires automatic logging of events relevant to risk and traceability, tamper-evident, retained for six months, or twenty-four for biometric and law-enforcement uses. Transparency obligations require AI systems to disclose themselves and generated content to be marked.
I want to be precise about what that does and does not mean for a delivery team. It is aimed at AI systems being placed on the market, not at your internal use of an assistant to write a CRUD endpoint. No tool makes an organisation compliant with it, and anyone telling you otherwise is selling something.
What it does tell you is the direction of travel of the question being asked. The question is: for this behaviour, can you show what was intended, what was produced, and that the record has not been quietly rewritten? That is an intent-provenance question, and an organisation that keeps specs as records can answer it while one that keeps them as pre-work cannot.
There is a notable gap worth sitting with. Native provenance attribution exists for generated images. There is no documented equivalent for generated code. The thing most likely to end up in a regulated system has the weaker provenance story.
Spec as pre-work
- Written to unblock the build
- Edited freely afterwards, no history
- Nobody reviews it
- Lives in a ticket, dies in a migration
- Answering "why" means finding a person
Spec as artifact of record
- Written to bind the outcome
- Versioned, with the state at acceptance preserved
- Reviewed before it becomes binding
- Retained deliberately, linked to the change
- Answering "why" means reading the record
Where this breaks down
Specs lie and code cannot. This is the strongest objection and I do not have a full answer. A spec can say the retry cap is 30 seconds while the code says 45, and the code is the one that runs. Elevating specs risks recreating exactly the wiki-full-of-lies problem that “the code is the documentation” was invented to escape. The only mitigation I trust is that the spec must be checked against the diff mechanically, so drift surfaces rather than accumulating. An unchecked spec is worse than no spec, because it is believed.
Most code does not deserve a record. A logging tweak, a copy change, a dependency bump: attaching an artifact of record to these is pure overhead, and a practice applied uniformly gets hollowed out fast. The judgement about which changes carry intent worth preserving is itself work, and getting it wrong in either direction is costly.
Intent capture may be automatable. If tooling can reconstruct rationale from the conversation that produced a change, the case for a separate human-authored artifact weakens considerably. I am sceptical, because the conversation records what was said and not what was ruled out silently, but I would not bet heavily against it.
The four obligations have a real price. Versioned, reviewed, retained, linked: that is a meaningful process load, and it lands on whoever writes criteria, who is usually already the constraint. The benefit lands on someone else, months later. That is the same incentive problem that kills every good documentation practice, and naming it does not solve it.
“Artifact of record” can become theatre. The moment it becomes a compliance checkbox, it will be satisfied by a template with fourteen fields filled in with the word “standard”. A record nobody reads is not a record, it is a filing cabinet.
The takeaway
The code remains the only trustworthy answer to what the system does. It was never the answer to why, and we papered over that with human memory. That memory got thinner as authorship shifted, and the specification is the only artifact positioned to carry the weight.
Treating it as an artifact of record means four concrete things: version it, review it, retain it, link it. It also means checking it against the diff, because a spec that is not checked will drift and be believed anyway.
If you take one thing into next week: open the oldest ticket behind a piece of code you are currently afraid to change, and see whether it tells you why. If it does not, you have already found the gap, and the next ticket you write is where you start closing it.