Skip to content

From Spec to Code: Spec-Driven Development with Agents

A coding agent will happily build exactly what you typed, which is not always what you meant. On small tasks the gap is cheap to fix; on a feature that touches the data model, the API and the UI, it is not. Spec-driven development closes the gap by giving the work before the code a fixed shape: spec, plan, task breakdown, implementation and verification. This guide covers the building blocks, the common tools, what you need in place and where the approach breaks down. Checked against the vendor documentation in October 2026.

What is spec-driven development, and when is it used?

Spec driven development means the agent does not start from a chat message but from a written document that defines behaviour, boundaries and acceptance criteria. The plan and the tasks are derived from that document, and the finished work is checked against it. The spec, not anyone's memory of the conversation, is the yardstick.

Writing specs before code is not new. What is new is how much it matters when the implementer is a model. A human developer handed a vague ticket tends to ask questions. An agent tends to fill gaps with reasonable-looking assumptions and keep going. The Claude Code best practices describe this failure directly: when Claude builds something different from what you had in mind, it is usually missing information it cannot get from reading the repository.

GitHub's Spec Kit methodology takes the strongest position: "Specifications don't serve code—code serves specifications." You do not have to adopt that view in full. Even the weaker version, where the spec is simply the thing every review is measured against, changes how work is handed to agents.

Where it pays off:

  • Features that span several layers, such as an endpoint with a schema, validation and a front-end form.
  • Changes with many edge cases: permissions, pricing rules, data migrations, time zones.
  • Unattended runs, where the agent has to decide on its own when it is finished.
  • Work split across agents or sessions, because every session needs the same written reference point.

How is this different from agentic coding in general?

Agentic coding is the broader practice of building software with tools such as Claude Code, Codex or Cursor, including tool choice, rollout and permissions. Spec-driven development is one slice of it: the process that happens before the first line of code and the verification that happens after the last one.

The overview of agentic software development in teams compares the tools and how teams adopt them. This guide sits one level below and asks a narrower question: what does a single piece of work look like when it starts as a spec rather than a prompt? Most of the answers hold regardless of which agent you use.

How does it work? The building blocks

There are five building blocks, each feeding the next: project rules, the spec, the technical plan, the task list and verification. Each one is either a file in the repository or a step in the workflow. Tools give them different names, but the jobs they do are the same.

Project rules

Project rules apply to every piece of work: architectural decisions, testing approach, dependencies that are off-limits. Spec Kit calls this file the constitution and stores it at memory/constitution.md; its methodology describes it as the "architectural DNA of the system". In Claude Code, CLAUDE.md plays a similar role. The best practices advise keeping it short and limited to what the agent cannot infer from the code, such as the exact test, typecheck and lint commands, or decisions that live in nobody's documentation.

The spec

The spec describes the what: behaviour from the user's point of view, acceptance criteria, edge cases and what is explicitly out of scope. It does not pick libraries. Kiro writes requirements to requirements.md and, according to its feature spec documentation, uses EARS notation (Easy Approach to Requirements Syntax) with the pattern "WHEN [condition/event] THE SYSTEM SHALL [expected behavior]". Spec Kit's templates tell the model to flag ambiguity with [NEEDS CLARIFICATION: specific question] instead of guessing.

The technical plan

The plan describes the how: architecture, data model, interfaces and test strategy. In Kiro this is design.md, which the Kiro docs describe as covering technical architecture, sequence diagrams and implementation considerations. Spec Kit produces plan.md and, depending on the feature, supporting files such as research.md, data-model.md, a contracts/ folder and quickstart.md.

The task list

The task list breaks the plan into steps that can each be verified on their own. Both Kiro and Spec Kit write it to tasks.md. What matters is that every task has a clear outcome and that dependencies between tasks are visible. Spec Kit marks independent tasks with [P]; Kiro builds a dependency graph when you run all tasks.

Verification

Verification closes the loop: tests, type checks, linting and a review against the spec. Without it, a spec is just a longer prompt. The value appears only when the result is compared, requirement by requirement, with the document it was built from.

Which tools and variants are there?

Three approaches are common: a template toolkit such as Spec Kit, an IDE with a built-in spec workflow such as Kiro, and a lightweight setup with a Markdown file and the coding agent's plan mode. All three follow the same order. They differ in how much structure they impose.

Spec Kit is an open-source toolkit from GitHub. Its README lays out the core workflow as commands run inside the agent's chat: set project principles (the constitution, once per project), specify the feature, create the technical plan, break the work into tasks, and implement. Setup runs through the specify command-line tool, and the toolkit offers integrations for several coding agents rather than being tied to one. You get ready-made templates and a consistent folder layout; you also get more ceremony than a small project needs.

Kiro builds the workflow into the development environment. The Kiro documentation distinguishes feature specs, bugfix specs and a Quick Spec that generates all three files in one pass without approval gates. Feature specs come in two orders: Requirements-First (requirements, then design, then tasks) for product-driven work and greenfield projects, and Design-First for projects with strict non-functional requirements or existing design documents.

A Markdown spec plus plan mode is the minimal option. The Claude Code best practices describe it plainly: ask the agent to interview you until it could write the spec, have it save the result as SPEC.md, then start a fresh session that builds from that file. Plan mode keeps the agent reading and planning without touching source files until you approve. No extra tooling is needed, which makes it a good place for a team to start.

Follow-up articles in this series go deeper on individual steps, including how to write specs that agents implement reliably and how plan mode works day to day. They are listed at the bottom of this page as they are published.

What needs to be in place first?

You need three things: a repository with automated checks, someone who can sign off a spec on domain grounds, and a willingness to spend time up front on larger pieces of work. Without them, the workflow mostly produces extra documents.

Automated checks. The agent has to be able to tell whether it is done. The best practices put it bluntly: if the agent has nothing to run that tells it whether the work is actually done, "looks done" is all it has to go on, and you become the test suite. At minimum, a test run, a type check or a linter that starts from a single command.

Domain sign-off. A spec is only as good as the person who approves it. For internal tools that is often the business team; for an API it may be the team consuming it. Agree in advance who signs off and how quickly.

Version control for the documents. Keep the spec, plan and tasks in the same repository as the code. Changes become traceable, and a reviewer can read the spec and the diff side by side.

Separate checkouts for parallel work. Running several agents at once needs isolated working copies. Claude Code can start a session in its own git worktree with claude -w <name>. As the best practices note, a worktree is a fresh checkout, so gitignored files such as .env are missing and dependencies are not installed.

What are the steps?

The workflow has six steps: clarify the request, write and approve the spec, produce a plan, split it into tasks, implement, and review against the spec. Between steps there are deliberate checkpoints where a person decides whether to continue.

1. Clarify the request

If you are not sure yet what you want, let the agent ask. The best practices suggest a prompt along the lines of: interview me until you could write the spec, then write it to SPEC.md. In the documentation's rate-limiting example, the agent comes back with questions such as per-user versus per-key limits and what is out of scope.

2. Write and approve the spec

A spec that an agent can work from needs only a few fixed sections:

# Feature: Export unpaid invoices to CSV

## Goal
Finance staff export all unpaid invoices for a chosen date range.

## Requirements
- WHEN a user selects a date range and clicks "Export",
  THE SYSTEM SHALL return a CSV file with all unpaid invoices.
- WHEN the range contains no unpaid invoices,
  THE SYSTEM SHALL return a file with the header row only.

## Edge cases
- Commas, quotes and non-ASCII characters in customer names
- Ranges that cross a financial year end

## Out of scope
- XLSX output, scheduled exports

## Acceptance
- Tests for every requirement and edge case pass
- [NEEDS CLARIFICATION: which currency format does accounting expect?]

The out-of-scope list and the open questions do most of the work. Both stop the agent from inventing answers. Approve the spec only when no clarification markers remain.

3. Produce a plan

For planning, switch to a mode where the agent reads but does not write. In Claude Code that is plan mode: press Shift+Tab, prefix a single prompt with /plan, or start with claude --permission-mode plan. The agent reads files, runs exploratory commands and writes a plan, but does not edit your source until you approve it. Ctrl+G opens the proposed plan in your editor so you can change it first.

# start a planning session in plan mode
claude --permission-mode plan

4. Split it into tasks

A good task is small enough to finish in one session and has a checkable outcome, ideally a test that fails before and passes after. Spec Kit's methodology makes this explicit: tests are confirmed to fail, the "Red phase", before implementation. Tag each task with the requirement it satisfies, so that gaps are obvious at the end.

5. Implement

Start implementation with a clean context. The best practices recommend opening a fresh session once SPEC.md exists, so the build begins with a written definition of done rather than a long planning conversation. Have the agent run the checks after every task and show you the output. As the documentation points out, "all tests pass" on its own tells you very little; the command and its output tell you a lot.

6. Review against the spec

Finally, the work is reviewed by something that did not write it. The best practices suggest asking a subagent to review the diff against SPEC.md: is every requirement implemented, and do the listed edge cases have tests? They also advise telling the reviewer to skip style. A reviewer asked to find problems will always find something, and acting on every finding adds layers of abstraction and tests for cases that cannot happen.

How do you run tasks in parallel safely?

Parallel work only makes sense for tasks that touch different files and do not wait on each other. The task list is what makes this decision possible: once dependencies are written down, you can see what may run at the same time. Each parallel stream needs its own working copy.

The tools handle this differently. Spec Kit marks independent tasks with [P] and outlines safe parallel groups. According to the Kiro docs, running all tasks builds a dependency graph and groups independent tasks into waves; waves run in sequence and tasks within a wave run concurrently. In Claude Code, you separate parallel sessions with git worktrees.

Three rules hold up well in practice:

  • Shared contracts first. Data models and interfaces used by several tasks belong in an early task that is finished before any parallel work starts.
  • No shared files. Two tasks that edit the same file are not independent, however separate they look on paper.
  • Merging is a task of its own. After each wave, run the full checks on the merged result, not just inside each working copy.

Keep the cost in view. The best practices note that every subagent sends its own requests, and a fresh one first has to gather context the main session already had. Parallelism buys you speed or a fresh pair of eyes, not a smarter answer.

What are the limits and risks?

Spec-driven development moves effort to the front. On small or exploratory work, that effort costs more than it returns. And a wrong spec will steer the agent, very consistently, in the wrong direction: structure does not protect you from bad requirements.

  • Too much paperwork. A full spec, plan, data model and task list for a ten-line change is bureaucracy. The Claude Code documentation is clear that a vague prompt is fine when you are exploring.
  • Stale documents. If requirements change during implementation and the spec is not updated, the review checks against the wrong version. Change the spec first, then the code.
  • False precision. Formal notations such as EARS make requirements easier to test, not automatically correct. Domain sign-off remains human work, which is one reason the approval step works as a form of human-in-the-loop control.
  • Tasks that are too big. When a task does not fit in one session, context grows and corrections pile up. The best practices advise running /clear after two failed corrections and writing a better prompt. In spec terms: cut the task smaller.
  • Reviews that nitpick. A review agent that reports everything creates work without value. Limit the review to deviations from the spec that affect correctness.

How do you get started?

Pick one medium-sized feature and use the lightweight variant: a Markdown spec in the repository, a planning phase with no code changes, and a review against the spec at the end. Adopt a template toolkit only once that loop works for your team.

A practical first round:

  1. Write down your check commands. Put the test, typecheck and lint commands in the project rules, for example CLAUDE.md. Without them no agent can verify its own work.
  2. Create a spec template. Goal, requirements, edge cases, out of scope, acceptance, open questions. That is enough to begin.
  3. Review the first run. After the first feature, note where the agent deviated from the spec and why. Usually a section was missing or a requirement could not be tested as written.

In our own operations, the checkpoint after the plan has proved its worth: a short look at the plan costs little and stops an agent from building in the wrong direction. If you want to embed the workflow in a team, a hands-on workshop is a practical way to rehearse spec, plan and review on your own codebase.

Frequently asked questions

Do I need a dedicated tool for spec-driven development?

No. Spec Kit and Kiro add templates and a fixed sequence, but a plain Markdown file in the repository, which the agent reads and the reviewer checks against, gives you most of the discipline.

How detailed should a spec be?

Detailed enough that every requirement can be tested and every open question is visible. Clear acceptance criteria and an explicit out-of-scope list matter more than page count.

Is it worth it for a small bug fix?

Usually not. A precise prompt that names the file, the symptom and a failing test does the job with far less overhead.

Should a human or the agent write the spec?

Both. A practical split is that the agent drafts the spec by asking you questions, and a person with domain knowledge reviews and signs it off before planning starts.

Sources

  1. GitHub Spec Kit – repository and README github.com
  2. GitHub Spec Kit – Spec-Driven Development methodology github.com
  3. Kiro Docs – Specs kiro.dev
  4. Kiro Docs – Feature Specs kiro.dev
  5. Claude Code Docs – Best practices code.claude.com
  6. Claude Code Docs – Permission modes (plan mode) code.claude.com