How the Claude Code team does Code Review: six layers of checks and fast rollback

How Claude Code Does Code Review: Replacing "Has Anyone Read It" with Layered Checks and Fast Rollback

Given that Claude writes about ninety percent of Claude Code's code and the volume of changes has surged, the team did not abolish review. Instead, it reframed the quality question from "has someone read every line" to "where could this change break, and which layer—automated or human—should catch it": most reading and error correction is handed to machines, while humans are reserved for product judgment and high-risk surfaces, with heavy investment in fast detection + easy rollback; from June to September, the number of merged PRs in the Claude Code repo more than doubled, while the share requiring revert fell by more than 40%.

First, redefine: what is review doing? Traditionally two things: catching bugs before release; and letting the team share an understanding of the codebase. The Claude Code team focuses on the former.

The key rewrite is in the metrics: "has someone read it" is no longer treated as a sufficient condition; instead the question is "what could go wrong, and which kind of check (automated or human) is most likely to catch it." Timing has changed too—from a gate after the PR to a spellcheck during the writing process: most changes, before a human sees them, have already been reviewed and revised at least once by Claude, filtering out everyday bugs and leaving humans for higher-level issues.

Human time is a two-sided ledger Time spent reviewing PRs + time spent fixing broken code: cutting only the former without the latter just moves the cost around. The goal is stated bluntly: in the Claude Code repos for CLI / desktop web / mobile, most PRs should have at most one human in the loop (possibly the author), and the revert / incident rate must not rise. Tracking: median and P95 approval time per person, number of human comments, time spent waiting for people; revert and incident rates as guardrails.

# The journey of a change: six layers of checks, with rollback as the safety net Whether it comes from an engineer's local machine or a Claude session in Slack, the typical path is multiple layers stacked, each catching some and missing some; very few get through all of them, and those that do are handled by rollback.

1. Pre-PR verification (the bulk is here) Require "runnable results" rather than a verbal done: run tests, build, screenshot against the design; then have a subagent with fresh context review the diff. Before opening a PR, internal skills are often run: find bugs, shrink the diff, end-to-end, UI against design specs. Boris Cherny estimates that giving Claude verification yields roughly 2–3x the output quality; the form varies by domain (bash, test suites, browser/simulator). If the same class of problem keeps being caught in review, fix the skill / lint / docs: CLAUDE.md: stack, conventions, goals and non-goals; loaded on every review, so in large repos keep it short and link out. Violations of conventions or outdated docs should be flagged.

REVIEW.md: owners tell reviewers what counts as a failure locally (e.g., docs that "lie," config that "misroutes"), fewer nits, paths to ignore, required file+line numbers, a top-level summary with counts and an explicit statement when there are no issues.

2. AI review on every PR Before a human looks, Claude goes first: against the whole repo and the PR's intent, does it actually solve the problem, does it fit the system, does it break elsewhere; when fixing a bug, trace the root cause. On the product side: Code Review for Team/Enterprise; local /code-review. After the research preview, the share of internal PRs with "substantive comments" went from about 16% to 54%; most changes over 1000 lines are caught, and most small PRs are clean. Depth: Quick / Standard / Deep (use Deep when missing a bug is expensive). Multiple agents search for bugs in parallel → vote to filter false positives → discard purely stylistic/cleanup items; comments are labeled Important / Nit / Pre-existing. Threads must be fixed or explicitly closed with an explanation; agents often fix them overnight.

3. Blocking security review Security gets its own round; if a code/bug or security finding is open, the PR cannot merge. It can be fixed, or a false positive closed with a short reason; a later commit that fixes it can auto-close it. Can align with the open-source security Action or /security-review.

4. Blocking automated checks Lint, types, multi-platform tests, builds, etc.; CLI PRs often run dozens of these before a human looks. The template requires "how to test" and "how to revert," which Claude can fill in but the author must verify.

5. Human approval scaled by risk · Low: docs, copy, internal-only features, additive changes behind a flag; after automated review + security pass, human approval may not be required · Medium: ordinary product changes; sensitive areas such as caching, auto-updater, system prompts; 1 human approval · High: the highest-risk code; plus a small number of paths that always require two people; 2 human approvals

There are also classifiers that can still add one person even when "no approval tier is required"; paths marked sensitive by owners, CI workflows, and the like often force human approval. Only trusted lists (mostly the team that owns the repo) get relaxed paths; everyone else needs a second person. Agent approval never substitutes for a human; low-risk changes can clear via automated review, but the slots that need a human cannot be filled by machines. For a PR opened by an agent, the operator counts as one required reviewer. An approval is valid only for the current commit: an untrusted new commit (the agent pushes again, conflicts are resolved by hand, etc.) revokes approval and requires re-approval.

6. Merge queue, feature flags, staged rollout The queue re-runs on "main with that change included," avoiding two individually green PRs merging into a broken main. New features usually go behind a flag first, to employees first; public rollout starts with latest, and stable lags behind.

Rollback layer: detect fast, revert fast Bad merges are inevitable. A flag can be turned off without redeploying; weekly on-call rotation; incident postmortems ask "which layer should have caught this." Detection still relies on authors, on-call, and the revert/incident dashboard. There is not yet a circuit breaker that automatically tightens approvals based on these metrics, but engineering wants one before more "zero-human-merge" changes. The priority is to increase the speed of detection and correction rather than slowing everything down (slowing down reduces errors mostly because less gets done).

Making reviewers better: incidents as evals, forced convergence · Turn incident PRs + fix-forward/revert into an eval set; people who understand the code verify the bug location; the review system scores daily; whenever prompts/tools/models change, re-run the full set. · Use how people handle comments (fix/reject/clarify as intentional/don't care) to manage noise; also run review on known-clean PRs to see whether it induces harmful changes. Priorities are fixed: real bugs first, then fewer rounds. · For an agent author, handling a nit costs far more than a human glancing and closing it: it commits again and goes through another review round. · We once saw an author agent and a review agent loop overnight for 50+ rounds on the CLI; git blame showed that about 59% of the re-reported issues were old code that already existed in the first round. Countermeasures: after about three rounds, require a re-evaluation of the approach; afterward review only the new diff; fix bugs in batches by category; do not re-report; scan historical code at night. After convergence, the internal average number of review rounds dropped.

Things humans must still be in the loop for Whether to build it, taste and scope; dangerous surfaces such as billing / auto-updater / CI; architecture that sets conventions; verifying the "proof" (test output, commands, screenshots, review comments)—if you can't say what a check would miss, don't just ask for a 👍; the person responsible for each merge is a human, no matter who typed the words.

How to build shared understanding After machines read most of the diff, no human holds the whole repo in their head, and we don't aim for that. To learn a slice, have Claude write an explainer (which can then be turned into a small visual artifact); it's far more useful than scanning a one-line copy diff. Collaborate in public channels by default, and see what others are building as you work.

You land it, you own it When a small or medium change has a problem, the norm is that the author usually fixes it themselves. This relies on: small changes, revertibility, blast-radius thresholds, telemetry and internal dogfooding exposing problems fast, and incident reviews looking at the system rather than assigning blame; open channels let non-owners give feedback too. Agents make "start writing" cheap; if someone in the channel points out a wrong path, close the PR early / change course, and don't use sunk cost as an excuse to drag it to final review before blocking.

Transferable lessons · Before the PR: a short CLAUDE.md checklist + hooks; local /code-review, /security-review, or a fresh-context subagent; REVIEW.md collects repeated comments. · On the PR: CI; the template includes Testing / Risk / How to revert; first try AI review in one repo and tune REVIEW.md for a few weeks; security review; threads must be closed; choose Quick/Standard/Deep by risk; limit rounds, then review only the new diff. · Approval: write risk tiers by change, strict first then loose; relax only for trusted parties; bots cannot substitute for human approval; a new commit revokes approval; CODEOWNERS protects auth, billing, CI, release, and installers. · After merge: queue, flag, internal testing, staging, one-click revert; incidents/reverts go into evals; when watching people, use revert/incidents as guardrails. · Direction: externally, the product is still "post findings, human makes the final approval"; for our own repos, owners are already letting some low-risk changes auto-merge after checks are green, and the boundary keeps moving outward; when something slips through, add to CLAUDE.md / skills / new checks. · The goal is unchanged: reduce human-hours per person while keeping reverts no worse than today.