How to write a spec for an AI coding agent

A specification (spec) for an AI coding agent is a short document that says what changes, which decisions you have made about it, how to check the result and what must stay untouched. Write the request in a line or two, have the agent question you until every decision in it is yours, then write the spec from your answers. The questions do most of the work, because they bring out what you had not decided.

What a one-line request leaves undecided

Take a meal-planning web app with three tabs in this order: Recipes, Plan, Shopping list. You use the shopping list most, so you type this:

Move the Shopping list tab to the first position.

The request reads as complete, and an agent will carry it out without asking anything. To do so it has to settle several things you never mentioned:

whether the app opens on Shopping list, because so far it has opened on whichever tab came first;
whether the shopping list is fetched at start-up, as the first tab's content is, or when its tab is opened;
whether a returning user lands on the tab they used last or on the new first tab;
whether the keyboard shortcuts 1, 2 and 3 follow the new order;
whether the bottom bar of the phone layout changes too.

None of these is difficult. Each is a decision about your product, and an agent that isn't told makes it for you without saying so. Anthropic's best practices for Claude Code put the limit in one line: "Claude can infer intent, but it can't read your mind." A longer prompt doesn't help here, because you can't list decisions you don't know you are facing.

Have the agent ask before it writes code

The agent can find the open decisions faster than you can, because it reads the code the change touches. Ask it to. Anthropic recommends an interview for larger features and notes that the agent then "asks about things you might not have considered yet". The tab move shows that the same step pays on a small change.

I want to move the Shopping list tab to the first position.

Before you write any code, read how the tabs are built. Then ask me about
every decision this change forces that I haven't made. Give two to four
options per question and say which you would pick and why. Skip anything
the code already answers.

For the tab move, the round of questions comes out like this:

Question	Options	Decision
Which tab is selected when the app loads?	Shopping list; Recipes as before; the tab used last	The tab used last, and Shopping list on a first visit
When is the shopping list fetched?	At start-up; when its tab is opened	When its tab is opened
Do the shortcuts `1`, `2` and `3` follow the new order?	Follow the visual order; keep their tabs	Follow the visual order
Does the bottom bar of the phone layout change?	Same order as desktop; leave it	Same order as desktop
Does a link to `/recipes` open Recipes for a returning user?	The link wins; the tab used last wins	The link wins

Two of the five answers differ from what the one-line request implied. The app will open on the tab used last, which the request never mentioned. The question about links exists only because the agent read the router and saw that two rules would collide.

Stop when a round of questions changes nothing about what will be built. Questions about naming or code style are answered by your project's rules file, so they don't belong in this session.

Write the spec from your answers

The spec for the tab move fits on one screen:

# Move the Shopping list tab to the first position

## Outcome
The tab bar reads Shopping list, Recipes, Plan on desktop and on the phone
layout. People who shop with the app reach the list in one tap.

## Decisions
- The app opens on the tab the person used last. On a first visit it opens
  on Shopping list.
- The shopping list is requested when its tab is opened. It is not requested
  at start-up when another tab opens first.
- The shortcuts follow the visual order: 1 Shopping list, 2 Recipes, 3 Plan.
- A link to /recipes or /plan opens that tab, whichever tab was used last.

## Acceptance criteria
- Given a first visit, when the app loads, then Shopping list is selected
  and its items are shown.
- Given a person whose last tab was Plan, when the app loads, then Plan is
  selected and no request for the shopping list is made.
- Given any tab, when the person presses 1, then Shopping list is selected.
- Given a phone-width screen, when the app loads, then the bottom bar shows
  Shopping list, Recipes, Plan.
- Given a person whose last tab was Plan, when they follow a link to
  /recipes, then Recipes is selected.

## Out of scope
- The content and layout inside each tab.
- Tab names and icons.
- The onboarding tour, which lists the tabs in its own order. Report what
  you find there and leave it unchanged.

## Verify
- `npm test -- tabs` passes, with one new case per criterion.
- In a browser with site data cleared, load the app and check the selected
  tab and the network panel.

Outcome and the reason for it

The outcome is one or two sentences on what is different for the user afterwards, with the reason. The reason is there because the agent meets small choices that no spec lists, and "reach the list in one tap" tells it which way to lean.

Decisions you made in the question round

The decisions are your answers, written as statements. A spec written without the question round has nothing to put in this section, and the agent fills the gap by guessing.

Acceptance criteria a test can check

Each criterion names one behaviour that a test or a person can check. The example uses the Given/When/Then form. Kiro's specs use EARS, the Easy Approach to Requirements Syntax, whose pattern is "WHEN [condition/event] THE SYSTEM SHALL [expected behavior]". Either form works. A criterion such as "the tabs feel faster" fails, because nothing can check it.

What is out of scope

The out-of-scope list names the neighbours of the change, the code the agent will read on the way and may want to improve. Say what to do with a problem found there. How to keep track of what your AI agent finds covers that line and what to do with the reports.

How the agent verifies the change

The last section gives the command to run and the thing to look at. Anthropic's advice is to give the agent "a check it can run". Without one, the agent stops when the work looks done, and you become the one who finds the mistakes.

A spec template to copy

# <What changes, in one line>

## Outcome
<What is different for the user afterwards, and why it matters.>

## Decisions
- <One answered question per line, written as a statement.>

## Acceptance criteria
- Given <state>, when <action>, then <result that can be checked>.

## Out of scope
- <What the agent must leave unchanged, and what to do if it finds a problem there.>

## Depends on
- <Other specs or existing parts that must be in place first.>

## Verify
- <The command to run, or the thing to look at.>

Leave out a section that has nothing to say. The tab move has no "Depends on" section, and a spec for a bug fix can be one decision and one criterion.

How long a spec for an agent should be

A spec for one change fits on a screen. Addy Osmani, in How to write a good spec for AI agents, cites research on what he calls the "curse of instructions": as directives pile up, a model may follow the first few and overlook the rest. A spec is a set of directives, so every line that isn't needed makes the needed lines weaker.

Cut anything the agent can read in the code. Move a convention that holds for every change into the rules your agent loads in every session, where you can share it across projects. Drop implementation steps, unless a step is a decision you made. GitHub's advice for the first version of a spec is the same: focus on the what and the why and leave the technical details for the plan.

When the criteria fall into groups, or the spec covers several things a user can do, it is several specs. How to break down a spec for AI coding agents shows how to split it and keep the parts connected.

Working this way has a name, spec-driven development (SDD). The guide to spec-driven development covers where it came from and what its critics say, and the comparison of SDD tools describes the tools that generate specs of this kind for you.

The question round in Athenode

Athenode is a spec-driven development platform that runs this question round inside your AI coding tool. A mind map in Athenode is a session in which your AI agent asks rounds of questions and turns your answers into a spec. The agent looks at your codebase first, each question comes with options, and every question and answer is kept with the spec in your Athenode project. A change the size of the tab move needs the mind map and no further step. The mind map page describes a session, and the quickstart takes you from a new account to a first spec.

Sources

Anthropic, Best practices for Claude Code
Addy Osmani, How to write a good spec for AI agents, January 2026
Kiro, Feature specs
Den Delimarsky, Spec-driven development with AI: Get started with a new open source toolkit, GitHub, September 2025