Guides

Using Claude Code for code review

Claude Code can be a sharp reviewer, or a firehose of speculative nitpicks. The difference is almost entirely in what you ask for: what to review, which issues matter, and proof for every finding.

Review your local changes

Before committing, point Claude at the diff:

Review my uncommitted changes (git diff HEAD) and the branch as a whole
(git diff main...HEAD). Read the surrounding code and callers, not just the hunks.

Report only issues you have verified by tracing the code. For each:
- severity: critical / high / medium / low
- file:line
- the concrete failure scenario (input → wrong result)
- a specific fix

Priorities: correctness, security, data integrity, broken callers, missing tests.
Skip style nits a linter would catch. If you find nothing significant, say so.

Review a GitHub pull request

With the GitHub CLI installed and logged in:

Review PR #123. Use `gh pr view 123` for the description and
`gh pr diff 123` for the changes. Check out the branch if you need to run
tests (`gh pr checkout 123`). Same reporting rules as above.

Keep a human in the loop for posting. Have Claude draft the comments, then post the ones you agree with yourself, or explicitly ask it to post with gh pr review.

Use a reviewer subagent

A subagent reviews with a fresh context. It didn't write the code, so it has no attachment to it. Save this as .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Independent, skeptical reviewer for a diff. Use proactively after
  finishing a non-trivial change, or when the user asks for a review.
tools: Read, Grep, Glob, Bash
---

You are a senior engineer reviewing code you did not write.
1. Determine the diff (git diff HEAD, else git diff main...HEAD).
2. Read each hunk plus callers, callees and tests. Grep for call sites of changed functions.
3. Verify each suspected issue before reporting. Drop anything you can't substantiate.
Report findings by severity with file:line, scenario and fix, then a one-line verdict:
Ready to merge / Merge after fixes / Needs rework. Do not modify files.

Leaving Edit and Write out of tools keeps the reviewer from "fixing" things silently. More in the subagents guide.

Cutting false positives

• Demand a scenario. "This could be null" isn't a finding. "When user.team is null for invited users, line 42 throws" is.
• Ask it to check for existing guards: types, validation upstream, or a test that already covers the case.
• Cap the output. "At most 10 findings, most severe first" forces prioritization.
• Allow "nothing found". Without explicit permission, reviewers tend to invent issues to seem thorough.

What AI review is good and bad at

Good at	Weaker at
Null and edge-case bugs, missed error handling, stale callers after signature changes, missing authorization checks, obvious injection, untested branches	Product intent ("is this the right feature?"), cross-service assumptions it can't see, performance under real production load

Use it to clear the mechanical issues before a human reviewer spends time, not to replace that reviewer.

Make it a habit

• Add to CLAUDE.md: "After finishing a non-trivial change, run the code-reviewer subagent and address critical and high findings before reporting done."
• Run a safe git workflow so every review is against a clean, single-purpose diff.