Claude Code Review: Keep Four Roles Separate

How should Claude Code review a pull request?

Use local /code-review for pre-push feedback, managed Claude Code Review for PR-native findings, and a separate repository-owned check for merge policy. Keep four roles distinct: Claude as author, a review-only invocation as reviewer, deterministic code as evidence policy, and GitHub plus maintainers as the merge gate.

This distinction matters because “Claude Code Review” now names several different surfaces. Anthropic's managed service runs specialized agents on its infrastructure, posts inline findings and annotations, and verifies candidate issues. The local command runs from a Claude Code session against a chosen diff. The programmable GitHub Action runs Claude in your workflow and may have write-capable tools. They are related products, not interchangeable security boundaries.

The managed service is deliberately advisory. Anthropic's currentCode Review documentationsays its check run always concludes neutral and does not approve or block a pull request. GitHub treats a neutral conclusion as successful for required checks, so a repository needs a separate failing check if findings must affect merge eligibility. That is a policy decision, not a prompt-writing trick.

Choose the right Claude Code review surface

Start with the job you need done. Local review is fastest for the author. Managed review creates a durable pull request record. A custom Action gives you broader orchestration, so you must define its permission surface explicitly. A repository gate turns admitted findings into an enforceable status. Combining them is often useful; confusing them is not.

Local /code-review can target the current work, a file, a pull request number, a branch, or a ref range. It follows CLAUDE.md, but Anthropic's docs say it does not read REVIEW.md. Managed Code Review reads both: hierarchical CLAUDE.md files provide shared project context, while a root REVIEW.md controls review-only behavior at higher priority.

Do not collapse adjacent commands into the same job. /review is a fast review pass, /code-review ultra escalates to a deeper cloud review, and/security-review is scoped to security risks. Choose the command whose target and cost match the decision you need to make.

TheClaude Code GitHub Actionis broader than managed Code Review. It can analyze issues, modify code, and create pull requests when the workflow grants those tools and permissions. Treat it as an automation runtime. If the task is review-only, narrow its prompt, tools, event, token permissions, and publication path accordingly.

If your team uses OpenAI Codex instead, theCodex code review guide maps local/review, GitHub @codex review, scopedAGENTS.md rules, and the same exact-head merge requirement. For Cursor teams, theCursor code review guide separates local/review, Bugbot findings, finding disposition, and the repository verdict.

Use a four-role Claude Code review contract

The practical gap is an authority map. Four roles participate in a defensible review. The same vendor or model may appear twice, but each role needs a distinct invocation, context, permission set, and artifact.

Model diversity is not the boundary. Asking a second model to review the first model's code may reduce correlated mistakes, but it does not stop the pull request from changing the instructions or policy that judges it. Conversely, the same model can provide a useful independent pass when it receives a clean context and cannot mutate the code or its own admission rules.

ReviewGate implements this separation in public source. A reviewer proposes structured findings; deterministic policy admits a blocker only when classification, P0-P3 severity, confidence of at least 0.85, and repository evidence all pass. Thefinding policythen derives a fixed score and a separate GitHub check. Model prose cannot set the check conclusion directly.

That design also keeps authoring and repair outside the reviewer. ReviewGate is review-only. Itscoding-agent workflowassigns edits, tests, commits, and pushes to the external agent, while the review result stays a source of evidence. A maintainer remains responsible for intent and acceptable risk.

Run Claude Code review as a six-step workflow

The sequence below produces a durable chain from intent to merge. Each step has a visible output, which makes failures easier to classify than a single conversational instruction such as “review this and fix everything.”

1. Define the intended change. Record the pull request goal, affected contracts, expected tests, and explicit non-goals before asking any reviewer to judge the diff.
2. Run local review before the pull request. Use the local /code-review command against the intended branch or ref range, validate its findings, and rerun deterministic tests after each accepted fix.
3. Run a separate pull request review. Use managed Code Review or another review-only invocation with permissions and context separate from the authoring session.
4. Admit only evidence-backed findings. Require each potential blocker to identify the checked claim, exact repository evidence, causal failure path, severity, and relevant test state.
5. Bind the result to the current revision. After every relevant push, require a fresh result for the commit GitHub is evaluating and preserve unresolved findings until evidence settles them.
6. Leave merge authority with the repository. Let deterministic CI, branch policy, required human approvals, and the maintainer's risk judgment decide whether the pull request may merge.

1. Write the intent before the review

A reviewer can inspect code, but it cannot recover an unstated product decision. Put the user-visible goal, compatibility constraints, affected security boundary, expected tests, and non-goals in the pull request. Keep that text as untrusted scope context, not as permission to override repository policy.

2. Use local review as author feedback

Run deterministic tests first so the reviewer spends attention on logic that those tools cannot settle. Then run local /code-review against the exact branch or ref range you intend to publish. Validate every accepted finding against source and tests. If you use --fix, inspect the resulting diff and use Git to revert unwanted background changes; Anthropic notes that background review edits fall outside the session's checkpoint rewind behavior.

3. Push into a separate review context

The pull request review should not inherit the author's conversation or treat the author's final self-assessment as evidence. Managed Code Review provides this separation by running on Anthropic infrastructure. A CI-owned reviewer can provide it with a fresh process, a pinned runtime, read-only source access, and an explicit output schema.

4. Convert findings into checked claims

Severity is not proof. For every candidate blocker, require the changed location, the exact claim being checked, a causal path to observable failure, and the test or contract that confirms it. Use theevidence-bound PR review prompt libraryfor the reviewer side, then apply deterministic admission rules outside the model.

5. Re-evaluate the revision GitHub is merging

A fix creates a new revision. GitHub'srequired-check documentationsays checks from earlier commits do not satisfy the latest revision. Depending on repository settings, GitHub may evaluate the pull request head or a synthetic test merge commit. Read the merge box, require the displayed revision's checks, and do not reuse a clean finding set from an older head.

6. Make the merge decision explicitly

A complete chain distinguishes four statements: Claude found no Important issue; the evidence policy admitted no blocker; the required check passed for the current revision; and a maintainer decided the change matches intent. Each is useful. None implies all the others.

Configure managed Claude Code Review without stale advice

Anthropicannounced managed Code Reviewon March 9, 2026 and currently labels it a research preview for Team and Enterprise organizations. It is unavailable to organizations using Zero Data Retention. The service supports three trigger modes: once when a pull request opens or becomes ready, after every push, or manual. Current documentation, accessed August 3, 2026, records a July behavior change for manual commands.

• @claude review runs one review without subscribing later pushes.
• @claude review once is the explicit one-shot alias.
• @claude review always runs now and subscribes subsequent pushes.

Older help pages and third-party posts may still say the bare command subscribes the pull request. Follow the live product documentation for time-sensitive trigger behavior. Use a top-level pull request comment, not an inline reply.

Managed review is best-effort. A failed or timed-out run stays neutral and does not retry automatically; trigger it again with a top-level review command or a new push when the pull request is subscribed.

Keep REVIEW.md narrow. Define what counts as Important, cap nit volume, skip generated or vendored files, and demand source evidence for behavior claims. Put shared architecture and coding conventions in scoped CLAUDE.mdfiles. OurClaude review prompt guidancecovers the instruction boundary in depth; the merge policy still belongs outside both files.

Plan cost and latency at the trigger layer. Anthropic currently reports an average of about 20 minutes and $15-$25 for a managed review, with cost varying by pull request size, codebase complexity, and verification work. Every-push mode multiplies that spend. Those figures describe the managed service, not ordinary local/code-review usage.

Trace one Claude Code finding across all four roles

Suppose Claude authors a session-cache change. The new code starts a token refresh and lets logout clear the session, but a late refresh response can write the old token back. A local review flags the race. Here is what a defensible handoff looks like.

1. Author: the pull request states that logout must invalidate the session immediately and includes a focused concurrency test. The authoring agent does not declare its own patch safe.
2. Reviewer: a separate review cites the changed callback and the logout path, states the interleaving, identifies stale-session restoration as the impact, and points to the missing cancellation or generation check.
3. Evidence policy: deterministic code verifies that the cited lines exist in the reviewed diff and that required causal-path and test-assessment fields are present. It then applies classification, confidence, severity, and evidence rules to derive blocking_reason rather than trusting the reviewer's prose as policy.
4. Merge gate: an admitted blocker lowers the code-derived score and status, both tied to reviewed_sha. CI remains a separate requirement, and the pull request cannot merge until a new revision resolves the race and receives a fresh required check.

After the fix, reviewer silence is not resolution evidence. The new result should either re-emit the finding with current evidence or record why the changed code settles it. ReviewGate'srereview convergence contractkeeps unresolved findings open across model wording drift and ties disposition to the reviewed revision.

This is the concrete payoff of the four-role model. Claude can remain the fastest author and a useful defect detector. Deterministic code decides whether a claim meets repository policy. GitHub and the maintainer decide whether the exact change may ship.

Avoid these Claude Code review failure modes

Treating neutral as clean

Managed reviews with findings, clean reviews, timeouts, and internal errors all complete with a neutral conclusion. Read the check title and details. A neutral conclusion tells GitHub not to block; it does not tell a maintainer that review found no issue.

Letting the pull request define its own gate

Repository guidance can improve a review, but contributor-controlled text is still input. A pull request should not be able to replace the executable policy or runtime that converts findings into a required check. The broadermerge-safe AI review workflowcovers event and runtime boundaries for GitHub Actions.

Confusing a new push with a resolved finding

Changed line numbers, absent comments, or a fresh model response do not prove the defect disappeared. Carry stable finding identity forward and record whether it is fixed, rejected with evidence, intentional, disputed, or still open. Thereview comment contractshows how to preserve that state without turning every advisory note into a blocker.

Buying review volume without a feedback loop

Automatic review after every push can multiply cost and comment load. Start with representative pull requests, record accepted and rejected findings, tightenREVIEW.md, and decide which classes deserve a required gate. Expand only when the evidence shows maintainers receive more useful signal than triage work.

Use this pre-merge checklist for Claude-written PRs

• The pull request states intent, contracts, tests, and non-goals.
• Deterministic tests, types, linters, and security checks pass.
• Local review examined the intended branch or ref range.
• The PR reviewer ran in a separate context with bounded permissions.
• Every blocker cites exact evidence and a causal failure path.
• Advisory findings are visibly separate from required changes.
• The review result belongs to the revision GitHub is evaluating.
• Earlier open findings have an explicit current-revision disposition.
• A reviewer failure is reported as unavailable, not converted into a pass.
• A maintainer confirms intent and accepted risk before merge.

If your repository needs a machine-readable version of that contract, install ReviewGate from theGitHub Actions guide. Run it in advisory mode on known pull requests first. Compare admitted blockers, suppressed candidates, and rereview convergence against known outcomes. Once its evidence and noise behavior match your repository, you can choose whether its current-revision check belongs in branch protection alongside deterministic CI and human approvals.

Questions about Claude Code review