The Claude Code team shares its workflow for reviewing AI-written code

According to the Claude Code team, approximately 90% of Claude Code's own code is written by Claude. As the volume of changes grows, engineers find it increasingly difficult to read every commit line by line.

From June to September, the number of merged pull requests (PRs) in the Claude Code repository more than doubled, while the proportion requiring rollbacks fell by more than 40%. (A PR, or Pull Request, is a proposed set of changes submitted to a codebase for review and merge; a rollback reverts an already merged change.)

When AI authoring accounts for such a massive share of code, traditional line-by-line human review increasingly struggles to keep pace and turns into a bottleneck in the development lifecycle. Code review has also begun shifting from a final human gate to continuous checks throughout development. The Claude Code team has shared their concrete workflow for reviewing AI-generated code.

The core of this workflow is offloading most code reading to machines so engineers can focus their time and attention on critical risks that demand human judgment, while making mistakes faster to discover and easier to undo.

Why a Surge in Code Changes Calls for Rethinking Review

Code review typically serves two purposes:

1. Find and fix issues before merge.
2. Build understanding and shared context across the team.

In the past, these two needs were often bundled into the same step: write the code, submit a PR, and wait for colleagues to review it line by line.

Human time spent on review consists of two parts: how long it takes to inspect before shipping, and how long it takes to fix escaped issues later. If reducing the former leads to a massive surge in the latter, no total time is saved.

The team aims for most PRs to require at most one human involved at merge time, who can be the author themselves. To determine whether human burden has genuinely dropped, they track human approval counts per PR, human comments, and the time spent waiting for a human; approval counts are monitored at both the median and the 95th percentile (P95) to understand not just the common path, but also requests requiring heavier human participation.

These metrics differ from how many rounds of machine review took place: even if automated checks finish quickly, a PR may still sit waiting in line for a human. If fewer approvals result in more post-deployment incidents and remediation, human effort is merely pushed downstream. Therefore, rollback rate and incident rate form the non-negotiable floor for this optimization.

Here, Claude provides the underlying model capabilities, while an Agent is an AI agent that uses models and tools to perform specific tasks. In this workflow, writing code, running verification, and reviewing changes can be distributed across different Agents; the Agent responsible for code review is referred to below as the "review Agent" or "reviewer."

When Agents write vast amounts of code and the volume of changes surges, traditional post-hoc human gating easily turns into a bottleneck. "Whether a human has read the code" rarely correlates accurately with "what could go wrong with this change."

Thus, the core premise of review shifts to a more practical question: "What could go wrong with this change, and which automated check or human judgment is best suited to catch it?"

This also shifts when review occurs. Review is no longer just a final gate waiting for human sign-off; it behaves more like a spell-checker running as code is written. Most routine mistakes are already caught and corrected by automated checks before ever reaching human eyes.

Suppose the team introduces a flag named --retry-timeout to a command-line tool to control retry duration during network outages and print status messages. Such a change no longer simply sits in a queue waiting for colleagues to read line by line; instead, it first passes through multiple layers of targeted automated checks and tiered routing.

Defense in Depth: From Local Validation to Production and Beyond

Faced with a rapidly mounting volume of changes, a single layer of human review is prone to blind spots and cannot handle the load. In practice, Anthropic combines multiple layers of checks: each excels at catching certain classes of issues, and each has its own risk of missing defects; the rare issues that slip through all checks rely on fast rollbacks and feature flags after merge as safety nets.

1. Pre-Commit Verification: Letting Code Prove Itself Before Others Review

The vast majority of routine errors should be resolved before creating a PR. Requiring an Agent to actually run and demonstrate results is far more reliable than merely asking whether it has finished:

• Run and show results: Provide the model with an executable environment and commands (such as running test suites, executing builds, outputting CLI results, or comparing UI screenshots in browsers and emulators), requiring concrete execution output as proof.
• Fresh-context re-review: Spin up a separate reviewer sub-Agent that does not inherit the conversation history from writing the code, but instead re-reads project materials and inspects the code diff afresh. This minimizes the anchoring bias from the authoring phase.
• Internalizing engineering conventions: A concise CLAUDE.md outlines the project's tech stack, conventions, goals, and explicit non-goals, pointing to more detailed documentation. The reviewer verifies both whether the code violates these conventions and whether new changes make existing instructions in the file obsolete.

Many engineers also run several internal skills before submitting, searching for defects, simplifying diffs, and checking end-to-end behavior; UI changes are also checked against design specs. Passing tests and end-to-end correctness are two distinct types of evidence requiring separate verification.

REVIEW.md, maintained by owners of each module, tells the reviewer what issues are worth reporting here. Beyond concrete failure definitions, it restricts nitpicks, lists paths that can be skipped, and demands file and line numbers as evidence rather than guessing issues based on function names; the summary must lead with the count of issues found, and explicitly state none if nothing is worth fixing. The team also independently audits whether the reviewer genuinely adheres to these guidelines.

For example, consider an illustrative rule for this article's hypothetical retry parameter: "Verify whether retries respect the configured total duration; if exceeded, cite the relevant file, line number, and trigger condition. Do not suggest changes based solely on variable naming preferences; state clearly if no issues were found." It defines what errors to look for and what evidence is required, making it far more actionable than a vague "review the code carefully." Recurring issues are fed back into guidance files, skills, or linter rules so future development avoids them earlier.

In the --retry-timeout example, the Agent must locally run tests covering timeout scenarios and print output containing actual elapsed times and logs. If a parameter name is misspelled or types mismatch, it surfaces locally without waiting for human intervention.

2. Continuous Integration Checks (CI)

Once code is pushed to remote, cross-platform style checks, type checks, unit tests, and build packaging run consistently. Any CI failure (red build) directly blocks merging.

3. Every PR Undergoes AI Review First

Every PR passes through automated review before any human inspects it. The public product version of this review is named Code Review for Claude Code. Its concrete practices include:

• Combining full codebase context with intent: The model evaluates whether the change resolves the intended problem, fits into the existing system, and avoids breaking other modules by examining full codebase context and the stated intent in the PR description. After launching this capability as a research preview, the proportion of internal PRs receiving substantive review feedback rose from 16% to 54%. This reflects that more PRs received meaningful feedback, not that 54% of known bugs were caught.
• Separating defect finding from verification: Multiple Agents search in parallel for potential defects in the background, followed by another group of Agents voting on each finding, publishing comments only when sufficient consensus is reached to filter out pure stylistic preferences or nitpicks.
• Grading and mandatory response: Retained comments are tagged as important, minor, or pre-existing issues. PR authors must either make fixes or provide rationale to resolve discussions; comments cannot simply be ignored.

4. Independent Automated Security Review

Security review runs as an independent check. If unresolved findings remain in either security review or code review, merging is blocked. In the retry parameter example, if log output inadvertently exposes unredacted credentials, security review blocks the merge if it detects the issue. The block is lifted only after the author fixes the issue or explains why it is a false positive.

5. Risk-Tiered Human Approvals

Different changes carry different levels of potential impact. Documentation fixes, routine feature development, and modifications to auto-update logic carry different risks; the system decides how many human approvals are required based on the change's intrinsic risk tier.

6. Merge Queue and Employee Dogfooding

A merge queue re-runs all checks against the latest main branch, preventing two individually passing PRs from breaking main when merged together. Feature flags decouple "code has merged" from "feature is exposed to users": code can enter main first while functionality is turned on gradually. New features typically sit behind flags and are dogfooded by Anthropic employees in daily work, often uncovering regressions before external users encounter them. During public releases, new versions first deploy to the latest production channel, with the stable channel following later.

7. Fast Discovery and Fast Reversal: Lowering the Cost of Mistakes

Even with multiple layers of defense, issues can still reach production, making rapid response essential:

• Feature flags can be toggled off directly online without waiting for rebuilds or redeployments; the team notes that flags, rollbacks, and staged rollouts allow most mistakes to be undone within minutes.
• The team maintains weekly on-call rotations where authors and on-call engineers monitor telemetry, internal feedback, and dashboards to detect regressions and track rollbacks and incidents. Post-mortems focus on systemic vulnerabilities—investigating which layer of defense should have caught the issue but failed, rather than assigning individual blame.

Applying this path back to the --retry-timeout scenario: the Agent runs timeout tests locally, then submits a PR for cross-platform CI, code review, and security review. After addressing findings and satisfying the corresponding human approval requirements, the change enters the merge queue to be re-verified against the latest main branch. Once merged, it is first made available to internal employees via feature flag before rolling out incrementally to users. If real-world network conditions combine with other features to produce issues untested locally, the feature is disabled, patched, or rolled back based on monitoring. Earlier checks minimize errors, while subsequent measures constrain the blast radius of escaped defects.

Risk-Based Human Approval and Accountability

In this review process, reducing the number of approvers is predicated on stricter automated constraints and clear accountability, not abandoning oversight.

Change Nature Determines Risk Tier

In the Claude Code repository, the number of approvers depends on the nature of the change:

• Low risk: Docs, copy, internal-only features, and incremental changes guarded by feature flags can bypass human approval if simplified conditions like trusted authorship are met and automated checks pass.
• Medium risk: Standard product features, as well as changes touching sensitive areas like caching, auto-updaters, or system prompts, require one human approval; for PRs authored by an Agent, the engineer directing the Agent can serve as this approver.
• High risk: The highest-risk code, along with a small set of fixed paths, requires two human approvals.

Tiers are assigned by a classifier analyzing the code, and a second classifier double-checks whether an additional human review is still warranted. Concurrently, any CI workflow files and paths explicitly flagged as sensitive by code owners require at least one human approval.

Approval Boundaries and Trusted Author Lists

• Trusted author lists: Relaxed approval paths are available only to authors on the repository's trusted list (mostly core team members maintaining the repo); code submitted by other authors requires approval from someone other than the author.
• Agents cannot substitute for human approvals: Automated reviews can waive human approval in low-risk scenarios, but whenever a tier demands human participation, an Agent's sign-off cannot count toward the human quota.
• New commits require re-verification: Human approval binds to a specific commit. If subsequent commits are added that the system cannot vouch for (such as fresh patches pushed by an Agent or manual merge conflict resolutions), original approvals must be regranted.

Who Authors the Change Owns It to the End

Regarding accountability, the engineer directing the Agent is just as responsible for merged changes as if they had written every line by hand. If a small or medium change misbehaves in production, the author is typically responsible for fixing it, as they hold the most complete context for that change.

This accountability model functions because changes are kept sufficiently small: when problems occur, isolating the specific change is easier, and fixing or reverting is simpler. Combined with feature flags, staged rollouts, and rapid rollbacks, the team ensures most errors can be promptly reversed, while telemetry and high-frequency internal usage expose anomalies early. Changes with wider blast radiuses and higher failure costs are assigned more human oversight and automated checks.

Therefore, "who merges owns it" is supported by engineering practices designed to reduce remediation difficulty; it does not mean an individual bears all consequences alone. Team post-mortems examine systemic and procedural gaps rather than assigning personal blame. Moreover, code ownership is shared across the team—engineers collaborate in open channels where anyone can observe what others are building and provide feedback.

Under this division of labor, engineer time shifts from reading routine diffs line by line to five critical decisions where machines fall short:

1. Whether the feature should be built: Direction, business judgment, and requirement scoping.
2. Gating high-risk code: Critical areas involving billing, auto-updaters, and CI workflows.
3. Architecture and design patterns: Evaluating whether newly introduced patterns will be widely replicated in subsequent work.
4. Evaluating objective evidence: Reviewing test outputs, command execution results, UI screenshots, and reviewer reports to judge what automated checks might have missed; if unable to judge what automation missed, initiating a real human review rather than fast-tracking approval.
5. Ownership of delivered outcomes: Regardless of who typed the code, an identifiable human ultimately stands behind every shipped change.

When Agents Review Agents: Why Review Loops Fail to Converge and How to Constrain Them

When code is written by an Agent and the first line of review is also assigned to an Agent, engineering teams encounter the challenge of reviews and fixes failing to converge.

Nitpicks carry a higher cost here. When a human sees an inconsequential suggestion, they can decide in seconds to ignore it; a code-authoring Agent, however, may obediently implement the change, generate a new commit, and trigger another review round. Consequently, a low-value comment can spiral into an entire cycle of "suggest – edit – commit – re-review."

In early experiments, an Agent-authored CLI change underwent over fifty rounds of review and edits overnight until the author manually intervened. The code-authoring Agent addressed review comments point-by-point and pushed new commits, while the review Agent raised fresh suggestions in the new context, causing review rounds to balloon indefinitely.

Why Review Rounds Ballooned: 59% of Flagged Code Existed at First Review

After using git blame to trace what the reviewer repeatedly flagged, the team discovered: approximately 59% of the flagged code had already been present during the reviewer's first round of review.

This showed that the reviewer was rarely finding new defects introduced by recent commits in later rounds; rather, it was finding a few more pre-existing issues from the original code in each pass. Because the first review round failed to report existing issues exhaustively, each round of fixes triggered fresh reviews, locking the interaction into an endless loop. Furthermore, the team had initially grown accustomed to multi-round review patterns; while valuable in certain high-risk contexts, enforcing this across all PRs imposed unnecessary overhead.

Four Adjustments to Drive Review Convergence

To ensure reviews converge efficiently, the team tracks "review rounds required to approve" alongside defect recall: catching issues while avoiding endless ping-pong. To achieve this, they implemented specific adjustments:

1. Cap review rounds: After three rounds of review, the reviewer requires the author to step back and reconsider the implementation approach rather than continuing to spin in local micro-adjustments.
2. Review diffs only after initial rounds: After the initial review rounds, subsequent re-reviews inspect only the newly added diff from the latest commit (Diff-only), preventing the reviewer from continually re-combing older code.
3. Highlight defect patterns: The reviewer groups issues by defect category, prompting the author to fix all instances of a pattern at once rather than patching lines piecemeal.
4. Do not repeat existing comments: Comments that have already been posted are not re-issued under different phrasing.

Revisiting the retry parameter example: if multiple retry paths fail to limit total execution time correctly, flagging only one line might lead the author to fix just that single spot, only for another path to be flagged in the next round. "Highlighting defect patterns" instead explains the shared defect clearly, prompting the author to inspect and fix all related paths in one pass. After the initial rounds of review, re-review looks solely at the diff introduced by the new patch, focusing on whether the fix introduced new regressions rather than re-traversing the entire batch of older code to nitpick scattered issues.

Older issues are not left unaddressed as a result. Review Agents run overnight scans on existing code, providing a dedicated avenue for surfacing historical issues. Requiring a step back to reconsider the approach after three rounds does not mean automatic approval once three rounds are reached.

Average Rounds Dropped, but Long-Tail Outliers Matter

Following the implementation of convergence measures, review round metrics on Anthropic internal PRs showed noticeable shifts:

View Original Figure D: Review Round Data

The proportion of PRs approved after a single round of review and fix increased from 65% to 78%, indicating that more requests conclude after a single round trip, not that they required zero fixes.

These metrics come from internal PR data without specified sample sizes or time windows. While average rounds dropped from 2.08 to 1.32, the more significant shift occurred in the long tail requiring 5 or more rounds, which was compressed from 8.9% to 1.5%, showing that PRs stuck in endless back-and-forth grew much rarer; how much wall-clock time was saved requires separate measurement.

The Reviewer Takes Tests Too: Calibrating with Real Incidents

By collecting past PRs that caused incidents or prompted rollbacks, engineers familiar with the domain identify defects and their exact locations. Treating historical PRs as test prompts, with the corresponding fix or rollback records providing the ground truth, yields an evaluation benchmark grounded in real-world risk. During evaluation, the reviewer re-inspects these flawed changes, and its reported findings are compared against engineer-confirmed defects to see whether genuine issues were caught.

This case suite expands continuously with new incidents rather than remaining static. When missed detections are uncovered, the team investigates: what context was the model missing at the time? The resulting fix may be added to CLAUDE.md, a skill, or a new linter check.

The team runs daily reviewer evaluations. Whenever its prompts, tools, or underlying models are modified, it must be evaluated across the complete case suite, and changes are kept only if benchmark performance improves. This forms an ongoing loop: real incidents are confirmed by engineers and added as test cases; missing context or checks are updated based on misses, and all cases are backtested to determine whether a new version warrants keeping. The system must learn to catch newly emerged issues while verifying that previously detectable bugs are not missed once again.

However, flagging more issues can superficially inflate recall, so false positives must also be scrutinized. The team tracks whether each comment is subsequently fixed, deemed incorrect, considered intentional behavior, or dismissed as inconsequential; the reviewer is also tested on known-clean PRs to measure whether it suggests counterproductive changes.

They explicitly prioritize catching real defects first, and reducing review rounds second. Otherwise, a reviewer that rapidly rubber-stamps all code could easily produce impressive round counts.

With Less Code Reading, How Does the Team Maintain System Understanding?

The second traditional function of code review is spreading codebase understanding across the team. If machines handle most code reading, how does the team maintain its mental model of the system?

The Claude Code team notes that they currently have no formal process for this aspect. No single person on the team retains a complete mental model of the entire codebase, nor do they consider it necessary to do so.

When an engineer needs to understand or modify an unfamiliar module, they typically ask Claude directly to generate explanations tailored to the current code slice, or rely on model-generated visual diagrams to aid comprehension.

Such on-demand explanations cannot replace all necessary code reading, but when dealing with minor changes, they reduce the cognitive drain of parsing irrelevant diffs. Additionally, the team defaults to working in public Slack channels, where engineers can see in real time what others are building, maintaining awareness of system evolution through open discussion and collaboration.

How Other Engineering Teams Can Adopt This Workflow

Engineering teams looking to learn from this review mechanism must first distinguish between public tools and internal systems.

The managed Code Review feature for Team and Enterprise users, the locally executed /code-review CLI command, and the open-source GitHub Action represent distinct tool form factors designed for different usage contexts, rather than a single bundled package. Among them, managed Code Review focuses strictly on analyzing code and posting comments: it does not approve or block merges, nor does it run builds, tests, or push fixes on the team's behalf.

Anthropic's ability to allow certain low-risk changes to merge without human approval relies on its own internally constructed CI checks, security filters, merge queues, and rapid rollback mechanisms.

For other teams, a safer adoption path involves transitioning progressively through foundational constraints rather than copying zero-person approvals outright:

1. Enable Agents to self-verify first: List verification commands in a concise CLAUDE.md, and use hooks to automate formatting and linting; run /code-review, /security-review, or fresh-context sub-Agents before submitting. Maintain a module-owner-authored REVIEW.md to define what issues are genuinely worth reporting for that area.
2. Pilot in a single repository first: Make passing CI tests a mandatory requirement for merging; add "Testing", "Risk", and "How to revert" sections to PR templates, confirmed by the author. After integrating AI review, tune REVIEW.md for several weeks based on real feedback before expanding to additional repos.
3. Tie review findings to merge constraints: Assign code and security reviews to find issues, and enforce repository rules ensuring that "checks pass and discussions are resolved before merging." Use quick checks for daily changes and deep checks where missed bugs carry high costs; managed Code Review allows choosing Quick, Standard, or Deep per repository. Reporting an issue and actually blocking a merge are two separate configurations.
4. Clarify human approval rules while curbing unproductive ping-pong: Tier by change risk, reserving simplified paths for trusted authors. Use CODEOWNERS to designate owners for sensitive paths, and enforce required human approvals via branch protection; paths covering authentication, billing, CI, release workflows, and installers must retain human gatekeeping. Bots cannot substitute for required human approvals, and new commits require re-verifying approvals. Concurrently, cap review rounds and inspect diffs only after initial passes.
5. Prepare deployment and recovery pathways together: Implement merge queues, feature flags, internal dogfooding, and staged rollouts, alongside one-step rollback mechanisms. Collect problem PRs, fix records, and rollback histories to continuously expand the eval benchmark; re-test real defect recall and false positives whenever reviewer prompts, tools, or models change.
6. Relax approvals progressively based on data: Clearly delineate risk tiers, keeping human oversight on critical paths and CI workflows; track human review duration in practice while holding rollback and incident rates as the baseline. As automated checks, feature flags, and reversal mechanisms mature while rollbacks remain low, teams can progressively relax approval thresholds for low-risk changes based on their own context, rather than ruling out this direction from the outset.

Unbuilt Automated Circuit Breakers and Delivery Control

Anthropic has not yet implemented automated circuit breakers for metric degradation; the system cannot automatically tighten approval rules if incident or rollback rates spike, still relying on on-call engineers monitoring dashboards. Team engineers also hope to establish automated circuit breakers before expanding zero-person approvals more broadly.

Furthermore, while Agents drastically lower the barrier to writing code, this does not mean all generated code belongs in main. Discussions on whether a feature "should be built" are best held early in open discussion channels rather than blocking after code is written and a PR is submitted. Because generating code has become inexpensive, closing a PR when direction falters is far more acceptable than reluctantly merging simply because the code was already written.