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 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)

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]

⚠️ Golden rule: never skip from spec straight to code. Review the plan before task decomposition; review the tasks before implementation.

The tooling landscape (2026)

The open-source reference everyone benchmarks against:

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:

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.

## 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.

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.

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. 👇

Compiled June 2026.