RSS
Tips

How the Claude Code team verifies agent work: a verify skill, REVIEW.md on a protected branch, and a commit gate

Claude writes and reviews about 90% of the Claude Code team's code. A new post explains how they check it: a verify skill that runs the app before each commit, review rules read from the protected default branch, and a commit gate that starts in observe mode.

Person writing on a clipboard beside a laptop, illustrating Claude Code verification before commits
Photo by Zulfugar Karimov on Unsplash

On the Claude Code team, Claude writes and reviews about 90% of the code, according to a November 16 post on claude.dev by Addy Osmani. The post explains what lets them run many Claude sessions in parallel without reading every diff: verification that produces evidence, kept out of reach of the changes it judges.

The post describes the team's practice; Claude Code's docs describe the features behind three of its pieces: the verify skill, REVIEW.md and hooks. Those you can set up from this guide. The commit gate is described only by its behavior, with no implementation, so section 5 gives its design points rather than a recipe.

1. Make 'verify' mean running the app

The team's first rule is that running the change end to end matters more than tests. Claude should drive the app the way a QA engineer would: the Claude Chrome extension for web changes, an iOS or Android MCP for mobile, computer use for desktop, or a local run for backend services.

The way to codify that is a skill named verify. Claude Code ships three related skills: /run and /verify, which infer how to launch a project from its type and from its README, package.json or Makefile, and /run-skill-generator. For anything beyond a standard launch (a database, an env file, a multi-step build), the docs say to record the recipe: /run-skill-generator gets the app running from a clean environment and saves what worked as a project skill under .claude/skills/run-<name>/. Run it once per project, and again when the build or launch changes. /verify can also record its own recipe: when it has to work out the launch without one, it writes what worked to .claude/skills/verify/SKILL.md at the repo root, or in the touched package directory in a monorepo. At the repo root that recorded skill replaces the bundled /verify.

Since Claude Code v2.1.286, a skill named verify (or simplify) changes commit behavior: Claude's built-in commit instructions tell it to run the skill right before each commit, except for changes to docs or tests. Per the docs, the skill has to be in place when the session starts, so one added mid-session takes effect in the next session. It must also load from an enterprise, personal, project or additional-directory location (the bundled /verify, plugin skills and claude.ai skills don't count), Claude must be allowed to invoke it (no disable-model-invocation: true), and includeGitInstructions must not be turned off; turning it off removes the rest of the built-in commit and PR instructions too.

Commit the recorded skill so everyone working in the repo uses the same recipe. Project skills don't load in cloud threads in a project, per the docs. Because the recipe can capture environment variables, check the file before you commit it and keep secrets, tokens and .env contents out of it.

The post's advice on the skill itself: treat it as your smoke-test harness. Ask Claude to iterate on it and stress-test it until it is fast and reliable, because flaky checks teach an agent to re-run instead of fixing code, and slow checks get run less often.

2. Pick tests that are hard to fool

The post names three kinds of tests worth investing in when an agent writes the code:

  • End-to-end tests: if you pick only one type, pick this. A real user flow either works or it doesn't, and a failure comes with a screenshot and the step that broke instead of a bare timeout.
  • Property tests: state something that must always hold, such as round-trip encoding, a balance that can never go negative, idempotent retries, or optimized code matching a naive version, and let a library (fast-check, Hypothesis, proptest) generate thousands of inputs. The inputs don't share the bias of the agent that wrote the code.
  • Differential tests: for migrations, run the old and new systems on random or sampled production inputs and compare, normalizing irrelevant differences like whitespace and keeping a list of approved changes.

3. Keep the rules out of the change's reach

'If a change can modify the check that judges it, the check is broken,' the post says. A pull request can still edit REVIEW.md, but Claude's Code Review service doesn't read that copy: it reads REVIEW.md from the pull request's base branch or the default branch. So merge a REVIEW.md change before you rely on it.

Protection matters, because it decides which copy is read. For the default branch, Code Review counts a classic branch protection rule or a ruleset; for any other branch, only a ruleset. A ruleset counts when it restricts updates, or requires pull requests with at least one approval that is dismissed on a new push or must come after the last push. With the default branch unprotected and no protection on the base branch, a review reads only the root REVIEW.md from the default branch; if Code Review can't confirm the protection settings, it reads none.

REVIEW.md isn't the only input. The Code Review service also reads your CLAUDE.md files as project context and flags changes that break their rules. The local /code-review command is a separate tool and reads different files.

Two related habits from the team: they review commits, not moving branches, because a pass on an out-of-date commit means nothing; and they improve one reviewer through REVIEW.md rather than stacking a second, more expensive reviewer on top.

4. Run the cheap checks before the PR

On the team, Claude runs the tests, build and linter before opening a pull request. The post suggests enforcing it with a hook that runs the tests when Claude finishes, or a /goal of a passing suite. The post doesn't name the hook event; in Claude Code the natural fit is a Stop hook, which fires when Claude finishes responding. The hooks guide shows a Stop hook of type agent that runs the test suite and keeps Claude working until it passes. Agent hooks are marked experimental and may change, and they have a 60-second default timeout, so a long suite needs a higher timeout or a command hook (10-minute default).

Three cautions from the docs. A Stop hook fires every time Claude finishes responding, not only when the task is done (but not on user interrupts), so the test command runs often: keep it fast, and never point it at anything that writes to a real database, deletes data or calls external services. Claude Code overrides a Stop hook after it blocks eight times in a row with no tool call in between, so a command hook should read stop_hook_active from its JSON input and exit early when it is true; the cap can be raised with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP. And the team has its own escape valve: if a check is still failing after three rounds, Claude stops and brings in a human.

5. Roll out a commit gate in observe mode

The team stamps every commit with how it was verified, including 'none', so unverified commits can be queried. Its commit gate blocks a commit if the session didn't run /code-review or /verify, and has three modes: off, observe (log what would have been blocked, to find false positives) and enforce. A blocked commit can carry an explanation in its message, and after two blocks in one session the next commit goes through so Claude doesn't get stuck. The post describes this behavior but gives no implementation, so building it is up to you; those four rules (stamp, three modes, an explanation escape, a block cap) are the design to copy.

6. Check the checks

Two practices from the post apply at any scale:

  • A diff-triggered checklist. The team keeps 39 reliability items, each with a trigger readable from a diff, a check, and the incidents behind it. One is '--resume loads old transcripts': when session storage changes, does a new field load safely from older transcripts? Claude checks only the items whose trigger matches, usually 3 to 10.
  • Turning misses into rules. A pattern from human review comments or reverts must appear in at least two PRs and be detectable from a diff; three agents try to disprove it, and a human approves it in a PR. Flaky tests get the same treatment: Claude can't skip them, add sleeps or retry until they pass, and if it can't find the root cause, it deletes the test and writes down why.

The team also measures its reviewers: reverts of merged changes, changes maintainers rejected, and a size-matched set of changes that stayed clean as a control against over-flagging.

Try it with your AI. Paste this into Claude Code in your repo to set up the verify skill and a test hook. Fill in the bracketed parts first. It reports before it writes anything:

Help me set up verification for this repo the way the Claude Code team describes it.
Report first; change nothing until I approve.

1. Tell me which Claude Code version is running. If it is older than v2.1.286, note that
   the verify-before-commit instruction won't apply, and continue with the other steps.
2. Check whether .claude/skills/verify/SKILL.md exists, and whether
   includeGitInstructions is turned off in .claude/settings.json,
   ~/.claude/settings.json or managed settings.
3. Propose a verify skill for this project: the exact commands to install, start [MY APP
   / SERVICE], and drive one real user flow ([DESCRIBE ONE FLOW]) end to end, plus what
   output counts as a pass. Use only commands that already exist in this repo's README,
   package files or Makefile. Keep secrets, tokens and .env values out of the file.
4. Propose a Stop hook entry for .claude/settings.json that runs [MY TEST COMMAND] and
   exits early when stop_hook_active is true. Check the hook format against the Claude
   Code hooks docs. The test command must not write to real databases, delete data or
   call external services.

Show me both files in full and wait for my OK before writing them. Do not read or edit
credential or .env files.

FAQ

Does Claude Code run my verify skill automatically? From v2.1.286, if a project, personal, enterprise or additional-directory skill named verify is in place when the session starts and Claude can invoke it, Claude's commit instructions tell it to run the skill before each commit, except for docs or test changes.

Where should REVIEW.md live? At the repository root on your default branch, with that branch protected by a classic rule or a qualifying ruleset. Code Review reads it from the PR's base branch or default branch, never from the PR's own changes.

Why does my Stop hook stop working after a few rounds? Claude Code overrides a Stop hook that blocks eight times in a row without a tool call in between. Check stop_hook_active in the hook input and exit early when it is true, or raise CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

What does /run-skill-generator record? It gets your app running from a clean environment and saves what worked, including install commands, env vars and the launch script, as a project skill at .claude/skills/run-<name>/, which /run, /verify and other agents in the repo then follow.

Which tests matter most for coding agents? The post ranks end-to-end tests first, then property tests for edge cases and differential tests for migrations.

Source: claude.dev: How the Claude Code team thinks about verification, Claude Code docs: Skills, Claude Code docs: Hooks guide, Claude Code docs: Customize Code Review

This story first appeared in the claudefox daily briefing for November 18, 2026.