How to Write Acceptance Criteria for AI Coding Agents

Write acceptance criteria before you write the prompt. That is the single change that moved my AI coding from a slot machine to a machine. An agent with no acceptance criteria optimizes for looking done. An agent with real criteria optimizes for being done. Those are different outcomes, and the gap between them is where your afternoon goes.

Acceptance criteria are a short list of statements that are either true or false about the finished work. Not goals. Not vibes. Checkable claims. "The endpoint returns 401 when the token is expired" is a criterion. "Make auth better" is a wish. The agent can verify the first. It cannot verify the second, so it guesses, and it guesses in your favor.

What makes a good acceptance criterion

A good criterion is binary and observable. You should be able to point at the running code, the test output, or the diff and say yes or no with no debate. If checking it requires an opinion, rewrite it until it does not.

Each criterion should also be independent. Bundle "handles empty input, handles null, handles unicode" into one line and the agent will satisfy the easy part and quietly skip the rest. Split them. Three lines, three checks, three chances to catch a miss.

Cover the unhappy paths on purpose. Left to itself, an agent writes the sunny-day version and calls it finished. Your criteria are where you force the error cases: what happens on timeout, on a duplicate request, on a value that is one past the limit. This is the same discipline behind idempotency in AI workflows, just applied to a single task instead of a pipeline.

Acceptance criteria versus the spec

People conflate these. A spec describes the shape of the thing: the data model, the interfaces, the flow. Acceptance criteria describe how you will know the thing is correct. You need both, and they do different jobs. I lay out the spec argument in full in write the spec before the prompt, and criteria are the layer on top.

Think of it this way. The spec tells the agent what to build. The criteria tell the agent, and you, when to stop. Without the second layer, an agent will keep gold-plating or stop three steps early, and you cannot tell which until you read every line yourself. Good criteria replace that reading with a checklist.

The other reason to separate them: criteria survive rewrites. If the agent's first attempt is wrong and you throw it out, the spec might change but the criteria usually hold. They are your contract with the outcome, independent of the implementation that happens to be in front of you.

Turn criteria into tests where you can

The strongest acceptance criterion is one that runs. If a criterion can be a failing test before the agent starts, make it one. Now "done" is not a judgment call, it is a green check. The agent gets an unambiguous target and a feedback signal it can use inside its own loop.

Not everything reduces to a test. "The migration is reversible" or "no secrets in the logs" might need a human eye. Keep those as written criteria and check them by hand. But push as many as you can into executable form, because executable criteria are the ones the agent cannot talk its way around. This connects directly to how the AI build loop actually works: the loop is only as good as the signal you give it.

A practical rule I use: if I find myself re-reviewing the same category of mistake across tasks, I promote that check into a standing criterion or a lint rule. The review taught me the criterion. Now the criterion does the review.

Keep the list short and current

A criteria list with thirty items is a spec pretending to be a checklist, and nobody reads it, including the agent. Aim for five to ten sharp criteria per task. If you need more, the task is too big; split it. Smaller tasks with tight criteria beat big tasks with loose ones every time.

Update the list when reality changes. If you discover a new edge case mid-task, add the criterion, do not just fix the code. The criterion is what stops the same bug from walking back in on the next change. Skipping this step is one of the common AI-assisted development mistakes that keeps teams stuck at prototype quality.

Acceptance criteria are cheap to write and expensive to skip. Ten minutes up front buys you a task the agent can actually finish and you can actually verify. That is the whole trade. The tools that make this easy, like the workflow we build at Bootspring, treat criteria as a first-class input, not an afterthought you bolt on when the review goes sideways.