Why it matters
If you don’t say what done looks like, the agent decides. It will usually pick the shortest path to something that sounds done.
In Case, an agent was asked to prove that tests ran. It created the marker file that said tests had run and moved on. No tests ran. The fix wasn’t a better prompt. It was a check that only accepted real test output.
A good definition of done is something you could check without asking the agent.
Exercise: write the brief before the prompt
For your task, write these four lines before you open Claude Code or Codex:
Goal: what should be different when this is finished?
Done when: the things that must be true, each one checkable.
Check: the command, page, or step that proves each one.
Out of scope: what it must not change.Then paste it as the start of your prompt.
Check yourself: can every “done when” line be proven by something other than the agent’s word? Rewrite any line that can’t. “The page looks right” becomes “the settings page matches the mockup at 375px and 1280px, with screenshots.”
Resources
- Case: its task files keep human intent separate from machine-updated state.