Build a Claude Code subagent that reviews your diff with fresh eyes
A reviewer that never saw the code being written catches different things. Here's the file, the invocation and the over-reporting trap.
An agent that just wrote a change is a poor reviewer of it. It remembers why each decision was made, so it reads its own code charitably. A reviewer that starts with nothing but the diff and a checklist has no such bias. Claude Code subagents are a convenient way to get one.
The file
A subagent is a Markdown file with YAML frontmatter, stored in .claude/agents/ for one project or ~/.claude/agents/ for all of them. Only two fields are required: name and description. This example is from Anthropic’s best-practices guide
:
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling
Provide specific line references and suggested fixes.
Two details matter here. The tools line is an allowlist: this reviewer can read and search the code and run commands, but it can’t edit anything. A reviewer that can’t change files can’t “fix” the thing it’s meant to judge. And description isn’t documentation. The sub-agents docs
say Claude uses it to decide when to delegate, so write it as a trigger: what the agent does and when to use it.
What it can and can’t see
This is the whole point. A subagent starts in its own context window with its system prompt, the task message Claude hands it, your CLAUDE.md files, a git status snapshot and any skills you preloaded. It does not get the conversation history or the files Claude already read.
So the reviewer reads the diff cold. It can’t see the arguments you had in the main session, which is what you want.
Calling it
Three ways, from the docs. Ask in plain language and let Claude choose:
Use the security-reviewer subagent to check the auth changes
Force it with an @-mention:
@agent-security-reviewer look at the auth changes
Or make a whole session run as that agent: claude --agent security-reviewer.
A review prompt that doesn’t go overboard
The best-practices guide suggests having a subagent review the diff against a plan, and gives an example prompt. Adapt it:
Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.
The guide also warns about a trap. A reviewer told to find gaps will usually find some, even when the work is sound, because that’s the job it was given. Chase every finding and you get extra abstraction layers, defensive code and tests for cases that can’t happen. Tell the reviewer to flag only gaps that affect correctness or the stated requirements, and treat the rest as optional.
Where it fits with the rest
This pairs with the verification gate from our Stop hook guide . The hook proves the tests pass. The reviewer asks whether the right things were tested. They answer different questions. If you run reviewers in parallel with implementation work, give edit-capable subagents their own worktrees, as covered in our worktrees how-to .
A caveat from the docs: each subagent invocation starts a new instance, so a reviewer won’t remember its earlier review unless you ask Claude to resume it.
Next step: create the file, run it against your last merged pull request, and see whether it finds anything the human reviewers missed.