# Spec-Driven Development With AI Agents: The Loop, a Template, and How Teams Run It

> Spec-driven development: a reviewed spec before an AI agent codes, then a plan, tasks and a check against it. The loop, a template, and how teams run it.

Published November 17, 2026 · by the AQ team · Canonical: https://aq.dev/guides/spec-driven-development-with-ai-agents/

Spec-driven development is a way of working with AI coding agents where the intent comes first: you write the requirements, constraints and acceptance criteria as a short document that a person reviews before any agent writes code. The agent then derives a plan and a task list from that spec, implements the tasks, and the result is checked against the spec's acceptance criteria. The spec stays the record of what was asked for, so it can be reviewed, changed on purpose and reused by the next agent.

**AQ is where a team runs spec-driven development together: the spec and plan sit in one shared thread, a lead agent proposes the plan for a person to approve, and builders work in their own worktrees with review by a different vendor where one is connected.** The rest of this guide is tool-neutral and works with any coding agent.

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

Every published version of spec-driven development uses some form of the same five steps. The step names differ by tool; the table lists what each step should leave behind.

| Step | Artifact | What it must contain | Who approves it |
| --- | --- | --- | --- |
| **1. Spec** | A spec file (for example `SPEC.md` or `spec.md`) | The goal, numbered requirements, what is out of scope, and acceptance criteria that end in a command someone can run. | The person who owns the outcome, plus one reviewer who did not write it. |
| **2. Plan** | A plan file or the agent's proposed plan | The approach, the files it expects to touch, the order of work, and the questions the spec leaves open. | The spec owner. This is the main gate. |
| **3. Tasks** | A task list (for example `tasks.md`) | Small, ordered tasks, each tied to a requirement number and each with its own check. | Usually nobody separately; it should follow mechanically from an approved plan. |
| **4. Implement** | Commits on a branch | Code for the tasks and nothing else. New requirements discovered mid-build go back into the spec first. | No approval during the build; the agent works. |
| **5. Verify** | The acceptance run and a review | The acceptance command's real output on the final commit, and a review of the diff against the spec. | A reviewer, then whoever merges. |

Two rules make the loop work. The plan is reviewed against the spec before any code exists, because that is the cheapest moment to catch a misunderstanding. And changes in direction go into the spec itself, so the document stays true to what was built.

## A spec template you can copy

A useful spec fits on one screen. This is the shape we use; the example below is the real spec from the worked run later on this page.

```
# Spec: <feature name>

## Goal
One or two sentences: who needs this and why.

## Requirements
1. Each requirement is one testable statement.
2. Name inputs, outputs and limits with real values.
3. Say what happens on bad or missing input.

## Out of scope
What this change must not touch.

## Acceptance
The command that proves it works, and any file the agent must not edit.
```

The example spec, as first written:

```
# Spec: parse the Retry-After header

## Goal
Our HTTP client retries after a 429 or 503. It needs to know how long to wait,
from the server's Retry-After header.

## Requirements
1. Export `retryAfterMs(value, now)` from `retryAfter.mjs`.
   `value` is the raw header string (or undefined). `now` is a Date.
2. A delay in seconds ("120") returns that many milliseconds (120000).
3. An HTTP date ("Wed, 21 Oct 2026 07:28:00 GMT") returns the milliseconds
   from `now` until that date.
4. A date in the past returns 0.
5. A missing, empty or unparseable value returns null (the caller then uses
   its own backoff).
6. Never wait longer than 10 minutes: cap the result at 600000.

## Out of scope
Making requests, the backoff schedule itself, any other header.

## Acceptance
`node --test retryAfter.test.mjs` passes. Do not edit retryAfter.test.mjs.
```

Kiro writes requirements in EARS form ("WHEN [condition/event] THE SYSTEM SHALL [expected behavior]"), which is a good habit even without Kiro: it forces every requirement to name its trigger and its result. How to write the acceptance checks so an agent cannot satisfy them with a shortcut is covered in [executable specs as guardrails for AI coding agents](https://aq.dev/guides/executable-specs-for-ai-coding-agents/).

## A real run: what the plan step caught

We ran the spec above through Claude Code (version 2.1.326, Sonnet) on November 17, 2026, in a throwaway repository. The acceptance test file was committed first and failed, since no implementation existed yet.

**Plan, in plan mode.** We asked for an ordered plan and for any requirement that was ambiguous, contradictory or not covered by the tests, with no code. The plan found no contradictions, but it listed gaps we had not noticed:

- The spec did not say whether values like "120abc", "-5" or "1.5" count as seconds. The plan proposed digits only, and checking for digits before trying date parsing, because JavaScript's date parser is lenient.
- The spec showed one date format, and Node's date parsing reads some strings in the machine's local time zone, so results could depend on where the code runs.
- The 10-minute cap was tested only for seconds. A date far in the future was not tested at all.

**Spec change.** We accepted two of its proposals and wrote them into the spec as requirements 7 and 8 (seconds are digits only; dates must be the GMT form, independent of time zone), and added two acceptance tests: "120abc" and "-5" return null, and the cap applies to dates. The plan's other questions, such as what to do with a missing `now`, we left out of scope on purpose.

**Implement, in a fresh session.** A new session read the revised spec and wrote a 30-line implementation. The acceptance command passed all 7 tests, and we reran it ourselves on the final file and again with a different machine time zone: 7 of 7 both times. The test file was unchanged. The agent's report also said it rejects impossible dates and a weekday that does not match the date, behavior the spec never asked for. It was harmless here, and it is exactly the kind of small scope widening a reviewer should read the diff for.

In this run, the plan step was most useful as a list of questions about the spec, and the answers belonged in the spec, where the next agent would see them.

## Spec-driven tools today

Each tool below produces a spec, a plan and tasks in its own format. Facts are from each vendor's documentation as of November 17, 2026.

- **GitHub Spec Kit.** An MIT-licensed open source toolkit, installed with `uv tool install specify-cli` and run through slash commands in your agent: `/speckit.constitution` (project principles), `/speckit.specify` (the feature spec), `/speckit.plan`, `/speckit.tasks` (a dependency-ordered `tasks.md`) and `/speckit.implement`, with optional checks such as `/speckit.clarify` (up to five questions written back into the spec) and `/speckit.analyze` (a read-only consistency check across spec, plan and tasks). Its integrations page lists about 40 agents, including Claude Code, GitHub Copilot, Codex CLI, Cursor and Gemini CLI. GitHub's [launch post](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) (Den Delimarsky, September 2, 2025) describes four phases with checkpoints: Specify, Plan, Tasks, Implement. Source: [github.com/github/spec-kit](https://github.com/github/spec-kit).
- **Kiro specs.** [Kiro's spec documentation](https://kiro.dev/docs/specs/) says every spec produces three files: `requirements.md` (user stories and acceptance criteria in EARS notation), `design.md` (architecture and implementation considerations) and `tasks.md` (discrete, trackable tasks). Feature specs run requirements first or design first; bugfix specs replace the requirements file with `bugfix.md`, which records current, expected and unchanged behavior. Specs live under `.kiro/specs/` in the repository.
- **Claude Code plan mode.** [Anthropic's docs](https://code.claude.com/docs/en/common-workflows) describe plan mode as Claude reading files and proposing a plan while making no edits until you approve; start it with `claude --permission-mode plan` or press Shift+Tab. Anthropic's [best practices](https://code.claude.com/docs/en/best-practices) also suggest asking Claude to interview you until it could write `SPEC.md`, then building from that file in a fresh session.
- **Codex plan mode.** OpenAI's Codex command reference lists `/plan`, which switches Codex into a plan mode for proposing an execution plan before implementation starts.

None of these is required. A Markdown spec in the repository, a plan mode, and a test command cover the whole loop; the tools add structure and repeatable prompts.

## Running spec-driven development as a team

Solo spec-driven development is mostly a prompting habit. On a team, the spec becomes a shared contract, and a few decisions need owners.

- **One author, one reviewer for the spec.** The person who will own the result writes it. A second person reads it before planning starts and asks one question: could an agent build the wrong thing and still pass the acceptance check?
- **Plan approval is the gate.** Approve the plan as a whole; the tasks follow from it. Check that it touches only what the spec covers, names the files it will change, and lists open questions rather than silently answering them.
- **Keep an inspectable record.** The goal, the reasons behind each decision, and the acceptance criteria should live in the spec and the plan, where anyone can read them in a minute. A long chat transcript holds the same facts but nobody rereads it.
- **Change the spec when the build teaches you something.** If an agent hits a case the spec did not cover, stop, add a numbered requirement, and replan the affected tasks. A fix made only in chat is lost the next time anyone builds from the spec.
- **Know when it is overkill.** A typo, a dependency bump or a one-line bug fix with an obvious test does not need a spec. A rule of thumb: write one when the change touches more than one module, when someone other than the author will review it, or when more than one agent will work on it.

In a [software factory](https://aq.dev/software-factory/), spec intake is the front station: issues and requests become specs, and everything downstream (planning, parallel builds, review, merge) reads from them. The [software factory levels guide](https://aq.dev/guides/software-factory-levels-from-autocomplete-to-dark-factory/) calls this level 4, spec-driven, where people write specs and acceptance criteria and approve the plan, and agents build and open pull requests.

## How spec-driven development fails

- **Spec drift.** The code changes during review or follow-up work and the spec does not. Fix it by treating the spec as part of the diff: if behavior changes, the spec changes in the same pull request.
- **Plans that widen scope.** A plan adds a refactor, a new dependency or "while I'm here" cleanup. Compare the plan's file list with the spec's out-of-scope section before approving.
- **Specs that cannot be checked.** "Fast", "secure" or "user-friendly" with no number or command. Every requirement should map to an acceptance check, or be marked as something a person verifies by hand.
- **Treating the transcript as proof.** An agent saying the tests passed is a claim. The proof is the acceptance command's output on the final commit, rerun by CI or a reviewer, and a review of the diff by someone other than its author. The [software factory security guide](https://aq.dev/guides/software-factory-security-permissions-secrets-review-gates/) covers review evidence and merge gates.

## Where AQ fits

AQ is where a team runs spec-driven development together: the spec and plan sit in one shared thread, a lead agent proposes the plan for a person to approve, and builders work in their own worktrees with review by a different vendor where one is connected.

- **One thread per piece of work.** Each work item has its own branch and git worktree on a machine the team controls, and its conversation can be shared with the team, so the spec, the plan and the discussion are in one place anyone with access can open.
- **A plan gate.** A [crew](https://aq.dev/docs/crews/) has a Lead agent that plans and delegates build, test, review and research to other agents. With the plan gate on, the Lead proposes its steps and waits: you approve, edit the plan, or run it in one thread instead, and no role that can edit code starts until you approve.
- **Builders in their own worktrees.** The Lead can delegate a step into its own worktree, and each member ends with a report of what it claimed, the files it touched, the commands it ran and the tests.
- **Independent review.** When Auto chooses the reviewer, it prefers a different vendor and account than the builder's. In the [Changes panel](https://aq.dev/docs/changes/), merge waits while checks are pending or failing, or while the review is older than the head commit.
- **Your agents.** The same loop runs on the agents and subscriptions a team already has, such as Claude Code and Codex, so Spec Kit commands or a plain `SPEC.md` work unchanged.

AQ does not write your specs or decide what is in scope; the team owns both. See [AQ Crews](https://aq.dev/product/crews/) for an overview, [pricing](https://aq.dev/pricing/) for plans, and the [guide to building a software factory with Claude Code and Codex](https://aq.dev/guides/build-a-software-factory-with-claude-code-and-codex/) for a step-by-step setup.

## Frequently asked questions

### What is spec-driven development with AI agents?

It is a workflow where a person writes the requirements, constraints and acceptance criteria as a reviewed document before an AI agent writes code. The agent derives a plan and tasks from that spec, implements them, and the result is checked against the spec's acceptance criteria. The spec stays the record of what was asked for.

### Is spec-driven development the same as TDD?

No. Test-driven development works one behavior at a time: write a failing test, make it pass, refactor. Spec-driven development works at the level of a feature: requirements, a plan and tasks come first, and tests are one way to express the spec's acceptance criteria. Many teams use both, with failing acceptance tests written from the spec before the agent starts.

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

No. GitHub's Spec Kit gives you templates and slash commands for each phase, and Kiro builds the same loop into its editor, but a Markdown spec in the repository, an agent's plan mode, and a runnable acceptance command cover the whole loop. Use a toolkit when you want the same structure across many people and projects.

### How long should a spec be?

Long enough that an agent could not build the wrong thing and still pass the acceptance check, and short enough that a reviewer reads it in a few minutes. For most features that is one screen: a goal, numbered requirements, an out-of-scope list and the acceptance command. If it runs to several pages, split the feature.

### Who approves the plan in spec-driven development?

The person who owns the outcome, usually the spec's author. They check that the plan covers every requirement, touches only what the spec allows, and lists the questions the spec leaves open. On a team, a second person reviews the spec itself before planning and reviews the diff before merge.

### When is spec-driven development overkill?

For small, obvious changes: a typo, a dependency bump, a one-line fix with a clear test. Write a spec when a change touches more than one module, when someone other than the author will review it, or when more than one agent will work on it.

---

About AQ: AQ is where teams put AI agents to work on everything they do: code that lands as a reviewed pull request, bots that run the jobs that repeat, and an assistant that starts each day, all on the agents and subscriptions they already have, like Claude Code and Codex, on private cloud machines of their own or on their own Mac. Start at [aq.dev](https://aq.dev/).
