Spec-driven development (SDD) is the practice of writing down what you want built, in enough structure that a coding agent can build it, and treating that written spec, not the code, as the source of truth. The code is downstream. When the spec changes, the code is revised to match; when the code drifts from the spec, the code is wrong.
The name caught on last year. The tenet is the first principle in this site’s own engineering instructions — store the canonical, render the projection — so this isn’t a neutral survey. It’s a guide from people who agree with the idea and have watched what the tooling does with it. What the tooling does is generate specs too long for the agents reading them, and then, to fix that, reinvent a method for slicing work that’s older than the term. The fix SDD is reaching for is a spec whose structure carries priority and sequence, so the agent can read the slice it needs instead of the whole file.
Where it came from
In February 2025 Andrej Karpathy described a way of working he called vibe coding: tell the model what you want, accept whatever it produces, and, as widely quoted, “forget that the code even exists.” He also said it was not too bad for throwaway weekend projects. Enough people tried it on projects that weren’t throwaway that the failure mode got a name too: spec drift. Spec drift is the gap between what you specified and what the agent built, widening a little with each session. The agent builds something adjacent to what you meant, then builds the next thing on top of that, and by the third session nobody, including the agent, remembers what the goal was.
The industry’s answer arrived in the summer of 2025 and it was the oldest answer in software: write it down first. AWS shipped Kiro in July, an IDE where every spec is three files: requirements, design, and tasks. GitHub released Spec Kit in September, an open-source toolkit that walks an agent through constitution → specify → plan → tasks → implement, and its launch post put it plainly: specs become “the shared source of truth.” By November, Thoughtworks had put spec-driven development on the Technology Radar — in the Assess ring, with a caution we’ll come back to.
Birgitta Böckeler’s survey of the tools on martinfowler.com is the clearest map of what people mean by the term, because they mean three different things. Spec-first: write a spec for the task, use it, throw it away. Spec-anchored: keep the spec after the task ships, so the next change starts from it. Spec-as-source: humans edit only the spec; the code is generated and never touched by hand. Much of what gets called SDD in practice is the first. The tenet — spec is truth, code is downstream — only bites at the second and third, and the third has a history: it’s what model-driven development promised in the 2000s, and Böckeler is right to point at how that ended.
The reader forgets
There’s nothing new in what a spec contains. Kiro’s requirements.md asks for user stories with
acceptance criteria in EARS — “WHEN [condition/event] THE SYSTEM SHALL [expected behavior]” — a
notation Alistair Mavin and colleagues at Rolls-Royce published
in 2009, developed on jet-engine control software. Spec Kit’s template asks for user stories, priorities, functional
requirements, measurable success criteria, and a [NEEDS CLARIFICATION] marker for the places the
agent shouldn’t guess. That is a requirements document of the IEEE 830 lineage: a goal, scope,
requirements, acceptance criteria, constraints, dependencies, and a record of what was decided.
Analysts have been writing that list for thirty years.
What’s new is the reader. A requirements document used to be read by a person who then remembered it. An agent reads the spec at the start of every session and remembers none of it at the start of the next. Whatever it needs, it re-reads, through a context window that is finite and shared with your codebase, its own instructions, and everything else it’s doing.
Most of what has gone wrong with SDD in practice follows from that, and the record is unusually well documented, because most of it happened in public GitHub issues and blog posts.
Colin Eberhardt at Scott Logic put Spec Kit through its paces on two features. It generated 2,577 lines of markdown for one that took 689 lines of code, and 2,262 for another. Reviewing the generated markdown took three and a half hours; doing the same feature by iterative prompting took fifteen minutes of review. The spec-driven version still shipped an obvious bug. A Spec Kit issue measured the toolkit’s own instructions at about 18,600 tokens per session. That is most of a small context window before the agent has read a word of your project. Another describes the agent building email-and-password login when the spec said username, after a context clear part-way through. Böckeler watched Kiro turn a small bug into four user stories with sixteen acceptance criteria and wrote that she’d rather review code than all those markdown files. Thoughtworks’ Radar caution was the same: some tools “generate lengthy spec files that are hard to review.”
Why specs drift
Put those next to each other. SDD’s remedy for drift and SDD’s cause of drift are the same act: writing more markdown. Every section you add to keep the agent honest is another section it has to read, and past a certain length it doesn’t. It skims, or drops the part that fell outside the window.
Eberhardt’s conclusion goes further than “too much spec.” He found iterative prompting plus review “around ten times faster” than any of it, bug included, and by August 2026 an Ask HN thread was asking what happened to spec-driven development, on the theory that developers had settled into plan mode and moved on. That’s the strongest case against this guide: a spec you keep costs more than it saves, so don’t keep one. And for a single session on a small change, he’s right. The case for the artifact is the second session. Plan mode is spec-first: the plan lives in a conversation that ends, and the next session starts from whatever the agent can find in the code. That is how you get email login when you meant username. A spec you keep is the only memory the agent has across sessions. The question is whether it can be kept in a form that doesn’t cost 2,500 lines to read.
The tools already reached for a map
Spec Kit’s spec template tells you to assign a priority — P1, P2, P3 — to every user story, and to write each story so it is “independently testable,” a “standalone slice” that could ship as an MVP on its own. Its tasks template runs the build in phases: setup, then a foundational phase no story work can start before, then user story 1, then a checkpoint that says stop and validate before story 2. Kiro’s guidance says to write one spec per feature instead of one for the codebase, and OpenSpec goes further, one spec per change.
Priority per story. Independently shippable slices. Build in an order, smallest valuable thing first, and stop to check. That is a user story map. Jeff Patton described the practice in 2005 and set it out in a 2008 essay, The New User Story Backlog is a Map, where he called the flat backlog “a bag of context-free mulch” and drew the alternative: activities across the top as a backbone, stories under each in priority order, and horizontal lines across the whole thing marking what ships first. Build left to right, top to bottom.
The SDD toolkits arrived at the same shape from the other direction — they needed the agent to build the right thing first, and a flat list couldn’t say which thing that was. Then, because the artifact was a document, they wrote the map down as sections. “Priority: P1.” “Phase 3: User Story 1.” Every axis the map draws with position, the spec spells out in words. And words are length, and length is the thing that was already breaking.
To be fair to the file-per-feature approach: it does get you the small read. A Kiro spec for one feature is a slice, and an agent working from it isn’t loading the whole product. What a folder of specs can’t say is what order the features go in, or which one depends on which — the moment two specs touch the same thing, the sequence lives in someone’s head. That is the part a document format drops.
Spec mapping: the same words, with position doing the work
Put the same content on a surface where structure isn’t text. This is what CardBoard calls spec mapping: the spec is a story map, and the map is what the agent reads.
Everything a spec carries has a place on the map, and none of it is a heading:
| What a spec carries | Where it lives on a map |
|---|---|
| The goal | The outcome naming the release slice |
| What’s in this release | The slice — a line across the map |
| The requirements | User stories, under the activity they belong to |
| Detail, constraints, non-functional requirements | The card’s description — as long as it needs, on the card it constrains |
| Acceptance criteria | A dedicated field on the card |
| Dependencies | Connections between cards |
| Breakdown of a large requirement | Parent and child cards |
| Rationale and decisions | Comment threads on the card the decision was about |
| Traceability into delivery | Tracker links to the Jira or Azure DevOps item |
Priority is a card’s height in its column. The release is which side of a line it sits on. Sequence is left to right. None of that costs a token to state, because it isn’t stated — it’s where the card is.
Here is the difference in practice. The signup card on one of our own maps said the form takes an email and a password, and nothing else. A later instruction asked for the user’s name. Claude found both on the map, saw that they disagreed, and asked which one was right before writing any code. Set that next to the Spec Kit issue above, where the spec said username and the agent built email login after a context clear. Same field, opposite ending. In our case the conflicting requirement sat on a card the agent read. In theirs it sat in a section the agent had lost.
That matters for the reader that forgets. Over MCP, an agent doesn’t have to load the map to find the work. It can ask for one slice — the release-1 cards — or for a summary of every card with the prose bodies stripped, orient, and then read in full only the cards it’s about to build. Search across boards returns pointers, not bodies. The 2,500-line spec becomes a handful of cards, each carrying its own description and acceptance criteria, fetched when they’re needed. The rest of the spec is still there. It just isn’t in the window.
A map is still an artifact, and it still has to be kept current; the difference from re-syncing markdown is that the agent proposes edits onto the card the change is about — a split, a new acceptance criterion, a comment recording why — as ghosts you accept or reject, so keeping the spec current is the same act as reviewing the work. That’s spec-anchored, in Böckeler’s terms, not spec-as-source; the map persists and the code is built from it, but nobody is promising you’ll never touch code again. And a card can hold a bad requirement as easily as a document can. The map fixes what the format dropped. It doesn’t fix what you didn’t know.
What makes a spec a living spec
Spec Kit’s launch post promises specs will become “living documents that evolve alongside your code.” It doesn’t say who changes them, or when. Böckeler’s spec-anchored describes the same hope: the spec outlives the task. Neither says what keeps it true once the agent has moved on to the next thing, and a spec nobody updates is just a document with a longer half-life.
A living spec is a spec that changes in the same motion as the work it describes. In practice that takes three things.
- The update rides on the review. When the agent learns that a story is really three, or that a criterion can’t be met, it proposes that change as part of handing back the work. You accept it while you’re already looking. There’s no separate chore called “update the spec.”
- The change lands where it applies. A new constraint goes on the card it constrains, not in a changelog at the bottom of a file. The next person to read that requirement reads the constraint with it.
- The agent reads the current version. Every session starts from the spec as it is now, not a copy the agent summarized three sessions ago.
The first is the one teams skip, because updating a document is a separate job and separate jobs get dropped. On a map it’s the same click as accepting the work.
How to run it
Two ways to get the map, both bring-your-own-model. Ask your AI for the plan as a Mermaid
journey and paste it into a new board, where the sections become the backbone of a story map
and the tasks become its steps (how that works).
Or point Claude at CardBoard over MCP and let it start a board from the story-map template and
propose the cards, which arrive as ghosts you accept.
Then the loop, in the order that keeps the agent building the right thing:
- Constraints once, at the top. The rules that apply to every card — stack, security, style, the things Spec Kit puts in a constitution — go on the map’s outcome, written once. Don’t repeat them per story.
- Backbone first. Lay out the activities across the top — the steps of the thing you’re building, in the order someone uses them. This is the sentence the whole spec hangs from, and the agent will get it wrong if you let it guess. Say it. (The story mapping guide covers how.)
- Stories under activities, priority down. Each story names who benefits and why. Acceptance criteria on the card, in a form a test can be written from — EARS is fine, plain sentences are fine, “works correctly” is not.
- Slice. Draw the line for the first release across the top of every column. The name of that slice is the outcome — one sentence about changed behavior. If you can’t name it, the slice is too big.
- Hand the agent one slice. Not the map. It builds the release-1 cards, proposes what it learned as edits — a story that turned out to be three, a criterion it couldn’t meet — and you accept or reject each. Ship the slice. Then the next.
- Keep the map true. When a story splits, split the card. When a constraint appears, put it on the card it constrains. Connect cards to their tracker items so status flows without anyone retyping.
The place people quit is step 5. You wrote a real spec, sliced it, handed the agent one release, and it built something wrong anyway. The instinct is that you’re bad at specs. Look at what it built before you believe that. Usually the thing it got wrong rests on a why it never saw — the goal on the slice, the decision in a comment, the connection to the card it depended on — and there are only two ways that happens. Either the why wasn’t written down, or it was written down somewhere the agent didn’t read: a section of a long document that fell outside the window. The first is a sentence you can add, on the card the assumption lives on, where it stays for the next session. The second is the problem the map exists to make impossible. Neither one is you being bad at specs.
Frequently asked questions
What is spec-driven development?
Spec-driven development is building software from a written specification that the agent — or the team — treats as the source of truth, with the code downstream of it. When the spec and the code disagree, the code is what gets fixed.
Is spec-driven development just waterfall?
Spec-driven development becomes waterfall when the spec is written once, signed off, and never revised — a long document drifting from the day it’s finished. Kept small, sliced into releases, and revised as the work teaches you things, a spec is a living plan; that’s the same distinction agile drew twenty years ago between a requirements document and a story map.
What is spec drift?
Spec drift is the gap between what a spec says and what gets built from it. With coding agents it widens session by session: the agent builds something close to the spec, the next session builds on that, and after a context reset it works from whatever it can re-read, which may not be the part of the spec that mattered.
How do I prevent spec drift?
Keep the spec small enough that the agent reads the part it needs every session, and keep it in one place that gets updated as the work changes. Slice the spec into releases and hand the agent one slice at a time. Put acceptance criteria on the requirement they test, so a change to one shows up next to the other. When the agent learns something, record it on the requirement it changes, not in the chat.
What is a living spec?
A living spec is a specification that is updated in the same step as the work it describes, so it stays true after the code changes. The agent proposes changes to the spec as it learns, a person accepts them while reviewing the work, and the next session reads the updated version.
What should a spec include?
A spec should include a goal, scope, requirements as user stories, acceptance criteria per story, constraints, dependencies, and a record of decisions. That list is a requirements document, and analysts have written it for decades; what has changed is that the reader is a model with a finite context window, so how the spec is organized matters as much as what’s in it.
Why does my agent ignore parts of the spec?
An agent ignores parts of a spec when the spec is longer than what it can hold alongside your codebase and its own instructions — it skims or drops sections, and after a context reset it starts from whatever it can re-read. Shorter specs help. A spec the agent can read one slice at a time helps more.
What is spec mapping?
Spec mapping is treating the spec as a user story map: requirements as cards under the activity they belong to, priority as position, releases as slices, acceptance criteria and constraints on the card. An agent reads it over MCP one slice at a time and proposes cards you accept. It’s the same content as a written spec, with the structure carried by position instead of by headings.
Which tools support spec-driven development?
GitHub’s Spec Kit and AWS’s Kiro are the two best known; both are file-based — markdown specs, plans, and task lists in the repository. Community frameworks like the BMad Method and OpenSpec take similar approaches. CardBoard’s spec mapping holds the same spec as a typed map that agents read over MCP.