What Is Spec-Driven Development?

Table of Contents

Every developer has now experienced the “AI demo high”: you describe a feature, the agent builds something that almost works, you iterate a few more times, and thirty minutes later you have spaghetti that vaguely resembles what you wanted.

That’s vibe coding. It’s fast. It’s fun. And it falls apart at scale.

Spec-Driven Development (SDD) is the antidote — a structured approach where you write the specification first and let the AI handle implementation. Not because you want to slow down, but because a good spec makes the agent dramatically faster and more reliable.

The Core Idea
#

SDD flips the traditional development loop:

Old loop: write code → write tests → document what you built
SDD loop: write spec → AI generates code → code is disposable, spec is the truth

The spec isn’t a README afterthought. It’s a contract: what the system does, how it behaves at the edges, what constraints it operates under. The AI doesn’t guess at intent — it executes against a document that captures intent precisely.

This sounds familiar because it is. It’s what good software engineers do in their heads before touching a keyboard. SDD just makes that mental model explicit, and hands it to the agent as context.

The Four-Phase Workflow
#

In practice, SDD follows a repeatable structure:

1. Specify — Describe what you’re building and why. User stories, acceptance criteria, edge cases. The more precisely you capture intent here, the less correction you’ll do later. The AI can help draft and challenge this document — treat it like a pairing session.

2. Plan — Define the technical constraints: stack, patterns, architectural decisions, service boundaries. The agent produces an implementation plan grounded in your spec. Review it before a single line of code is written.

3. Break down — The plan becomes concrete, testable tasks. Each task has inputs, expected outputs, and validation criteria. Tasks that can run in parallel are flagged. Dependencies are explicit.

4. Implement — The agent works through the task list, using the spec and plan as context for every decision. When it gets stuck or diverges, you update the spec, not the code.

The key insight: the spec is the thing you maintain. Code is regenerated as needed.

Is This Just Waterfall with AI?
#

It’s the most common objection, and it’s worth taking seriously.

Waterfall failed for a specific reason: the cost of discovering your specification was wrong came after months of implementation. Fixing a misunderstood requirement meant rewriting systems that took teams quarters to build. The feedback loop was catastrophically long.

SDD compresses that loop to minutes. You can generate a 2,000-line implementation, discover the architecture is wrong, update the spec, and regenerate — in an afternoon. When code is cheap to produce, the economics of writing a good spec upfront change completely.

What remains from waterfall is the discipline of thinking before building. That part was always correct. SDD keeps it.

Three Levels of Commitment
#

Not every team needs to go all the way. Martin Fowler’s team recently mapped out three patterns for how teams are using SDD in practice:

Spec-first: The spec guides the AI but code remains primary. Think of it as structured prompting — you write requirements and the agent references them, but you’d never throw the code away.
Spec-anchored: The spec persists as a governing contract. Code can diverge temporarily, but the spec is the source of truth for reviews, onboarding, and future changes.
Spec-as-source: The spec is the source. Code is treated as a build artifact — an intermediate product between your requirements and compiled binaries. You maintain the spec; the agent handles the rest.

Most teams land on spec-anchored today. Spec-as-source is where the genuinely radical practitioners are headed, and the tooling is catching up fast.

The Tooling Ecosystem in 2026
#

The SDD tooling landscape has consolidated fast. As of mid-2026, Martin Fowler has catalogued 30+ distinct agentic coding frameworks that implement some version of spec-first development — up from a handful at the start of the year. McKinsey has formally endorsed SDD as an enterprise implementation pattern. The methodology has moved from practitioner blog posts to board-level IT strategy documents.

GitHub Spec Kit v0.3.2 remains the closest thing to a canonical open-source SDD toolkit: works with 22+ AI coding platforms including Claude Code, GitHub Copilot, Amazon Q, and Gemini CLI. Its slash commands structure the full workflow — /speckit.constitution, /speckit.specify, /speckit.plan, and parallel task generation with explicit file paths. One engineer shipped a full CLI tool with TUI and web interfaces in under three days using it.

Amazon Kiro, launched May 7, 2026, is the most significant commercial SDD platform yet — not a plugin, but a ground-up IDE built on Code OSS as a full replacement for Amazon Q Developer. Kiro formalizes the three-document SDD contract: requirements.md captures user stories and acceptance criteria in EARS format, design.md specifies the technical architecture, and tasks.md breaks work into a verifiable implementation checklist. Agent Hooks fire on file save, PR open, and repo events to cascade spec changes through the codebase automatically. Kiro routes reasoning-heavy spec work to Claude Sonnet and high-throughput code generation to Amazon Nova via Bedrock. Free tier: 50 interactions/month. Pro: $19/month.

OpenSpec targets brownfield projects with delta markers that track spec changes relative to existing functionality — a harder problem than greenfield that most frameworks still ignore.

For Claude Code users specifically, several community-maintained spec workflows exist on GitHub, including claude-code-spec-workflow which automates the requirements → design → tasks → implementation pipeline.

Google’s Jules agent (now GA, powered by Gemini 3.1 Pro) has built SDD-style Plan Mode as a first-class feature. Windsurf’s Plan Mode, shipped with Wave 13, takes a similar approach. When the mainstream tools build spec-first planning into their default UI, SDD practices — explicit requirements, upfront constraint capture, structured decomposition — become the default mode of AI-assisted development, not a specialist methodology.

What Makes a Good Spec?
#

The quality of the spec determines the quality of the output. A few principles that hold up in practice:

Be explicit about constraints, not just features. “Users can reset their password” is a feature. “Password reset tokens expire after 15 minutes, are single-use, and must invalidate all active sessions on use” is a spec. The agent needs the second version to make sound implementation decisions.

Write acceptance criteria, not implementation details. Specify the behavior, not how to achieve it. The agent is better than you at picking implementation details; it’s not better than you at knowing what the system should do.

Define the edges. What happens when the API is down? When the user provides invalid input? When a race condition occurs? Agents that don’t have edge cases specified will make choices for you — sometimes good ones, often not.

Keep the spec updated. This is where most teams fail. When a requirement changes, update the spec before touching the code. If the spec drifts from reality, you lose the main advantage of the approach.

The Bigger Picture
#

Anthropic’s 2026 Agentic Coding Trends Report documents how fast this is moving in production: TELUS has deployed 13,000+ custom AI solutions with 30% faster engineering cycle times and 500,000+ hours saved. Zapier reports 800+ internal agents in active use. McKinsey cites 20–40% operating expense reductions at AI-centric organizations. Mercado Libre has set a public target of 90% autonomous coding across 23,000 engineers by Q3 2026 — the most ambitious production commitment in the industry. Google reports that 75% of new code at the company is now AI-generated. These aren’t pilot numbers.

Dario Amodei has predicted that within months, 90% of all code will be written by AI. Whether or not that exact timeline holds, the direction is clear: the bottleneck in software development is shifting from writing code to knowing what to build.

Spec-Driven Development is what happens when that shift gets formalized. Engineers who are good at capturing requirements, thinking through constraints, and communicating intent precisely will find their leverage increasing substantially. Engineers who relied on implementation skill alone should be paying attention.

The spec is the new source of truth. The code is the build artifact. That’s the paradigm shift, and it’s already happening.

Keep reading
#

The Spec File as Source of Truth — how to write a spec an agent can implement without hand-holding
Agentic Coding 101 — the plan → build → test → ship loop SDD runs on
The Complete CLAUDE.md Guide — give your agent the project context that makes specs executable
Claude Code: The Complete Hub — the terminal-native agent built for this workflow

Updated 2026-03-28: Added Jules/Gemini and Windsurf Plan Mode context; updated real-world deployment numbers from Anthropic’s 2026 Agentic Coding Trends Report. Updated 2026-06-06: Added Amazon Kiro GA (May 7, 2026), expanded tooling ecosystem to 30+ frameworks, added Mercado Libre 90% autonomous coding target and Google 75% AI-generated code data.

Sources:

The Core Idea#

The Four-Phase Workflow#

Is This Just Waterfall with AI?#

Three Levels of Commitment#

The Tooling Ecosystem in 2026#

What Makes a Good Spec?#

The Bigger Picture#

Keep reading#