Spec-driven development means you write down what to build, for whom and why before the agent writes code, and you keep that document current while it works. The spec is the source. Prompts, tickets and chat messages are copies of it. This guide covers what a spec needs, where its evidence comes from, and how to keep it alive after the first build.
What spec-driven development is
A coding agent will build whatever you describe, fast. The problem is what you leave out. A one-line prompt carries your intent but none of your constraints, none of your users and none of your history. The agent fills every gap with a default.
Spec-driven development fixes the order of work. First you write the spec: who the feature is for, why it matters, what must be true when it is done, and what you are not building. Then the agent plans from the spec and writes code. When something changes, you change the spec and hand it over again.
The practice is older than coding agents. Teams have written requirements for decades. What changed is the reader. A developer asks when a spec is unclear. An agent guesses, and guesses confidently. So the spec has to carry what a person would have asked about.
Three habits make it work:
- The spec lives outside the chat. A chat is a copy, and copies go stale.
- Every section says where it came from: a customer, a decision, a document, or "not recorded".
- Done is defined before the build starts, as criteria the agent can check.
Why the agent builds for a default user
Ask an agent for "a pay page" and it builds a pay page for the average web user it has seen most often. Desktop first. Standard font size. Every payment method it knows. Refunds, because pay pages usually have refunds.
None of that is wrong in general. It is wrong for your users. If your users are freelance designers who invoice from a phone, the agent needed to know that. If older clients pay those invoices, the agent needed to know about large text. If you decided refunds come later, the agent needed to know that too, or it builds them and you own the code.
Founders describe the result in the same words: "building the wrong thing faster". The agent is not at fault. It did what it was told and filled the rest with defaults. The spec is where you replace defaults with facts.
There is a second cost. An agent that does not know what already exists re-builds it, or breaks it. It "forgets your database schema" between sessions and "re-breaks what it fixed" last week. A spec that says what exists and what is already broken stops both.
What a spec needs
Seven sections. Each one answers a question the agent would otherwise answer with a default.
Who
The person the feature is for, in one line, with the device and any accessibility needs. "Solo freelance designers who invoice monthly. Phone first, also desktop. Large text for older clients." The agent reads this and makes a hundred small choices differently.
Why
The problem, in the users' words if you have them. "Freelancers chase late invoices by hand." One sentence is enough. It tells the agent what the feature is for, so when two implementations are possible it can pick the one that serves the problem.
Metric
What should move, and in which direction. "Median days-to-paid goes down." If you have no baseline, say so: "Target: establish baseline first." A metric with an invented number is worse than one with none, because the agent treats it as true.
Must-haves with acceptance criteria
The short list of things the feature must do, each with criteria someone can tick. "Given an unpaid invoice, the client can pay by card. The invoice then shows Paid." Criteria are the part of a spec that keeps the agent honest, because they are checkable. A story without criteria is a wish.
Out of scope
What you are not building, by name. "Refunds. Partial payments." This is the section founders skip and regret. Without it the agent builds what pay pages usually have, and you inherit the code.
Known issues
What is already broken in the area the feature touches. "The pay button does nothing on Safari (in progress)." The agent then works around the bug, or fixes it on purpose, instead of tripping over it or masking it.
Done when
The exit condition, written once. "Every story meets its criteria. The metric can be measured. Nothing in Out of scope was built." The agent stops here instead of continuing to improve things nobody asked for.
Two more sections help once your product has shape: what already exists in the codebase and what this work touches. They stop the re-breaking. More on them under keeping the spec current.
Where the evidence comes from
A spec is only as good as its sources. The Who and Why sections should come from people, not from you. Here is where founders get them.
- Feedback in their words. Support emails, app store reviews, form answers, messages in a shared channel. Keep the exact quote and where it came from. "I chase every invoice by hand" is evidence. "Users want faster payment" is your summary of evidence, which is weaker.
- Conversations. Transcripts of calls, with consent recorded. Only the other person's words count. Yours never do, because you were leading.
- Counts. How many people raised this, from which channels, over what period. "12 pieces of feedback: Email 9, App Store 3. 5 in the last 30 days." Counts are the only numbers that belong in a spec unless you have a measured baseline.
- Decisions. Why something is out of scope, and when you decided it. A decision with a reason survives the next loud request.
What never counts: compliments, public threads from people who are not your users, your own description of the problem, and anything a competitor says about their product. Show these if they help the agent understand context, but label them. The evidence ladder explains what moves a belief and what does not.
Keeping the spec current
The first build is the easy part. The spec earns its keep in weeks two through ten, when the codebase has changed and the agent has forgotten.
Treat the spec as the source, and copy again. Every time the spec changes, hand the agent the new version. Do not patch the old chat. If the agent has a way to pull the current spec itself, use it, so each session starts from today's version.
Record what already exists. After a few features, write down what the product does by area and how it is built: the main parts, the conventions, what never to do. Your coding agent can write this map itself, because it already reads your code. Then each spec can say "this extends the invoice page; it touches the payments service and the email templates" instead of leaving the agent to rediscover it.
Keep known issues live. Open bugs in the feature's area go in the spec; closed ones come out. An agent that knows the Safari button is broken does not ship a second broken button beside it.
Have the agent report back. When a build finishes, ask the agent for the files it changed, the stories it completed and what it left undone. Put that into the map. The next spec starts from the truth.
Check what changed before you publish. Read the commit titles since your last release. Ask whether anything new is public that should not be. This is a two-minute habit that catches most surprises.
A worked example
Below is a spec for one feature of Tallyhop, a made-up invoicing product for freelancers. It is sample data. The format is a Build Pack, which is one way to lay a spec out; the sections are the seven above plus evidence. Notice that every number is a count, and that the metric has no target yet.
# BUILD PACK · TAL-13 — Client pay page Status: Planned · PRD: Draft, edited 14 Oct ## WHY Freelancers chase late invoices by hand. *from the PRD (Draft, edited 14 Oct)* ## FOR Who: Solo freelance designers who invoice clients monthly. Device: phone first, also desktop Accessibility: large text for older clients ## METRIC Median days-to-paid goes down. Target: [TBD — establish baseline] ## MUST HAVE - Pay by card - Show what is owed ## STORIES - [ ] TAL-2 Pay an invoice by card - Given an unpaid invoice, the client can pay by card - The invoice shows Paid - [ ] TAL-3 See what is owed - The pay page shows the amount and due date - It works on a phone ## OUT OF SCOPE - Refunds - Partial payments ## KNOWN ISSUES - TAL-21 Pay button does nothing on Safari (In progress) ## EVIDENCE 12 linked signals: Email 9, App Store 3 · 5 in the last 30 days > "I chase every invoice by hand." — Email > "Clients never pay on time, a pay link would fix it." — App Store ## DONE WHEN - All stories meet their acceptance criteria. - The metric above can be measured. - Nothing in Out of scope was built.
Read it as the agent would. It knows the user is on a phone, so the layout starts there. It knows large text matters. It knows refunds are off the table, so it does not build them. It knows the Safari button is broken, so it tests on Safari. It knows what done means, so it stops.
Now read it as you would in a month. The evidence section tells you where the feature came from. If the metric moved, you know which quote to go back to. If it did not, you know who to ask.
The full sample, with the security checklist and the map sections, is on the sample Build Pack page. The format itself is documented in the Build Pack format guide.
Spec Kit, plan mode and related approaches
Several tools have moved in the same direction. Spec Kit is GitHub's open-source toolkit for spec-driven development: it gives a coding agent a specification, then a plan, then tasks, before any code is written. It is a good fit if you work in a repository and want the spec checked into it.
Claude Code, Cursor and Lovable each have a plan mode. The agent writes out what it intends to do before it changes anything, and you approve or edit the plan. Plan mode is the agent planning the how. It works best when the what and the why already exist, which is what the spec provides. Hand the agent the spec, then let it plan.
PMs call the same document a PRD. Builders call it a spec. Agents call it a plan. The names matter less than the habit: write it down first, from evidence, and keep it current. If you want the PRD version with a copyable template, read a PRD your coding agent can build from.
Related guides: The Build Pack format · The evidence ladder · Vibe coding without building the wrong thing
Do this in MindBacklog
The spec, written from your evidence and handed to the agent. Your coding agent pulls the Build Pack: why it matters, who it's for, the metric, and the must-haves with acceptance criteria. Every section of a Build Pack names its source, and the only numbers are counts. The Build Pack tells your coding agent what's already broken, not only what to build.
Copy it for Claude Code or Cursor, paste a short prompt into Lovable, or let your agent pull it over MCP. Ask your coding agent to map your product for MindBacklog. Every Build Pack then says what already exists, where the work fits and what it touches. Your coding agent writes the product map. MindBacklog never reads your code.
