Spec-Driven Development

What Is Spec-Driven Development?

Spec-driven development is the practice of writing a precise specification, with requirements and acceptance criteria, before an AI agent starts building. The spec becomes the durable source of truth that the agent implements against and reviewers verify against, replacing the scattered prompt history that ad hoc AI coding leaves behind.

Key Takeaways

• The spec is the deliverable the human owns. Code becomes an output that can be regenerated; the spec records intent, constraints, and what "done" means.
• Acceptance criteria do double duty: they steer the agent during implementation and give reviewers an objective checklist afterward.
• Specs fix the biggest failure mode of agentic coding, which is the agent confidently building the wrong thing because requirements lived only in the engineer's head.
• Tooling has formalized the practice. GitHub's Spec Kit, Amazon's Kiro, and plan modes in agentic tools all structure work as specify, plan, then implement. Spec Kit alone drew over 126,000 GitHub stars and 11,000 forks within a year of its August 2025 launch [1].
• Spec quality is the new bottleneck. A vague spec produces plausible code that misses edge cases, and no amount of agent capability compensates for that.

How It Works

The workflow splits delivery into phases with a checkpoint between each. First comes the specification: what the feature does, its inputs and outputs, error behavior, non-goals, and a set of acceptance criteria concrete enough to test. Good specs read like a careful ticket plus a contract, not a novel. Many teams draft them with the model itself, letting it interrogate the requirements and surface ambiguities before a human signs off.

Next the agent, or the engineer with the agent, turns the spec into a technical plan: which files change, what the data model looks like, how the change is sequenced. Reviewing a plan takes minutes and catches architectural mistakes before they cost hours. Only then does implementation start. The agent builds against the spec, runs the tests derived from the acceptance criteria, and iterates until they pass. Because the spec sits in the repo as a file rather than in a chat log, a fresh agent session, a different tool, or a teammate can pick up the same work without archaeology through prompt history.

The final phase is verification. Human in the loop review checks the diff against the spec, criterion by criterion. This is the piece that separates the practice from vibe coding: acceptance is defined before generation, so "looks right" never substitutes for "meets the spec."

Example

A payments team needs webhook handling for a new provider. The lead writes a one-page spec: the five event types to process, idempotency keyed on event ID, exponential backoff on downstream failures, a dead-letter path after five attempts, and eight acceptance tests including a duplicate-delivery case. An AI coding agent proposes a plan, the lead corrects the queue choice, and the agent implements. Two of the eight tests fail on the first pass; the agent fixes both. Review takes twenty minutes because every criterion is checkable. Three months later, another engineer extends the handler by amending the spec first, and the original intent is still legible.

What People Get Wrong

The common objection is that spec-driven development is waterfall wearing a new badge. The comparison misses the cycle time. Waterfall failed because the gap between specification and working software was months, so specs rotted before contact with reality. Here the gap is minutes to hours, and the spec is versioned alongside the code and updated the moment reality pushes back. It behaves less like a big up-front design document and more like a tight loop of stated intent and immediate verification, closer in spirit to test-driven development than to anything from the waterfall era.

FAQ

How detailed should a spec be? Detailed enough that a competent stranger could judge whether an implementation satisfies it, and no more. Concrete acceptance criteria, explicit edge cases, and stated non-goals matter most. Prescribing line-level implementation detail wastes the agent's strengths and turns the spec into a maintenance burden.

Does every task need a spec? No. A rename, a dependency bump, or a one-line fix needs a sentence, not a document. The practice pays off on work with real ambiguity: new features, integrations, anything touching money, auth, or data. Teams usually set a threshold and skip the ceremony below it.

What tools support spec-driven development? GitHub Spec Kit and Amazon Kiro build the whole workflow around specs. More generally, the plan modes in Claude Code, Cursor, and similar tools, plus a specs directory in the repo and instructions in AGENTS.md or CLAUDE.md, get most teams there without new tooling. None of the options is complete: a June 2026 comparative study of six spec-driven frameworks, including Spec Kit and OpenSpec, found that no framework strongly covered all six process dimensions it assessed, so expect a trade-off between process depth and portability [2].

Sources

1. GitHub. "Star and fork counts for the github/spec-kit repository." https://github.com/github/spec-kit. Accessed August 2026.
2. arXiv. "Comparative assessment of six frameworks supporting AI software development agents." https://arxiv.org/abs/2606.04967. Accessed August 2026.