A field guide to the practice that's reshaping how software gets built with AI agents.
TL;DR— Spec-Driven Development (SDD) makes aprecise, executable specificationthe source of truth and treats code as a generated, verifiable artifact. The spec declaresintent; the coderealizesit. In 2026 it went mainstream because AI agents are great at writing code and terrible at guessing what you meant.
Jump to: Why now · Specs vs. executable specs · Maturity model · Workflow · Tooling · EARS · Worked example · Caveats · Bottom line
The movement defines itself against "vibe coding" — the term Andrej Karpathy popularized in early 2025 for loosely prompting an AI and shipping whatever comes back. Vibe coding is great for throwaway prototypes and miserable for anything that has to be maintained.
SDD is the disciplined counterweight: if AI writes most of the code, then the specification becomes the highest-leverage artifact a human produces. The skill that matters shifts from typing the implementation to defining the intent precisely enough that a machine can't get it wrong.
This is the single most important distinction in the whole topic — and the one most "SDD explainers" skip.
| Traditional design docs | SDD specs | |
|---|---|---|
| Read by | ||
| Humans | Humans and agents | |
| Enforcement | ||
| Advisory — devs may diverge | Executable — tests fail on drift | |
| Lifecycle | ||
| Goes stale, becomes archaeology | Living, continuously validated | |
| Lives in | ||
| A wiki nobody opens | The repo + CI/CD |
"Traditional specs are read by humans, while SDD specs are executed as BDD scenarios, API contract tests, or model simulations."
— Deepak Babu Piskala,Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants(arXiv, Jan 2026)
Almost every serious 2026 source converges on the same ladder. Pick the rung you actually need — not the most aggressive one.
flowchart TD
A["<b>Spec-First</b><br/>specs seed generation,<br/>code is allowed to drift"]
B["<b>Spec-Anchored</b> 🎯<br/>specs + code evolve together,<br/>tests enforce alignment"]
C["<b>Spec-as-Source</b><br/>humans edit only specs,<br/>code is fully generated"]
A -->|"add living tests<br/>+ CI enforcement"| B
B -->|"trust generation,<br/>stop hand-editing code"| C
style B fill:#dff3e4,stroke:#2ea44f,stroke-width:2px
🎯
Recommendation:aim forspec-anchored. Spec-as-source is where the hype lives; spec-anchored is where the value is today.
Every major tool implements roughly the same pipeline, with a human review gate at each phase boundary to stop drift before it compounds:
flowchart LR
C[constitution] --> S[specify] --> CL[clarify] --> P[plan] --> T[tasks] --> I[implement] --> A[analyze]
| Phase | What happens |
|---|---|
| Constitution | |
| Project-wide rules the agent must always obey (language, frameworks, testing, deps) | |
| Specify | |
| What and why: user stories + acceptance criteria. No tech choices yet | |
| Clarify | |
| The agent surfaces ambiguities before any planning | |
| Plan | |
| How: architecture, data models, technical decisions | |
| Tasks | |
| Decompose the plan into atomic, independently-shippable items | |
| Implement | |
| Execute tasks, verifying each against its acceptance criteria | |
| Analyze | |
| Cross-check spec ↔ plan ↔ tasks for consistency |
⚠️
Golden rule:never skip from spec straight to code. Review the plan before task decomposition; review the tasks before implementation.
| Tool | Strengths | Best for |
|---|---|---|
| GitHub Spec Kit | ||
| Open-source, model-agnostic, the reference implementation | Teams avoiding vendor lock-in | |
| AWS Kiro | ||
| Agentic IDE with automated guardrails ("hooks"), deep AWS integration | AWS-native / serverless shops | |
| Claude Code (cc-sdd) | ||
Native /sdd:specify , /sdd:plan slash commands, terminal-first |
||
| Solo devs, CLI workflows | ||
| Cursor (Plan Mode) | ||
| IDE-first, inline diff review, MCP support for Spec Kit | Teams prioritizing UX | |
| OpenSpec | ||
| Lightweight, framework-agnostic, Markdown + YAML | Indie devs, minimal tooling | |
| BMAD-METHOD | ||
| Community methodology, constitution + multi-agent role-play | Teams wanting a flexible framework | |
| Tessl | ||
| Compliance-focused, audit trails, regulated templates | Fintech, healthtech | |
| Google Antigravity | ||
| "Agent-first," specification-constrained autonomy | Teams exploring deep agent autonomy |
The open-source reference everyone benchmarks against:
An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch.
Spec-Driven Development flips the script on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: specifications become executable, directly generating working implementations rather than just guiding them.
Requires ** uv**…
None of these are new. SDD's contribution is wiring them together as the primary artifact an AI agent generates from — not the documentation you write afterward.
AGENTS.md
- Spec Kit via MCPEARS (Easy Approach to Requirements Syntax) is the de facto standard for acceptance criteria that are unambiguous to humans and models. Five patterns cover almost everything:
| Pattern | Template | Example |
|---|---|---|
| Ubiquitous | ||
| The system shall … | ||
| The system shall log every auth attempt. | ||
| Event-driven | ||
| WHEN … THE system SHALL … | ||
| WHEN a user submits the login form THE system SHALL validate credentials. | ||
| State-driven | ||
| WHILE … THE system SHALL … | ||
| WHILE a sync is running THE system SHALL show a progress indicator. | ||
| Unwanted behavior | ||
| IF … THEN … | ||
| IF validation fails 3× THEN lock the account for 15 min. | ||
| Optional | ||
| WHERE … THE system SHALL … | ||
| WHERE MFA is enabled THE system SHALL require TOTP. |
The payoff: criteria written this way map almost 1:1 onto test cases — which is exactly what makes the spec executable rather than advisory.
Talk is cheap; here's a (trimmed) end-to-end slice so the artifacts are concrete.
📄 spec.md (excerpt)
## Feature: Passwordless magic-link login
### Acceptance criteria (EARS)
- WHEN a user submits a valid email
THE system SHALL send a one-time login link valid for 15 minutes.
- IF a login link is used more than once
THEN the system SHALL reject it with HTTP 410 Gone.
- WHERE the email is not associated with an account
THE system SHALL still return HTTP 202 (no account enumeration).
- THE system SHALL store link tokens hashed, never in plaintext.
### Out of scope
- Social login, SSO, password fallback.
## Stack
- Node 22 + Fastify, Postgres 16, Redis for token TTL.
## Data model
- magic_tokens(id, user_id, token_hash, expires_at, consumed_at)
## Decisions
- Tokens = 32 bytes CSPRNG, stored as SHA-256 hash.
- 202-for-unknown-email enforced at the controller layer.
- [ ] T1 migration: magic_tokens table
- [ ] T2 POST /auth/magic-link (issue + email) refs spec §1, §3
- [ ] T3 GET /auth/verify (consume + session) refs spec §2
- [ ] T4 contract tests for 202 / 410 paths
- [ ] T5 rate-limit issue endpoint (5/min/IP)
Notice the thread: each task cites the spec clause it satisfies. That traceability is the whole point — when a test fails, you know which intent broke.
Constitutional foundations
AGENTS.md
or .specify/memory/constitution.md
Specification discipline
specs/NNN-feature-name/
).Phase boundaries
Documentation & traceability
feat(auth): magic link, refs specs/004-magic-link/spec.md
./checklist
passes for security, accessibility, observability.SDD has real skeptics, and they're worth more than the hype:
Skip it: throwaway prototypes · solo, short-lived projects · exploratory work where requirements are still unknown.
Vendor-reported numbers should be treated as directional, not proven. With that caveat: early adopters (GitHub, AWS) report meaningfully higher first-pass success from agents working off a good spec, and Piskala's paper cites error reductions on the order of tens of percent when LLMs work from refined specs versus loose prompts. The consistent, less-disputable finding is a shift in where humans spend time — away from typing implementation, toward review and clarification.
If you take one number away, make it this one:
the spec is now where the thinking happens.
In 2026, SDD is best understood not as a tool but as a discipline: when agents write the code, the spec is the most leveraged thing a human can produce. The pragmatic path:
Building with SDD already? What's worked and what's been pure ceremony? Drop it in the comments. 👇
Compiled June 2026.