How to write a spec for an AI coding agent

Published 23 October 2026

A good spec for an AI coding agent is short, covers one change, says why, and turns every requirement into cases the agent can run and pass or fail. It says “must”, names what is out of scope and what must not change, points to the code it touches, and marks what nobody knows yet. Someone writes it, or at least cuts down the agent’s draft, before the agent plans; someone reviews the plan; and when the work finds something the spec got wrong, the spec changes first. Below are twelve rules, each with the research or the practice behind it, a vague spec rewritten by them, and a checklist.

Time spent making the spec precise pays off more than time spent watching the implementation.

— Claude Code documentation, Anthropic

The twelve rules at a glance

Rule 1: Keep it to one change you can check in a day

A spec that covers a whole feature area is hard to read and hard for the agent to follow. Birgitta Böckeler of Thoughtworks, testing TDD with agents, saw the effect directly: “They frequently overshot and implemented more than the current test demanded, because they had the full requirement available” (martinfowler.com, 2026). Practitioners mostly settle on one story or one module. One developer who built 100,000 lines of Rust with agents: “a single user story feels like the “sweet spot” unit of work they can manage effectively” (Cheng Huang, 2025). And on Hacker News: “Make sure the first iteration of the spec is small, small, small” (Hacker News, 2026).

The lower bound matters too. Anthropic’s guidance for Claude Code: “If you could describe the diff in one sentence, skip the plan.” Bug fixes and one-line changes do not need a spec.

Rule 2: Start with why

One or two sentences: the problem, and who has it. It is what the agent — and the reviewer — can fall back on where the spec says nothing. The largest study of spec-driven development in practice found that “Practitioners agreed that specs should capture intent” (Agarwal et al., 2026, preprint), and the habit has shifted that way: “These days it’s more about saying why than what” (Hacker News, 2026).

Rule 3: Write acceptance as cases that pass or fail

This is the rule with the strongest evidence. Giving a model the tests with the task “improves correctness by 9.15 to 29.57%” (Mathews and Nagappan, ASE 2024). In 2,700 runs with specs built from the Spec Kit template, removing the acceptance scenarios made a difference and removing prose success criteria did not: “What matters is concreteness about which cases must pass, not the presence of a stated requirement” (Smékal, 2026, preprint).

Write each criterion as an example with real values — a date, an amount, a state — and the expected result. Given/When/Then is one way; a numbered list of cases is another. The forms are in acceptance criteria, Gherkin examples and EARS.

Rule 4: Say “must”, not “should”

From the interviews behind one 2026 study: “One practitioner we interviewed said their team writes “must” instead of “should” when instructing a coding agent, because the agent may treat “should” as optional” (EPIC, preprint). Requirements standards draw the same line, with “shall” for what is required. If something really is optional, say so, and say who decides.

Rule 5: Say what is out of scope and what must not change

An agent sees nothing that tells it to stop. Anthropic’s description of the most useful specs: they “name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works.” Product managers make the same point about prototypes: “A prototype tells you what to build, but it doesn’t explain what you are explicitly not building” (r/ProductManagement, 2026).

“Must not change” is the line that protects what already works: existing behaviour, other screens, an interface someone else depends on.

Rule 6: Point to where; keep the how light

Location helps an agent. In a study of 433 issues attempted by 87 agents, naming the file a fix changes multiplied the odds of success by 2.33 (Khatib et al., 2026, preprint). An agent that cannot see the codebase stays “context blind”, in the words of another study.

Design detail is different. The tools keep the “how” in a plan, yet 77.6% of real specs carry implementation detail — class names, file paths, library versions. It may help, and it has a cost: “implementation detail may help agents while making specs prone to decay” (Agarwal et al.). Name the places and interfaces the change touches; leave the design to the plan, which is thrown away or redone more easily.

Rule 7: Cut it down

Longer is not better for an agent. Across those 433 issues, longer reports went with lower success — 51% lower odds per standard deviation of length (Khatib et al.). People report the same:

If you leave it to the AI, it will bloat the spec with 10x the details, many of which should be left out of the spec.

— Hacker News, 2026

A founder whose product turned plans into long specs: “The spec contained more information without creating more clarity” (Ayman Nadeem, 2026). Cut background the agent cannot use, repeated rules that belong in CLAUDE.md or AGENTS.md, and anything the acceptance cases already say.

Rule 8: Mark what you don’t know, and let the agent ask

Agents rarely stop to ask. In one benchmark, “more than 60% of responses from Code LLMs still generate code rather than ask questions” (HumanEvalComm); in another, “models struggle to distinguish between well-specified and underspecified instructions” — but when they did ask, results improved by up to 74% (Ambig-SWE, ICLR 2026).

So write the open questions into the spec, with who answers each, and make asking part of the process. Anthropic’s pattern for Claude Code is to let the agent interview you: “Keep interviewing until we’ve covered everything, then write a complete spec to SPEC.md.” One developer’s experience of that step: “The questions are usually 80% useless but those 20% often do point me to stuff I have not considered” (Hacker News, 2026).

Rule 9: Write security and other limits in

What the spec does not say, the code does not do. A 2026 benchmark found that “functional behavior is described explicitly, while security behavior remains implicit, generic, or postponed to post-generation review”. Adding security requirements to the spec cut the failures in its test application from 50 to 42, or to 36 with the authors’ own security model (Grynets et al., preprint, one application). In 2,303 agent context files, “non-functional requirements such as security (14.8%) and performance (14.5%) are rarely specified” (Agent READMEs, TOSEM).

Who may do it, what must never leak, how fast, how many: one line each, with a number where there is one. Examples are in non-functional requirements.

Rule 10: Write it yourself, or edit the agent’s draft hard

An agent can draft a spec in seconds, and that is the problem: the draft is long, plausible and unread. “Do I read the full spec it produces at the end? Usually not” (Hacker News, 2026). The Thoughtworks Technology Radar, on agent instruction files: “research suggests that hand-written versions are often more effective than LLM-generated ones” (Thoughtworks, April 2026). One developer who writes specs by hand: “writing the spec manually prevents infecting the spec with the typical LLM specification slop” (Hacker News, 2026).

Let the agent draft and ask questions; then cut the draft to what you would sign, in your own words. If someone else has to agree to it, they read that version — see who reviews the spec.

Rule 11: Review the plan, then build in a fresh session

The plan the agent derives from the spec deserves its own look. Across 21,120 agent runs: “Providing the standard plan improves issue resolution, and we observe that periodic plan reminders can mitigate plan violations and improve task success” — and “A subpar plan hurts performance even more than no plan at all” (Liu et al., ASE 2026).

How the spec reaches the agent matters as well. In a small pilot, asking for “a specification, then the code” in one prompt did no better than asking for code; writing the spec first and implementing from it in a fresh step nearly doubled the pass rate (Nitin Garg, InfoQ, 2026). Anthropic’s guidance is the same: once the spec is written, start a fresh session to build from it.

Rule 12: When the work finds something, change the spec first

Building always finds something the spec got wrong. If the fix goes into the code alone, the spec starts to decay the same day. One commenter’s rule: “I propose updating the spec then do the implementation” (Hacker News, 2026). Marc Brooker, an engineer at AWS, which makes Kiro: “Specs stay in sync with implementation by being upstream of implementation for most changes” (brooker.co.za, 2026).

Give the agent the current spec, not the trail of changes that led to it. In one 2026 study, of 100 cases where agents succeeded from the final spec, 35 failed on at least one history of revisions that ended in the same spec (SpecPath, preprint). Keep the history for people — see tracking changes to requirements — and the latest version for the agent.

Before and after: one spec, rewritten

A request as it often arrives:

Remind customers about unpaid invoices.
Send an email when an invoice is overdue
so they pay faster. Should be
configurable and look professional.

The same request as a spec, by the rules above — the payment reminder from the customer portal used across this site:

SPEC: Payment reminder (FR-016, v2)

Why: invoices stay unpaid too long
(BR-03); the accounts team chases them
by hand.

FR-016  The portal must send one
        reminder, seven days after the
        due date, for every invoice not
        paid in full, to the company's
        billing contact.

Acceptance cases
1. Due 1 March, unpaid on 8 March:
   one reminder that day.
2. The same invoice on 9 March: no
   second reminder.
3. Paid in full on 5 March: none.
4. Partly paid by 8 March: one
   reminder.

Security: the email links to the
invoice in the portal (sign-in
required); no attachment.

Touches: the nightly reminder job and
the email templates.

Must not change: the receipt email
(FR-015); invoice statuses.

Out of scope: a second reminder;
push notifications (CR-8).

Open question: should the reminder
show the amount still due? (finance
lead)

“Configurable” and “professional” are gone: nobody could test them. What was meant by them either became a case, a limit or a question, or it was not needed.

A checklist before the agent starts

1. One change; you could check the result in a day.
2. Why, in two sentences at most.
3. Every requirement says “must” and has cases with real values.
4. Out of scope and must-not-change are written down.
5. The files or interfaces it touches are named; the design is left to the plan.
6. Security, limits and numbers are in, where they apply.
7. Open questions are listed, each with who answers it.
8. You have read every line, and cut what the agent does not need.
9. The person who has to agree has read it.
10. You will review the plan before the code.

The empty file to start from is the spec template; what the research says about spec-driven development as a whole is in does spec-driven development work?

Where Specroot fits

This is the problem Specroot works on: specs short enough that the people who have to agree with them actually read them, and that stay true when the work changes them. Specroot for teams using AI coding agents.