AI & automation · Guide
What is Spec-Driven Development (SDD), and how does it work?
Spec-Driven Development (SDD) is a method in which the specification comes before the code: the team writes and approves what the software must do, with acceptance criteria, and only then do AI coding agents or people implement from it. The spec becomes the source of truth, and tests check that the delivery meets it.
Master TimmUpdated on 7 min read
How Spec-Driven Development works
In SDD, every change goes through the same sequence of short documents, kept in Markdown in the repository next to the code. The AI coding agent reads those documents on every task instead of relying on what is left in a chat history.
- Project principles: The rules that apply to all work, such as coding standards, required tests and security constraints.
- Specification: What the software must do and why, as scenarios with verifiable acceptance criteria, without choosing a technology.
- Technical plan: How to build it, with the architecture, the stack, API contracts and the decisions recorded in ADRs.
- Tasks: The plan broken into small steps, each tied to a requirement in the spec.
- Implementation and verification: The agent implements one task at a time, and tests and human review check each one against the spec.
When a requirement changes, the spec changes first and the code follows. That way the specification keeps describing the system in production, not what was planned months ago.
Spec, ADR and acceptance criteria: what each document decides
Each document answers a different question; when one tries to answer another's questions, the spec grows long and nobody uses it. The example below is order cancellation in an online store.
| Document | What it decides | Example: order cancellation |
|---|---|---|
| SpecThe expected behavior, as scenarios | What the system does and why | A customer can cancel an order until it ships |
| Acceptance criterionThe verifiable condition of a scenario | When a task is done | Unshipped order canceled: stock is restored and a refund is created |
| ADRThe record of an architecture decision and its reason | How to build it and why this option, not another | Notify the ERP through an event queue, not a synchronous call |
| TasksThe steps of the plan | The order of the work and the size of each pull request | Cancellation endpoint, event to the ERP, E2E test of the flow |
On the program we work on for The Hackett Group, the Spec-Driven Development operating model holds 39 ADRs, 45 specs, 14 RFCs and 139 functional and non-functional requirements with traceability.
SDD with AI coding agents: from spec to pull request
An AI coding agent is fast and literal: it does what it understood from the request. With the spec in the repository, the request stops being a loose prompt and becomes a reviewed document that Claude Code, Codex, Cursor, Copilot or OpenCode read the same way.
- Stable context: The agent starts every task by reading the spec, the plan and the ADRs, not whatever is left of an earlier conversation.
- Small scope: Each task fits in a pull request a person can review, tied to a requirement.
- Objective review: The reviewer compares the code with the acceptance criterion, not with a memory of the request.
- Switching tools without rework: The spec is Markdown in the repository, so the process carries on if the team changes agents.
With SDD, people decide earlier: the time that went into fixing code goes into specifying and reviewing, and the merge stays a human decision.
Spec Kit and OpenSpec: the SDD tools we use
Both tools are open source (MIT license), keep everything in Markdown in the repository and work with Claude Code, Codex, Cursor, Copilot and OpenCode. The difference is in how each one organizes the work.
| Tool | How it works | When to pick it |
|---|---|---|
| Spec KitGitHub's toolkit for Spec-Driven Development | Project principles once; then specify, plan, tasks, implement and converge for each feature, invoked as skills in the agent's chat | When the team wants a complete path, with extra steps for clarification, checklists and consistency analysis |
| OpenSpecFission-AI's framework, built with existing systems in mind | Each change becomes a folder with a proposal, specs, design and tasks; the spec describes only what changes (ADDED, MODIFIED, REMOVED) and is merged into the main spec on archive | When the work is a series of incremental changes to a system already in production |
We pick one per project, based on the size of the change and the code that already exists. The method matters more than the tool: without spec review and tests, either one is just another folder of Markdown.
Quality gates: tests, coverage and human review
A spec is only worth something if someone checks that the code meets it. In SDD, that check is automated wherever possible and human where it takes judgment.
- Tests from the acceptance criteria: Every scenario in the spec becomes at least one automated test.
- Minimum coverage: CI blocks the merge when coverage drops below the target set for the project.
- Static and security analysis: Linters, type checks and secret scanning run on every pull request.
- Human review: A person approves the merge by reading the spec, the ADR and the diff together; the agent does not approve its own work.
At The Hackett Group, this setup sustains about 4,000 unit and integration tests with 95% coverage gates.
When SDD is not worth it
SDD has a fixed cost: writing and reviewing documents before the code. It pays for itself when a change carries business rules, involves more than one person or will live long in production. In other cases it gets in the way.
- Throwaway prototype: When the goal is to learn whether an idea works, the spec comes later, if the idea survives.
- Trivial fix: A copy or configuration change needs no plan or ADR; one acceptance criterion is enough.
- Unknown requirement: If nobody knows yet what the software should do, the first task is to find out, not to specify.
- Abandoned spec: If the team does not update the spec when a requirement changes, it starts lying about the system, which is worse than having no spec.
Related service
AI Software Automation
Coding agents on your team, with specs and quality gates.
Free first conversation · Reply within 1 business day
See also: Legacy Modernization and Technical Mentoring & AI Training.
Frequently asked questions
Isn't SDD just bureaucracy?
It does not have to be: the spec is sized to the change, and a small feature fits on one page of scenarios and acceptance criteria. What turns into bureaucracy is a document nobody reads; in SDD, the agent reads the spec on every task and the tests check it on every pull request.
Does SDD work for a small team?
It does: with a few people, the spec replaces some alignment meetings and keeps decisions that would otherwise live in someone's head. A small team can start with OpenSpec, or just spec and ADR templates in the repository, and add steps when the project calls for them.
Does SDD replace the product manager?
No: SDD gives the product manager a fixed place to decide. Whoever knows the business writes or approves what the software must do and the acceptance criteria; engineering writes the plan and the ADRs; the agent implements. The method makes explicit who decides what.
What is the difference between a spec and a user story?
A user story says who needs something and why; a spec says what the system does, as verifiable scenarios. A story usually becomes one or more scenarios in the spec, with acceptance criteria that tests can check, and the spec stays valid after the story is closed.
Sources
Master Timm · Updated on