Asking the main Claude Code session to review its own work tends to produce a polite summary of what it just wrote. A separate reviewer with its own context and a fixed method gives you findings you can act on, with the file and line for each one.
When to use the Code Reviewer agent
- Before you merge a branch or open a pull request
- After Claude Code finishes a multi-file change and you want a second opinion
- Before a release or a handoff to another developer
- When a change touches authentication, payments, migrations or anything shared
What is in the agent file
| Name | code-reviewer |
|---|---|
| Tools | Read, Grep, Glob, Bash. No write or edit tools, so it reports and does not change files. |
| Model | sonnet, up to 35 turns per task |
| Kit | Engineer kit, 100 lines |
How it works. Beyond its role statement, the file sets out 5 rules it follows: Three passes; Severity rubric; Checklist; Evidence standard; Run what is cheap.
What it reports. Every run ends in the same structure: Change summary, Requirement coverage, Blocking, Should fix / Consider / Note, Validation run, Verdict.
Excerpt from the agent file
The settings and opening instructions, as they appear in .claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Reviews a diff for correctness, requirement coverage, security and maintainability, returning severity-ranked findings with file:line evidence and concrete failure scenarios. Use PROACTIVELY before merge, release or handoff, and after significant implementation work.
model: sonnet
maxTurns: 35
tools: Read, Grep, Glob, Bash
---
You are a Code Reviewer. Review the **diff**, not the final files. The question is always "what did this change do?", never "is this file good?" — and a file that reads fine can still contain the change that broke something.
## Three passes
Reviewing linearly finds typos and misses design problems. Each pass asks one question.
1. **Intent.** What is this trying to achieve, and does the diff achieve it? Read the requirement first. If you cannot state the intent in one sentence, that is your first finding.
2. **Correctness.** Line by line, with the surrounding code open. Most real bugs live at the **boundary between changed and unchanged code** — a new caller violating an old invariant, a modified function whose other call sites were not updated.
3. **Consequence.** What else does this touch? Who else calls this? What happens on the second request, with an empty list, with a slow network, with two users at once?The full file continues with the rules above and the exact report format. It is included in the Agentsforce kit.
Example requests
Name the agent to be sure Claude uses it, or describe the task and let its description trigger it:
- "Use the code-reviewer agent to review my uncommitted changes before I commit."
- "Review the diff between main and this branch. Focus on the new checkout endpoint."
- "Use code-reviewer on the last three commits and tell me what blocks a merge."
- "Review this migration and the code that depends on it for rollout problems."
When to use a different agent
| If you need | Use instead |
|---|---|
| Fixing the problems it finds | It reports and does not edit; hand the findings to the main session or the debugging-specialist |
| Visual and accessibility review of a rendered page | Use ui-reviewer, which checks the page in a browser |
| Big design questions about whether a subsystem fits | Use architecture-reviewer |
Works well with
- Debugging Specialist: finds why a bug happens before changing code
- TDD Engineer: writes a failing test, watches it fail for the expected reason, writes the smallest code that passes, then refactors, one small slice at a time
- Tech Lead: plans work instead of writing it
Related playbooks in the kit, which Claude loads when the task calls for them: diff-review, threat-modeling, regression-test-design.
How to get it
- Write your own: the free Subagent Generator drafts a starter code reviewer file you can edit and save in
.claude/agents/. - Use the tested version: Agentsforce includes this agent with 54 other specialists and 89 playbooks for a one-time $49, installed with one command.
Frequently asked questions
Can a Claude Code subagent review code without changing it?
Yes. Give it only read and search tools. This reviewer gets Read, Grep, Glob and Bash; Bash is there so it can run git diff, tests and linters, and its instructions tell it to report rather than edit.
How is this different from asking Claude to review my code?
It runs in its own context, so it is not grading work it just wrote, and it follows a fixed method: three passes, a four-level severity scale and an evidence rule that every finding names a file, a line and a concrete failure scenario.
Does it review the whole repository?
No. It reviews the diff, meaning what changed. Reviewing whole files finds style issues and misses the change that broke an unchanged caller, so it reads the surrounding code only to judge the change.