What if your specs were the best code you ever write? Not the code the AI generates. The spec that describes it.
That’s the question I opened with at my workshop at Agile Tour Strasbourg on 29 May 2026. In this article I’ll explain why I think the specification matters more now than it did two years ago, and when it’s worth the effort. If you want the commands instead of the reasoning, I wrote a command-by-command walkthrough of Spec Kit.
What changed
This is the part people move past too quickly, and it’s the whole argument.
Before, we wrote few specs and a lot of code. That worked, because writing code was slow. The slowness gave us time to notice when we were building the wrong thing. We didn’t like that friction, but it was protecting us.
Today the AI writes the code in seconds. The friction is gone, and the protection is gone with it. The specification is now the slow part of the process.
That’s also why it’s the most useful place to spend your time. It’s the only step left where thinking carefully still changes the result.
Three symptoms
Before talking about tools, let’s talk about the problem. Here are three signs that this is already happening on your project.
The avalanche. The AI produces code faster than anyone can read it or test it. Your code review stops being a real check. You start approving volume instead of decisions.
The amnesia. The why disappears. What’s left is code that works and that nobody can explain. You can read every line and still not know which requirement it was answering. And if you don’t know that, you can’t change it safely.
The drift. Each feature moves a little further from the original intention. No single step is wrong. Three months later the project is somewhere nobody decided to go, and you can’t point to one commit and say this is where it went wrong.
None of these is really a problem with AI. They happen when the only thing your process keeps is the output.
What makes a good spec
“Write a spec” is not useful advice on its own. We’ve all seen the wiki page that nobody opened twice. So here are the four properties I ask for. If a spec is missing one of them, it won’t work with an agent.
Explicit. A clear intention, constraints that are written down, nothing left to interpretation. If you expect the reader to guess the obvious parts, the agent will guess differently.
Verifiable. You can write a test from it. If you can’t, it’s too vague. This is the fastest check I know, and it takes ten seconds.
Living. It changes with the product. It’s not a document you write once and leave at the top of a wiki.
Executable. An agent must be able to read it and decide what to code. This is the real test, and it’s new. Before, we judged a spec on whether a human could understand it. Now we judge it on whether a machine can act on it, and a machine is a much stricter reader.
That last property changes the other three. A spec that nobody reads can stay vague for years. A spec that something executes cannot, because you find out quickly: you get the wrong code.
The spec becomes the source
Here is the shift, in one sentence: the specification becomes the source, and the code becomes the translation.
That sounds like a slogan, but look at what it does to a file. For years we treated specifications as documents written for other people. They went out of date as soon as development started, and nobody read them again. When your agent works from the spec, that changes. The spec has to be precise, because something uses it. It has to stay current, because the next feature is built on top of it. An old spec produces wrong code, and you see it immediately.
Documentation goes out of date when nothing depends on it. This kind can’t.
Spec Kit is the open source toolkit from GitHub for working this way. It’s a CLI plus a process your agent follows, where each step produces a Markdown file that you review before the next step. It’s the tool I demonstrated, but the tool is not the point. The point is which file you treat as the source.
When it’s worth it
I’m not going to tell you this makes AI agents reliable. It doesn’t. And for some tasks all these steps are simply too much, so let me be clear about where I draw the line.
It’s worth it for a new feature with real business rules, for rewriting a complex module, for a project that several developers will work on, and for a domain where the why is important.
It’s not worth it for a fifty-line script you’ll throw away, for a small isolated bug fix, for a proof of concept you’ll delete next week, or for anything purely cosmetic. For those, write the code. Spending forty minutes on a spec for a script you’ll run once is a waste of time.
The rule I gave during the workshop is the one thing I’d keep: if someone will have to understand this code in three months, the spec is worth the effort.
What really changes
If you remove the tooling, three things change.
You stop writing code and start writing intention. The code becomes a result, not the goal.
You stop writing prompts and start writing specifications. No more one-off prompt, and no more arguing with an agent that doesn’t remember what you agreed five minutes ago.
You stop reviewing code and start making decisions. That’s where craft belongs. Reading a paragraph of Markdown takes a few minutes. Reading a wrong implementation takes an afternoon.
In six months, a developer joining your project should be able to read the spec and understand why the code looks like this. Not only how.
The code is generated. The thinking is written down. And the AI works better when it knows what it’s working for.
