How to write a spec a coding agent can build from
A prompt describes what you want. A spec describes what done means. The ten sections that make the difference, and what each one is for when the reader is a machine.
Checked against the tools’ own documentation on .
A prompt describes what you want. A spec describes what done means. The gap between those two sentences is most of the frustration people have with coding agents.
An agent given a paragraph will build something. It will also make several dozen decisions you never saw, because a paragraph cannot answer them and the work cannot proceed until something does. Three sessions later you are arguing with your own tool about a choice neither of you remembers making.
A spec is not ceremony. It is the set of answers written down once, in a place the agent reads every time, so it stops guessing and you stop re-deciding.
What makes a spec machine-readable
Three properties, and none of them is about formatting:
- Every claim is checkable. “Fast” is not a requirement; “p95 under 400 ms on a 4G connection” is. An agent cannot test itself against an adjective.
- The boundaries are explicit. What the thing does not do has to be written down, because the space of features nobody forbade is infinite.
- The assumptions are labelled as assumptions. A spec that quietly presents a guess as a requirement is worse than one with a gap in it: you can argue with a gap.
The ten sections
This is the shape this product writes, and the order matters less than the fact that each section answers a question the agent would otherwise answer for you.
1. Summary
What is being built, in a few sentences, including the scope of the first version. This is the section the agent re-reads when it has drifted.
2. Problem & target user
Who this is for and what is wrong today. It is what lets an agent choose between two defensible implementations — the one that suits the user you named usually wins.
3. Goals & success metrics
Not aspirations. Numbers, with the terms defined well enough to measure. “80% of sessions complete without a download” is only a metric once you have said what a session is, when it starts, when it ends, and what you are excluding.
4. Non-goals
The section nobody writes and the one that pays for itself fastest. It getsits own page.
5. Features
Each with acceptance criteria: a sentence per feature that can be answered yes or no. “The user can search within a document” is a feature. “Searching a 300-page PDF returns results in under 1.5 seconds” is a criterion. Without the second one, “done” is a matter of opinion.
6. Tech stack & deployment
The choices already made, and the constraints those choices carry. An agent that knows it is on a serverless runtime will not reach for the filesystem. One that does not will, and you will find out in a deploy log.
7. Data model
The entities and what they hold. Also — importantly — what is not stored. “Never document bytes, only metadata” is a data-model line that prevents a whole category of wrong implementation.
8. Decisions & constraints
The settled arguments, so they stay settled. This is where the assumptions live too, marked as such. An agent that hits an ambiguity should be able to look here and find either an answer or an admission that there is not one.
9. Phases
What is in the first version and what is deliberately later. Without it, an agent building phase one will helpfully lay foundations for phase three, and phase three will turn out to be a different shape.
10. Instructions for the AI coding agent
The meta-section: what to check before starting, what never to change without asking, and how to tell whether a change is correct. This is where you write “stop and report the ambiguity with both options and their cost — do not resolve it by adding a feature.”
Where the spec goes
A file in the repository, committed, referenced from your context file. Not a ticket, not a Notion page, not a message in a thread — the agent reads the repository, and a spec it cannot open is a spec that does not exist.
Keep it separate from CLAUDE.md or AGENTS.md. Those hold conventions that are true in every session forever; a spec describes a scope that changes as the project moves.Which file does what covers the distinction.
The part people skip
Writing one of these by hand takes an afternoon, which is why most projects do not have one — and why the afternoon feels like a bad trade against just prompting and seeing what happens.
It is a good trade. But you do not have to make it from a blank page: the material you already have — the notes, the voice memo, the paragraph you typed at midnight — contains most of the answers, and what it does not contain is a short list of questions rather than a document.