Claude Code Review: From /code-review to Automated PR Reviews (2026)

A managed Claude review averages $15 to $25 and takes about 20 minutes. Put that next to the cost of a logic bug reaching production and the arithmetic looks easy, which is exactly why it's worth being precise about what you actually get for the money. Claude Code review is three different products wearing one name, and the one people reach for first is usually the wrong one for their situation. This walks through all three, what each costs, how the severity system works, how to teach the reviewer your team's rules with a file most people don't know exists, and the classes of problem it still doesn't catch.

Three Ways Claude Reviews Code

Start by picking the right tier, because the setup cost and the plan requirements are completely different.

The managed service is not available to organizations with Zero Data Retention enabled. On other plans you can still review a diff locally, which is where most people should start anyway.

Reviewing a Diff Locally with /code-review

The simplest version needs no GitHub App, no workflow file, and no admin rights. From the session where you're working:

/code-review

With no arguments it reviews your branch's commits ahead of its upstream plus any uncommitted changes, so it needs actual work on the branch or in the working tree to have something to report. To review something else, pass a target: a file path, a PR number, a branch name, or a ref range such as main...my-feature.

It reports correctness bugs alongside reuse, simplification, and efficiency cleanups. Two flags change what happens with the findings. --fix applies them to your working tree after the review; --comment posts them as inline PR comments. /review is an alias of the same command; before v2.1.223 it was a separate single-pass command that reviewed a GitHub pull request read-only.

The review runs as a background subagent with its own context window, so it doesn't fill your conversation, and the findings arrive when it completes. That detail matters more than it sounds: a review that eats 40,000 tokens of your main context makes the rest of the session worse. If you want to understand the mechanism, it's the same isolation that makes subagents useful generally.

One sharp edge worth knowing before you use --fix: a background review applies its edits outside your session's checkpoints, so /rewind won't undo them. Use git to revert. When the review runs in the foreground instead, it edits during your own turn and /rewind works normally.

Tuning the Review with Effort Levels

You can trade coverage against confidence by passing an effort level. At low and medium, the review reports only the findings it's most confident in, so you see fewer false positives. From high through max, coverage broadens and you'll get findings the review is less sure about.

/code-review high

The stickiness here catches people out. When you don't type a level, the review reuses the last one you typed, even from an earlier session, and shows a notice such as Reusing high effort, the level you typed last time. Type a level to change what later runs reuse. A level passed in a non-interactive -p run doesn't update the remembered value.

Rahul, a staff engineer at a 30-person startup, ran medium for a month on the theory that fewer false positives meant more trust from his team, then switched to high only for PRs touching auth or billing. His reported ratio was roughly two extra findings per high-effort review, of which about one was worth acting on. That's the actual shape of the tradeoff: not "better," just wider.

There's also an escalation path. /code-review ultra --fix runs a deeper cloud review and applies its findings to your working tree when they come back. Ultrareview scopes itself to your current branch against the repository's default branch plus uncommitted and staged changes, requires a claude.ai account, and isn't available on Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or to Zero Data Retention organizations.

Automated PR Review: What It Costs, What It Catches

The managed service is the one that reviews every pull request without you asking. An Owner enables it once for the organization at the Claude Code admin settings page, installs the Claude GitHub App, and picks which repositories to include. Each repository then gets a review behavior:

Under the hood, multiple agents analyze the diff and surrounding code in parallel, each looking for a different class of issue. A verification step then checks candidates against actual code behavior to filter false positives, and the survivors are deduplicated, ranked, and posted as inline comments on the specific lines. That verification pass is the interesting part of the design, and it's why reviews take about 20 minutes rather than 20 seconds.

Three comment commands trigger reviews on demand regardless of the repo's configured behavior. @claude review starts a single review without subscribing the PR to future pushes. @claude review always starts one and subscribes the PR going forward. @claude review once behaves the same as the bare command. Post them as top-level PR comments, not inline on a diff line, with the command at the start of the comment. Note that before a July 2026 update, the bare @claude review subscribed the PR; if you relied on that, you now want @claude review always.

If you'd rather run reviews on your own runners, the GitHub Action does it with a workflow file. This one runs the review plugin on every new or updated pull request:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

Findings land in the workflow run log rather than on the pull request, which is the main ergonomic difference from the managed service. That workflow also shows how plugins get pulled into CI, and the same mechanism works for any packaged capability, whether from Anthropic's marketplace or a skill registry.

Teaching the Reviewer Your Rules with REVIEW.md

Two files shape what the managed reviewer flags, and they work differently. CLAUDE.md is read as project context, and newly introduced violations get flagged as nits. REVIEW.md is review-only and gets injected into the system prompt of every agent in the pipeline as the highest-priority instruction block, taking precedence over the default guidance.

That precedence is the whole point. A rule buried in a long CLAUDE.md competes with everything else in the file; the same rule in REVIEW.md lands. Because it's pasted verbatim, @ import syntax isn't expanded and referenced files aren't read in, so put the rules directly in the file.

Five patterns earn their space. Redefine severity, since the default calibration targets production code and a docs repo needs a narrower bar. Cap nit volume, because prose and config files can be polished forever. List skip rules for generated code, lockfiles, and anything CI already enforces. Add repo-specific checks like "new API routes must have an integration test." And set a verification bar, such as requiring a file:line citation rather than an inference from naming, which cuts the false positives that cost an author a round trip.

# Review instructions

## What Important means here

Reserve Important for findings that would break behavior, leak data,
or block a rollback. Style, naming, and refactoring suggestions are
Nit at most.

## Cap the nits

Report at most five Nits per review. If you found more, say "plus N
similar items" in the summary instead of posting them inline.

## Do not report

- Anything CI already enforces: lint, formatting, type errors
- Generated files under `src/gen/` and any `*.lock` file

Keep it short. A long REVIEW.md dilutes the rules that matter most, and length has a real cost here. Note also that the local /code-review command follows your CLAUDE.md like any session but does not read REVIEW.md, so the two tiers won't behave identically until you account for that. If you're setting up project context for the first time, the CLAUDE.md guide covers the hierarchy.

Reading the Severity Table

Every finding carries one of three markers, and the third one is unusually useful:

Separating pre-existing bugs from newly introduced ones is the detail that keeps reviews usable. Without it, every PR that touches an old file inherits blame for everything around it, and authors learn to ignore the reviewer. Each finding also carries a collapsible extended reasoning section explaining why it was flagged and how it was verified.

Findings never block a merge: the check run always completes with a neutral conclusion. If you want a gate, read the machine-readable comment on the last line of the check run's Details text:

gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

That returns counts per severity, such as {"normal": 2, "nit": 1, "pre_existing": 0}, where normal is the Important count. A non-zero value means at least one bug worth fixing before merge, which is enough to fail your own job on.

What an AI Reviewer Still Misses

Every finding is scoped to the diff and the code around it, which quietly defines the blind spots.

The first is runtime and integration behavior. A review reads code; it doesn't run your stack against a real API, a real browser, or a real device. Silent API restrictions, platform quirks, content-security-policy rejections, and environment-specific config all live outside what a static read can see. A clean review means "no logic errors found in this diff," not "verified working," and treating those as the same is how a green PR surprises you in production.

The second is the branch that was never exercised. When a feature has an opt-in flag that routes through different code, reviews catch logic errors in the diff but cannot catch "this path has never actually run." The default path masks bugs in the alternative path because most usage flows through the default.

The third is intent. A reviewer can tell you a function is wrong relative to its own contract. It's far weaker at telling you the contract is wrong, or that this feature shouldn't exist, or that the three-line fix papers over a design problem that will cost a rewrite in six months. That's still the human job, and it's the part worth protecting the reviewer's time for.

Reactions on findings are worth using because they feed back. Each comment arrives with 👍 and 👎 attached; reaction counts are collected after the PR merges and used to tune the reviewer. They don't trigger a re-review or change anything on the PR, so they're purely a signal.

Run It on a PR You Already Reviewed

The only benchmark that tells you anything is a diff whose bugs you already know. Take a pull request you reviewed by hand last month, one where something got caught, and run /code-review against it. Count three things: what it found that you found, what it found that you missed, and what it flagged that isn't real. Ten minutes and one PR gets you a calibration number that no vendor claim can, and it tells you whether to wire up the managed service, keep it local, or set REVIEW.md rules before you trust it on anything that ships. Start there, then decide how much automation to buy.

Browse next: Claude Code Subagents (2026) | Claude Code Agent Teams (2026) | Claude Code Commands (2026) | Claude Code Pricing (2026)

Back to Blog