Spec-Driven Development Explained Simply

GitHub built a toolkit for it. Amazon built an entire IDE around it. And a large slice of the developer community thinks the whole idea is nonsense. Spec-driven development went from obscure to the most polarizing concept in AI coding in under a year.

Whether you end up loving it or hating it, you are going to need an opinion on it. This is what it actually is, what the data says, and the cases where writing a spec helps versus where it just slows you down.

What is spec-driven development?

Spec-driven development is a workflow where you write down what you want, clearly and in structured markdown, before you let an AI write a single line of code. That spec becomes the source of truth. The AI reads it, generates code to match, and you verify the output against the spec rather than against a one-line prompt and a hopeful feeling.

The name is new, the instinct is not. Senior developers have written requirements documents and OpenAPI specs for years. What changed is who reads the spec now. It used to be other humans. Today the reader is an AI agent: a literal-minded pair programmer that will hallucinate when the instructions get fuzzy. Writing for a human reviewer and writing for a machine that executes on its own are two different jobs.

What problem does it actually solve?

It solves code that gets written wrong faster than humans can catch it. AI coding agents can produce software quicker than any person, but the speed has a cost that shows up downstream. A METR study from July 2025 found experienced open-source developers were 19% slower at finishing issues when using AI tools, even though they believed the tools had sped them up by about 20%.

The pattern repeats in team data. Faros AI, drawing on telemetry from more than 10,000 developers, found AI lifted individual task completion by 21%, but time spent reviewing pull requests jumped 91% and bugs per developer rose 9%. Work moved faster into the queue and then clogged the part where humans check it.

METR study 19% slower

Experienced open-source developers took 19% longer to finish issues with AI tools, while believing AI had sped them up by about 20%.

PR review time +91%

Time spent reviewing pull requests nearly doubled once AI entered the workflow, across Faros AI telemetry from 10,000+ developers.

Bugs per dev +9%

Bugs per developer rose 9% over the same period. Individual task completion went up 21%, but the defects came with it.

Andrej Karpathy named the failure mode in a February 2025 post: vibe coding. You prompt an AI, accept whatever it returns, never read the diffs, and pray. For a throwaway prototype, fine. For anything you have to maintain, it is technical debt accumulating at machine speed. Spec-driven development is the deliberate opposite: decide what should exist before the machine builds it.

How does spec-driven development work?

The loop is simple once you have done it once. You start with an idea, then write a high-level spec describing what the feature does, its constraints, and its edge cases. The AI reads it and asks clarifying questions: where do you store this data, what happens on a timeout, what error does the user see. You answer until the ambiguity is gone.

From there the AI drafts a technical plan and breaks it into small tasks. You approve the plan, it implements each task, and you review every diff against the spec you already wrote. Tests get generated from the acceptance criteria baked into that spec. The spec is written once and consumed at every step after it, which is the structural difference from vibe coding.

1. 01 Start with an idea

   A feature, a fix, a migration. The same place every project starts.

2. 02 Write the spec

   Plain markdown: what it does, its constraints, its edge cases. This becomes the source of truth.

3. 03 AI asks questions

   “Where is this stored? What happens on timeout?” You answer until the ambiguity is gone.

4. 04 AI drafts a plan

   It turns the spec into a technical plan broken into small tasks. You approve it.

5. 05 AI implements

   It writes each task in turn. You review every diff against the spec, not against a vibe.

6. 06 Tests from the spec

   Acceptance criteria you already wrote become the tests. The spec verifies its own output.

The spec is written once at step 2 and read by the AI at every step after it. Change the feature later and you edit the markdown, not the code.

This is also where SDD asks more of you than a chat prompt does. You cannot hand-wave a spec the way you can hand-wave a request to a coworker who shares your context. The agent has no context except what you write down, so the gaps in your thinking surface immediately, as questions, before they become bugs.

The tools: Spec Kit, Kiro, and Tessl

Three tools dominate the space in 2026, and each takes a different position on how tightly the spec should control the code. GitHub Spec Kit is open source, has crossed 100,000 stars, and plugs into 30-plus coding agents including Claude Code, Copilot, and Cursor. Kiro is AWS’s agentic IDE, running on Claude under the hood, with a Requirements-to-Design-to-Tasks flow built into the editor. Tessl pushes the idea furthest.

Spec guides the code Spec replaces the code

Spec guides GitHub Spec Kit

Open source, 100,000+ stars, works with 30+ coding agents (Claude Code, Copilot, Cursor). The spec steers the work, but you still own and edit the code.

Spec structures Kiro

AWS’s agentic IDE, Claude-powered. Bakes a Requirements → Design → Tasks flow into the editor so the spec drives each phase, not just the first prompt.

Spec is the source Tessl

Pushes the idea furthest: you cannot edit the generated code. You change the spec and regenerate everything. The spec is the artifact you maintain.

With Tessl, you do not edit the generated code at all. You update the spec and regenerate everything, treating the spec as the real artifact and the code as its compiled output. That is the boldest version of the philosophy, and it is also the one most developers find hardest to accept. The table below lines the three up.

Is it just waterfall with extra steps?

This is the loudest criticism, and it is half right. Writing detailed requirements before any code does have the waterfall shape, and pretending otherwise is dishonest. The thing that breaks the comparison is iteration cost. In waterfall, changing direction meant months of rework. In SDD, you edit a markdown file and the AI regenerates the code in minutes.

That gap is the whole argument. Developer Roger Wong put it well: that is not waterfall, that is Agile wearing a trench coat. You keep the “decide what you want” discipline that waterfall got right and drop the slow, expensive build cycle that made waterfall painful. Whether that trade holds up depends entirely on how reliable the regeneration step is, which is exactly where the harder criticism lands.

Where the data turns against SDD

The sharpest pushback comes from people who have actually shipped with these tools, not from the comment section. Colin Eberhardt, CTO of Scott Logic, ran a head-to-head test and his iterative approach beat Spec Kit by roughly ten times. Spec Kit produced more artifacts, a stray bug, and hours of review for output his normal prompting matched in minutes.

With Spec Kit Iterative

Agent time 57 min 8 min

Lines of code ~989 ~1,000

Spec / markdown 4,839 lines none

Review time 5.5 hours 24 min

Bugs 1 0

~10× faster without SDD, on this task. The headline number that is hard to wave away.

Then there is spec drift. Birgitta Böckeler, who writes about SDD for ThoughtWorks, points out that most workflows today are spec-first but vague about spec maintenance. You write a clean spec, ship the feature, and six months later the code has moved on while the spec quietly becomes fiction. Tessl tries to solve this by forbidding code edits. Others treat specs as disposable history. Neither answer feels finished.

When should you use spec-driven development?

Use it when intent is worth capturing and the work will outlive the session. SDD pays off on greenfield projects, on cross-service migrations where you need to lock down intent before regenerating code, on compliance-heavy work that needs an auditable trail, and on complex features where ambiguity would otherwise cost you days of debugging. It also helps on any AI session long enough that the agent might forget what it is building.

It does not pay off everywhere, and forcing it where it does not fit is how SDD earns its bad reputation. Böckeler described using a full spec tool on a small bug fix as a sledgehammer to crack a nut. The same goes for exploratory prototyping, solo weekend projects, and large legacy codebases where writing a spec for existing behavior is harder than just fixing the thing.

Pays off

• Greenfield projects, where the spec is the only source of truth there is
• Cross-service migrations that need intent captured before code is regenerated
• Compliance-heavy work that demands an auditable paper trail
• Complex features where ambiguity would cost you days of debugging
• Long AI sessions where the agent might forget what it is building

Bad fit

• Small bug fixes: a sledgehammer to crack a nut
• Exploratory prototyping, where you cannot spec code you do not yet understand
• Solo weekend projects, where the overhead exceeds the work
• Large legacy codebases, where speccing existing behavior is harder than the fix

This judgment is the actual skill. Knowing when to write a spec and when to just let an agent run is worth more than mastering any single tool, and it is the part that takes reps to learn.

How to try spec-driven development today

The lowest-friction path is GitHub Spec Kit plus whatever coding agent you already use, whether that is Claude Code, Codex, Copilot, or Cursor. Run the init command, write a spec for your next real feature, and see if the output improves. That is the entire experiment, and it costs you one afternoon.

Keep the first spec small. Pick a feature you understand well enough to describe precisely, because the value of SDD is bounded by how clearly you can state what you want. If you cannot write the spec, that is useful information too: it means the design is not settled yet, and no amount of prompting will paper over that.

The verdict: hype or the future of AI coding?

Spec-driven development solves a problem that exists, and it has obvious limits. Both of those are true at once, which is why the topic is so divisive. The developers who get the most out of the next few years will be the ones who learn when to write a spec and when to just vibe code the thing, rather than treating either as a religion.

The durable skill underneath all of it is knowing what code should exist and being precise enough about it that a machine can build it for you. Most developers underestimate how hard that second part is. For the animated version, with every study, quote, and benchmark on screen, watch the full breakdown on YouTube.