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
#

Two weeks ago, GitHub released Spec Kit v0.3.2 — an open-source toolkit that formalizes the SDD workflow and works with 22+ AI coding platforms including Claude Code, GitHub Copilot, Amazon Q, and Gemini CLI.

Spec Kit introduces slash commands that structure the entire workflow: /speckit.constitution to define your project’s principles, /speckit.specify to describe what you’re building, /speckit.plan to produce an implementation plan, and task generation that breaks work into parallel and sequential steps with explicit file paths.

Developers are already building serious things with it. One engineer shipped a full CLI tool with TUI and web interfaces in under three days — zero lines written by hand.

On the IDE side, Kiro (built on AWS infrastructure) implements SDD natively using EARS syntax (Easy Approach to Requirements Syntax) with hooks that keep the spec synchronized as the agent works. OpenSpec targets brownfield projects with delta markers that track what’s changing relative to existing functionality — a harder problem than greenfield, and one most frameworks 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.

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
#

Dario Amodei predicted this month that within six months, 90% of all code will be written by AI. Whether or not that 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.

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#