What Is Spec-Driven Development? A Guide for AI Coding Teams

Spec-driven development is a way of building software where a written spec, not a chat prompt, tells AI coding agents what to build and why. The spec comes first. Humans review it, agents follow it, and the code is checked against it.

Two out of three developers name AI answers that are almost right, but not quite, as a frustration, the most common one in the 2025 Stack Overflow survey. Faster agents will not fix that, because the gap lives in the instructions, not the typing. This guide shows how spec-driven development closes that gap: the workflow, the tools, the honest critiques, and the piece most teams still miss.

What is spec-driven development?

The idea is simple. You describe what you want, why it matters, and how you will know it works. Then an agent writes code from that description, and you check the result against it.

GitHub calls the spec "a contract for how your code should behave" in its launch post for Spec Kit. That contract matters more with agents than with people. A human teammate can ask a follow-up question, but an agent will often fill the gap with a guess.

The three levels of spec-driven development

Birgitta Böckeler of Thoughtworks mapped SDD into three levels in her review of SDD tools on martinfowler.com. The levels describe how long the spec lives and how much it controls.

• Spec-first: You write a spec for one task, use it, and set it aside when the task is done.
• Spec-anchored: You keep the spec after the task and update it as the feature changes.
• Spec-as-source: Humans edit only the spec, and the code is generated from it.

Böckeler found that every SDD approach she reviewed works at the spec-first level. The real payoff, and the real difficulty, starts when the spec has to stay true for months.

Why did spec-driven development come back with AI coding agents?

Writing specs before code is not new. Teams did it for decades, then moved toward lighter documents and working software. What changed is who reads the spec.

AI agents are now part of daily work. In the 2025 Stack Overflow Developer Survey, 47.1% of respondents said they use AI tools daily, and 14.1% said they use AI agents at work daily. Yet trust is low, with about 46% saying they distrust the accuracy of AI output.

Those numbers point to the same root cause. An agent that gets a vague prompt returns a plausible answer, and a human then spends time finding what is wrong with it. A spec moves that effort to the front, where it is cheaper.

It also gives teams an alternative to vibe coding. Martin Fowler describes vibe coding as prompting an LLM and accepting results without looking at the code, which he says fits "disposable software written for a limited audience." Production systems need something sturdier, and a spec is the most direct answer.

How does the spec-driven development workflow run?

The tools use different names, but the loop is close to the same. GitHub Spec Kit uses specify, plan, tasks, and implement, and Kiro uses requirements, design, implementation planning, and execution. We add a fifth step that every team needs: verify.

1. Specify: Describe what you are building, who it is for, and why. Include user journeys and how you will measure success.
2. Plan: Add the technical choices, such as stack, architecture, and constraints. The agent turns the spec into a technical plan you can review.
3. Tasks: Break the plan into small tasks that can each be built and tested on their own.
4. Implement: The agent works through the tasks, and a human reviews each focused change.
5. Verify: Check the code against the spec, not against your memory. Update the spec if the plan changed during the build.

Kiro makes the first step concrete with testable requirements. Its docs show the pattern "WHEN [condition/event] THE SYSTEM SHALL [expected behavior]," so each requirement can become a test case. Spec Kit also uses what Böckeler describes as a "constitution," a set of high-level principles meant to stay fixed.

The human role shifts from writing code to deciding and checking. As the GitHub team puts it, the developer's job is to steer and verify. For a deeper look at how this loop scales into a full pipeline, see our guide to the software factory.

What are the main spec-driven development tools?

Three tools defined the category in 2025. Each takes a different view of how long a spec should live.

GitHub Spec Kit

GitHub released Spec Kit as an open source toolkit in September 2025. It is a command-line tool that adds slash commands like /specify, /plan, and /tasks to coding agents such as GitHub Copilot, Claude Code, and Gemini CLI. Böckeler notes that each spec gets its own branch, which suggests a spec tied to one change rather than one feature.

AWS Kiro specs

Kiro is an AI IDE from AWS built around specs. Each spec has three files: requirements.md, design.md, and tasks.md, with decision points between phases. Kiro also keeps project memory it calls "steering."

Tessl

Tessl launched its framework and Spec Registry in September 2025. The framework keeps specs in the codebase as long-term memory for agents, paired with tests as guardrails. The registry holds more than 10,000 pre-built specs that help agents use open source libraries correctly.

The Thoughtworks Radar view

The Thoughtworks Technology Radar placed spec-driven development in its Assess ring in November 2025. It called the space interesting but warned that "the workflows remain elaborate and opinionated." It also noted that some tools "generate lengthy spec files that are hard to review."

How does spec-driven development compare to agile docs and vibe coding?

SDD sits between two familiar habits. Agile teams write light documents for humans, and vibe coders write almost nothing at all. Our post on vibe coding vs. spec-driven development goes deeper on that second contrast.

The key difference is the reader. Agile docs can stay thin because people share context in standups and hallways. Agents share none of that, so the spec has to carry it.

What are the honest critiques of spec-driven development?

SDD has real skeptics, and their points are fair. The best critiques come from people who tried the tools closely.

• Spec overhead: In Böckeler's test, Kiro turned one small bug into four user stories with 16 acceptance criteria. One fixed workflow does not fit every size of problem.
• Review burden: Spec Kit produced many long, repetitive markdown files. Böckeler wrote that she would rather review code than all of them.
• False sense of control: Agents still ignored instructions at times, such as recreating classes that already existed.
• Waterfall fears: Böckeler is skeptical of heavy up-front spec design and argues that small, iterative steps keep teams in control.

“Crucially, your role isn't just to steer. It's to verify.”

Notice what these critiques share. None of them says specs are a bad idea. They say specs get too long, too hard to review, and too easy to ignore, which are problems of size and process.

That is the right way to read them. The answer is not to drop the spec but to keep each change small enough for a human to actually judge.

What is missing from most spec-driven development setups?

Most SDD tools focus on writing a spec. Few focus on what happens to it after week one: who may change it, how changes are reviewed, and how it stays in sync with the code.

Researchers have started to name this gap. A June 2026 arXiv paper on the Spec Growth Engine describes "silent spec-code drift," where code changes while the spec does not. Its proposed fix is a drift gate that blocks merges when the two diverge.

We see drift in a wider form. Feature specs get appended to a core spec no one can read, deprecated copies multiply, and each team pulls context from a different version. We cover the signs in detail in our post on spec drift.

How Crema governs the spec

Crema is one way to handle this layer. It is a spec control plane that keeps the spec in GitHub as one source of truth and sizes each change for human judgment.

Each change lands on a decision card: who it is for, why, the change, the limits, and the spec text, on one screen. Permissions are set per proposer in a repo file and revoked with a one-line change. That matters even more when everyone in the company codes.

How do you start doing spec-driven development?

You do not need a new platform to start. You need a habit and a few rules. Use this checklist on your next feature.

1. Pick one real feature. Choose something small enough to ship in a week, not a full system rewrite.
2. Write who it is for and why first. If you cannot state both in two sentences, the agent will not guess them either.
3. Add testable requirements. Use a WHEN and SHALL pattern so each line can become a test.
4. Keep each spec change short. Aim for a change one person can review in a single focused sitting.
5. Put the spec in version control. Treat spec edits like code edits, with a pull request and a named reviewer.
6. Set agent limits in writing. Decide which sections an agent may change and how much it may propose.
7. Verify against the spec. Review the code by asking whether it matches the written intent.
8. Update the spec when reality changes. If the build taught you something, fix the spec before the next task.

For help writing the spec itself, our guide on how to write a PRD for AI coding agents walks through a full template. The free Crema PRD skill also helps you write specs and spec changes for agents.

Once the spec is live, record why each change was made. Our guide to decision records for AI teams shows the fields to capture, and the product builder guide covers who should own the spec.