What is spec-driven development?
Spec-driven development is a way of working with coding agents where you write down what to build and why before any code exists. The agent turns that specification into a technical plan, then a list of tasks, then an implementation it checks against the spec. The document, not the chat, is the source of truth for the feature.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
You describe the feature as a spec: who it is for, what the system shall do, and how you will know it works. No implementation detail yet.
The agent turns the spec into a technical plan: architecture, data flow, the parts it expects to touch. You review that too.
The plan becomes small, ordered tasks the agent can carry out and tick off one at a time.
The agent implements each task and checks the result against the acceptance criteria in the spec.
When the intent changes, you change the spec first and let the plan and tasks follow, so the document stays true.
Source: GitHub spec-kit
Spec-driven development versus vibe coding
In vibe coding you type a request, look at what comes back, and type another. The intent lives in the chat, and once the window is gone so is the reasoning. Spec-driven development moves the intent into a document first. You describe what to build and why, agree on it, and only then let the agent plan and implement. GitHub's spec-kit describes the method as defining what to build and why, then turning that specification into a plan, tasks and working code.
The practical difference is where you argue. With a spec, disagreements about scope happen in a Markdown file before anything is written, where a change costs a sentence. Without one they happen in a pull request, where the same change costs a rewrite.
Example: a feature in three files
Kiro's IDE builds specs in. Describe a feature and it writes three files. The requirements file holds user stories with acceptance criteria in a structured notation, a fixed sentence shape: when some condition or event occurs, the system shall do a specific thing. The design file records the technical architecture, sequence diagrams and implementation considerations. The tasks file breaks the work into discrete, trackable tasks that you can run one at a time or all at once; Kiro groups tasks that don't depend on each other into waves and runs each wave's tasks concurrently.
You can also start design-first when the architecture is the constraint, and let the requirements follow. Either way the files are plain Markdown in your repository, so other agents and other people can read them.
spec-kit does the same without an IDE. Its specify CLI adds a set of slash commands to a supported coding agent: a constitution for the project's principles, then specify, plan, tasks and implement, with a convergence check you repeat until it reports converged.
When to use it
Use a spec when a change touches more than one part of the system, when more than one agent or person will work on it, or when you will need to explain the decision in six months. A one-line bug fix doesn't need one. A new billing flow does.
A spec also works as the hand-off between roles. Product writes the requirements, engineering's agents read them and plan, and the same file is what reviewers check the code against. Teams that keep the PRD as a shared board, where each engineer's agent pulls the current version before it starts, get this without a separate tool: the spec sits where the agents already look.
Common mistakes
- Writing the design into the requirements. Requirements say what the system shall do; the design says how. Mixing them locks in an implementation before the agent has looked at the code.
- Letting the spec rot. If the code changes and the spec doesn't, the next agent plans against a fiction. Treat the spec like code and change it in the same pull request.
- Treating the task list as a script. Tasks are a plan, not a promise. When a task turns out to be wrong, go back to the plan rather than forcing the implementation through.
- Skipping acceptance criteria. Without a testable statement of done, the agent decides for itself when it has finished.
FAQ
- Is spec-driven development the same as waterfall?
- No. A waterfall spec covers a whole system and is written once. Here the spec covers one feature, the agent drafts it in minutes from your description, and you revise it as the implementation teaches you things. What they share is the order: intent before code.
- Which tools support spec-driven development?
- Kiro builds it in, with requirements, design and task files for each feature. GitHub's spec-kit adds the same phases to several coding agents through slash commands. Any agent that can read a Markdown file can follow a spec you keep in the repository or on a shared board.
- How detailed should a spec be in spec-driven development?
- Detailed enough that two people would build the same thing from it, and no more. Requirements as testable statements, a design that names the parts and the data flow, and tasks small enough to finish and check one at a time.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.