What is spec-driven development? Kiro and Spec Kit explained

In this lesson you'll learn:

• what spec-driven development is, and its three levels of commitment;
• how Kiro and GitHub Spec Kit each put it into practice;
• the honest critiques, and the parts of a spec that a tool cannot fill in.

Sound familiar?#

• The agent built something plausible and wrong, because the only "spec" was a chat thread it half-remembered.
• Six months later nobody knows why the code behaves as it does, because the reasoning lived in a conversation.
• A spec tool generated four long markdown files for a one-line bug fix, and nobody read them.

The first two are the problem spec-driven development solves. The third is the problem it can create, and the reason depth matters.

What is spec-driven development?#

Spec-driven development is writing a spec before writing code with AI (documentation first) and treating that spec as the authoritative reference for both people and agents. Birgitta Böckeler, writing on Martin Fowler's site in October 2025, distinguishes three levels of commitment:

This manual asks for spec-anchored on every change: the spec is the one artefact that survives the code, and a change with no spec change is a change nobody can review.

How the tools do it, step by step#

Step 1 · Kiro: requirements, design, tasks#

Kiro, AWS's agentic IDE released in public preview in July 2025, keeps three files per feature. requirements.md holds user stories with acceptance criteria in EARS (WHEN … THE SYSTEM SHALL …), the requirements syntax developed at Rolls-Royce. design.md holds the architecture, data flow and testing strategy. tasks.md is the implementation plan, each task traceable to a requirement. You can start from requirements or from design.

Step 2 · GitHub Spec Kit: constitution, specify, plan, tasks, implement#

GitHub Spec Kit, open-sourced on 2 September 2025, is a toolkit of templates and commands that work inside coding agents such as GitHub Copilot, Claude Code and Gemini CLI. It moves work through a constitution of project-wide principles, then specify, plan and tasks, and finally implement, with checklists that serve as the definition of done at each step.

Step 3 · Choose the level of commitment per change#

Neither tool decides how much of this a change needs. A defect fix may need one updated acceptance line; a new feature needs all of it. Pick the level, and the depth, from the risk of the change, not from the tool's default. How much process a change needs.

Step 4 · Fill in what the tool cannot#

A spec tool gives you the places to write things down. It does not know how accurate the agent in your product must be, which of its actions need a person, or where a limit must be enforced. Those are the five agentic fields of this manual's eight-field spec (the model's role, autonomy per action, the bar per slice, the fallback and the records), and they belong in the requirements file whichever tool holds it.

The honest critiques#

Böckeler's review is worth reading before you adopt either tool. Her main points:

• Workflow mismatch. The tools do not scale their process to the size of the problem, so small bugs get elaborate treatment.
• Review burden. Long generated markdown files can be more tedious to review than the code.
• An illusion of control. Agents still ignore or over-interpret instructions, however full the spec.
• An old echo. Spec-as-source recalls model-driven development, with the risk of combining inflexibility with non-determinism.

Each critique is an argument for depth by change and for checks that do not depend on the agent reading the spec: the harness, the tool signatures and the tests.

Where you'll use it#

• On every change, at the depth it needs: at minimum, the spec is updated and reviewed.
• As the input a coding agent builds from, in place of a chat thread.
• As the record an auditor or a new engineer reads to find out why the system behaves as it does.

Why it matters#

A coding agent builds whatever it understands. Spec-driven development moves the understanding out of a conversation and into a file that people review, version and keep, which is what makes the agent's output reviewable, and the system maintainable, after the conversation is gone.

Key takeaways#

1. Spec-driven development writes the spec first and keeps it as the artefact agents build from.
2. Kiro keeps requirements, design and tasks files; Spec Kit runs constitution, specify, plan, tasks and implement.
3. The tools hold the spec; you still decide its depth, its bars and its limits, and enforce the limits in code.

FAQ#

What is the difference between spec-driven development and test-driven development?#

Test-driven development writes a failing test before the code that makes it pass. Spec-driven development writes the specification (requirements, design and tasks) before any code, for an AI agent to build from. They combine well: the acceptance criteria in the spec become the tests.

What are requirements.md, design.md and tasks.md?#

The three files Kiro keeps for each feature: the requirements, as user stories with acceptance criteria in EARS notation; the technical design; and the implementation plan, as tasks traceable to the requirements.

Is spec-driven development the same as AI-DLC?#

No, though they fit together. Spec-driven development is about what agents build from; AWS's AI-DLC is a wider methodology with phases, mob rituals and bolts. An AI-DLC team would typically keep its Inception output as a spec.

Do I need Kiro or Spec Kit to do spec-driven development?#

No. The practice is writing and keeping the spec; the tools make it convenient inside a coding agent. A markdown file in the repository, read by path from the agent's context file, is spec-driven development.

Apply it in your role#

Across the enterprise. Adopt one SDD tool where you can and keep specs in the repository, so specs are reviewed like code across teams and survive the people who wrote them.

The ten-minute workflow. Review a spec the way a coding agent will misread it:

Here is our spec (requirements, design and tasks): <paste>. Find (1) requirements without a
measurable acceptance criterion, (2) actions with no stated limit or approver, and (3) tasks that
implement nothing in the requirements. Output three lists with line references.

Sources and credits#