Skip to content
Module

Writing a spec an AI coding agent can execute

A spec for an AI coding agent says what to build, why, and how to check it. Sections, task slicing, reviewing agent work, plus a free SPEC.md template.

Guide written by Alex Dionisio, Senior Product Manager. Updated November 13, 2026.

In short

A spec for an AI agent is a short document that tells a coding agent (Claude Code, Cursor, Codex…) what to build, why, within which limits, and what proves the work is finished. It differs from a PRD in scope: one precise task, testable acceptance criteria and an explicit boundary. Without it, the agent plugs the gaps with assumptions that sound right. With it, you can check the result against something written down.

What is a spec for an AI agent?

A spec for an AI agent is a file, often called SPEC.md, that describes a feature thoroughly enough for a coding agent to build it without guessing: goal, context, scope, testable acceptance criteria, constraints and edge cases. It is also the reference you use to review the agent’s work.

An AI coding agent reads your repository, edits files, runs commands and chains steps on its own until it decides the task is finished. It executes what you wrote, not what you meant. The spec is there to close the gap between the two.

In practice, a spec for an agent runs one or two pages of Markdown, saved in the repository or pasted into the session. It is written for a reader who knows nothing about your users, your meetings or the history behind a decision, and who will not always ask when something is missing.

Spec-driven development is the name for making that spec the starting point of the work: first write what to build and why, then derive a plan, tasks and finally the code. GitHub’s open source Spec Kit provides tooling for this approach. The Claude Code documentation describes a lighter version: have the agent draft a SPEC.md, then build from that file in a fresh session.

Spec vs PRD vs user story: what is the difference?

A PRD frames an initiative (problem, audience, goals), a user story states what a user needs, and a spec for an agent describes one precise task with its limits and its proof of completion. The agent spec is narrower and more explicit than the other two.

These documents do not compete; they nest. The PRD answers “why this initiative?”. The user story answers “who needs what, and to do what?”. The agent spec answers “what must be true in the product when this task ends, and how do we observe it?”.

  • Reader: the PRD is for the team and decision makers, the user story for the team that will discuss it, the agent spec for an executor who will attend none of those discussions.
  • Scope: a PRD often covers weeks of work; an agent spec covers a task whose result you can review in one sitting.
  • What stays implicit: a user story deliberately leaves details to conversation. An agent spec has to write them down, because that conversation will be short or will not happen at all.
  • Proof: an agent spec ends with criteria the agent can run or observe, not with a general intention.

So keep your PRD and user stories. The agent spec pulls out the piece to build and adds what the agent cannot know. The lesson What is a spec? PRD vs feature spec vs ticket helps you pick the right level of detail for the decision at hand.

Why does an AI coding agent need a spec?

An AI coding agent needs a spec because written material is all it has to go on: the code in the repository, its instruction files and your message. Decisions made in meetings, priorities and the cases your team knows about are invisible to it, so it fills those gaps with plausible but sometimes wrong choices.

  • Missing context. A current agent is very good at reading a repository: structure, conventions, existing tests. What it cannot read is what was never there: the business rule agreed last week, the customer with a special case, the reason behind a choice. The Claude Code documentation gives the same advice: write down only what the agent would not find by reading the code.
  • Ambiguity. Given a vague request, a colleague asks a question. An agent often goes ahead with the most likely interpretation. The result runs, looks finished, and does not do what you wanted. It works much like an LLM hallucination: a plausible answer standing in for missing information.
  • The context window. Everything the agent holds during a session lives in its context window: instructions, files read, command output, the conversation. A context cluttered with failed attempts leads to worse answers, while a session that starts from a written spec starts clean. Anything you explained in a previous session is gone for the agent unless it is written somewhere.

A spec is not about “talking to the AI” with special phrasing. It puts in writing the decisions that are not in the code. For installing and getting started with the tool itself, see the guide Claude Code for Product Managers.

What should a spec for an AI agent include?

A good spec for an AI agent has seven parts: the goal, the relevant context, scope and out of scope, testable acceptance criteria, constraints, concrete examples and edge cases. Each part answers a question the agent would otherwise settle on its own.

  1. Goal: the problem solved and the expected outcome, in two or three sentences. The “why” helps the agent make small trade-offs in the right direction.
  2. Context: what the agent cannot guess. Affected users, business rules, decisions already made, the starting screen or file if you know it.
  3. Scope and out of scope: what should change, and above all what must not. One line saying “do not touch the payment module” prevents a lot of surprise edits.
  4. Acceptance criteria: verifiable acceptance criteria, ideally in Given/When/Then form: a situation, an action, an observable result. “Fast” or “intuitive” cannot be checked; “the list renders in under one second with 500 items” can.
  5. Constraints: non-functional requirements (performance, security, accessibility, personal data) and imposed technical constraints, such as an existing library to reuse or a ban on new dependencies.
  6. Examples: an input and its expected output, the exact wording of an error message, the screen mockup. One example removes more ambiguity than a paragraph of explanation.
  7. Edge cases: empty data, extreme values, duplicates, interrupted actions, missing permissions. These are the situations an agent handles worst when nobody wrote them down.

Finish with a definition of done: the check command to run, what must pass, and what the agent must show you as evidence. If the feature itself produces an AI response, the format of that response belongs in the spec too: the course Structured outputs shows how to write it as a contract.

How do you break a feature into tasks for an agent?

Break a feature into tasks an agent can finish and whose result you can review in one sitting: one task, one observable behavior, one list of criteria. If you cannot say how a task will be checked, it is too big or still unclear.

A single spec for “rebuild onboarding” produces a huge change that is hard to review and easy to hide mistakes in. A better setup is one feature spec that keeps the big picture, followed by a series of short tasks that point back to it.

  • Slice by visible behavior, not by technical layer. “The user can skip step 2” is testable; “create the data model” does not say when it is done.
  • Order by dependency: foundations first, variants and polish after.
  • One task, one session: starting each task from a clean context keeps the agent from mixing up instructions.
  • Isolate the risky parts: data migrations, payments, access rights. These deserve their own spec and a closer review.

A quick test: can you list the task’s acceptance criteria without writing “etc.”? If so, it is ready for the agent.

How do you check an AI coding agent’s work?

Check an AI coding agent’s work at two moments: before it codes, by reviewing its plan against the spec, and after, by asking for evidence for each acceptance criterion (tests run, output, screenshots). An agent that says “done” has not proved anything yet.

  1. Review the plan. In Claude Code, plan mode has the agent explore the repository and propose changes without editing code until you approve. Look for missed criteria, out-of-scope files and unstated assumptions.
  2. Give it a check to run. A test, a build or a script that returns pass or fail lets the agent fix things on its own before handing back. Without one, you end up playing the test suite.
  3. Ask for evidence. The command it ran and its output, or the screenshot, criterion by criterion. Reading test output is faster than redoing everything yourself.
  4. Get a review against the spec. A fresh reviewer, human or subagent, compares the changes with SPEC.md: is every requirement covered, every edge case tested? The Claude Code documentation suggests telling the reviewer to skip style so it only reports the gaps that matter.
  5. Try the flow yourself. Open the screen, attempt an edge case. A few minutes of real use catch what the tests did not anticipate.

The lesson on reviewing a coding agent’s plan walks through this review for a PM who does not read code. On the tooling side, the course Claude Code: context, plan and review sets up permissions, guardrails and review on your repository.

What mistakes should you avoid in an agent spec?

The most common mistakes in a spec for a coding agent are criteria that cannot be checked, a missing out-of-scope list, a solution with no problem behind it, missing edge cases and a spec so long the essentials get lost. Each one lets the agent decide for you.

  • Criteria that cannot be checked: “simple”, “robust”, “the usual way”. Replace every adjective with an observable result.
  • No out-of-scope list: the agent tidies up a neighboring component, renames files, adds a dependency. Say what must not change.
  • The solution without the problem: “add a CSV export” without saying the need is to share a report with leadership. The agent ships the export, not necessarily what solves the problem.
  • Too much text: a ten-page spec that re-explains the repository’s architecture. The agent already reads the code; save the space for what it cannot read.
  • Instructions in capitals: “ALWAYS”, “IMPORTANT”. The Claude Code docs note that current models follow plainly worded instructions; a rule with no exceptions should be enforced by an automated check, not by capital letters.
  • A spec written after the fact: drafted to document what the agent already did, it no longer guides anything and can no longer be used to check the work.

How do you keep a spec alive after release?

Keep a spec alive by versioning it alongside the code, in the same repository, and updating it whenever a decision or a newly found case changes the expected behavior. A spec that no longer describes the product misleads both the team and the agents.

An agent spec is not disposable. When the agent uncovers a case nobody planned for, fixing the code is not enough: add the case to the spec, so the next session, or the next agent, starts from the right version.

  • Version it with Git, in a dedicated folder or next to the feature, so every behavior change leaves a trace.
  • Log decisions at the bottom of the file: date, choice, reason. That is the information that disappears fastest.
  • Move lasting rules out: conventions that apply to the whole repository belong in the agent’s instruction file (CLAUDE.md for Claude Code, AGENTS.md for Codex, Cursor and other tools), not in every spec.
  • Delete what has become wrong instead of stacking up exceptions.

To apply the whole method to a real feature in your product, from intent to a versioned file in the repository, the course Writing specs for developers and AI agents guides you step by step.

Free template: SPEC.md

Copy this file into your repository, fill in one copy per task and give it to your agent before asking for a plan. Delete any lines that do not apply.

Download SPEC.md
# Spec: [feature name]

Status: draft | ready | shipped
Last updated: [date]

## Goal
[Which problem, for which users, what outcome is expected. 2 to 3 sentences.]

## Context
- Affected users: ...
- Business rules to respect: ...
- Decisions already made: ...
- Starting point (screen, file), if known: ...

## In scope
- [What should change]

## Out of scope
- [Files, screens or behaviors to leave untouched]
- No new dependency without approval.

## Acceptance criteria
1. Given [situation], when [action], then [observable result].
2. Given ..., when ..., then ...
3. ...

## Constraints
- Performance: ...
- Security and personal data: ...
- Accessibility: ...
- Technical: [library to reuse, compatibility to keep]

## Examples
- Input: ... → expected result: ...
- Exact error message: "..."

## Edge cases
- Empty data: ...
- Extreme value: ...
- Interrupted or repeated action: ...
- Missing permissions: ...

## Definition of done
- [ ] Every acceptance criterion has a passing test
- [ ] Check command: [e.g. npm test]
- [ ] Evidence provided: command run, output, screenshots
- [ ] No out-of-scope file modified

## Decisions
- [date]: [decision], because [reason]

Put it into practice

The “Write specs that developers and AI agents understand” course walks you through it step by step, on your own product, all the way to the deliverable.

See the course

Frequently asked questions

Do you need to code to write a spec for an AI agent?

No. A spec describes expected behavior, rules and evidence, not code. Being able to read test output helps with checking, but most of the work is product work: clarifying intent, limits and criteria.

How long should a spec for a coding agent be?

One to two pages per task is usually enough. If the spec runs much longer, the task probably needs splitting, or the spec is re-explaining things the agent will find in the code.

Can you ask the AI to write the spec?

Yes, as a starting point. The Claude Code documentation suggests asking the agent to interview you until it can write a SPEC.md, then building in a fresh session. Still review every criterion: the agent only knows your decisions if you give them to it.

Does the same spec work with Claude Code, Cursor and Codex?

Yes, as long as it is plain Markdown with no tool-specific syntax. What changes from one tool to another is the permanent instruction file and how you ask for a plan or run the checks.

Is specifying a coding agent the same as specifying an AI agent inside my product?

No. Here, the agent is the executor writing the code. Specifying an agent built into your product (its tools, its loop, its human approvals) is a different exercise, covered in the course Designing reliable agents and tool calling.