Claude Code Verification: Make Claude Prove Its Work Before It Says “Done” (Tested)

Claude Code Verification: Make Claude Prove Its Work Before It Says “Done” (Tested)

Claude Code is quick to say “done.” The hard part is knowing whether it actually checked anything, or just wrote code that looks right. So we built a small verification setup, a few lines in CLAUDE.md plus one Stop hook, and ran the same two coding tasks with and without it.

Below you will find the exact files to copy, the three kinds of checks that matter, and what our side-by-side test showed. The short version: Opus 5.5 already checks a lot on its own. What the setup changes is where those checks end up and whether anything enforces them next time.

Quick verdict

Both runs produced correct code. Our hidden grader, which Claude never saw, threw 3,000 random strings, 5,000 random orders and 7 real files at each version, and both passed everything.

The difference was what stayed behind. Plain Claude Code checked its work in throwaway scripts under /tmp and left 4 small new tests. With the verification rules, Claude left 13 new tests in the repo, including property tests, a differential test against the old code and a speed test. It cost $0.55 instead of $0.35 and took 157 seconds instead of 104.

Then we planted a one-line bug, the kind a later change might sneak in. The plain repo caught it with 1 test. The verification repo caught it with 4, and its Stop hook refused to let Claude finish. If you work on code that has to stay correct over many sessions, the setup is worth the extra 20 cents.

Results card comparing plain Claude Code and Claude Code with verification rules and a Stop hook
Our scorecard. Both versions were correct; the gap is in what Claude left behind and what enforces it later.

What Claude Code verification means

Running the existing tests is not enough. A test suite only checks the cases someone thought of, and Claude writes tests for the cases it thought of too. Real verification means checking behavior in ways that can surprise you.

Three kinds of checks do most of the work:

CheckWhat it doesBest for
Property testGenerates thousands of random inputs and checks a rule that must always hold, such as “decode(encode(x)) gives back x”Parsers, encoders, formatters, anything with a round trip
Differential testRuns the old code and the new code on the same random inputs and compares every resultRefactors and speedups that must not change behavior
End-to-end runUses the feature the way a real user would, on real files, and checks the outputCLI commands, scripts, anything with input and output

A Stop hook adds the last piece. It runs when Claude tries to finish, and if the suite fails, it sends Claude back to work. That turns “please run the tests” into a rule Claude can’t skip.

How to set up Claude Code verification

You need two things in your project: a short section in CLAUDE.md and a Stop hook. Our test project was a small Python package called textkit, so adjust the commands to your own stack.

Step 1: Add verification rules to CLAUDE.md

Claude reads CLAUDE.md at the start of every session. Put the rules there so they apply to every task, not just the one where you remembered to ask:

## Verification rules
A task is done only when you can show evidence that it works. Before you say "done":

1. Rewrites must not change behavior. Use the old code as the oracle (`git show HEAD:<path>`) and write a
   differential test that runs old and new on thousands of random inputs and compares every result.
2. Anything that encodes, decodes or parses gets a property test with Hypothesis (installed in .venv):
   round trips, invariants, and inputs you would not think of (digits, unicode, empty, newlines).
3. Run the feature end to end the way a user would: `python3 -m textkit ...` on real files, then check the output.
4. Run the whole suite: `.venv/bin/python -m unittest discover -s tests`. It must pass. A Stop hook runs it too.
5. In your final message, list each check you ran and its result.
Terminal showing the Verification rules section of the project's CLAUDE.md file
Five rules: differential, property, end to end, full suite, and a list of checks in the final message.

For JavaScript, swap Hypothesis for fast-check and the unittest command for your test runner. The idea stays the same.

Step 2: Add a Stop hook that runs the tests

Add this to .claude/settings.json in your project:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify.sh", "timeout": 300 }
        ]
      }
    ]
  }
}

Then save this script as .claude/hooks/verify.sh and make it executable with chmod +x:

#!/bin/bash
# Stop hook: Claude can't finish while the test suite fails.
input=$(cat)
cd "$CLAUDE_PROJECT_DIR" || exit 0
if out=$(.venv/bin/python -m unittest discover -s tests 2>&1); then
  exit 0
fi
if echo "$input" | grep -q '"stop_hook_active": *true'; then
  exit 0   # already sent back once; don't loop forever
fi
echo "Tests are failing, so the task isn't done. Fix the code (not the tests) and run them again:" >&2
echo "$out" | tail -25 >&2
exit 2
Terminal showing the Stop hook in settings.json and the verify.sh script
The hook and its script. Exit code 2 blocks Claude from stopping and shows it the error output.

Two details matter here. Per the Claude Code hooks reference, exit code 2 on a Stop hook keeps Claude working and passes your stderr message to it. The stop_hook_active check lets Claude stop on its second try, so a test it truly can’t fix won’t trap it in an endless loop.

The line “Fix the code (not the tests)” is there on purpose. Without it, the easiest way to make a red test green is to edit the test.

Step 3: Commit the setup

Commit CLAUDE.md and the .claude folder. The differential rule depends on git show HEAD, so Claude needs a clean commit to compare against. It also means everyone on your team gets the same rules.

Why property and differential tests catch what normal tests miss

Before the real test, we wrote two deliberately naive versions ourselves to show what each check finds. The first is a run-length encoder that writes each run as a count plus a character, so “aaab” becomes “3a1b.”

Terminal showing a naive run-length encoder and a Hypothesis property test failing on the input '0'
Hypothesis found the bug in 0.06 seconds and shrank it to the smallest failing input: the single character “0”.

It passes every example you would think to write by hand. But text that contains digits breaks it, because “0” encodes to “10”, which decodes back to an empty string. Hypothesis, the Python property-based testing library, found that instantly.

The second is a “faster” order total that stores prices in a dictionary. It looks clean, but it uses the last price for each product when the original used the first.

Terminal showing a naive pricing rewrite and a differential test where 3,484 of 5,000 random orders differ
Comparing the rewrite with the original on 5,000 random orders: 3,484 totals were wrong.

The repo’s two pricing tests use one line per product, so this rewrite passes them. The differential test needed no idea of what could go wrong. It just compared old and new until they disagreed.

How we tested it

We made one small Python repo with a word-count CLI, a legacy order_total() function that slowed down badly on big orders, and 3 tests. Then we made two identical copies. One got the verification rules and the Stop hook; the other got nothing extra.

Claude Code ran headless with Opus 5.5, the same prompt word for word, and web search and subagents turned off. The prompt asked for two things: run-length compress and decompress commands that “must work for any text file,” and a much faster order_total() “without changing its results.”

Flow diagram of the Claude Code verification test: the same tasks sent to a plain copy and a copy with verification rules, then checked by a hidden grader
Same repo, same prompt, same model. Only the verification setup changed.

Before either run, we wrote a grader and kept it outside both projects. It ran a 3,000-string property test, a 5,000-order differential test against the original pricing code, 7 files through the real CLI, a speed test on 100,000 lines and the project’s own tests.

What plain Claude Code did

We expected plain Claude to skip checks. It didn’t. It saved the original pricing code from git, compared old and new on random orders, and round-tripped 20,000 random strings, including emoji, Windows line endings and digits.

Its encoder escapes digits and backslashes, so the “0” trap never caught it. Its new order_total() ran 100,000 lines in 0.01 seconds; the old one needed 0.13 seconds for just 10,000.

The catch is where those checks lived. All of them were scripts in /tmp, gone after the session. The repo got 4 new example tests, and the final message said “all 7 tests pass.” That is true, but the next person to touch the pricing code gets almost none of that protection.

What Claude did with the verification rules

With the rules in place, Claude did the same kind of checking but kept it. It copied the original pricing code into tests/oracle/pricing_v1.py and wrote a differential test against it, plus a Hypothesis test that compares the two on generated orders.

It also wrote Hypothesis round-trip tests for the encoder, tests for bad input, and a speed test. Its final message ended with a table of every check and its result, as rule 5 asks.

Terminal showing 16 passing tests in the verification repo, including differential, property and speed tests
The verification repo after the run: 16 tests, 13 of them new, all passing.

Claude also explained one choice it made on purpose: “each SKU is priced at the unit price on its first line.” That is exactly the behavior our naive rewrite broke. In this run, the Stop hook never had to step in, because the suite was green the first time Claude tried to finish.

The later bug: where the Stop hook earns its keep

The real value shows up on the next change. We applied the same one-line bug to both finished repos: a small edit so each product uses its latest price instead of its first. Then we ran each suite and the hook.

Terminal showing a one-line pricing bug, four failing tests and the Stop hook exiting with code 2
Four tests fail, and the Stop hook exits with code 2, so Claude would be sent back to fix the code.
After the one-line bugPlain repoVerification repo
Tests that fail1 of 74 of 16
Which checks caught itOne hand-written exampleRandom orders, property test, same-SKU example, speed test
Does anything force a fix?No, only if Claude chooses to run testsYes, the Stop hook blocks “done”

Both suites caught it, which is a credit to plain Claude’s single extra test. But one example test is a thin net, and nothing makes Claude run it. With the setup, the safety net is wide and the hook enforces it on every task.

The numbers behind the Claude Code verification test

CheckPlain Claude CodeWith verification setup
Time and API cost104 s, $0.35157 s, $0.55
Turns and output tokens15 turns, 8,96419 turns, 15,329
Hidden graderAll passAll pass
Tests in the repo afterward7 (4 new)16 (13 new)
Checks kept in the repoExample tests onlyProperty, differential and speed tests
Stop hook blocks in the runNot installed0 (tests passed first time)

The setup cost about 57% more and took about 51% longer on this task. Most of that went into writing tests that will keep paying off after the session ends.

Tips for a Stop hook that helps instead of annoys

  • Keep the suite fast. The hook runs every time Claude tries to stop, so a 10-minute suite makes every small question slow. Run a quick subset in the hook and the full suite in CI.
  • Set a timeout. We used 300 seconds so a hung test can’t block the session forever.
  • Keep the loop guard. The stop_hook_active check gives Claude one retry, then lets it stop and explain what is still broken.
  • Tell Claude not to edit tests to make them pass, and review any test changes in the diff.
  • Update the oracle on purpose. When you do want behavior to change, commit first so git show HEAD points at the new baseline.

If a hook does not seem to run, our guide to hooks not firing walks through the usual causes. For more ready-made ideas, see our Stop hook examples and ready-to-copy hooks, or the basics in our Claude Code hooks guide.

If you want Claude to write the tests before the code, our test-driven development workflow pairs well with this setup. For bigger cleanups, our guide to refactoring messy code uses the same “old code as the oracle” idea, and every CLAUDE.md location explains where your rules can live.

What we did not test

Each version ran once through claude -p, so treat time and cost as a rough guide. The tasks were small and Python-only, and Opus 5.5 handled them well even without rules. On harder tasks or with a smaller model, plain Claude may check less, and the gap could be larger.

We planted the later bug by hand instead of asking Claude to make a second change. That kept the test fair between the two repos, but it means we showed what the hook would do, not a full second session.

Conclusion

Claude Code verification is less about making Claude smarter and more about making its checks stick. In our test, plain Opus 5.5 wrote correct code and even checked it carefully, but threw those checks away. A short CLAUDE.md section and one Stop hook made Claude keep property and differential tests in the repo and made “done” depend on a green suite, for about 20 cents more per task. Set it up once, commit it, and every later change gets the same proof. Find more hands-on tests in our Claude Code tutorials.

Newsletter

New AI tools in your inbox

The best new tools and the AI news that matters, in one short email. Unsubscribe any time.

Free · No spam · Unsubscribe any time

✓ Looks like you’re subscribed

Loading Google’s sign-up form…

Looks like you’re already subscribed

Thanks for reading! New AI tools and the AI news that matters will land in your inbox.

Not subscribed yet? Refresh the page to load the sign-up form.

The sign-up form couldn’t load. If you use an ad or content blocker, allow news.google.com and reload the page.

Free instant check before you pay. Takes a few seconds.

Scroll to Top