How the Claude Code Team Does Code Review: The Agent-Scale Blueprint

Claude writes about 90 percent of the code for Claude Code. So who reviews it? The team behind the product just published the answer, and it's the most complete public blueprint yet for running an agent-scale engineering org. Between June and September, merged pull requests to the Claude Code codebase more than doubled while the share that had to be reverted fell by more than 40 percent. The monorepo they live in went from ~2,500 changes merging per day in May to over 30,000 in September. Line-by-line human review is not just expensive at that volume — it's impossible. So they rebuilt the entire review process around a different question: not "did someone read this code?" but "what could go wrong, and which check — automated or human — is the right one to catch it?" This post breaks down the full system: the six review layers, the self-improving reviewer, the convergence failures they hit, and the exact checklist for adopting it.

The Bottleneck: 30,000 Changes a Day

The starting point is scale. Code review has always served two purposes: catch bugs before they ship, and build shared understanding of the codebase. At human writing speed, both worked — the PR was the unit of review and the unit of learning. At agent writing speed, the unit breaks. In Anthropic's monorepo, merged changes went from roughly 2,500 per day in May to over 30,000 in September — a twelve-fold increase in four months. Claude Code's own repos feel the same pressure. When you move that fast, manual line-by-line review "becomes increasingly hard, if not impossible."

The team's reframing is the conceptual move that everything else hangs on: they treat "did someone read the code?" as an imprecise measure of the real question — "what could go wrong with this change, and what check is the right one to catch it?" That single reframe changes the timing of review. Traditionally review is a gate at the end of the road: code written, PR filed, wait for a human. Instead, the Claude Code team runs review continuously, "more like a spellcheck that you continuously do while writing." The majority of changes have already been reviewed and corrected by Claude — at least once — before a human is asked to look. Humans are reserved for the high-level considerations that machines are bad at; the machines catch the routine.

Human time is a dual-sided cost

The metric design is worth copying even if you never use Claude Code. The team measures human time two ways: time people spend doing review, and time people spend fixing bugs that bad code introduced. "If we reduce the first without reducing the second, we're not really saving human time." Their stated goal: the majority of PRs in the Claude Code repos (CLI, desktop/web, mobile) should merge with a maximum of one person in the loop — possibly just the author — without an increase in reverts or incidents. The tracked metrics: median human approvals per PR (plus 95th percentile), number of human comments, and how long a PR waits on a person. Revert rate and incident rate are the guardrails: if they rise, you haven't saved human time, you've just relocated it. That's a rare, honest formulation — most "AI cuts our review time" claims ignore the second term entirely.

The Journey of a Change: Six Layers + Rollback

Every change — from an engineer's laptop or a Claude session in Slack — passes through six layers of checks, each catching some bugs while missing others, with a rollback mechanism for what slips through all of them. Most of the process is automated; human attention is focused on the risky part.

Two details in layer 1 deserve emphasis. First, the team's guide to best practices centers on getting the agent to produce runnable evidence rather than claims — run the tests, run the build, compare the screenshot to the design. Second, Boris Cherny, who created Claude Code, estimates that equipping the agent with a verification process improves output quality "by a factor of two to three" — he calls it probably the single biggest lever. That number matters: it says the verification loop around an agent matters as much as, or more than, the model doing the work. The same dynamic we've seen across this site's coverage: the harness, not the model, is where quality is bought.

Layers 1 and 2 are steered by two small files that the whole article quietly organizes around. CLAUDE.md is the project description — tech stack, conventions, goals, non-goals — pulled into every single review; when code breaks a convention in it, the reviewer flags it. REVIEW.md is where code owners tell the reviewer what matters in their part of the code: define project failure, limit nitpicking, define ignored paths, require file+line references instead of guessed filenames, require a top-level summary with a count and an explicit "no issues" statement. The team even separately verifies whether the reviewer is following these guidelines. A few hundred words of configuration is the control surface for the automated reviewer — which makes it the highest-leverage document in the whole system.

The Reviewer That Improves Itself

Here's the part that makes this a real operating system rather than a tool purchase: the review system is evaluated daily against a growing collection of real incidents. The team collected every incident-causing PR, its fix-forward, and its revert; engineers who know the codebase verified the location and correctness of each bug. Every new incident adds to the collection, and every change to the review system is evaluated against the entire collection. That's a benchmark built from production pain, re-run continuously — the same idea as an eval suite, except the evals are your own post-mortems.

Equally important is how they measure noise. It's trivial to improve bug-finding rate by flagging everything, so they categorize how each review comment was handled: fixed, rejected, clarified as intentional, or dismissed as unimportant. They also run the system against PRs known to be clean and count how often it would have produced a harmful change. Stated priorities, in order: (1) detect real bugs, (2) reduce the number of review cycles.

And the article is strikingly honest about where the agent-reviewer loop goes wrong. The failure they call convergence: an agent author and an agent reviewer can cycle forever. They observed one PR in the CLI project cycle more than 50 times overnight between author-agent and reviewer-agent before someone stopped it manually. Running git blame on what the reviewer kept flagging showed ~59% of it was code that had existed since the first pass — the system wasn't finding new bugs, it was re-discovering a few old ones each cycle. Part of the problem was self-inflicted: the team had developed the habit of running several review cycles by default, because each cycle can find a different bug. The fixes, all concrete: cap the cycles (after three, the system asks the author to re-evaluate the approach instead of iterating lines), limit re-review to just the new diff, specify the class of bug so the author fixes the whole category, and never re-report an issue already observed. As a bonus, the review agents now run on the current codebase overnight, surfacing historical bugs before they propagate.

What Humans Still Do

The goal isn't zero human review — it's humans exactly where machines can't reach. The article lists the tasks that stay human, and the list is a useful map of the human/agent boundary as of late 2026:

• "Should we even build this?" — vision, taste, goals. Notably, a team that claims to have solved the review bottleneck still performs human review for changes from outside the team, specifically to confirm it's the right thing to build. Review caught up with in-team velocity; judgment about direction did not.
• Auditing dangerous code — billing, the auto-updater, CI workflows. The layers that can ship anything to everyone get the strictest human gates.
• Architecture review — because architecture choices set the conventions everyone else (and every agent) follows.
• Verifying proofs — the test output, the commands run, the screenshots, the reviewer comments. Their rule is sharp: "If you can't describe what the checks would miss, don't ask for a 👍 — you need a real review." A thumbs-up isn't verification; it's a transfer of liability.
• Taking responsibility — "a person answers for every change that ships, whoever typed it." If an agent authors a PR, the operator of that agent is always counted as one of the required reviewers. Approval is a human act, even when the code isn't.

Notice the asymmetry: automation absorbs reading, but humans keep accountability, direction, and architecture. That's a stable division of labor — the parts that scale are the parts that are repeatable, and the parts that stay human are the parts that are judgment.

The team-learn question: who reads the diffs anymore?

Code review's second purpose — shared understanding of the codebase — is what happens to the team when machines do the bulk of the reading? The answer is almost radical: no member of the team has a full mental model of Claude Code in their head, and they don't think anyone needs to. Instead, when someone wants to understand a slice of the codebase, they ask Claude to generate an explainer about that exact slice — a few minutes, always up to date. Some people go further and have Claude build a mini artifact that visualizes the area and teaches it in their preferred style. Their argument: reading a trivial diff line-by-line teaches you almost nothing (a one-line copy change), while creating an explainer about the module you're about to change teaches you a lot. Add open-by-default work in public Slack channels — seeing what others build as they build it — and the learning channel shifts from "read every diff" to "generate targeted explainers + watch the open work." Whether that fully replaces diff-reading as a learning mechanism is the open question the article concedes ("we don't have any formal mechanism for this") — but it's the first serious attempt to answer it.

"You land it, you own it"

When a small or medium change ships and something goes wrong, the expectation is that you fix it yourself. The article is explicit that this doesn't spiral into blame or heroics, for structural reasons: small changes are easy to review, debug, and revert; everything can be reverted — flags, reverts, staged rollouts reverse most mistakes in minutes; blast radius sets the bar, so expensive code gets more eyes; regressions surface fast through telemetry and internal usage; and it's not a blame game — the person who fixes it owns it because they have the most context, and incident reviews consider the system, not the individual. The last clause is the real culture point: at agent scale, ownership follows context, and context increasingly means "whoever can ask the agent the right question about this code."

The Adoption Checklist (Mostly Available Today)

The article's best feature for practitioners is that nearly every component is available now — the "how to implement" section is effectively a 30-day program. Compressed:

Three items in that list are the ones most teams would skip, and the article is clearest about why they matter. First, start with one repo and iterate the review config for a few weeks — the reviewer's quality is a property of the CLAUDE.md + REVIEW.md + model combination, and that combination is tuned empirically, not from a template. Second, re-score the reviewer whenever anything in the pipeline changes — a model upgrade that makes the writer better can quietly make the reviewer's noise profile worse; the incident-collection eval exists to catch that. Third, the revert/incident guardrail before the time savings — this is the difference between a system and a gamble.

Why This Is the Blueprint, Not Just a Post

This is the first time a shipping product team has published the complete review stack of an agent-written codebase with its numbers, its failures, and its config files. It matters for three reasons.

1. The unit of engineering work is no longer the PR

When 30,000 changes land a day, the PR is a transport mechanism, not a review unit. The real unit becomes the class of change — risk-tiered, each with its defined check stack. The classifier that assigns tiers "based on the change, not the author" is the organizational primitive: it decouples review cost from human attention the same way CI decoupled correctness from vigilance. Any team that lets agents open PRs will converge on this shape, because it's forced by arithmetic. The interesting work is moving upstream — deciding which classes are low-risk — and that's a judgment call the article keeps firmly human.

2. Verification is the product; the model is the input

The 2–3× quality multiplier from adding a verification process to the agent is the number to carry around. Combined with the convergence story — the reviewer is an eval'd, re-scored, noise-regulated system, not a prompt — the post argues that the durable asset in agent engineering is the verification-and-review apparatus: the CLAUDE.md/REVIEW.md control surface, the incident-collection benchmark, the voting agents, the risk classifier, the rollback machinery. All of it is config, prompts, and pipelines — inspectable, versionable, portable. That's the same thesis as the harness posts on this site, now proven at the scale of a real product's daily merge traffic. The moat isn't "we have Claude"; it's "our reviewer has been re-scored against 400 of our own post-mortems."

3. The human role compresses to direction, architecture, and accountability

Read the "humans in the loop" list as a job description of the future senior engineer: decide what to build, set architecture, audit the dangerous paths, verify the proofs, and own what ships. Nothing in that list is "read the diff." That's a bigger cultural claim than the tooling: it says the scarce skill at agent scale is not code comprehension volume but judgment about what the checks would miss. The "if you can't describe what the checks would miss, don't ask for a 👍" line is the best single-sentence definition of senior review in the agent era I've seen anywhere — because it inverts the default. Today most "reviews" are exactly that 👍: a liability transfer. The agent-scale world forces reviews to be real, because the volume makes fake ones untenable.

Bottom Line

Most of the AI-engineering discourse in 2026 is about the writer — which model, which agent, which harness. This post is about the other half of the equation, and it's the one that determines whether agent output is production-grade: how do you review what agents write when agents write more than you can read? The Claude Code team's answer is a complete, measured, and refreshingly self-critical system: review shifted from a gate to a continuous spellcheck; human time is counted as a dual cost with revert rate as the guardrail; six layers of checks with risk-tiered human approval where bot approval never substitutes for a human; a reviewer that's benchmarked daily against your own incident history and tuned for noise as much as recall; and a rollback culture that makes "you land it, you own it" survivable at 30,000 changes a day. The failures are as instructive as the results — a PR that cycled 50 times overnight, a reviewer re-flagging 59% pre-existing code, the habit of default multi-cycle review making both worse — because the post treats the review system itself as the thing under construction, with evals and regression tracking. For any team letting agents open pull requests, this is the current best public answer to the question that matters, and nearly every component is available today. The writer is the easy half. The review pipeline is the product.

References

• Addy Osmani, Morgan Westlee Lunt, Qing Wang — "How the Claude Code team does code review," X Article (Oct 26, 2026) [x.com]
• Addy Osmani, Morgan Westlee Lunt, Qing Wang — "How the Claude Code team does code review," claude.dev Blog (Oct 15, 2026) [claude.dev]
• Claude Code Docs — Code Review (product, four-stage pipeline: Find / Verify / Rank / Post) [code.claude.com]
• Anthropic Engineering — Redesigning source control (scaling CI referenced in the post) [anthropic.com]
• Claude Code Docs — Best practices (fresh-context subagent review, verification-first workflow) [code.claude.com]
• Boris Cherny — creator of Claude Code, on verification (referenced quote) [x.com]

Process details, metrics (merge volume, revert reduction, 16%→54% substantive review, 50-cycle PR, ~59% pre-existing flags), and the adoption checklist verified against the X Article and claude.dev blog version as of October 27, 2026. Figures are the team's self-reported internal metrics. Code Review for Claude Code is available to Team and Enterprise customers; the local /code-review and /security-review commands are available on broader plans.