A field guide to the practice that's reshaping how software gets built with AI agents.
TL;DR — Spec-Driven Development (SDD) makes a precise, executable specification the source of truth and treats code as a generated, verifiable artifact. The spec declares intent; the code realizes it. 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
Why now? The "vibe coding" backlash
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.
Raw specs vs. executable specs
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)
[2602.00180] Spec-Driven Development:From Code to Contract in the Age of AI Coding Assistants
The rise of AI coding assistants has reignited interest in an old idea: what if specifications-not code-were the primary artifact of software development? Spec-driven development (SDD) inverts the traditional workflow by treating specifications as the source of truth and code as a generated or verified secondary artifact. This paper provides practitioners with a comprehensive guide to SDD, covering its principles, workflow patterns, and supporting tools. We present three levels of specification rigor-spec-first, spec-anchored, and spec-as-source-with clear guidance on when each applies. Through analysis of tools ranging from Behavior-Driven Development frameworks to modern AI-assisted toolkits like GitHub Spec Kit, we demonstrate how the spec-first philosophy maps to real implementations. We present case studies from API development, enterprise systems, and embedded software, illustrating how different domains apply SDD. We conclude with a decision framework helping practitioners determine when SDD provides value and when simpler approaches suffice.
arxiv.org
The maturity model: three levels
Almost every serious 2026 source converges on the same ladder. Pick the rung you actually need — not the most aggressive one.
- Spec-First — Specs seed the initial generation, then code is allowed to drift. Good for AI-assisted features and prototypes. Low overhead, no long-term guarantees.
- Spec-Anchored — Specs and code evolve together as living documentation; automated tests enforce alignment. Piskala's paper calls this "the sweet spot for most production systems."
- Spec-as-Source — Humans edit only the spec; code is fully generated and never hand-edited. Eliminates drift by design — but demands mature, trusted generation tooling. Still aspirational for most teams.
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 for spec-anchored. Spec-as-source is where the hype lives; spec-anchored is where the value is today.
The canonical workflow
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.
The tooling landscape (2026)
| 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:
🌱 Spec Kit
<div class="markdown-heading" dir="auto">
Build high-quality software faster.
An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch.
Table of Contents
- 🤔 What is Spec-Driven Development?
- ⚡ Get Started
- 📽️ Video Overview
- 🌍 Community
- 🤖 Supported AI Coding Agent Integrations
- 🔧 Specify CLI Reference
- 🧩 Making Spec Kit Your Own: Extensions & Presets
- 📚 Core Philosophy
- 🌟 Development Phases
- 🎯 Experimental Goals
- 🔧 Prerequisites
- 📖 Learn More
- 📋 Detailed Process
- 💬 Support
- 🙏 Acknowledgements
- 📄 License
🤔 What is Spec-Driven Development?
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.
⚡ Get Started
1. Install Specify CLI
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.Supporting standards & frameworks that predate the AI wave but power SDD
30-second tool-selection rubric
- Already in Claude Code? → Spec Kit + cc-sdd skills
- In Cursor? → Plan Mode +
AGENTS.md+ Spec Kit via MCP - AWS shop? → Kiro
- Regulated industry? → Tessl
- Want minimal ceremony? → OpenSpec
EARS: how to write specs an LLM can't misread
EARS (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.
A worked example: "magic-link login"
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.
🏗️ plan.md (excerpt)
## 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.
✅ tasks.md (excerpt)
- [ ] 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.
Recommendations & best practices
Constitutional foundations
- Commit
AGENTS.mdor.specify/memory/constitution.mdbefore the first spec. - Codify project-wide decisions as ubiquitous EARS statements: "The system shall use TypeScript strict mode."
Specification discipline
- One feature = one spec directory (
specs/NNN-feature-name/). - Keep specs to 1–3 pages; split if larger.
- Use explicit "out of scope" sections to bound the agent's exploration.
- Write in domain language (business intent), not implementation detail.
Phase boundaries
- Never jump spec → code. Review the plan, then review the tasks.
Documentation & traceability
- Cite specs in commits:
feat(auth): magic link, refs specs/004-magic-link/spec.md. - Treat specs as durable — they outlive the generated code.
- Run pre-flight
/checklistpasses for security, accessibility, observability.
The honest caveats
SDD has real skeptics, and they're worth more than the hype:
- It can be old wine in new bottles. Brandon Kindred's "Same Patterns, New Hype" (2026) argues SDD is largely waterfall/contract-design rebranded — and that "the value is the thinking you do while writing the spec, not the tooling around it."
- Drift and hallucination don't disappear. Thoughtworks stresses that executable code remains the source of truth requiring maintenance, explicitly rejecting the "specs alone suffice" view. They place SDD in the "Assess" ring of their Technology Radar — not "Adopt."
- Over-specification defeats the purpose. When a spec becomes pseudo-code, you've written the program twice.
- False confidence. Matching a wrong spec satisfies no real requirement.
- Tooling complexity can add ceremony without proportional value.
Skip it: throwaway prototypes · solo, short-lived projects · exploratory work where requirements are still unknown.✅ When SDD is worth it / ❌ when to skip it
Worth it: using AI coding assistants · complex requirements · multiple maintainers · integration-heavy or regulated systems.
What the data says (read with a skeptic's eye)
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.
The bottom line
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:
- Target spec-anchored, not spec-as-source.
- Write acceptance criteria in EARS.
- Keep code as the source of truth and tests as the enforcer.
- Use the tooling (Spec Kit, Kiro, cc-sdd) to enforce the loop — not to replace the thinking.
Building with SDD already? What's worked and what's been pure ceremony? Drop it in the comments. 👇
📚 Sources
Compiled June 2026.
Top comments (0)