What Is Spec-Driven Development (SDD)? A Guide for Engineering Teams
Spec-driven development (SDD) is a way of building software in which a written specification, not the code or a chat history, is the source of truth. Teams describe intent, acceptance criteria and constraints first, then have people or AI agents plan, implement and test against that spec.
What is spec-driven development?
In SDD the spec captures what the software must do and why: behaviour, edge cases, constraints and success criteria, written so that both people and language models can act on it. Code becomes an output that is checked against the spec, rather than the place where intent is discovered. The idea is not new, but AI coding agents have made it practical and urgent. Thoughtworks lists it on its Technology Radar, and GitHub publishes an open-source toolkit, Spec Kit, built around it.
Why does SDD matter now?
An AI agent will happily build something from a vague prompt. If the prompt hides an ambiguity, the agent resolves it silently, and you find out in review or production. Writing the spec first moves that discovery earlier, when it is cheap. It also gives reviewers something explicit to check output against, and gives a team a shared artifact instead of one engineer's private prompting habits.
What does the SDD loop look like?
Spec Kit and similar workflows break the work into stages. The exact command names vary by version, but the loop is consistent:
- Constitution: project principles and non-negotiables (testing standards, security rules, architecture limits).
- Specify: the feature as user stories with acceptance criteria.
- Clarify: resolve open questions before any design work.
- Plan: the technical approach, data model and contracts.
- Tasks: a dependency-ordered task list.
- Analyze: check spec, plan and tasks for gaps and contradictions.
- Implement: the agent builds task by task, and humans review against the spec and tests.
What does a good spec contain?
- User stories that state who needs what and why.
- Acceptance criteria that are testable, ideally in given-when-then form.
- Edge cases and failure behaviour, not just the happy path.
- Constraints: performance, security, compliance and compatibility limits.
- Open questions marked explicitly so they get answered, not guessed.
- Out of scope, so the agent does not build more than asked.
A good spec is detailed enough to remove guesswork and light enough to change as you learn. A spec nobody can review in ten minutes will not be reviewed.
Where does Claude Code fit?
According to Anthropic's documentation, Claude Code is an agentic coding tool that reads your codebase, edits files and runs commands. Several of its features map directly onto SDD:
| SDD need | Claude Code feature |
|---|---|
| Project principles every session must follow | CLAUDE.md project memory |
| Reusable spec and review workflows | Skills and custom slash commands |
| Enforcing rules automatically | Hooks that run before or after actions |
| Linking to Jira, Confluence or test tools | Model Context Protocol (MCP) servers |
| Parallel or specialised work | Subagents |
When should you not use SDD?
For a throwaway script, a quick spike or an exploration where you do not yet know what you want, a full spec is overhead. Use a light spec, or none, and promote the work to a spec once it becomes something you will keep and share.
Frequently asked questions
Is spec-driven development the same as test-driven development?
No. TDD starts from tests written by developers. SDD starts from a spec with acceptance criteria, and tests are derived from it. The two combine well: acceptance criteria can become the first tests.
Do I need GitHub Spec Kit to do SDD?
No. Spec Kit is one toolkit that structures the workflow. The principles work with your own templates, as long as the spec is written, reviewed and used to drive implementation and tests.
Who writes the spec?
On most teams it is a joint effort: Business Analysts or product owners supply intent and acceptance criteria, engineers add constraints and design, and testers add edge cases. AI can draft and check for gaps, but people own the content.
Sources: Spec Kit: What is spec-driven development?, GitHub Spec Kit, Thoughtworks Technology Radar, Claude Code overview.
Keep reading: Spec-driven development vs vibe coding · Claude Code for QA engineers
Train your team on this
VEDNIQ runs live, 1-day Claude Code programs for delivery teams, with hands-on labs.