Definition of done for AI agents

A definition of done is the list of things that must be true before a piece of work counts as finished. For AI agents, it is a short checklist every job passes before the agent says "done", with a record of how each line was checked.

When to use it: any job you hand to Claude Code, Cursor, Codex or Grok that a customer will touch. When not: a throwaway experiment on a branch nobody will merge. Even then, one line helps.

Why an agent's own "done" isn't enough

Agents finish confidently. They may have written the code, but not run it, or run it locally but not where your customers are. Merged isn't deployed, and deployed isn't checked. Without a checklist, you only find the gap when a customer does.

Anthropic's own advice for Claude Code names the problem plainly: "Claude stops when the work looks done." Without a check it can run, looking done is the only signal the agent has, and you become the person who notices every miss. The same guide's fix is the one this page is built on: give the agent a check that passes or fails, and have it show evidence rather than asserting success.

This isn't a flaw in one model. Any builder, person or agent, works toward the finish line they can see. If the line is vague, the finish is vague.

What is a definition of done?

The idea comes from Scrum. The 2020 Scrum Guide calls it "a formal description of the state of the Increment when it meets the quality measures required for the product." Work that misses it "cannot be released or even presented at the Sprint Review." For the short version, see definition of done in the glossary.

Fig 2.1 · All or nothing

Two parts of that idea still hold. It is shared, so everyone means the same thing by done. And it is all or nothing: a job that is done except for one line is not done.

What changes with agents is who reads it. A team of people can carry an unwritten standard in their heads. An agent can't. It starts each session with whatever you wrote down, and nothing else. So the standard has to be written, short and checkable from outside the code.

The other change is the gate. Scrum puts the check at a review meeting. A small team running agents may ship 5 times a day with no meeting at all. The gate moves to the live product: does the line hold where customers are?

How is a definition of done different from acceptance criteria and Done When?

People use these 3 terms loosely, and the overlap causes most of the confusion. Here is how they split.

Done When lines are acceptance criteria written so an agent can check them on its own. The definition of done is the standard all of them sit on top of. A job is finished when it meets both.

Two levels of done

1. Your team's standard, true for every job: tests pass, nothing else broke, it's deployed where it should be. See definition of done.
2. This job's lines, true for this job only. These are acceptance criteria written so an agent can check them.

Keep the two apart. Your standard goes in your rules file, AGENTS.md, which Claude Code, Cursor, Codex and Grok can all be pointed at. The job's lines go at the end of the job's plan, the spec. If "tests pass" appears in every spec, it belongs in the standard. If "the export keeps filters" appears in the standard, it belongs in a spec.

A team standard for a small product runs about 5 to 8 lines. Here are 5:

• The test suite passes, and no test was skipped or deleted to get there.
• The type check and the linter pass.
• The change is on the live branch and deployed to production.
• Nothing outside the job's files changed without a note saying why.
• Any customer-facing words were read by a person.

That's often enough. Before you add a line, ask whether it's something that has slipped through before. If not, leave it out, and stop at about 8.

Then tell the agent how to use it. One instruction near the top of AGENTS.md does most of the work: "Before you say a job is done, check every line of our standard and every Done When line in the spec. For each one, say how you checked it and where I can see it. If you couldn't check a line, say which and why." Agents follow a rule they can see far better than one they're expected to infer. Claude Code reads AGENTS.md when there's no CLAUDE.md, and a CLAUDE.md can import it with an @AGENTS.md line, so one file covers all your agents.

If a rule must hold every time with no exceptions, such as "the test suite passes", make it a check that runs on its own, in CI or a hook, rather than a sentence the agent is trusted to remember. Keep the written standard for the things only a reader can judge.

How to write lines an agent can check

Use "Given a state, when an act, then a result you can see":

• Given a customer with saved filters, when they export, then the file keeps every filter.
• Given the pricing page, when it loads on a phone, then nothing scrolls sideways.

If you can't picture the line failing, it isn't a check.

One check per line. If a line says "and", split it.

The form is older than coding agents. Martin Fowler credits Daniel Terhorst-North and Chris Matts with it, as part of behavior-driven development. "Given" is the state of the world before the act. "When" is the act. "Then" is the change you expect. It works for agents for the same reason it worked for people: it forces you to say where you start, what happens and what you'll look at.

A few rules make a line checkable:

• Observable from outside the code. A page, a file, an email, a row, a status code. "The function is refactored" can't be seen by a customer.
• It can fail. If you can't picture the line failing, it isn't a check. "Works well" never fails.
• Numbers, not adjectives. "Under 2 seconds", "exactly 1 email", "within 5 minutes". Fast, simple and clean can't be verified.
• Name the place. On staging, on production, on a phone. Where it was checked is part of the line.
• One edge per job, at least. The happy path is the line agents check without being asked. The empty list, the expired card and the member without access are the lines that catch real bugs.
• Written before the build. A line written after the code tends to describe what was built, not what was needed.

Three to six lines covers most jobs. If you need 10, the job is probably two jobs.

What do good and bad lines look like?

Here are 10 lines as people often write them, and the same lines rewritten so an agent can check each one. They're made up to show the pattern.

The last row is worth a second look. "Customers love it" is a fine goal. It belongs in the spec's outcome, and you'll learn whether it came true after the ship. Done When is about what you can check the day the job finishes.

Receipts

For each line, the agent writes down how it checked: a test name, a URL, a screenshot, a thread. A line it couldn't check stays unchecked, and it says so. You can read the receipts without reading the code.

A receipt is the evidence for one line. It answers 4 questions: how was it checked, where can I follow it, when and what was seen. A receipt that says "verified" and nothing else is a claim, not evidence.

What counts as evidence for each line?

Not all evidence is equal. Pick the strongest kind the line allows.

Here's a receipt for one line, in a shape you can copy:

• Line: Given an invoice 3 days overdue, when the daily job runs, then exactly 1 reminder is queued for it.
• How: test, "reminders: queues one reminder per overdue invoice", plus a staging run.
• Where: the CI run for the branch, and the staging job log for 21 Oct.
• Seen: 1 reminder queued for invoice 1042. A second run queued none.

An honest unchecked line is also a valid result: "Unchecked: the reminder email's look in Outlook, because there's no test inbox. Worth a manual check before we announce it." That tells you exactly what's left and lets you decide.

Who verifies the work?

The agent that built the job checks every line first. That's its job, and it's cheap. But it shouldn't be the only check, for the same reason you don't proofread your own writing well: it reads what it meant, not what it wrote.

Anthropic's Claude Code guide suggests a second opinion for this reason, so "the agent doing the work isn't the one grading it." In practice, a small team can split it like this:

You don't need to read the code. You need to read the receipts, open the 1 or 2 that touch customers and decide on whatever's unchecked. That takes minutes, not an afternoon.

If you work with others, say who signs off on customer-facing work before the job starts. "Someone will look" means nobody will. Which calls should wait for you is its own topic, covered in human in the loop for AI agents.

it reads what it meant, not what it wrote.

What does "merged is not shipped" mean?

A merged pull request tells you the code landed on a branch. It doesn't tell you the job works, or that anyone can use it yet. Between "the agent opened a PR" and "a customer can do the thing" there are 4 separate steps, and each one can fail on its own.

1. Merged. The code is on the main branch. Proof: the merge commit.
2. Deployed. The code is running where customers are. Proof: the release or deploy record, and the change visible on the live site.
3. Checked. Each Done When line holds there. Proof: a receipt per line.
4. Told. The people who asked know it's ready. Proof: the note you sent them.

Agents tend to stop at step 1, because that's where their tools end. Deploys often wait for a person, a schedule or a pipeline the agent can't see. So a job can sit merged for days, marked done in a chat, while the customer who asked still can't use it.

The fix is a rule in your standard: "Done means checked on production, not merged." If your agent can't reach production, it says so, and the job waits at "merged, not checked" until someone can. That label is honest, and it's the one people skip.

When the agent says done but isn't

• It checked locally, not where it runs. Ask for the live URL.
• It checked the happy path only. Add a line for the edge case.
• The line was vague. Rewrite it so it can fail.

Two more show up once you run several agents:

• It removed the test that failed. Ask which tests changed, and add "none skipped or removed" to your standard.
• It checked a line that changed. Someone reworded the line after the receipt was written, so the receipt proves something else. Freeze lines once a receipt points at them, and add a new line instead.

What does this look like on one job?

Here's a made-up example. Say a 3-person team with 60 customers has 4 accounts asking to pause a subscription instead of canceling. They hand the job to Claude Code with this spec ending:

• Given a paying customer, when they choose Pause for 2 months, then no invoice is created in those 2 months.
• Given a paused customer, when the pause ends, then billing restarts on the next cycle at the same price.
• Given a paused customer, when they open the app, then they see "Paused until 14 Jan" in billing settings.
• Given a customer on a yearly plan, when they open billing settings, then Pause isn't offered.

The agent builds it and reports back. Lines 1, 2 and 4 have tests written from the lines, plus runs on staging with a test account. Line 3 has a staging URL and a screenshot. Production is the gap: the deploy runs on Fridays, so every receipt says staging.

The founder reads 4 receipts and opens the screenshot. It shows the right date. She lets it stand. On Friday, after the deploy, the agent rechecks line 3 on production and adds a second receipt. Only then does the job count as done, and only then does she tell the 4 accounts.

Nobody read the code. Two people spent about 10 minutes between them. And the job was never called done while it sat merged.

What mistakes do people make with a definition of done?

• Writing the lines after the build. Then they describe what was built. Write them first, even roughly, and let the agent sharpen them before it starts.
• Mixing the levels. Team-wide rules in every spec, or one job's behavior in the team standard. Each copy drifts.
• Too many lines. 10 or more lines is a sign of two jobs. Split the job and keep each list short enough to read.
• "Tests pass" as the only line. It proves the tests ran, not that the right thing happened. Say what the test should prove.
• No place. A line without "on staging" or "on production" gets checked wherever is easiest.
• Hiding unchecked lines. An unchecked line isn't a failure. Pretending it was checked is.
• Taking "done" in a chat. If there are no receipts, ask for them. A good agent will either produce them or tell you which lines it couldn't check.
• Rewording a checked line. The receipt now points at a line that no longer exists. Add a new line instead.
• Never pruning the standard. Add a line when something slips through. Drop a line nobody has checked in a month.

For guarding the edges of a job as well as its finish, see scope creep.

Copy this

Put this at the end of every job plan, and have the agent fill in the receipts.

## Done When
- Given <state>, when <act>, then <result you can check>.
- Given <state>, when <act>, then <result you can check>.

## Receipts (one per line)
1. <how checked>: <test name / URL / thread>
2. <how checked>: <test name / URL / thread>
Unchecked: <line>, because <reason>

For a fuller version with the team standard and evidence types, use the definition of done checklist.

Where Annsa fits

Every spec in Annsa ends with Done When lines. Your agent checks each one and records a receipt, and the spec shows which lines are checked before you tell anyone it shipped. Shipping and verification

• Each spec has 5 sections: Problem, Evidence and direction, What to build, Files to touch and Done When. You, your agent or Ask writes it. Annsa never writes a spec on its own.
• Each Done When line takes the form given a state, when an act, then something you can check, and gets its own receipt.
• Claude Code, Cursor, Codex and Grok record a receipt with annsa.work verify. It says whether the check was a test, on staging, in production or by hand, and where you can follow it.
• A line that couldn't be checked is labeled on the spec. Receipts don't block a ship, so an unchecked line is your call.
• Annsa never deploys. Shipping has two paths. Your agent can mark a priority shipped and name any line it couldn't check, which is your call. Or a merged pull request that names the priority ships it once it reaches your live branch and every Done When line has a receipt. See Done When.
• After the ship, Share Back drafts a note to each person who asked. You review it and send it.

See how it fits together in Direct your agents.

Sources

• Scrum: Ken Schwaber and Jeff Sutherland, The Scrum Guide, November 2020.
• Given, when, then: Martin Fowler, GivenWhenThen, 21 August 2013.
• Verification: Anthropic, Best practices for Claude Code.