Write the spec last: spec-driven development from a working prototype
Spec-driven development works better in reverse. We build the prototype in Claude Code first, then write the spec from what survived client review.
A few weeks ago we handed a client's engineering team the spec for a product area we'd reimagined from scratch. Eight short documents, 14 screenshots, and a skill file their coding agents load before they touch the code. None of it existed when we started. We wrote it last.
That's backwards from how spec-driven development is usually pitched. Tools like GitHub's Spec Kit and Amazon's Kiro start with the spec: requirements, then a design, then tasks, then an agent like Claude Code builds from it. The spec is the source of truth, and the agent follows it instead of guessing.
The agent part is right. The order is where it breaks.
What spec-driven development gets right
Agents need something written down. Give Claude Code a vague prompt for a whole product area and you get a screen that demos well and that nobody can explain a month later. Every choice in it was a guess, and nothing records which guesses anyone agreed to.
A spec fixes that, as long as the spec holds decisions. A spec written before anyone has clicked anything mostly holds guesses, in a confident format. The agent can't tell the difference, so it builds the guess as faithfully as it would build a decision.
What a prototype finds that a spec can't
On this project the first version had a drill-down page. It looked right on paper: the obvious way to organize the information. It was gone by the end of the same day, once we saw that the people using the screen act on one item at a time, not on groups. A spec written up front would have specified that page, and an agent would have built it.
One column in the main table changed shape several times in a single week. Each version answered the client's question a little better and exposed the next problem. You can't write the spec for that column in advance. You find it by building the wrong versions and watching someone use them.
The whole reimagining took a few weeks from first commit to handoff. The client reviewed the live prototype every few days, and most of the spec came out of those sessions: 25 decisions, each with the reason behind it.
How we do spec-driven development with Claude Code
In construction, the drawings that matter at handover are the as-builts: the set marked up to show what was actually built, not what was drawn before the first wall went up. Our spec is an as-built.
We build the prototype in Claude Code, in a real browser, and the client pushes back on the live page (here's how that works). When the area settles, the spec gets written from the prototype:
What | Why it's there |
|---|---|
README and skill file | The skill goes into the engineering team's |
Eight reference documents | Information architecture, flows, the filters and table rules, the data contract, the decisions log, an acceptance checklist and a map of the prototype code. |
14 screenshots | The key states, taken from the prototype. |
44 acceptance checks | So each build phase can be tested against something concrete. |
7 invariants | Numbers that must agree everywhere they appear. A count on a button has to match the count in the list it opens. |
The decisions log carries the most weight. 14 of the 25 decisions include what we tried and removed. That column exists so a dropped idea doesn't come back in sprint three because the new person on the team thinks of it. Here’s our decision log template.
The client's engineers are building from the package now. Their agents work from what the client already argued over, instead of from what we guessed in week one.
Where it breaks: the parts nobody decided
Prototype-first has one weak spot, and spec-first has the same one. When the client isn't sure about an area, or doesn't have the answers yet, that area stays vague. Then one of two things happens. The agent quietly avoids it, or it fills the gap with something plausible that nobody asked for. A small hallucination built into a working screen looks a lot like a decision.
Discernment is the enemy of model hallucinations. Someone on the team has to notice the vague parts and say so out loud. In our package they're written down as questions, not answers: 16 of them, listed where the engineers will see them. The skill file tells the agent plainly: when something isn't covered, ask; don't invent a pattern.
Spec-driven development is right that agents need a spec. Write it from what survived.