Claude Code best practices that make "done" mean proven

Most Claude Code best practices lists are about context: keep CLAUDE.md short, clear the session between tasks, plan before you code. They are right, and Anthropic's own best practices page covers them well. This page is about the one failure those lists mention and rarely fix: the agent ends its turn with "Done. All checks pass." and the checks did not pass, or never ran. That sentence is the most expensive thing a coding agent writes, because everyone downstream reads it as a fact.

We run coding agents on our own production work every day. Over four days, 24 to 27 September 2026, a gate we built re-ran the proof behind every "pass" our agents claimed: 103 real requests, 1,156 QA checks. 36 of the pass claims could not be confirmed when the gate ran the check itself. The practices below are what closed that gap, in the order we would set them up again.

Why Claude Code says done when the work is not done

Anthropic's best practices page puts it plainly: Claude stops when the work looks done, and without a check it can run, looking done is the only signal available. The agent is not lying in any useful sense. It wrote the code, it read the code, the code looked right, and nothing in the session produced evidence to the contrary.

The trap is that the agent is also the one grading the work. It decides which test to run, reads the output, and summarises it. A test it never ran cannot fail, a screenshot it never opened cannot show overlapping text, and a command that printed its error far above its last line is easy to summarise as success. Every fix below takes some part of the grading away from the agent that did the work.

Give Claude a check it can run before it starts

The cheapest fix is in the prompt. Instead of asking for a feature, ask for the feature plus the thing that proves it: the test cases with expected results, the command whose exit code decides, the screenshot to compare against. Anthropic's guide calls this the difference between a session you watch and one you walk away from, and it is the first practice we would set up on any team.

Write the check so it can fail. A test that passes on the old code proves nothing about the new code. A useful habit: before keeping a test, break the thing it guards on purpose and watch the test go red. If it stays green, it was decoration.

Ask for evidence, not adjectives. "Show the command you ran and what it returned" turns a claim into something you can read in ten seconds. "All tests pass" with no output attached should be read as "tests were not run" until proven otherwise.

Make the check a gate, not a request: the Stop hook

CLAUDE.md instructions are advisory. On a long session the agent can drift past them, and on a busy one it will. Hooks are different: Claude Code runs them as scripts at fixed points, and the Stop hook runs when Claude finishes responding. If the hook exits with code 2, or returns a JSON decision of block with a reason, Claude Code prevents the stop and the conversation continues with that reason in front of the agent.

That is the mechanism that makes "no proof, no done" a rule rather than a hope. Put the check in a script: run the test suite, re-run the readback command, open the page. Exit 0 when it passes and 2 with the failure when it does not. Configure it in .claude/settings.json for the project so the whole team gets it, or in ~/.claude/settings.json for every project on your machine.

Two cautions from running this daily. Claude Code sets stop_hook_active to true when a Stop hook blocked the previous turn, so your script can tell a second attempt from a first one and avoid blocking forever. And keep the hook fast: a gate that takes ten minutes on every turn gets switched off by the first impatient engineer.

Proof is a command that fails, not a sentence that sounds right

Our gate asks every claimed result for a readback: a command that exits 0 only when the real result is there, such as the stored row, the HTTP response, the file on disk, or the message the provider says it delivered. The gate runs that command itself. It does not read the agent's summary of it.

Over the four days we measured, 30 of those readback commands failed when the gate ran them, on work the agent had already called passing. A further 6 claims were flagged by the screenshot scanner for text drawn over other text, and 3 of those 6 were false alarms. That last number matters: a gate is also a program that can be wrong, so a flag gets a human look before anyone acts on it.

The pattern generalises to any team. Decide what the readback is for each kind of work before the work starts. A database change reads the row back. A deploy curls the live URL. A sent email reads the provider's message ID. If you cannot write the readback, the requirement is not yet clear enough to build.

Look past the diff before calling a change safe

The second most common false done is a change that is correct where it was made and breaks something it never touched: a caller in another module, a second copy of the same config, a client that reads the old field name. Reviewing the diff cannot find these, because the breakage is outside the diff by definition.

We measured this on a deliberately broken change, same model (Sonnet 5), same repository, three runs each way. Plain Claude Code named the broken file in 1 of 3 runs and ran code to check it in 0 of 3. With the what-could-break skill it named the file in 3 of 3 and proved it by running code in 3 of 3, at about 14 seconds and 0.09 USD a run. The skill is free and MIT licensed, and the repository has the exact setup.

Check the page the way a visitor will see it

Front-end work has its own version of the problem. The agent reads its own markup, decides the layout is clean, and never opens the page. The defects that make a page look machine-made, such as a row of identical icon cards, low-contrast text, or one element sitting on top of another, are only visible once the page is rendered.

In our bench, Claude Opus 5.5 built the same landing page five times plainly and five times with the tastegate skill, which opens the result in a real browser at phone and desktop widths before it may finish. Scored by impeccable's own detector, plain pages averaged 29.2 design flaws and tastegate pages 2.2, at a cost of about 1.1 extra minutes and 0.24 USD a page. Prompts, pages and every score are in the repository.

When to have the gate set up with you

Everything above works for one developer with an afternoon. It gets harder on a team: several repositories, a CI that already has opinions, an app nobody has scripted a check for, and engineers who will switch off any gate that slows them down without catching anything.

That is the part we do for teams. We install the proof gate on your repositories, write a verifier that drives your own app the way a user does, tune the Stop hook so it is fast enough to keep, and hand it over running. If that is where you are, book the call below and tell us which agents you use and where a false done has already cost you.