# Spec-driven development with AI agents: a practical guide

URL: https://agentvera.dev/en/blog/spec-driven-development-with-ai/ · Published: 2026-10-28

Spec-driven development with AI agents: write the spec, plan, split into tasks, build and verify. Compares Spec Kit, Kiro, OpenSpec and plan modes, with an example.

**In short:**

- Spec-driven development means you write what to build and how to check it in a spec file first, then the agent plans, splits the work into tasks, builds and is verified against the spec.
- GitHub Spec Kit, Kiro specs and OpenSpec give you the files and commands for this loop; plan mode in Claude Code and Codex covers the planning step only.
- You don’t need a tool to start: a short spec.md with acceptance criteria, a plan you actually read and one task per prompt get you most of the benefit.

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

| Step | What you produce | Who does the work | What you check |
| --- | --- | --- | --- |
| Spec | What and why: goal, users, non-goals, acceptance criteria | You, with the agent asking questions | Is anything ambiguous or missing? |
| Plan | How: architecture, files, data model, risks | Agent | Does it fit the codebase and the constraints? |
| Tasks | Small, ordered steps, each with a way to test it | Agent | Is each task small enough to review in one sitting? |
| Implement | Code, one task at a time | Agent | Diff, tests, nothing outside the task |
| Verify | Evidence for each acceptance criterion | Agent or a second reviewer | Every criterion passes with proof, not with a claim |

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

| Tool | What it is | Where the spec lives | Key commands | License or price (October 2026) |
| --- | --- | --- | --- | --- |
| GitHub Spec Kit | A CLI plus skills/commands for your existing agent | `spec.md`, `plan.md`, `tasks.md` per feature | `/speckit-specify`, `/speckit-plan`, `/speckit-tasks`, `/speckit-implement` | MIT, free |
| Kiro specs | Built into the Kiro IDE, CLI and web app | `.kiro/specs/<name>/` | `/spec new <name>`, `/spec run <name>` in the CLI | Free tier with 50 credits, paid plans from $20 a month |
| OpenSpec | A CLI plus commands for your existing agent | `openspec/changes/<name>/` | `/opsx:propose`, `/opsx:apply`, `/opsx:archive` | MIT, free |
| Claude Code plan mode | A permission mode: research and plan, no edits | In the conversation, unless you save it | Shift+Tab, `/plan`, `--permission-mode plan` | Part of Claude Code |
| Codex plan mode | A collaboration mode in the Codex CLI | In the conversation, unless you save it | `/plan`, plus `/goal` for a lasting target | Part of Codex |

### GitHub Spec Kit

[Spec Kit](https://github.com/github/spec-kit "GitHub 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](https://docs.astral.sh/uv/ "uv") and a supported agent on macOS, Linux or Windows.

```bash
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](https://kiro.dev/docs/specs/ "Kiro specs") 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](https://github.com/Fission-AI/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.

```bash
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](/en/blog/claude-code-plan-mode/ "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`:

```markdown
# 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:

```text
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

```text
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

```text
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:

```text
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](/en/blog/prompts-for-ai-coding-agents/ "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](/en/blog/claude-md-agents-md/ "CLAUDE.md and 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](/en/features/task-line/ "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](/en/features/verify/ "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](/en/features/parallel-team/ "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](/en/blog/kanban-for-ai-agents/ "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](/en/blog/claude-code-plan-mode/ "Claude Code plan mode")
- [Prompts for AI coding agents](/en/blog/prompts-for-ai-coding-agents/ "Prompts for AI coding agents")
- [Task line](/en/features/task-line/ "Task line")

To try AgentVera, [download it](/en/download/ "Download AgentVera").

## Frequently asked questions

**What is spec-driven development?** It is a way of working with AI coding agents where a written specification comes first. You describe what to build, why, and how you will know it works; the agent turns that into a plan and tasks, writes the code, and the result is checked against the spec.

**How is it different from plan mode?** Plan mode in Claude Code or Codex makes the agent propose a plan before it edits anything, but the plan lives in one conversation. In spec-driven development the spec, plan and tasks are files in the repo that outlive the session and can be reviewed, versioned and checked against later.

**Do I need GitHub Spec Kit or Kiro to do it?** No. A spec.md with a goal, non-goals and acceptance criteria, a plan you review, and one task per prompt is already spec-driven development. Spec Kit, Kiro and OpenSpec add templates, commands and consistency checks on top.

**Is GitHub Spec Kit free?** Yes. Spec Kit is MIT licensed. As of October 2026 you install the specify CLI with uv tool install specify-cli, and it needs Python 3.11 or newer plus a supported coding agent.

**When is spec-driven development overkill?** For one-line fixes, quick experiments and changes you can describe fully in one sentence. Writing a spec costs time, so save it for features that touch several files, have edge cases, or will be built by more than one agent.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/