Spec-driven development with AI agents: a practical guide

Spec-driven development is a way of working with AI coding agents where a written spec comes before any code. You describe what to build, why, and how you will know it is done. The agent turns that spec into a technical plan, splits the plan into small tasks, implements them one at a time, and the result is verified against the spec’s acceptance criteria. The spec, plan and tasks are files in your repo, not messages buried in a chat, so they survive the session and can be reviewed like code.

This guide explains the loop, compares the tools that support it as of October 2026 (GitHub Spec Kit, Kiro specs, OpenSpec and the plan modes in Claude Code and Codex), walks through a small example with a real spec file and prompts, and lists the pitfalls. Tool details were checked against each project’s official docs and repository in October 2026.

Why specs matter more with agents

A human developer who gets a vague ticket asks questions. An agent that gets a vague prompt usually guesses, writes plausible code, and tells you it is done. The gap between “code was written” and “the feature works the way you meant” is where most rework comes from.

A spec closes that gap in three ways:

• It forces the decisions up front. Edge cases, error states and non-goals get written down before the agent picks for you.
• It gives every step the same source of truth. The plan, the tasks and the review all point back to one file instead of to your memory of a conversation.
• It makes “done” checkable. Acceptance criteria turn review from “looks fine” into “criterion 3 passes, here is the test”.

None of this is new. Requirements documents and acceptance tests are old ideas. What changed is that agents are fast enough that writing the spec is now the slow, valuable part, and the code is the cheap part.

The loop: spec, plan, tasks, implement, verify

Two rules make the loop work. First, keep the spec about behavior and the plan about implementation. “Users can reset their password by email” belongs in the spec; “add a reset_tokens table” belongs in the plan. Second, stop and review at every step. Each tool below is built around that pause; skipping it turns spec-driven development back into a long prompt.

Tools that support spec-driven development

GitHub Spec Kit

Spec Kit is GitHub’s toolkit for spec-driven development. It reached 1.0 this year, and the latest release as of October 2026 is v1.2.4. It does not replace your agent: the specify CLI installs templates and commands into the project, and you run the steps in your agent’s chat. It needs Python 3.11 or newer, uv and a supported agent on macOS, Linux or Windows.

uv tool install specify-cli
specify init my-project --integration claude
# in an existing repo:
specify integration install claude

The integration list covers more than 40 agents, including Claude Code (claude), Codex CLI (codex), Gemini CLI (gemini), GitHub Copilot (copilot), Cursor (cursor-agent), Kiro CLI (kiro-cli), opencode, Qwen Code and Amp. The docs write the commands as /speckit.specify and so on; how you type them depends on the agent. In Claude Code they are installed as skills under .claude/skills/ and called as /speckit-specify; in Codex they are $speckit-specify.

The short path is specify → plan → tasks → implement → converge. For production features the docs recommend the full path:

1. /speckit-constitution once per project, for principles such as testing rules.
2. /speckit-specify to write the feature spec from a plain description.
3. /speckit-clarify to ask up to five targeted questions and write the answers into the spec.
4. /speckit-plan to write the technical plan from your stack and constraints.
5. /speckit-checklist to generate “unit tests for your requirements”.
6. /speckit-tasks to produce a dependency-ordered tasks.md.
7. /speckit-analyze, a read-only consistency check across spec, plan and tasks.
8. /speckit-implement to work through the tasks in order.
9. /speckit-converge to compare the code with the spec and append any missed work to tasks.md.

You repeat implement and converge until converge reports Converged. The docs say to run each command on its own and review the result before the next.

Kiro specs

Kiro builds specs into the product. Every spec has three files in .kiro/specs/<name>/: requirements.md (or bugfix.md for a bug), design.md and tasks.md. Requirements are written in EARS notation, in the form “WHEN [condition] THE SYSTEM SHALL [behavior]”. Feature specs can start requirements-first or design-first, and Quick Spec generates all three files in one pass without the approval stops in between.

In the Kiro CLI you start with /spec new <name> and run the tasks with /spec run <name>. When you run all tasks, Kiro builds a dependency graph from tasks.md and runs independent tasks in parallel waves. As of October 2026 Kiro has a free tier with 50 credits and paid plans from $20 per user per month.

Kiro is the best pick if you want the spec workflow with a review UI built in and don’t mind working inside Kiro. If you want to stay in Claude Code or Codex, Spec Kit or OpenSpec fit better.

OpenSpec

OpenSpec is a lighter, MIT-licensed alternative built around changes. /opsx:propose add-dark-mode creates openspec/changes/add-dark-mode/ with proposal.md, a specs/ folder of requirements and scenarios, design.md and tasks.md. /opsx:apply works through the tasks, and /opsx:archive moves the change into the archive and updates the specs. /opsx:explore is a thinking step before you commit to a proposal.

npm install -g @fission-ai/openspec@latest   # needs Node.js 20.19.0+
cd your-project
openspec init

There is also a standalone binary and a Homebrew formula. Command spelling varies by agent, for example $openspec-propose in Codex; openspec init prints the right form for the tools you pick. The latest release as of October 2026 is v1.15.0.

Plan mode in Claude Code and Codex

Plan modes cover one step of the loop: the plan. In Claude Code plan mode the agent reads files and explores, then proposes a plan, and edits stay blocked until you approve. You enter it with Shift+Tab, /plan before a prompt, or claude --permission-mode plan.

The Codex CLI has /plan, which switches the chat to plan mode and can take the first request inline, for example /plan Propose a migration plan for this service. Codex also has /goal, which sets a persistent objective for a larger task and can be paused, resumed or cleared.

Plan modes are a good fit for a spec-driven workflow without extra tooling. The missing piece is persistence: ask the agent to write the approved plan and tasks to files, so the next session starts from them instead of from scratch.

A worked example: a spec file and four prompts

Here is the do-it-yourself version, which works with Claude Code, Codex or any agent that reads files. The feature: rate-limit failed logins in a small web app.

1. Write the spec

Save this as specs/login-rate-limit/spec.md:

# Login rate limiting

## Goal
Slow down password guessing on POST /login without bothering normal users.

## Non-goals
- No CAPTCHA.
- No change to how passwords are stored.

## Acceptance criteria
1. WHEN an IP has 5 failed logins within 15 minutes,
   THE SYSTEM SHALL answer further attempts with HTTP 429 for 15 minutes.
2. WHEN a login succeeds, THE SYSTEM SHALL reset that IP's failure count.
3. The 429 response SHALL include a Retry-After header in seconds.
4. Limits SHALL be configurable through LOGIN_MAX_FAILS and LOGIN_WINDOW_MIN.
5. Existing login tests SHALL still pass, and new tests SHALL cover 1–4.

## Constraints
- Use the existing Redis connection; no new services.

## Open questions
- Should the limit be per IP, per account, or both?

Keep it to one screen. The open questions section is there on purpose: it gives the agent a place to push back before it plans.

2. Clarify and plan

Start in plan mode and point the agent at the file:

Read specs/login-rate-limit/spec.md and the auth code.
First, ask me about anything ambiguous, starting with the open questions.
Then write a plan to specs/login-rate-limit/plan.md: files to change,
data stored in Redis and its expiry, how each acceptance criterion
will be tested, and risks. Don't edit any source files.

Answer the questions, then read the plan. Push back on anything that ignores a constraint.

3. Break it into tasks

Turn plan.md into specs/login-rate-limit/tasks.md: a numbered checklist
of tasks small enough to review in one diff. For each task, list the
files it touches and the test that proves it. Order them by dependency.

4. Implement one task at a time

Do task 1 from specs/login-rate-limit/tasks.md only. Run the tests,
tick the task in tasks.md, and stop. Tell me if the spec or plan
turned out to be wrong.

One task per prompt keeps diffs small and gives you a natural review point. If a task reveals that the spec was wrong, fix the spec first, then continue.

5. Verify against the spec

When the tasks are done, check the result against the spec, ideally in a fresh session or with a different agent so the reviewer did not write the code:

Read specs/login-rate-limit/spec.md. For each acceptance criterion,
find the code and the test that cover it, run the tests, and report
PASS or FAIL with evidence. Don't change any code.

That is the whole loop. Commit the specs/ folder with the code, so the next person, or the next agent, can see why the code looks the way it does. For more on writing the prompts themselves, see prompts for AI coding agents.

Pitfalls

• Specs that are really plans. If the spec names tables and functions, the agent can’t propose a better design and the reviewer can’t tell behavior from implementation. Keep the “how” in plan.md.
• Specs that are too long. A ten-page spec eats context and nobody reads it, including the agent. One screen per feature is a good limit; split bigger features.
• Approving without reading. An unread spec or plan is just a slower prompt. The review stop is the point.
• Tasks that are too big. If one task produces a diff you can’t review in one sitting, split it.
• Letting the spec drift. When the code teaches you something, update the spec. A spec that disagrees with the code is worse than none.
• Verifying with the author. The agent that wrote the code tends to confirm its own work. Use a fresh session, a second model or a human for the final check.
• Using it for everything. A one-line fix doesn’t need a spec. Save the process for features with edge cases or several files.
• Mixing project rules into every spec. Standing rules such as test commands and code style belong in CLAUDE.md or AGENTS.md or a Spec Kit constitution, not in each feature spec.

Spec-driven development in AgentVera

AgentVera is a desktop app for macOS, Windows and Linux that runs Claude Code, Codex, Kiro and other coding CLIs side by side. Each pane is the real CLI, so Spec Kit commands, OpenSpec commands, Kiro’s /spec and plan mode work in it as they do on their own. A few AgentVera features follow the same spec, plan, build, verify shape:

• Task line: a standing line of Analysis, Plan, Build and Review agents. Each task gets acceptance criteria, Analysis writes 01-analiz.md, Plan writes 02-plan.md, and the reviewer marks every criterion with evidence. A rejected task goes back to Build with the findings.
• AgentVera Verify: takes the acceptance criteria from the message you send an agent, and when its turn ends a separate verifier reads the diff, runs allowlisted test commands and marks each criterion pass or fail. The verifier can’t edit files.
• Parallel team: an agent splits a big job into up to 8 parts, each with its prompt, acceptance criteria, expected files and dependencies, runs them in separate worktrees and merges them into one branch and one PR.
• Team kanban: a card can be sent to a coding agent as its task, and the agent’s reply comes back as a comment. See kanban for AI agents.
• Automatic code review: when a turn ends, a Claude model you choose reviews the code and lists findings with file:line links.

The task line, Verify, parallel team and the team kanban are in the Pro and Team plans. If you only need the spec files and commands, Spec Kit and OpenSpec are free and work in any terminal; AgentVera helps once several agents are working through specs at the same time.

Wrapping up

Spec-driven development comes down to writing the “what” and the “how will I know” before the agent writes code, then holding every later step to that file. Start with a one-screen spec.md and plan mode. Move to Spec Kit or OpenSpec when you want templates and consistency checks, or to Kiro if you want the workflow built into the editor. Whatever you pick, review at every step and verify against the criteria, not against the agent’s summary.

Read more:

• Claude Code plan mode
• Prompts for AI coding agents
• Task line

To try AgentVera, download it.