A common way to set up Claude Code review is a single subagent with one prompt: "review this diff for bugs, missing tests, and security issues." One report at the end. It works, sort of — but the reports tend to be shallow in a specific, predictable way: whichever concern comes first in the prompt gets the most attention, and whatever comes last gets a token sentence or nothing at all.
That's not a model-quality problem. It's a structural one.
Why one agent doing three jobs underperforms
A single subagent has one context window and one output budget for the task. Ask it to reason about logic correctness, test coverage, and security in the same pass, and it has to allocate attention across three different mental models at once: "does this code do what it claims," "what inputs are missing coverage," and "how could this be abused." Those aren't the same lens. A reviewer scanning for logic bugs is pattern-matching against intent. A security auditor is pattern-matching against attacker behavior. Forcing one pass to do both means it either picks a dominant lens and treats the others as an afterthought, or it spreads evenly and goes shallow everywhere.
In practice, that tends to show up as: the review agent flags a naming inconsistency and an off-by-one, then adds a bullet like "consider adding tests" with no specifics, and rarely surfaces anything security-related unless the diff is obviously about auth.
Splitting the concern, not just the prompt
The fix isn't a better prompt — it's three separate subagents, each with a narrow job and only the tool access it actually needs:
- code-reviewer: read-only access to the diff and surrounding files. Its entire prompt is about correctness, security, and design issues, severity-ranked.
- test-writer: read access, plus write access scoped to test files. Its job is to find code paths the diff touches that have no coverage and write deterministic tests in the framework already in the repo.
- security-auditor: read-only, but with permission to grep across the whole repo, not just the diff. Injection risks, unsafe deserialization, and secrets-in-code usually require seeing how a value flows outside the immediate change — a diff-only view misses that.
Each one produces a short, focused report instead of one long generic one. Dispatched together (in parallel, since they don't depend on each other), the total review reads like three specialists each did a pass, because that's literally what happened.
The difference isn't that any individual subagent is "smarter" than the combined one — it's that scoping the tool access and the prompt to a single concern removes the tradeoff between depth and breadth. The security-auditor isn't competing for attention with "is this variable named well." It only has one job, so it does that job instead of a third of three jobs.
The part that's easy to get wrong
The temptation is to give every subagent full repo access "just in case." Don't — it slows them down and, worse, it re-introduces the same attention dilution you were trying to fix, just at the tool-selection level instead of the reasoning level. Least-privilege tool access isn't just a security nicety here, it's what keeps each subagent's job narrow enough to actually be good at it.
This reviewer/test-writer/security-auditor split, plus three more subagents (debugger, doc-writer, refactor-specialist), 12 slash commands, 5 hooks, a git-aware statusline, and a CLAUDE.md template are packaged into the Claude Code Power Pack (copy-paste into .claude/, €29): https://vincentdu2a.gumroad.com/l/bqndfi. It's an independent, unofficial project — not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.
(Written with AI assistance.)
Top comments (1)
The output budget framing explains something prompt tweaking never fixed for me: a single reviewer does not just attention-starve the last concern in the prompt, it caps the total findings it will report before it starts summarizing. Three agents means three budgets. The tool scoping is doing quiet work too - giving the security pass repo-wide grep while the correctness pass stays diff-scoped matches how the failure classes actually distribute, since injection and secrets problems live in how values flow outside the change. The cost I have seen with fan-out is on the merge side: three specialists produce overlapping findings with different severity labels, and plausible-but-wrong findings survive because no one is assigned to kill them. Do you run any synthesis step that dedupes and adversarially re-checks findings before they reach you, or do you read all three reports raw? In my experience the verify pass changes the signal-to-noise more than the split itself.