Skip to content

Writing a spec for AI coding agents: one line vs. ten

From the work/ 14 min read

A one-line prompt leaves the agent guessing. A ten-line spec gives it a goal, constraints and acceptance criteria it can check on its own.

  • AI
  • Claude Code
In this article (10)
  1. Why one line is not enough for an AI agent
  2. Goal: what changes, and for whom
  3. Constraints: what the agent cannot guess
  4. Acceptance criteria: how you know it is done
  5. A complete example: before and after
  6. Where to keep the spec: an issue or SPEC.md
  7. Check the spec before, and the work after
  8. Common mistakes
  9. Frequently asked questions
  10. Checklist

A spec for AI coding agents is a short text that says what to build (the goal), what not to touch (the constraints) and how to tell it is done (the acceptance criteria). Give an agent one line and it guesses the rest; give it about ten and it builds what you asked for and can check its work.

Below are the three parts, a full before-and-after example from a Next.js store, where to keep the spec, and a Node script that checks nothing is missing. What we attribute to the Claude Code documentation comes from its best practices page, read on November 19, 2026; the rest is practice.

Why one line is not enough for an AI agent

Type "add a free shipping bar to the cart" and a coding agent will do something reasonable. The catch is that many things are reasonable and only one of them is what you had in mind. With that line, the agent decides on its own where the bar goes, where the threshold comes from, how money is formatted, which files it may touch, what it must leave alone and, above all, when it is done.

The Claude Code documentation puts it this way: the agent is very good at reading your code and finds the layout, the conventions and the test framework by itself. What it cannot find is what was never in the repo: a decision made in a meeting, a preference between two valid approaches, or what "done" means to you. So the docs recommend naming the file, describing the symptom and saying up front what "fixed" looks like. Their example: instead of "fix the login bug", say when it fails, where to look, and ask for a failing test that reproduces it first.

There is a second reason. According to the same page, Claude tends to read a request conservatively and build the smallest thing that satisfies it, because it cannot see how much you were hoping for. If you want the empty and error states, or the whole flow wired up, you have to say so. A spec is where you say it once.

You do not need one for everything. When you are exploring ("what would you improve in this file?"), a vague prompt is fine and you correct as you go. A spec pays off when the change spans several files, when there are rules the code does not show, or when you are going to leave the agent running on its own. If what you have is a bug, a good bug report for AI is already a spec: the error, the steps to reproduce it and the expected result.

a one-line prompt against a ten-line specone lineadd a free shipping barto the cartthe agent guesses:· where the bar goes· where the threshold comes from· how money is formatted· which files it may touch· what it must not touch· when it is doneten lines# Free shipping bar## Goal## Constraints## Acceptance criteria## Out of scopethe agent knows what to do and when to stopthe same change, asked for in two ways

Scroll the figure sideways to see all of it

Goal: what changes, and for whom

The goal is one or two sentences that describe the outcome, not the implementation. "In the cart drawer, show how much the customer still needs to spend to get free shipping" says what the person sees and where. It does not say which component to create or which hook to use: the agent can decide that by reading the code.

Two quick tests for a good goal. First, someone who was not in the conversation can tell what is going to change on screen or in the system. Second, it does not bundle two changes. If your goal has an "and also", you probably have two specs and two branches.

the three parts of a spec1 · goalwhat changes?a free shipping barin the cart drawerfor the shopperone or two sentences2 · constraintswhat is off limits?only components/cart/threshold in lib/shippingno new dependencieswhat the repo cannot say3 · criteriawhen is it done?subtotal 60: $39 to gosubtotal ≥ 99: freenpm test passespass or failwithout the third, the agent stops when the work looks donethree parts, about ten linesillustrative amounts; example Next.js store

Scroll the figure sideways to see all of it

Constraints: what the agent cannot guess

Constraints are the edges of the change: which files it may touch, which existing utilities it must use, which dependencies stay out, and what is out of scope. To decide what to write, the Claude Code docs offer two questions: could it find this by reading the code? Would it actually go and look? If both answers are yes, leave it out.

In the example, "format with formatMoney from lib/money.ts" belongs in the spec, because there are other valid ways to format money and the agent could write its own. "The project uses TypeScript" does not: it sees that in the first file it opens. The same goes for preferences: if you care which of two reasonable approaches it picks, say so, because that is not in the code.

An "Out of scope" section prevents a lot of surprises. "The real shipping calculation at checkout is out of scope" stops the agent from helpfully fixing that too.

Be careful about what goes here. The docs separate instructions the model reads and then decides whether to follow (your prompt, CLAUDE.md, a skill) from rules the tool always enforces (hooks, deny rules). A spec is the first kind. If a rule cannot have exceptions, such as never editing a generated directory, put it in a hook or in the permissions. And if it is a project-wide rule rather than a rule for this task, it belongs in the instructions file: here is how to write AGENTS.md and pair it with CLAUDE.md.

Acceptance criteria: how you know it is done

This is the part people skip most often, and the one that changes the outcome the most. The Claude Code docs are blunt about it: the agent stops when the work looks done, and if it has nothing to run that tells it whether the work actually is done, "looks done" is all it has. Their advice is to give it something that comes back pass or fail: a test file, a build's exit code, a linter, a script that diffs output against a fixture, or a screenshot next to the mockup.

An acceptance criterion works if someone who did not write the code can check it from the outside and reach the same answer. "Make it look good" fails that test. "The text is fully visible at 375 px wide, with no horizontal scroll" passes.

VagueCheckableHow to check
Make it look goodThe text is fully visible at 375 px, no horizontal scrollScreenshot at 375 px
Make it workWith a subtotal of 60 and a threshold of 99 it reads "You're $39.00 away from free shipping"Unit test
Make it accessibleThe text lives in an element with aria-live="polite"Test or axe
Don't break anythingNo existing test is deleted or skippedDiff of the test files
Make sure it buildsnpm run typecheck exits with code 0Exit code

The amounts in the table are illustrative. The fourth row deserves attention: "the tests pass" can be satisfied by deleting the failing test. We covered that in the agent that passed the tests by deleting them. That is why the spec should also say what may not change in the tests, and why you review that part of the diff first.

acceptance criteria: vague against checkablevaguecheckablehow to checkmake it look goodtext visible at 375 px, no side scrollscreenshot at 375 pxmake it worksubtotal 60: "You're $39.00 away"unit testmake it accessiblethe text sits in aria-live="polite"test or axedon't break anythingno test is deleted or skippedgit diff of testsmake sure it buildsnpm run typecheck exits with 0exit codeif nobody can check it from outside, it is a wish, not a criterionevery criterion passes or failsillustrative example from a Next.js store

Scroll the figure sideways to see all of it

A complete example: before and after

Before, the one-line prompt:

add a free shipping bar to the cart

After, the same request as a spec. It is ten lines of content, title included, plus the section headings. The paths belong to an example Next.js store and the amounts are illustrative:

# Free shipping bar in the cart

## Goal
In the cart drawer, show how much the customer still needs to spend to get free shipping.

## Constraints
- Touch only components/cart/ and its tests.
- The threshold comes from FREE_SHIPPING_MIN in lib/shipping.ts; do not hard-code it in the component.
- Format with formatMoney from lib/money.ts. No new dependencies.

## Acceptance criteria
- [ ] Subtotal 60 and threshold 99: it reads "You're $39.00 away from free shipping".
- [ ] Subtotal equal to or above the threshold: it reads "Your shipping is free".
- [ ] The text lives in an element with aria-live="polite".
- [ ] No existing test is deleted or skipped; npm test and npm run typecheck pass.

## Out of scope
- The real shipping calculation at checkout.
  1. The title names the change; it doubles as the branch and pull request name.
  2. Goal describes what the shopper sees and where, without saying how to build it.
  3. The first constraint keeps the change to one folder and its tests, so the diff stays small and easy to review.
  4. The second says where the threshold comes from. Without it, the likely result is a 99 hard-coded in the component.
  5. The third picks between two valid paths (the existing utility or a new one) and rules out new dependencies.
  6. The first two criteria give concrete values and the exact copy, so they turn straight into tests.
  7. The third covers accessibility: a screen reader announces the change when the subtotal goes up.
  8. The fourth closes the deleted-tests loophole and names the two commands that must pass.
  9. Out of scope tells the agent where to stop.

With the file in place, the prompt to start is short. @ followed by a path includes that file in your message:

Read @SPEC.md. Before editing, tell me which files you will touch and how you will check each acceptance criterion. When you finish, paste the output of npm test and npm run typecheck.

The first part asks for a plan before any code; if you want the agent unable to edit until you approve it, use Claude Code plan mode. The last part asks for evidence: the docs recommend asking for the command that ran and its output, because "all tests pass" on its own tells you very little.

Where to keep the spec: an issue or SPEC.md

It depends on who else needs to read it and how long it needs to live.

WhereWhen it fitsWhat you give up
In the promptOne-session changes nobody else reviewsIt is gone when the session ends
An issueThe team discusses it, assigns it and links it from the pull requestThe agent needs it pasted in, or access to the issue
SPEC.md on the branchThe agent reads it with @SPEC.md and the reviewer has it next to the codeYou delete or archive it when you merge
AGENTS.md or CLAUDE.mdRules that apply to every taskNot for one task: it loads in every session

The Claude Code docs suggest a flow for when you are not sure what you want yet: ask the agent to interview you until it could write the spec, and to save it to SPEC.md. Their example is rate limiting for a public API; adapted to ours:

I want to add a free shipping bar to the cart but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.

The agent asks about the parts you have not pinned down (what happens with discounts, what is out of scope) until the answers add up to a spec. Then the docs recommend starting a fresh session to build from it, so the build begins with a clean context and a written definition of done. If you work on one branch per task, as in this git workflow for AI agents, SPEC.md travels with the branch.

Check the spec before, and the work after

An incomplete spec shows up late, once the diff already exists. This dependency-free Node script checks it before you start: all three parts are there with content, and the acceptance criteria are not wishes.

// Usage: node check-spec.mjs SPEC.md
import { readFileSync } from "node:fs";

const file = process.argv[2] ?? "SPEC.md";
const lines = readFileSync(file, "utf8").split(/\r?\n/);
const problems = [];

// Group the lines under their "## " heading.
const sections = {};
let current = "";
for (const line of lines) {
  if (line.startsWith("## ")) current = line.slice(3).trim();
  (sections[current] ??= []).push(line);
}

// The three parts, with Spanish or English headings, and not empty.
const parts = [["Objetivo", "Goal"], ["Restricciones", "Constraints"], ["Criterios de aceptación", "Acceptance criteria"]];
for (const names of parts) {
  const body = names.flatMap((n) => sections[n]?.slice(1) ?? []);
  if (!body.some((l) => l.trim())) problems.push(`missing or empty section: ## ${names.join(" / ")}`);
}

// Every acceptance criterion is a checkbox, and none of them is a wish.
const criteria = parts[2].flatMap((n) => sections[n] ?? []).filter((l) => /^- \[[ x]\] /i.test(l));
if (criteria.length === 0) problems.push("no acceptance criteria (- [ ] ...)");
const vague = /\b(bien|correctamente|bonito|limpio|properly|correctly|nice|clean)\b/i;
for (const c of criteria) if (vague.test(c)) problems.push(`vague criterion: ${c}`);

console.log(problems.length ? problems.map((p) => `FAIL ${p}`).join("\n") : `OK   ${file}: ${criteria.length} criteria`);
process.exit(problems.length ? 1 : 0);
  1. It reads the file you pass (SPEC.md by default) and splits it into lines; Windows line endings work too.
  2. The loop groups every line under its ## heading; the first line of each group is the heading itself.
  3. parts lists the three required sections, with their Spanish or English names.
  4. For each part it collects the lines below the heading and fails if none has text: an empty section counts as missing.
  5. criteria takes the - [ ] checkboxes (or ticked ones, - [x]) from the criteria section, and fails if there are none.
  6. vague looks for words nobody can check from the outside, such as "properly" or "correctly". The list is short on purpose: add the ones you see in your own specs.
  7. It prints OK with the number of criteria, or one FAIL per problem, and exits with code 1 if there is any, so you can use it in a hook or in CI.

We ran it with Node 22 on the spec above, on its Spanish version, and on a vague spec written by hand:

$ node check-spec.mjs SPEC.md
OK   SPEC.md: 4 criteria

$ node check-spec.mjs SPEC.vague.md
FAIL missing or empty section: ## Restricciones / Constraints
FAIL vague criterion: - [ ] It looks nice on mobile.
FAIL vague criterion: - [ ] It works properly.

When the agent finishes, review the work against the spec, not against your memory of what you asked for. The docs suggest a prompt for a reviewer that never saw the conversation: "use a subagent to review the rate limiter diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style". They also warn you not to drop the "skip style" part: a reviewer asked to find problems always finds something, and if you fix every finding you end up with extra layers.

Common mistakes

  • Describing the implementation instead of the outcome. "Create a useFreeShipping hook" locks in a path; "show how much is left for free shipping" lets the agent choose based on the code.
  • Repeating what the repo already says. The framework, the folder layout and the code style it finds by itself. Every extra line competes with the ones that matter.
  • Criteria nobody can check. "Make it work properly" neither passes nor fails. Write the value, the copy or the command.
  • Accepting "the tests pass" at face value. Require that no test is deleted or skipped, and review that diff first.
  • Leaving out what is out of scope. Without that section, the agent may "improve" something you did not ask for.
  • Using the spec for hard rules. If something must never happen, it goes in a hook or in the permissions, not in text the model interprets.
  • Building in the session where you discussed the idea. A fresh session with @SPEC.md starts with a clean context.
  • Not updating it. If you change your mind halfway, change the spec first; otherwise the reviewer checks against something that is no longer true.

Frequently asked questions

What is the difference between a spec and a prompt?

A spec is a prompt with structure and a definition of done. In practice, you can save it, review it with someone else and use it afterwards to check the result. A one-off prompt disappears with the session.

How long should a spec be?

Long enough that the agent does not guess anything that matters. For a change like the example, about ten lines is enough. If it runs past a page, check whether you are describing the implementation, or whether it is really two tasks.

Should I write it, or let the AI write it?

Both work. If you know what you want, write it yourself. If not, ask the agent to interview you and write it to SPEC.md, as the Claude Code docs suggest, and read it before anything gets built: it is your definition of done, not the agent's.

Does this work with agents other than Claude Code?

Yes. A Markdown file with a goal, constraints and criteria does not depend on any tool. What changes is how you hand it over: with @, by pasting it, or from an issue the agent can read.

Checklist

  • The goal fits in one or two sentences and describes the outcome.
  • The constraints only say what the agent cannot read in the repo.
  • There is an out-of-scope section.
  • Every acceptance criterion passes or fails, with values, copy or commands.
  • One criterion forbids deleting or skipping existing tests.
  • Rules without exceptions live in hooks or permissions, not in the spec.
  • The spec lives in an issue or in SPEC.md on the branch.
  • check-spec.mjs passes before you start.
  • You ask for evidence (commands and output) and review the diff against the spec.

The PDF guide has the blank template and two filled-in specs, ready to copy.

Saw this on Instagram? Comment SPEC on the Reel and I'll send you the guide.

Written by

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 19, 2026

← Blog