- Spec driven development means writing a structured description of the feature before the agent writes code, then generating a plan and a task list from that description rather than from a chat message.
- GitHub's Spec Kit runs four phases: Specify, Plan, Tasks, Implement. Only the first is about the user. The other three are about turning that into work an agent can finish one piece at a time.
- Not every part of a spec pulls its weight. Testable acceptance scenarios and explicit scope limits change what gets built. Paragraphs describing your intent mostly do not.
- The Spec Kit template has no section called non goals. Scope limits are smuggled into Assumptions, which is why so many specs quietly omit them.
- Below roughly an hour of work, writing the spec costs more than the mistakes it prevents. The method earns its keep on features with branching behaviour, not on a button.
Here is the failure that sends people looking for this method. You ask a coding agent for a discount code feature. It produces four files, a migration, some tests, and everything compiles. Then you read it and discover it applies the discount before tax instead of after, stacks two codes when your business never allows that, and silently accepts an expired code because nobody said what expiry should do. None of that is a bug in the usual sense. The agent solved a problem correctly. It was not your problem.
Adding more detail to the next prompt helps a little and then stops helping. The reason is not that the model is weak. It is that a chat message is a poor container for a decision: it has no structure, so there is nothing to check the finished code against, and the thing you forgot to mention is invisible to both of you.
Spec driven development is the response. Write the feature down first, in a shape that separates what the user needs from how the system will do it, then let the agent derive its plan and its task list from that document. This piece is about which parts of that document actually change what an agent builds, because they are not equally weighted and the guides tend not to say so.
What is spec driven development, exactly?
It is a workflow in which a written specification, not a prompt, is the artefact the agent works from. The spec captures behaviour and success conditions; a separate plan captures stack and architecture; a task list breaks the plan into pieces small enough to review individually.
GitHub published an open toolkit for it called Spec Kit. Its own announcement is blunt about the division of labour in the first phase: writing that the Specify step "isn't about technical stacks or app design" and is instead about user journeys, experiences and what success looks like. The technical decisions arrive in the next phase, deliberately.
The wider claim behind the method is stated in the project's own design document, which says specifications must be "precise, complete, and unambiguous enough to generate working systems". That is an ambitious bar and worth holding lightly. What matters for a working developer is the weaker and more defensible version: a spec that is precise about the things the agent would otherwise have to guess removes exactly those guesses.
The four phases
Specify. A short description becomes a detailed spec centred on user journeys and what success looks like. No stack, no schema, no framework.
Plan. You supply the stack, the architecture and the constraints, and the agent produces a technical implementation plan against the spec.
Tasks. The spec and the plan are broken into small, independently testable chunks.
Implement. The agent works the tasks in sequence, so you review focused changes rather than one large dump of code.
Microsoft's engineering blog frames the same idea around what it calls translation loss, arguing that the spec becomes "the connective tissue across the lifecycle" and adding a Clarify step between Specify and Plan whose only job is resolving ambiguity before any architecture is chosen. That extra step is the tell. Both descriptions agree that the expensive failures come from things nobody decided, not from things somebody decided wrongly.
Which parts of a spec does an agent actually act on?
The parts that can be checked. An agent turns a specification into code by looking for statements it can satisfy and verify, so a line with a testable condition attached changes the output, while a paragraph of context mostly changes the comments.
The table below maps the sections of the real Spec Kit feature template against how directly an agent can act on each. I built it by reading the template file in the repository section by section and asking, for each one, what a task would look like if it were derived from that section alone. Where a section cannot produce a task, it cannot produce code.
| Section of the spec | What it contains | Can a task be derived from it alone? | Practical weight |
|---|---|---|---|
| Acceptance scenarios | Given a state, when an action, then an outcome | Yes, directly. Each line is a test | Highest. This is the part that survives into the code |
| Functional requirements | Numbered lines of the form the system must do X | Yes, one task per requirement | High, provided each line names one behaviour |
| Edge cases | Questions about boundaries and error states | Yes, but only if you answer them | High when answered, zero when left as questions |
| Success criteria | Measurable, technology neutral outcomes | Partly. Drives verification, not construction | Medium. Catches the wrong build after it exists |
| Assumptions and scope limits | Reasonable defaults and what is out of scope | No, but it stops tasks being created | High, and consistently under written |
| Key entities | Data objects and their relationships | Yes, for schema work | Medium. Often re derived in the Plan phase anyway |
| Prose describing intent | Why the feature matters, who wants it | No | Lowest. Useful to humans reviewing the spec |
The template has no section called non goals
This is worth stating plainly because it explains a common disappointment. Read the mandatory sections of the Spec Kit feature template and you will find User Scenarios and Testing, then Requirements, then Success Criteria. Scope limits appear only inside Assumptions, illustrated with examples like mobile support being out of scope for a first version.
Putting the boundary inside a section named Assumptions has a predictable effect: people fill in assumptions about their users and their environment, then stop, because nothing on the page asked them what the feature must not do. Yet in practice, the sentence that most reliably improves an agent's output is the one that removes work. Do not add a settings page. Do not touch the existing checkout. Do not introduce a new dependency. The design document behind Spec Kit is explicit that the process is meant to prevent "speculative or 'might need' features", but the template makes writing those exclusions optional in practice by never asking for them directly.
If you adopt this method, add the heading yourself. It takes one line and it is the cheapest line in the document.
A worked spec for one small feature
Take a real, small feature: a single use discount code on a shop's checkout. Below is what an agent receives in each of the two styles. Neither is a benchmark and I am not reporting a measured outcome, because I have not run a controlled comparison and inventing one would be worse than useless. What the pair shows is narrower and checkable by eye: how many decisions each version leaves to the model.
The bare prompt
Add support for discount codes at checkout. A code should reduce the order total. Admins need to create codes in the backoffice.
Three sentences, and every one of them is a category rather than a decision. Reduce the total by what, a percentage or an amount? Before or after tax and shipping? Can two codes apply at once? What happens on an expired code, a code used twice, a code on an order below its minimum? Does an admin set a usage limit? Nothing here is wrong. There is simply nothing to be wrong about, which is why the code that comes back cannot be judged.
The same feature as a spec
User story, priority P1. A shopper enters a code at checkout, sees the discount applied to the order total before payment, and can remove it.
Acceptance scenarios.
- Given a valid percentage code and a cart of 100, when the shopper applies it, then the discount is calculated on the goods subtotal only, and shipping and tax are computed on the reduced amount.
- Given a code past its expiry date, when the shopper applies it, then the order total is unchanged and the checkout shows that the code has expired.
- Given a code already applied, when the shopper applies a second code, then the first stays and the second is refused with a message saying one code per order.
- Given a code with a minimum order value of 50 and a cart of 40, when the shopper applies it, then the code is refused and the shortfall is stated.
- Given a code at its usage limit, when the shopper applies it, then it is refused and the counter does not increment.
Functional requirements. The system must store a code as either a percentage or a fixed amount in the shop's currency. The system must record every redemption against the order that used it. The system must refuse a code whose usage count has reached its limit, checked at the moment payment is authorised rather than at the moment the code is typed.
Out of scope. No automatic discounts. No per customer codes. No changes to the existing tax calculation. No new admin screens beyond a list and a create form.
Success criteria. A shop owner can create a working code in under a minute without documentation. No order can ever be discounted twice by the same code.
Now look at what changed. The two most consequential lines in that document are not the requirements. They are the last acceptance scenario, which forces the usage check to happen at authorisation rather than at entry and therefore rules out an entire class of race condition, and the out of scope list, which prevents four plausible features from appearing uninvited. Neither line describes intent. Both describe a boundary.
Where an answer genuinely does not exist yet, Spec Kit's convention is to write a [NEEDS CLARIFICATION] marker into the spec rather than let the agent assume. The template's own guidance is to mark it if the prompt did not specify it. A spec with five honest markers is more useful than a spec with five confident guesses, because the markers are a list of conversations you still owe the work.
What does this cost, and when does it not pay back?
It costs real time, usually twenty to forty minutes for a feature of the size above, and there is a floor below which that never returns. If the task is a copy change, a new column on a table, a styling fix or anything you could describe completely in one sentence, the spec is overhead with a ceremony attached.
The second cost is maintenance, and it is the one people discover in month three. Red Hat's write up of the approach is unusually candid about the fork in the road: treating the spec as the source of truth and regenerating from it is described as resource hungry, while hand editing the code instead means the specs drift unless they are kept in sync. There is no third option where the document stays accurate for free.
My own rule of thumb, offered as a rule of thumb and nothing more: write the spec when the feature has branching behaviour that a reasonable person could resolve two ways. Discount codes qualify. Refunds, permissions, scheduling and anything involving money or time nearly always qualify. A new page that lists things you already have does not.
| Task shape | Typical spec cost | What the spec prevents | Worth it? |
|---|---|---|---|
| Copy or styling change | Longer than the task | Nothing | No |
| New list or detail page over existing data | 10 minutes | Minor layout rework | Rarely |
| Anything touching money, tax or refunds | 30 to 45 minutes | Wrong rounding, wrong order of operations, double charges | Yes |
| Permissions or roles | 30 minutes | A write call that never checks who is asking | Yes |
| Scheduling, availability, expiry | 30 minutes | Timezone and boundary errors that surface weeks later | Yes |
Does any of this apply if you are not a developer?
Yes, and more than you would expect, because the parts that carry the weight are the parts you already know. A shop owner cannot write a technical plan. A shop owner can absolutely write five sentences of the form given this, when that, then this, because those sentences are just the business rules said out loud.
If you are describing a site to an AI builder rather than to a coding agent, the transferable habit is the acceptance scenario and the out of scope line. Instead of asking for a booking page, say what happens when two people request the same slot, what happens when someone cancels an hour before, and what you explicitly do not want. We went through the same discipline from the other direction in our piece on what actually makes vibe coding work, and the conclusion matches: the prompt is not the lever, the decision is.
The tooling side matters less than people assume. Which assistant you use changes the ergonomics, not the method, and we compared those trade offs in our side by side of the main AI coding assistants. The model choice matters a little more, because a weaker model degrades faster on long documents, and we broke down where that line sits in our look at which model to use for coding work. Neither decision rescues a spec that never said what the feature must not do.
How does this fit with the tools an agent can already reach?
A spec tells an agent what to build. It says nothing about what the agent can see while building it, and that is a separate and often larger problem. An agent that cannot read your database schema will invent one; an agent that cannot see your existing components will write new ones beside them.
That is the gap connection protocols are meant to close, and it is why the two ideas are complementary rather than competing. If you want the mechanics of how an assistant gets access to real project context rather than guessing at it, our explanation of what an MCP server does and how MaShop exposes one covers the plumbing. The short version is that a good spec plus no context still produces confident, wrong code, just wrong in a more organised way.
The honest limits of the method
Three things are worth saying that the enthusiastic write ups tend to skip.
First, a spec does not make an agent correct. It makes an agent's errors legible. That is a genuine and underrated benefit, because a mistake you can point at in a document is a mistake you can fix in one line rather than in a code review. But the phrase about generating working systems from sufficiently precise specifications describes an ambition, not a measured result, and no source I read supported it with a controlled comparison.
Second, specs written by the agent itself inherit the agent's blind spots. If you ask a model to expand three sentences into a full specification, it will produce something that looks complete and quietly resolves every ambiguity in whichever direction is most common in its training data. Read the generated spec as a draft that you argue with, especially the assumptions section, which is where the guesses hide.
Third, the discipline decays under deadline. The first spec is thorough, the fifth is thorough, and somewhere around the twelfth someone writes a spec that says the system must handle discounts correctly. At that point you are back to a prompt with extra formatting, and the honest move is to notice it rather than to keep the ritual.
None of that argues against the method. It argues for using it where branching behaviour makes the cost worth paying, writing the exclusions the template forgets to ask for, and treating the acceptance scenarios as the real deliverable. Everything else in the document is scaffolding for those few lines.