The Complete Guide to Spec Driven Development (SDD)
As AI coding agents become more capable, a fundamental problem has emerged: the agents are fast, but the work is increasingly hard to control.
An AI agent will generate code confidently regardless of whether it has understood the requirements correctly. It will make architectural decisions without knowing what decisions were made last week. It will complete one phase of a feature while silently contradicting the design of another phase.
Spec Driven Development (SDD) is a methodology that addresses this. It provides the missing layer of structure that makes AI-assisted development reliable at scale.
What is Spec Driven Development?
SDD is a software development methodology where structured specifications are created and maintained as first-class artifacts — before coding begins, not as an afterthought.
A spec in SDD is not a traditional requirements document. It's a living artifact that:
- Defines what "done" looks like in terms of specific, testable acceptance criteria
- Captures key constraints and architectural decisions
- Tracks implementation status as the feature is built
- Serves as the source of truth for AI agents working on the feature
The crucial distinction from traditional specs: SDD specs are designed to be read by AI agents, not just humans. They're structured to provide the context an agent needs at the start of each session, and they're verifiable — you can check whether the implementation matches the spec.
The Problem SDD Solves
To understand why SDD matters, consider what happens without it.
Context loss across sessions. Every AI coding session starts from zero. An agent that helped you design an authentication system yesterday has no memory of those decisions today. Without a spec, you either re-explain everything (slow and inconsistent) or the agent makes up context it doesn't have (dangerous).
Spec drift. Even when a feature starts correctly, implementation can drift from the original intent as it grows. New edge cases appear, different agents handle different parts, small decisions compound. Without a spec to check against, drift often isn't caught until the feature ships.
Parallel agent conflicts. When multiple agents work simultaneously — one on the frontend, one on the backend, one on tests — they make decisions independently. Without shared specs, they make incompatible decisions. The interface the frontend agent designed doesn't match what the backend agent built.
Scope creep without visibility. Agents are helpful. When they encounter an ambiguity, they resolve it. When they see an adjacent improvement, they make it. Without specs, this helpful behavior is invisible until you review the code — and by then, the feature may have grown far beyond what was intended.
SDD creates a persistent, shared source of truth that prevents all of these problems.
Core Concepts
Specs
A spec is a structured document describing a single unit of work — typically a user story or feature. In SDD, specs live in your repository alongside your code.
A well-formed SDD spec contains:
- User story — who needs this and why ("As a developer, I want to...")
- Acceptance criteria — specific, testable conditions that define done
- Constraints — what this feature must not do, limits, dependencies
- Technical decisions — architectural choices that have been made and should not be revisited
- Implementation status — which criteria are complete, in progress, or pending
Acceptance Criteria
Acceptance criteria are the most important part of a spec. They answer the question: "How will we know this feature is done?"
Good acceptance criteria are:
- Specific — "The search results update within 200ms of keypress" not "The search is fast"
- Testable — you can write a test (automated or manual) that verifies the criterion
- Complete — they cover the happy path, error cases, and edge cases
Vague acceptance criteria are the root cause of most SDD failures. If an agent can interpret a criterion in multiple ways, it will pick the wrong one.
Drift Detection
Drift detection is the process of comparing the current implementation against the spec to identify divergences. In a well-implemented SDD workflow, drift detection runs automatically — either in CI/CD or as part of the agent's workflow.
Common forms of drift:
- A feature was implemented, but a specific acceptance criterion was never verified
- The implementation handles a case differently than the spec describes
- The spec was updated, but the code wasn't
Catching drift early is far cheaper than catching it in production.
The Tech Decision Log
Beyond the spec itself, SDD encourages maintaining a lightweight record of architectural decisions. When your team (or your AI agents) decide to use a particular pattern, structure, or library, that decision gets recorded.
This prevents the same decision from being made differently in different sessions, and it prevents agents from "helpfully" undoing decisions that were made deliberately.
The SDD Workflow
SDD follows a five-step cycle for every feature:
1. SPEC → Write the user story and acceptance criteria
2. APPROVE → Human reviews and approves the spec before coding starts
3. IMPLEMENT → Agent implements against the spec
4. VALIDATE → Verify implementation against acceptance criteria
5. MERGE → Integrate when all criteria passStep 1: Write the Spec
Before any code is written, create the spec. Include:
- The user story
- All acceptance criteria (aim for specificity over brevity)
- Known constraints and dependencies
- Any architectural decisions you've already made
The spec doesn't need to be exhaustive at this stage — you can refine it — but it should be clear enough that an AI agent could start implementing without needing to invent requirements.
Step 2: Approve the Spec
This step is non-negotiable in SDD. A human reviews the spec before implementation starts.
The review answers three questions:
- Does the spec capture what we actually want to build?
- Are the acceptance criteria complete and specific enough?
- Are there constraints or decisions we need to add?
Approval is the contract between the human and the AI agent. Without it, agents are guessing at requirements.
Step 3: Implement
With an approved spec, implementation begins. The agent reads the spec at the start of each session and works toward satisfying the acceptance criteria.
In practice, this means:
- The agent references specific criteria as it works ("Implementing criterion 3: user can filter by category")
- When the agent is uncertain, it resolves ambiguities in ways that align with the spec
- The agent marks criteria as it completes them
Step 4: Validate
After implementation, each acceptance criterion is verified. Some can be verified automatically (by running tests), others manually.
This step is where drift is caught. If the implementation doesn't satisfy a criterion, the work isn't done — regardless of whether the code "looks good."
Step 5: Merge
Only after all criteria are verified does the feature merge. This is a higher bar than traditional code review, which typically focuses on code quality rather than behavioral correctness.
SDD vs Other Methodologies
SDD vs TDD (Test Driven Development)
TDD and SDD are complementary, not competing.
TDD is about the implementation cycle: write a failing test, write code to pass it, refactor. It operates at the code level.
SDD is about the requirements cycle: write a spec, get approval, implement, verify against the spec. It operates at the feature level.
In practice, SDD specs inform the tests that TDD uses. An acceptance criterion like "search results update within 200ms" becomes a performance test. The two methodologies work together naturally.
For a deeper comparison, see SDD vs TDD: Why Spec Driven Development Changes the Game.
SDD vs BDD (Behavior Driven Development)
BDD is the closest methodology to SDD. Both focus on describing behavior rather than implementation, and both use structured acceptance criteria.
The key difference: BDD is typically expressed in formal Given/When/Then syntax (Gherkin) and is designed to be executable as tests. SDD acceptance criteria are more flexible — they don't need to follow a specific syntax and can describe behaviors that are difficult to automate.
SDD also has a stronger focus on the AI agent use case — keeping agents on-spec across sessions is a challenge that BDD doesn't specifically address.
SDD vs Traditional Spec Documents
Traditional spec documents (PRDs, functional specs) are written for humans and often abandoned once development starts. They're too long to share with AI agents, too vague for automated verification, and rarely updated as the feature evolves.
SDD specs are shorter, more structured, and designed to stay current. They're intended to be read by both humans and AI agents, and they track implementation status so you always know where the feature stands.
Tools for SDD
Planu
Planu is an MCP server that implements the full SDD workflow as 32 focused tools accessible to any AI agent. It handles:
- Creating and storing specs in a structured format
- Sharing specs with AI agents at the start of each session
- Tracking implementation status per acceptance criterion
- Running drift detection to catch when implementation diverges from spec
- Managing parallel specs to prevent conflicts between simultaneous agents
Planu is language-agnostic — it works with TypeScript, Python, Go, Rust, Java, and any other language your project uses. It integrates with Claude Code, Cursor, Windsurf, Cline, and any other MCP-compatible AI tool.
Manual SDD (No Tools)
SDD doesn't require specialized software. You can implement the core workflow with:
- Markdown files in your repository for specs
- A shared template for acceptance criteria
- A convention for marking criteria as done (e.g., checkboxes)
- Code review checklists that verify implementation against specs
This is how most teams start. The overhead is low and the value is immediate.
Getting Started with SDD
If you're starting from scratch, here's a practical first week:
Day 1: Write your first spec
Pick one feature you're about to build. Before writing any code, write a brief spec:
- One-sentence user story
- 3-5 acceptance criteria (be specific)
- Any known constraints
Day 2-3: Implement against the spec
Start each AI agent session by sharing the spec. Reference specific criteria as you work. Notice how differently the agent behaves when it has clear acceptance criteria versus vague instructions.
Day 4: Validate
Go through each criterion and verify it's satisfied. You'll almost certainly find at least one that's incomplete or implemented differently than intended.
Day 5: Reflect
What worked? What acceptance criteria were too vague? What constraints should you have specified upfront? Use these observations to improve the next spec.
Using Planu to automate this
If you want the workflow automated from day one, install Planu and use create_spec to create your first spec. The tool guides you through the structure and stores everything in a format your AI agent can read directly.
Common Mistakes
Criteria that are too vague. "The UI should be responsive" is not a useful criterion. "The layout renders correctly at 320px, 768px, and 1440px" is.
Skipping the approval step. When developers skip approval and go straight from writing specs to implementing, they often discover the spec was wrong halfway through implementation. The approval step catches this early.
Specs that describe implementation instead of behavior. "Uses a debounce function with 200ms delay" describes implementation. "Search results update no more than once per 200ms of user typing" describes behavior. The latter gives the agent more flexibility while still specifying what matters.
Not updating specs as requirements change. A spec that doesn't reflect the current requirements is worse than no spec — it actively misleads AI agents. When requirements change, update the spec first, then implement.
Too many criteria per spec. Specs with 30+ acceptance criteria are hard to implement in a single session and hard to validate. Split large features into smaller specs. A good target is 5-15 criteria per spec.
Conclusion
SDD doesn't make AI coding slower — it makes AI coding reliable at scale. The upfront investment in clear specs pays back quickly when you're no longer debugging features that implemented something other than what was intended.
The methodology is deliberately simple: write what done looks like before you start, approve it, implement it, verify it. The complexity that exists is in executing these steps consistently, especially under pressure to ship quickly.
Start with one feature. Write a spec. See what it changes.
Further Reading
- SDD vs TDD: Why Spec Driven Development Changes the Game — detailed comparison
- Why AI Coding Agents Need Specs — the problem in depth
- Vibe Coding is Fun Until It Breaks — when to add structure
- Getting Started with Planu — implement SDD with tooling support
- SDD Workflow Guide — Planu's implementation of the SDD workflow