Code review with Claude Code: findings you can trust

October 22, 2026 · 3 min read

Ask Claude Code to "review this PR" and you'll get a review. Often it's twenty bullet points, three of them real, and a closing paragraph saying the code looks great. The problem isn't the model. It's the request.

A good human reviewer follows a routine: find the actual change, read the context, look for the expensive bugs first, and only speak up about what they can back up. You can give Claude Code the same routine. Here's the one we use.

Why AI reviews get noisy

Wrong scope. It reviews the whole file, or only the last commit, instead of the branch against its base.
No context. It judges a changed function without opening its callers, so it flags "bugs" that a guard two lines up already prevents.
No priorities. Naming nits sit next to a missing permission check with the same weight.
No verification. Plausible-sounding findings go straight into the report. Nobody tried to prove them wrong.

Each of these has a direct fix.

1. Review the right diff

Tell Claude exactly what "the change" is, in priority order:

A PR number in the request: gh pr diff 123 plus gh pr view 123 for the title and description.
A branch or range: git diff main...feature.
Otherwise the current branch against its merge base with origin/main, plus uncommitted changes.

Read the PR description too. A change that doesn't do what its description says is a finding on its own.

2. Load the team's rules

If your repo has a REVIEW.md (or review rules in CLAUDE.md), the review should read it first, and those rules should beat the model's defaults. When a finding breaks a team rule, quoting the rule ends the argument before it starts.

3. Understand before judging

For every changed function whose signature, return value or error behavior changed, open its callers. Don't review a hunk you haven't understood in context. On a big diff, group files by area and review the risky groups first: data writes, auth, money, concurrency, migrations and public APIs.

4. Look for expensive bugs first

Correctness: inverted conditions, off-by-one, missing await, unhandled null, broken error paths.
Data and security: injection, missing auth checks, secrets in logs, destructive migrations with no way back.
Contracts: changed behavior that existing callers don't expect. Search for every caller before claiming this.
Concurrency and resources: races, missing transactions, leaked connections, N+1 queries in hot paths.
Tests: changed behavior with no test, or tests that can't fail.

Formatting and taste come last, or not at all. Linters exist for that.

5. Try to prove every finding wrong

This is the step that matters most. Before a finding goes in the report, Claude should:

write down a concrete input or sequence of calls that triggers it (if it can't, it's not a finding);
check whether validation, types or a framework default upstream already prevents it;
run a quick test or one-line script when that's cheap.

Findings that survive are reported as confirmed. Findings it couldn't fully confirm are labeled "plausible" instead of being dressed up as facts.

6. Report verdict first

Start with one line: Ready to merge, Merge after fixes or Needs rework. Then findings, most severe first, each with a location, the failure path and a fix:

### 1. [High] Refund can be issued twice on retry
src/billing/refund.ts:42
issueRefund writes the refund before marking the order refunded, and the
retry handler calls it again on timeout.
Failure path: payment API responds after 31s → retry fires → second refund.
Fix: wrap both writes in one transaction, or check order.refundedAt first.
Confirmed (traced the retry path in src/jobs/retry.ts:18).

No praise, no summary of the diff, no list of what was checked. If there are no findings, say so and name the riskiest part that was checked and why it's fine.

Make it a skill, not a prompt

You can paste this routine into a prompt every time, but it works much better as a skill: Claude loads it automatically whenever you say "review", every reviewer on the team gets the same standard, and you improve it in one place. If you haven't written a skill before, start with our guide on how to write a Claude Code skill.

Or skip the writing: the PR Review Pack below ships this exact workflow as a ready skill, plus skills for missing tests, PR descriptions, team review rules and replying to reviewers.