Spec-driven development means that before an AI agent writes any code, you put in writing what should be built, why, and how you'll know it's done. From that specification, or spec, the agent derives a technical plan and small tasks, works through them one by one, and at the end the result is checked against the spec. It pays off for features with several steps; for a typo or a small, obvious bug it's too heavy.
My AI employees work with Claude Code, and for them every job starts with an assignment that sets the expected result and the boundaries. At its core that is the same principle. Further down I show how I apply it.
What spec-driven development is
When you develop software with AI, there are two ways to work. In one, you type a wish and correct it message by message; accept the code unread and it's vibe coding. In the other, you settle in writing what gets built and measure the agent against it. That's spec driven development. How work with coding agents changes overall is in Agentic Coding: Beyond Vibe Coding.
GitHub's reasoning: the issue isn't the agent's coding ability but our approach. Coding agents are "literal-minded pair programmers" that need unambiguous instructions.
There's no fixed definition yet. Birgitta Böckeler of Thoughtworks writes that the term "isn't very well defined yet"; some use "spec" as a synonym for a detailed prompt. She distinguishes three levels: spec-first (a spec is written for one task and then used), spec-anchored (the spec is kept after the task and maintained) and spec-as-source (the human only edits the spec, never the code).
The five steps
- Specification: What should be built and why, from the users' point of view. No technology yet.
- Plan: Now comes the how: language, architecture, constraints.
- Tasks: The plan is broken into small pieces that can be built and tested on their own.
- Implementation: The agent works through the tasks. You review small changes instead of a thousand-line dump.
- Check against the spec: Is every requirement implemented, does every listed edge case have a test? Anything missing goes back as a new task.
Between the steps, it's your turn. In GitHub's words, your role isn't just to steer, it's to verify.
Tools and approaches, as of October 30, 2026
GitHub Spec Kit
Spec Kit is an open-source toolkit from GitHub under the MIT license; version 1.2.5 came out on October 28, 2026. It gives AI coding agents structured processes, templates and documented outcomes. You install the specify command line tool (Python 3.11 or later and uv) and use it to set up a project for your agent. Claude Code is one of the supported integrations, alongside GitHub Copilot, Codex CLI, Gemini CLI, Cursor, Kiro CLI and others.
You then drive the process in the agent's chat:
The spelling depends on the agent; in GitHub Copilot it's /speckit-specify. You repeat implement and converge until converge reports that everything is met.
Kiro
Kiro is a development environment with an agent, according to its maker built and operated by AWS. A Kiro spec has three files: requirements.md (for bugs, bugfix.md) with user stories and acceptance criteria, design.md with the architecture, and tasks.md with discrete, trackable tasks. Kiro writes requirements in EARS notation: "WHEN [condition/event] THE SYSTEM SHALL [expected behavior]". For well-understood features there is Quick Spec, which produces all three steps without approval gates in between.
Claude Code: plan mode and SPEC.md
Claude Code has no spec framework of its own, but two building blocks. Plan mode lets Claude read files and write a plan, but it changes nothing until you approve the plan. You switch it on with Shift+Tab, with /plan before a prompt, or with claude --permission-mode plan; Ctrl+G opens the plan in your editor. More commands are in Claude Code Commands: The 15 You Need.
Plan mode covers step two, the how. For the what, Anthropic's best practices suggest letting Claude interview you until it could write the spec into a SPEC.md file. You then build in a fresh session, starting with a clean context and a written definition of done. Why that helps is in Context and Context Windows in AI Explained. Finally, a read-only subagent reviews the changes against SPEC.md. How to set up such a role is in Claude Code Subagents: Best Practices.
What a good spec looks like
A made-up example: a trades business wants a callback request form on its website.
# Spec: callback request on the website
## Goal and why
Prospects can request a callback without having to phone.
The office calls back within one working day.
## Requirements
1. WHEN someone submits name, phone number and request,
THE SYSTEM SHALL store the request and show a confirmation.
2. WHEN the phone number is missing or invalid,
THE SYSTEM SHALL highlight the field and store nothing.
3. WHEN a new request comes in,
THE SYSTEM SHALL email the office, without the phone number in the subject.
## Out of scope
- Appointment booking, customer accounts, payment
## Constraints
- Privacy notice on the form
- Runs on the existing website (the plan decides the technology)
## Open questions
- Who deletes handled requests, and after how many days?
## Done when
- Every requirement has a test, and all tests pass
- A person has submitted the form once on a phone
What matters:
- Every requirement is testable. The EARS when-then form makes you name trigger and outcome, which later becomes a test.
- Non-goals are written down, so the agent doesn't add them.
- No technology in the spec. Framework and database belong in the plan.
- Open questions are visible. Better a question in the spec than an assumption in the code.
- "Done" is defined. Otherwise step five has no yardstick.
Benefits and limits
The main benefit for AI software development is checkability. Misunderstandings surface before any code exists, the agent delivers small changes you can follow, and the spec outlives the session, so a second agent can continue from the file. For unattended runs, Anthropic's first question is whether the agent knows what done looks like, for example through a spec file or a failing test it has to turn green.
Böckeler describes the limits from her own trials with Kiro and Spec Kit in October 2025. The tools have moved on, the questions remain:
- One workflow for every size. Kiro turned a small bug into four user stories with 16 acceptance criteria. She calls it "using a sledgehammer to crack a nut".
- A lot of text to review. Spec Kit produced many verbose files for her. In her words, she'd "rather review code than all these markdown files".
- A false sense of control. Despite templates and checklists, she often saw the agent not follow all the instructions. The spec doesn't replace the check, it makes it possible.
- Keeping it current. Spec Kit's docs don't prescribe how spec, plan and tasks are maintained when requirements change. That's up to you.
A tip from Anthropic's docs: a reviewer asked to find problems always finds something, so limit it to gaps against the spec and skip style.
When it isn't worth it
- Small bugs with a clear cause. The spec would be longer than the fix. Spec Kit has a shorter bug-fixing process, Kiro bugfix specs.
- Throwaway prototypes. A quick try shows better than a spec nobody maintains whether an idea holds up.
- You don't know yet what you want. Then the interview with Claude or a short prototype helps, and the spec comes afterwards.
- Nobody checks at the end. Without step five, spec-driven development is just a long prompt.
How I apply this to AI employees
My AI employees work with Claude Code, each in a folder of their own with a personnel file, work instructions, skills, knowledge and assignment folders. Every job starts with an assignment in a file called auftrag.md that sets the expected result and the boundaries. Before anything goes live, a separate reviewer checks it, and whoever created something never reviews it themselves.
Mapped onto the five steps: the assignment is the spec, and the check against the assignment is step five. How such a folder is set up is in Creating an AI Employee: How to Start, and how the workforce runs on a server is in Claude Code on a Server: tmux, Remote Control. A role that checks results against an assignment is Kai.
Frequently asked questions
What goes into a spec?
Goal and why, testable requirements, what's out of scope, constraints without technology choices, open questions and a definition of done. The template above shows all six parts in an example.
Do I need Spec Kit or Kiro for this?
No. A Markdown file with goal, requirements, non-goals and a definition of done is enough to start. Who drafts it, you or the agent, matters less than you approving it before anything is built. Spec Kit and Kiro add fixed processes and templates, which helps in a team.
Is plan mode in Claude Code already spec-driven development?
Only partly. Plan mode produces the how and blocks edits until you approve. The what and the yardstick are missing; with a SPEC.md and a subagent review, it becomes the full process.
What happens when the requirements change?
Then you change the spec first, and the plan and code after that. Whether you keep maintaining the spec after the task is your call; that is exactly the difference between spec-first and spec-anchored.
Where to go next
If you haven't set up Claude Code yet, start with Claude Code: A Guide for Beginners. Then write a spec for your next larger change and have a reviewer check the result against it. What such a review looks like with Anthropic's tools is in Claude Code Review: Cost, Setup, Limits. The bigger picture is in Agentic Coding: Beyond Vibe Coding. How others write assignments for their AI employees and have results reviewed is what we discuss in my community AI Employee Framework.
