Spec-Driven Development

Spec-driven development inverts the usual order of an AI coding session. Instead of describing a change in a chat message and steering the result, you write a specification first - what the feature must do, what counts as done, what is out of scope - and the agent implements against that document. The spec is reviewed, versioned, and amended like code. The code is what falls out of it.

The argument for doing this is economic rather than moral. Give a capable agent a vague prompt and it does not stall or ask for help. It produces plausible, well-formed, confidently-written code that compiles, passes a linter, and solves a problem adjacent to the one you had. Because the output looks finished, nothing signals that a decision was guessed. The mistake then surfaces in review, in QA, or in production - each a more expensive place to have the conversation than a paragraph nobody has implemented yet.

A specification moves the disagreement to the cheapest possible moment. Two engineers who read the same acceptance criterion differently discover that in minutes, and the fix costs one sentence. The same disagreement found in a nine-hundred-line diff costs a re-implementation. Agents worsen that asymmetry, because they produce the expensive artifact so fast that there is no natural pause in which somebody would have noticed.

The loop is usually summarized as specify, plan, tasks, implement, which is one step short. GitHub's Spec Kit, the reference implementation, lists constitution as step three of seven in its own getting-started sequence and puts it in the core command table, not the optional one. The accurate core loop is constitution, specify, plan, tasks, implement - and each stage has a characteristic failure when skipped.

The optional commands are gates, not stages. Analyze cross-checks spec, plan, and task list and reports where they have drifted apart; checklist generates review criteria to walk through before accepting work. Neither writes code. Both exist because the expensive errors here are inconsistencies between documents that each look fine alone.

Spec Kit is MIT licensed and installs as a CLI called specify, which scaffolds prompt templates and directory layout into an existing project. One detail catches out anyone following an older tutorial: every slash command is namespaced with a speckit. prefix. The bare /specify and /plan forms are pre-v0.0.30 names and no longer appear in the README.

# Install the CLI, pinned to a release you have tested against
uv tool install specify-cli --from git+https://github.com/github/[email protected]

# Scaffold the workflow into a project, wired to your agent of choice
specify init my-project --integration copilot

# Then, inside the coding agent, run the core loop:
/speckit.constitution    # durable project-wide rules
/speckit.specify         # the WHAT and the WHY
/speckit.clarify         # optional, recommended before planning
/speckit.plan            # the HOW: stack, architecture, constraints
/speckit.tasks           # decompose into independently verifiable units
/speckit.analyze         # optional gate: cross-check spec, plan, tasks
/speckit.implement       # the agent executes the task list

# Also in the core set:
/speckit.taskstoissues   # push the task list out as tracker issues
/speckit.converge        # reconcile drift between artifacts
/speckit.checklist       # optional: generate review criteria

The README describes support for "30+ AI coding agents", so the workflow is not tied to one vendor's assistant. Pin the version you scaffolded from: the command surface has already been renamed once, and templates from one release need not match the prompts of the next. Spec Kit is among the most-starred repositories in this space, at 123,823 stars with v0.14.2 current - both observed July 26, 2026, and both a snapshot rather than a stable figure.

Review is where agent-generated code accumulates, because generation is far cheaper than the attention needed to check it. Large machine-written diffs are also unusually hard to review well: the code is stylistically consistent, plausibly commented, and free of the small tells - a clumsy variable name, an obvious copy-paste - that normally warn a reviewer something was not thought through. Reviewers compensate by skimming, and skimming catches typos rather than misunderstood requirements.

A two-page spec inverts the yield. It is short enough to read properly, written in the domain's language rather than the framework's, and it exposes the expensive errors: the wrong feature, the missed edge case, the requirement nobody agreed to. Code review does not disappear but changes character. Instead of "is this right?", the reviewer asks the far more tractable "does this match AC-3?" - and where a criterion is mechanically checkable, a test answers it with no human at all.

That connects directly to the AI code review bottleneck: you cannot out-hire a generation rate, so the only durable fix is moving judgment earlier, where it is cheap. Spec-driven development is one half of that answer; agentic engineering is the other, covering how the agents themselves are designed and supervised.

Every stage before implement is a document problem. Implement is an infrastructure problem, and that is where teams are most often surprised. The value of checkable acceptance criteria is that something can check them, which means the agent must install dependencies, start services, run the tests, and read the failures. If setup lives in a senior engineer's shell history, or the tests only pass on a machine that has been up for three weeks, implement quietly degrades into generating code nobody has verified.

That is the prerequisite agent readiness covers, best audited before adopting a spec workflow rather than after. A machine-runnable setup - an AGENTS.md the agent reads on entry, plus hermetic builds giving the same result on a cold container as on a laptop - is what turns an acceptance criterion from an aspiration into a gate. Once it holds, the loop can run unattended: see headless agents in CI, and autonomous development for how far that can be pushed.

The ordering matters. Adopting spec-driven development on top of an environment your agents cannot reproduce buys the cost of the ceremony and none of the verification. Fix the environment first; the spec loop is what you build on top of it.