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.

1. 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.
2. 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."
3. 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:

    github
   / 
    spec-kit
  

💫 Toolkit to help you get started with Spec-Driven Development

🌱 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 …

View on GitHub

Supporting standards & frameworks that predate the AI wave but power SDD

• BDD: Cucumber, SpecFlow, Behave (Gherkin / Given-When-Then)
• API contracts: OpenAPI/Swagger, GraphQL SDL, Protocol Buffers, AsyncAPI
• Contract testing: Pact, Specmatic
• Model-based design: Simulink, SCADE

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.

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.md or .specify/memory/constitution.md before 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 /checklist passes 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.

✅ When SDD is worth it / ❌ when to skip it Worth it: using AI coding assistants · complex requirements · multiple maintainers · integration-heavy or regulated systems.

Skip it: throwaway prototypes · solo, short-lived projects · exploratory work where requirements are still unknown.

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:

1. Target spec-anchored , not spec-as-source.
2. Write acceptance criteria in EARS.
3. Keep code as the source of truth and tests as the enforcer.
4. 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

• Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants — Deepak Babu Piskala, arXiv (Jan 2026)
• Spec-Driven Development — Thoughtworks (Medium)
• Spec-Driven Development: The Definitive 2026 Guide — BCMS
• Spec Driven Development: The Fifth Generation of Programming — Mofi Rahman, Google Cloud (Medium)
• Same Patterns, New Hype: Spec-Driven Development — Brandon Kindred (Medium)
• Spec-Driven Development in 2026: The end of code as the center of development? — Devoteam
• Why the Future of Software Lies in Descriptions, Not Code — esveo
• What Is Spec-Driven Development? A Complete Guide — Augment Code
• GitHub Spec Kit

Compiled June 2026.