Ask ten engineers what spec-driven development is and you'll get ten slightly different answers, because the term went from niche to industry-standard in about eighteen months. This guide gives you the plain-English definition, the actual workflow, what belongs in a spec, why it is not a rerun of waterfall — and the question every other guide skips: how do you know your spec is any good before you build it?
Spec-driven development, defined
Spec-driven development (SDD) is a way of building software where the specification, not the code, is the source of truth. You write a durable document that states what you want built — goals, constraints, data model, and the acceptance criteria that define "done" — and an AI coding agent builds from that spec. Humans review the output against it. When something needs to change, you change the spec and regenerate, instead of patching the code and hoping the intent survives.
That single inversion is the whole idea. In ordinary AI-assisted coding, the intent lives in your head and in a scrolling chat history, and the code is the only durable artifact — so the code becomes the de facto spec, and nobody can read it as one. SDD flips it: the spec is the artifact you maintain, and the code is a build output generated from it. The spec is what you version, review, and trust.
Spec-driven development means you specify the behavior first, in a document precise enough that an AI agent can build it and a human can check it — and that document, not the code, is what you keep.
Where the term came from
The demand for SDD came from the failure mode of its opposite. In early 2025, Andrej Karpathy coined "vibe coding" — fully giving in to the vibes, describing what you want in natural language, and letting the model write code you barely read. It is fast and genuinely useful for prototypes. It also hits a wall on anything you have to maintain, because the intent was never written down anywhere durable. We walk through exactly where that wall is in vibe coding vs. spec-driven development.
The industry response in 2025–2026 was a wave of tooling built around writing the spec first. GitHub shipped Spec Kit, an open-source CLI and template set that drives a spec-first workflow through your coding assistant. AWS shipped Kiro, an agentic IDE that walks you through Requirements, Design, and Tasks before generating any code — now generally available with a CLI. Tessl pushed the idea furthest toward "spec-as-source," where the specification is the primary maintained artifact and code is regenerated from it. They differ in the details, but they all agree on the core claim: write the spec, build from it. We compare the major ones in Spec Kit vs. Kiro vs. Tessl vs. OpenSpec.
The spec-driven development workflow
Underneath the tooling, the spec-driven development workflow is a loop. The names vary, but the stages are consistent:
intent → spec → plan → tasks → build → verify
▲ │
└──────────── calibrate ◀──────────────┘- Intent. The raw idea — one or two sentences of what you want to exist. "A magic-link login that locks out brute-force attempts."
- Spec. The intent expanded into a durable, reviewable document: goals, scope, constraints, data model, and acceptance criteria. This is the artifact everything else hangs off of.
- Plan. The technical approach — architecture, key decisions, and the interfaces involved. Reviewed against the spec before any tasks are cut.
- Tasks. The plan broken into an ordered, individually testable list of work items, each tied back to an acceptance criterion.
- Build. The agent (Cursor, Claude Code, Codex, Copilot, Devin) writes the code, tests, and docs from the spec and tasks.
- Verify. The output is checked against the acceptance criteria — not against vibes. Did it actually satisfy what the spec stated?
The arrow back from verify to calibrate is the part that matters most and that most tools leave blank. We'll come back to it.
What actually goes in a spec
A spec isn't a wish list and it isn't a novel. It is a tight, structured document that an agent can act on without guessing. The load-bearing sections:
- Goals. What this feature is for, in plain terms. Why it exists.
- Scope and non-goals. What's in, and — just as important — what's explicitly out. Stated non-goals are what stop an agent from inventing scope.
- Constraints. The rules the build must respect: stack, performance budgets, security requirements, compliance, anything that must never happen.
- Data model and interfaces. The shapes of the data and the contracts between components — the schemas, endpoints, and types the build has to honor.
- Acceptance criteria. Testable statements of "done," written in given-when-then or EARS form. This is the section that makes the spec verifiable: given five failed login attempts, when a sixth is made, then the account locks for fifteen minutes.
- Out-of-scope, made explicit. A short list of things a reader might assume are handled but aren't — so the omission is a decision, not an accident.
EARS (Easy Approach to Requirements Syntax), incidentally, predates the AI era — it came out of Rolls-Royce in 2009 — and it became central to SDD precisely because its requirements are unambiguous enough for an LLM to act on. For a full, copy-pasteable template with all of these sections filled in, see how to write a spec for an AI coding agent.
Spec-driven development vs. vibe coding
The cleanest way to understand SDD is against its opposite. Vibe coding generates code straight from a conversational prompt; the intent lives only in chat history, and the code is the sole durable record. Spec-driven development writes the intent down first and treats that document as the thing you maintain.
| Dimension | Vibe coding | Spec-driven development |
|---|---|---|
| Source of truth | The latest prompt + the code | The spec |
| Best at | Prototypes, exploration | Anything you'll maintain |
| Intent lives in | Your head + chat history | A durable, reviewable document |
| Review surface | Diffs nobody read | Acceptance criteria |
This isn't a fight to the death — vibe coding is the right move on day one of a prototype. The deep dive on when to switch, and how to do it without losing speed, is in vibe coding vs. spec-driven development: surviving the 6-month wall.
Isn't this just waterfall?
It is the sharpest objection to SDD, and it deserves a straight answer: no, but the reason is specific. Waterfall also wrote a spec up front — and it failed, reliably, because that spec was expensive and disconnected. It took weeks of human effort to produce, it got frozen, the team built to it for months, and there was no mechanism to learn it was wrong until the build was finished. By then the document and reality had drifted apart.
Spec-driven development breaks both of those properties. An AI-drafted spec costs minutes, not weeks, so it is cheap to rewrite — you revise it as fast as you learn, which is the opposite of freezing it. And it is wired to a feedback loop: the rubric weights are tuned against the consensus of independent judges today — with real build outcomes feeding in as they report back — so the scoring gets better-calibrated over time instead of more stale. Waterfall froze an expensive, disconnected guess. SDD iterates a cheap, measured artifact. Those are opposites that happen to share a silhouette.
The question every guide skips
Here is the gap in nearly every SDD tutorial, tool, and launch post published so far. They all tell you to write a good spec. None of them tell you how to know your spec is good before you build it.
That omission is expensive, because an AI can write you 2,000 confident, well-formatted words that look exactly like a great spec and are actually plausible boilerplate — the kind of thing the model would produce for any vaguely similar prompt. A spec that looks complete but encodes none of your real intent is worse than no spec, because it hands everyone false confidence. And you find out it was hollow the same way vibe coders find out their code was wrong: by trying to build it.
The whole industry now agrees the spec is where AI builds succeed or fail. So why does almost nobody measure the spec? A bottleneck you don't measure is just a bottleneck you can't see.
The fix is to score the spec before you build it — and to score it with more than one judge, because a single reviewer carries the same blind spots into every spec. At SparkVibeAI, every spec runs through three independent judges: an LLM rubric across eight dimensions, a deterministic structural validator with no LLM in the loop, and a three-persona builder panel (a conservative senior, a strict junior, and a skeptical reviewer) that independently scopes the build. When judges that work differently agree, the agreement is real signal — especially when they run on different model families, where convergence is far stronger than two calls to the same model. When they disagree, the disagreement points at exactly which field is overstating quality.
How to get started with spec-driven development
You do not need to adopt a whole platform to start. A first pass:
- Pick something load-bearing. Not a throwaway script — the first feature where you'd be in real trouble if it broke. That feature earns a spec.
- Draft the spec, don't write it longhand. The reason people skip specs is that writing them by hand is slow. Have an AI draft it from your intent, then edit — that removes the excuse.
- Make the acceptance criteria testable. Every "done" statement should be checkable. If you can't write a given-when-then for it, it's still a wish, not a criterion.
- Score it before you build. Treat the spec like code: it gets reviewed before it ships. A calibrated reviewer that never gets tired beats a tired human skimming 2,000 words.
- Hand the scored spec to your builder. Cursor, Claude Code, Codex, Devin — every one of them builds dramatically better from a pressure-tested spec than from a one-line prompt. It's also why an agent loop needs a good starting spec: the spec is the objective the loop is missing.
Done this way, you keep most of the speed of conversational coding and shed most of its debt. The spec adds minutes. The wall it prevents costs weeks.
FAQ
What is spec-driven development in simple terms?
It means you write a clear specification first — goals, constraints, and acceptance criteria — and treat that document, not the code, as the source of truth. An AI coding agent builds from the spec, and humans review the result against it. The spec is what you maintain; the code is a build artifact generated from it.
Is spec-driven development the same as TDD or BDD?
No. TDD and BDD test code that already exists — you write tests, then code that passes them. SDD happens upstream of code: it specifies intent, constraints, and behavior before any code is written. They're complementary. SDD borrows from BDD by writing acceptance criteria in given-when-then or EARS form, and that's exactly what keeps the spec testable once an agent builds from it.
Do I need a special tool for spec-driven development?
No. You can practice it with a Markdown file and any AI coding agent — write the spec, hand it to the builder, review against the acceptance criteria. Tools like GitHub Spec Kit, AWS Kiro, and Tessl add structure and automation, but none of them score whether the spec is actually good before you build. That scoring step is the part most workflows skip.
Write the spec. Then find out if it's any good.
SparkVibeAI turns a one-line intent into a build-ready spec, then scores it with three independent judges before you ever hand it to a builder. It's spec-driven development with the one step every other workflow leaves out.