Blog · Learn · 2026-11-07

What Is Spec-Driven Development? Definition and QA Guide

TL;DRSpec-driven development means writing down behaviour, states, edge cases, and acceptance criteria before a coding agent writes the code. It targets the dominant bug class in AI-generated code: the silent assumption, where the model fills an unspecified gap with a plausible default nobody reviewed. For QA, the payoff is that numbered acceptance criteria become the test plan, so testing starts from a list instead of a blank page.

Spec-driven development is a way of building software where you write a precise specification first — what the feature does, its inputs and outputs, its states and edge cases, and the acceptance criteria that define "done" — and then have a coding agent implement against that document instead of improvising from a one-line prompt. The spec, not the chat scrollback, becomes the source of truth: the agent builds from it, reviewers check against it, and the acceptance criteria convert almost directly into test cases. For anyone shipping AI-generated code, spec-driven development is the most practical answer to vibe coding's core weakness — code that runs but was never defined clearly enough to verify.

How is spec-driven development different from vibe coding?

Vibe coding is a loop: prompt, generate, eyeball the result, prompt again. It is fast and genuinely good for exploration, but the definition of the feature only ever exists in your head and in a conversation that scrolls away. Spec-driven development moves that definition into a written artifact that outlives the session.

DimensionVibe codingSpec-driven development
Source of truthThe last prompt that workedA written spec in the repo
Where ambiguity goesThe model guesses silentlyResolved before code is written
Review question"Does this look right?""Does this match the spec?"
Test planInvented afterwards, if at allFalls out of the acceptance criteria
Regenerating the featureRe-explain everything from memoryHand the agent the same spec
HandoverLives in one person's chat historyLives next to the code

Tooling has grown up around the practice — GitHub's open-source Spec Kit, AWS's Kiro editor, and the now-common convention of keeping agent instructions in-repo in files like AGENTS.md or CLAUDE.md. None of it is required. A one-page Markdown file in a specs/ folder gets you most of the benefit on day one.

What goes into a good spec?

A useful spec is short and checkable. Length is not the goal; removing guesswork is. Cover these seven things:

  1. User-visible behaviour, in plain language — what someone can now do that they could not before.
  2. Inputs, outputs, and data contracts — field names, types, required vs optional, what the API returns.
  3. Every state — empty, loading, partial, success, error, offline, unauthorised, and already-done.
  4. Edge cases and limits — duplicate submits, zero results, very long strings, expired sessions, concurrent edits.
  5. Non-goals — what this feature explicitly does not do, so the agent stops inventing scope.
  6. Acceptance criteria, written as testable statements: "Given an expired token, when the user submits the form, then they see a re-login prompt and no data is written."
  7. Open questions — the things you genuinely have not decided, flagged rather than left blank.

The test for a criterion is simple: could a stranger verify it without asking you a single question? If not, it is a wish, not a criterion. That one rule does most of the work.

How does spec-driven development change QA?

Three practical shifts, and they are the reason the practice matters more for agent-written code than for hand-written code:

Testing starts from a list instead of a blank page

The hardest part of QA on a vibe-coded app is not writing tests — it is knowing what to test when nobody wrote down what the thing was supposed to do. Numbered acceptance criteria give you a finite list to work through. One criterion, one check.

Review becomes behavioural, not stylistic

Without a spec, reviewing generated code collapses into reading it and deciding whether it looks plausible. Generated code almost always looks plausible — that is precisely what the model optimises for. With a spec, the review question changes to whether the described behaviour is actually implemented, which is a question you can answer by running the thing.

Regressions get a fixed target

Agents refactor broadly. When a prompt touches five files, the spec tells you what must still be true afterwards. Without one, you are comparing today's behaviour to a vague memory of last week's.

Does spec-driven development actually reduce bugs?

It reduces one specific and very common class of bug, and does almost nothing for the others. Being honest about that split is what makes it useful rather than a ritual.

The class it attacks is the silent assumption. A coding agent handed an underspecified prompt does not leave a blank or ask a question — it fills the gap with a plausible default. What happens on an empty list, whether the submit button disables on the second click, which timezone a date renders in, what the error copy says when the network drops: nobody decided, the model decided, and nobody noticed. These are the bugs that cluster in AI-generated code, and writing the behaviour down beforehand is the only cheap fix.

What a spec will not catch: environment and configuration differences between your machine and production, integration drift when a third-party API changes shape, performance under real data volumes, accessibility failures, and the enormous category of "a real person used it in a way nobody imagined." Those need something running against the deployed app. A spec tells you what should be true; only execution tells you what is. That is the division of labour described in our complete guide to AI QA.

How do you turn acceptance criteria into tests?

  1. Number the criteria in the spec so each one has a stable identifier you can cite in a test name or a bug report.
  2. Pick the thinnest check that proves each one. Many criteria are satisfied by a single assertion; do not build a full end-to-end journey for something a unit-level check settles.
  3. Automate the criteria that must hold on every deploy — the money path, auth, and anything a client would notice within a minute. AutoSim covers these as self-healing end-to-end tests, so a selector change from the next agent refactor does not quietly turn the suite red.
  4. Leave the rest as a written manual pass list. A ten-line checklist that someone actually runs before a client demo beats a hundred tests nobody maintains.
  5. Send the unspecified paths through personas. The criteria you wrote are the behaviour you imagined; Sims walks the product as different kinds of user and surfaces the paths the spec never mentioned.
  6. Keep the criteria-to-test mapping in the spec itself, so the next agent that reads the spec also learns which behaviours are already guarded.

When a human still finds something — and they will — Snap turns a right-click into a bug report carrying the console, network, and DOM state, so the fix starts from evidence instead of "it's broken on my end."

Where does spec-driven development still go wrong?

  • Stale specs. A spec that no longer matches shipped behaviour is worse than none, because it makes reviewers confident about the wrong thing. Update the spec in the same pull request as the code, or delete it.
  • Specs that describe implementation. "Use a useEffect hook to fetch on mount" is not a spec; it is a guess at an approach. Specify behaviour and let the agent choose the code.
  • Spec theatre. Twelve pages nobody reads buys you nothing. If the spec is longer than the feature, the feature was too big.
  • Over-specifying exploration. When you genuinely do not know what you want yet, vibe-code a throwaway prototype first, then write the spec from what you learned and regenerate properly.

How do you start on a project that has no specs?

Do not retro-spec an existing codebase — that project never finishes. Start with the next feature you were about to build anyway, and keep it to one page. Write the acceptance criteria before you open the agent, keep the file in the repo next to the code it describes, and add a line to your AGENTS.md telling the agent to read the spec folder first. After three or four features you will have the only documentation most small teams ever actually keep current: the spec for the parts that matter, next to tests that reference it.

For a broader pre-ship pass, pair this with a vibe coding QA checklist — the spec covers what you intended, the checklist covers what everyone forgets.

Scan your next build free

A spec tells you what should be true. Klavity checks what is actually true in the running app — persona-driven reviews with Sims, self-healing end-to-end tests with AutoSim, and right-click bug reports with Snap. Try Klavity free and find the bugs before your client or your users do.

Key takeaways

  • Write acceptance criteria before you open the coding agent, not after.
  • Make every criterion checkable by a stranger without asking you a question.
  • Turn numbered criteria into tests; automate the ones that must hold every deploy.
  • Update the spec in the same pull request as the code, or delete it.

FAQ

What is spec-driven development in simple terms?

It is writing a short, precise document describing what a feature does, its states, its edge cases, and the criteria that define done, and then having a coding agent implement against that document instead of a one-line prompt. The spec lives in the repo, so it outlasts the chat session and gives reviewers and tests a fixed target.

How is spec-driven development different from vibe coding?

Vibe coding keeps the definition of the feature in your head and in a chat history that scrolls away, so ambiguity gets resolved silently by the model. Spec-driven development resolves that ambiguity in writing before code is generated, which changes the review question from does this look right to does this match the spec.

Does a spec replace testing?

No. A spec tells you what should be true; only running the app tells you what is true. Specs do not catch environment and configuration differences, third-party API drift, performance under real data, accessibility failures, or unexpected real-user paths. Use the spec to generate your test list, then verify against the deployed app.

How long should a spec be?

One page for most features. The goal is removing guesswork, not volume. If the spec is longer than the feature it describes, the feature is probably too big and should be split. A good test is whether a stranger could verify every acceptance criterion without asking you a question.

How do I start spec-driven development on an existing codebase?

Do not try to retro-spec what already exists. Start with the next feature you were going to build anyway, write its acceptance criteria before opening the agent, keep the file in the repo beside the code, and point your agent instructions file at the spec folder. Update the spec in the same pull request as the code so it never goes stale.

Catch bugs the moment a human sees them

Klavity: right-click bug reports, AI personas that review your product, and self-healing tests.

Get started free