What Is Spec-Driven Development?

Quick answer
Spec-driven development writes a clear specification of what to build before generating code.
The spec becomes the contract the AI agent works against, reducing guesswork and drift.
It’s the natural evolution of vibe coding: keep the speed, anchor the intent.

What is spec-driven development?

Spec-driven development is a workflow in which you first write a specification — the requirements, behavior, constraints, and acceptance criteria for a change — and then use that specification to drive the implementation, whether written by a human or generated by an AI agent. The specification, not the conversation, becomes the source of truth. GitHub’s open-sourced Spec Kit accelerated the pattern’s adoption by standardizing how specs are structured and consumed.

Why it emerged

Two failure modes made it necessary. Intent drift: over a long AI session, the assistant gradually forgets or reinterprets what you originally asked for, and each prompt shifts the goal slightly. Context decay: as the conversation grows, the assistant loses earlier constraints and starts guessing. A written spec gives both you and the agent a stable, reviewable artifact to return to.

How it works

Write the spec before coding: what the feature does, how it behaves at the edges, what it must not do, and how you’ll know it’s done. Review that spec like you’d review code — it’s cheaper to fix intent than code. Then let the agent implement against it, and validate the result against the spec’s acceptance criteria. See How to Write a Spec an AI Coding Agent Can Actually Follow.

Why it matters

A spec separates “what should exist” from “what the code happens to do.” That makes the work reviewable, testable, and resumable — you can hand the same spec to a different agent or a human and get the same target. For AI-assisted work, it’s the difference between a coherent build and a pile of plausible edits.

Where this bites vibecoders
The moment you notice you’ve asked the assistant to “fix that thing again” three times, you’re experiencing intent drift, and the cure is to stop prompting and start specifying. A ten-minute spec saves hours of corrective prompting and gives you a thing to check the output against. It’s the highest-leverage habit in this whole catalog.

Where AI coding assistants get this wrong

Implementing from a one-line prompt and filling gaps with assumptions.
Treating a spec as optional detail rather than the contract to satisfy.
Drifting across a long session because nothing anchors the original intent.
Skipping acceptance criteria, so “done” is never actually defined.

Checklist

Write the spec before any code is generated.
State the goal, the behavior, the edge cases, and the non-goals.
Include acceptance criteria you can test against.
Review the spec with a human before implementation.
Validate the finished code against the spec, not just “it runs.”

FAQ

How is spec-driven development different from TDD?

Test-driven development writes failing tests first to drive code. Spec-driven development writes the specification first to drive intent — often before tests exist. They’re compatible: a good spec feeds directly into tests and acceptance criteria. See What Is Test-Driven Development (TDD)?.

Do I need a formal spec for a small change?

Scale it to the change. A one-line fix needs a one-line spec. A feature spanning files and data needs real structure. The principle — write intent down before building — applies at every size.

Is spec-driven development only for AI coding?

No, the idea predates AI: writing requirements before implementation is classic engineering. What changed is that a written spec is now directly machine-consumable, which makes it newly powerful for agents.