Week one
Use one change proposal on a real ticket. Require a reviewer to challenge non-goals before implementation starts.
SDD workflow
Spec-Driven Development (SDD)
SDD turns a feature request into a chain of files reviewers can inspect: spec.md, design.md, tasks.md, and evidence.md. The point is not heavier process. The point is to stop humans and AI agents from coding against assumptions nobody reviewed.
The SDD artifact chain
Intent
spec.mdDefines goal, non-goals, acceptance criteria, edge cases, and release evidence before implementation starts.Versioning
specs/Keep the spec as code when the decision must live in git, be reviewed in PRs, and stay connected to implementation evidence. Open the Spec as Code Hub.Design
design.mdRecords architecture choices, rejected alternatives, interfaces, rollout order, and operational constraints.Execution
tasks.mdBreaks work into reviewable slices with owners, allowed files, acceptance links, and test commands.Proof
evidence.mdConnects criteria to tests, screenshots, logs, metrics, manual checks, and rollout stop signals.Why SDD improves AI-assisted delivery
| Failure mode | What SDD changes | Review signal |
|---|---|---|
| Vague prompt becomes broad diff | The spec states non-goals and allowed behavior before the agent starts. | Out-of-scope code can be rejected without debate. |
| Architecture is invented mid-generation | The design doc names interfaces, constraints, and rejected alternatives. | Generated code must follow the approved shape. |
| Large PR is hard to review | Tasks split implementation by acceptance criterion and file ownership. | Reviewers can inspect smaller, testable slices. |
| Approval is treated as proof | Evidence logs tie criteria to tests, screenshots, metrics, and rollout gates. | Merge review has something concrete to verify. |
How to adopt SDD without turning it into ceremony
Start with one high-risk ticket, not a company-wide process change. Good first candidates are payment flows, public APIs, migrations, permissions, notification delivery, or anything where a broad AI-generated diff would be expensive to review. The first packet should be small enough that a reviewer can read it in ten minutes.
The adoption rule is simple: only add an artifact when it reduces ambiguity. A small UI copy change may need only spec.md. A public API change may need design.md, tasks.md, and evidence.md. If a document does not change a decision, test, or release gate, it is probably ceremony.
Week two
Add task files only for work that needs narrow file ownership, multiple reviewers, or AI coding agent boundaries.
Week three
Add evidence logs for high-risk changes and compare release review quality against the old process.
Copy-ready SDD templates
Change Proposal
Turn a vague request into a reviewable spec with goal, non-goals, criteria, open questions, and evidence.
Open templateDesign Doc
Capture architecture choices, interfaces, constraints, rejected alternatives, rollout order, and rollback.
Open templateTasks Plan
Split implementation into reviewable tasks with owners, allowed files, acceptance links, and test commands.
Open templateEvidence Log
Record tests, screenshots, logs, metrics, manual checks, and release stop signals against the spec.
Open templateAI Coding Review
Review generated code for spec alignment, file drift, missing tests, and behavior added outside scope.
Open templateEngineering Constitution
Define team rules for spec gates, evidence standards, AI coding boundaries, and exceptions.
Open templateSDD, spec-first, TDD, and BDD
| Method | Primary question | Best used for |
|---|---|---|
| Spec-first development | What behavior should exist before code is written? | Clarifying product and engineering decisions before implementation. |
| Spec as code | Where should the spec live and how should it be reviewed? | Keeping spec.md in git so PR review, tests, and release evidence can reference one artifact. |
| Spec-driven development | Which repo artifacts should guide planning, coding, and evidence? | Coordinating humans and AI agents through reviewable files. |
| TDD | Which tests should drive implementation? | Proving units, contracts, and regressions during coding. |
| BDD | Which examples describe user-visible behavior? | Writing shared examples in business-readable language. |
What current SDD tools teach
OpenSpec pattern
Keep the proposed change reviewable before code generation starts. The valuable idea is explicit change intent, not tool lock-in.
Superpowers pattern
Give coding agents durable skills and repo rules so repeated work follows the same standards instead of a fresh chat each time.
Spec Kit pattern
Move from specification to plan to task execution so AI-assisted implementation has a visible decision trail.
FAQ
What is spec-driven development?
Spec-driven development is a workflow where product behavior, constraints, implementation tasks, and verification evidence are written as reviewable artifacts before major code changes begin.
How is SDD different from spec-first development?
Spec-first development is the broad principle of writing behavior before code. SDD is a more explicit repo workflow that usually includes spec, design, tasks, and evidence files.
Does SDD replace TDD or BDD?
No. SDD decides the behavior and constraints first. TDD and BDD can then provide tests and examples that prove the spec was implemented correctly.
Why does SDD matter for AI coding?
AI coding agents need narrow instructions, non-goals, allowed files, and evidence requirements. SDD gives the agent a reviewable source of truth before it changes code.
What is the smallest useful SDD packet?
A small SDD packet can be one folder containing spec.md, tasks.md, and evidence.md. Add design.md when architecture choices or trade-offs need review.
Use the SDD templates on one real ticket first. Keep the packet small enough to review, but specific enough to stop implementation drift.