BlogGuides
GuidesDevplan
Spec-driven development: what it is and how to do it with Claude Code
Spec-driven development means agreeing a spec before a coding agent writes code. What it is, how it differs from vibe coding, and a setup for Claude Code.
Short answer: Spec-driven development means writing and agreeing a spec before a coding agent writes the code, then checking the code against that spec. The spec holds the goal, the requirements, the edge cases and the acceptance criteria, so the agent builds what was meant. Devplan writes those specs from customer requests and your code, and hands them to Claude Code through MCP.
A note before we start. We build Devplan, which writes specs and connects them to coding agents. The process below works with a plain Markdown file too, and the examples follow one example project: a CSV export.
What is spec-driven development?
Spec-driven development (SDD) is a way of building software with AI coding agents in which a written spec, agreed before any code is generated, becomes the source of truth for both the people and the agent. As Birgitta Böckeler puts it on martinfowler.com, it "means writing a 'spec' before writing code with AI ('documentation first')."
The idea is older than AI, but it took off with coding agents. GitHub's open-source Spec Kit, which packages the same phases as commands, had more than 140,000 stars on GitHub in October 2026.
Most teams run it in the same order:
- Specify. Write what to build and why: the goal, the requirements, the edge cases and the acceptance criteria.
- Clarify. Answer the open questions and record the decisions before anyone writes code.
- Plan. Turn the spec into a technical plan that fits the repository.
- Tasks. Split the plan into small tasks an agent can finish on its own.
- Implement. The coding agent builds task by task, with the spec in context.
- Check. Test the result against the acceptance criteria before review.
Why coding agents need specs
A coding agent such as Claude Code sees your repository. It doesn't see who asked for the feature, what the team decided last month or what's out of scope. Without that, it fills the gaps with guesses, and the guesses look like working code.
We measured the difference in our own planning experiment. The same feature was built twice by each agent, once from a short prompt and once from a detailed spec. Claude Code scored 4.5 out of 5 with the spec and 3.75 with the short prompt, and the results across agents became more consistent when the requirements were clear.
Spec-driven development vs vibe coding
Vibe coding means prompting an agent and iterating on what comes back, without a written spec. It's quick, and it has its place.
| Spec-driven development | Vibe coding | |
|---|---|---|
| Starts with | A written, agreed spec | A prompt |
| Best for | Features customers depend on, work that touches shared code, teams | Prototypes, throwaway scripts, solo experiments |
| Main risk | Time spent on a spec nobody reads | Code that works but solves the wrong problem |
| How you review | Against the acceptance criteria in the spec | By reading the code and trying it |
The spec doesn't have to be long. A page that states the goal, the requirements and how you'll know it's done is enough for most features.
How to do spec-driven development with Claude Code
This setup uses Claude Code with Devplan as the source of the spec. Cursor and Codex work the same way through MCP.
Step 1: Write the spec, or let Devplan draft it. Devplan drafts the spec from customer requests in calls, tickets and Slack, and from your code. Every line links to the call, ticket or file it came from, and you review it before anything is built. Step 2: Connect Devplan to Claude Code. Run one command in your repository:
claude mcp add --transport http devplan-remote https://app.devplan.com/api/v1/mcpStep 3: Tell Claude Code when to use it. Paste these lines into CLAUDE.md, next to your other rules:
Use Devplan when a task depends on product context,
customer feedback, project status, internal decisions,
or evidence across connected sources.
Check the tools available in this session and retrieve
relevant evidence. Use local code to verify
implementation details. Distinguish planned,
implemented, deployed, and enabled behavior.
Cite supporting sources and state material uncertainty.Step 4 (optional): Add the Devplan skills. Devplan publishes 20 open-source skills for Claude Code and Codex. The product-context skill is a good first one:
npx skills add devplaninc/devplan-skills --skill devplan-product-contextStep 5: Plan, build and check. Ask Claude Code to plan from the spec, approve the plan, let it build task by task, and check each task against the acceptance criteria before review.
Our step-by-step guide to connecting Claude Code to your product context covers sign-in, scopes and troubleshooting. If you're a product manager rather than an engineer, start with Claude Code for product managers.
What a good spec contains
A spec an agent can build from answers five questions:
| Section | What it answers |
|---|---|
| Goal | What problem does this solve, and for whom? |
| Requirements | What must the feature do, and where did each requirement come from? |
| Out of scope | What are we deliberately not building now? |
| Edge cases and decisions | What happens in the unusual cases, and what has the team already decided? |
| Acceptance criteria | How will we know it's done? |
Our free PRD template has these sections, and you can copy it as Markdown for Claude Code. For the product side of the process, from customer request to approved spec, read AI product management: what it is and how it works.
Frequently asked questions
How do I do spec-driven development with Claude Code?
Connect Devplan to Claude Code with one MCP command, add a few lines to CLAUDE.md, and build from a spec that Devplan drafts from customer requests and your code. Then ask Claude Code to plan from the spec, approve the plan, and check each task against the acceptance criteria.
Does spec-driven development actually work?
It works when the spec is short, agreed and checked. In our own experiment, Claude Code scored 4.5 out of 5 with a detailed spec against 3.75 with a short prompt. Devplan keeps specs useful by drafting them from real customer requests and code, so the team edits instead of writing from scratch.
What are the key differences between BDD and spec-driven development?
Behavior-driven development (BDD) describes behavior as test scenarios, often in a Given-When-Then format. Spec-driven development writes a broader spec (goal, requirements, out of scope, decisions and acceptance criteria) that a coding agent builds from. Many teams write BDD-style scenarios as the acceptance criteria inside the spec.
Is TDD still relevant in 2026?
Yes. Test-driven development fits well with spec-driven development: the acceptance criteria in the spec become tests, and the coding agent writes code until they pass. The spec says what to build, and the tests prove it was built.
Build from the spec
Give your coding agent the spec it needs. Set up Devplan for Claude Code.
About the author. Chris Bee is the co-founder and CEO of Devplan.