The Code-Review Agent

Claude Code Agents: Fundamentals

Chapter 6 · The Code-Review Agent

A code-review agent examines code and reports what's wrong with it — it deliberately does not fix anything itself. Keeping "finding a problem" and "fixing a problem" as two separate steps, done by two different agents, is a deliberate design choice this chapter explains in full, along with how to structure what a review agent actually reports back.

Designing a Code-Review Agent's Definition

"Use this agent after implementation is finished, before merging, to check for bugs, security issues, and style problems. Do not use it to make the fix — it reports findings only." Tool access is deliberately restricted to Read, Grep, and Glob — no Edit or Write at all. This is Chapter 1's isolation principle applied for a specific reason here: a reviewer that structurally cannot modify code keeps its findings honest and separate from the act of fixing, rather than quietly "fixing" something it noticed while reviewing and never actually reporting it as a finding. Model choice should favor the most capable model available — catching a genuinely subtle bug requires real judgment, not just pattern-matching against common mistakes.

Structuring Findings: Why Format Matters

An unstructured wall of prose — "I noticed a few issues, one around the loop and something with error handling" — is hard to act on and easy to skim past. A well-designed review agent reports each finding in a consistent shape: the specific file and line, a one-sentence summary of the problem, and a concrete failure scenario — the specific input or state that would actually trigger it, not a vague "this could be a problem in some cases."

Severity Levels

Findings should be ranked most-severe first, and it's worth distinguishing confirmed issues (verified as a real, reproducible problem) from plausible ones (looks likely but not fully certain without further testing). Treating every finding — a genuine security hole and a minor naming inconsistency — with identical urgency makes the truly serious ones harder to spot at a glance.

// Example structured finding
file: src/orders/discount.ts
line: 47
summary: Off-by-one error excludes the last item from the discount total
failure_scenario: A cart with 3 items only applies the discount to the first 2 — the loop condition uses `< items.length - 1` instead of `< items.length`
verdict: CONFIRMED

Writing the System Prompt for a Review Agent

A review agent's system prompt should instruct it to surface genuine, concrete issues rather than padding out a list with stylistic nitpicks dressed up as bugs, to always state a real failure scenario per finding rather than a vague concern, to rank findings by severity, and — importantly — to treat an empty findings list as a perfectly valid, good outcome, not something to stretch for content to avoid appearing unhelpful.

Aspect	Coding Agent (Ch.5)	Code-Review Agent
Modifies code?	Yes	No — read-only, findings only
Typical tools	Read, Edit, Write, Grep, Bash	Read, Grep, Glob only
Output	A completed code change	A ranked, structured list of findings

Give it the actual diff, not the whole file

Reviewing an entire file when only a small section actually changed wastes the agent's attention on code nobody asked it to look at, and risks findings about pre-existing code unrelated to the current change. Provide the actual diff (or clearly state what changed) so the review stays focused on what's actually new.

Zero findings isn't proof the code is bug-free

A review agent reporting no issues means it didn't find anything within its own read of the code — not that the code has been proven correct. A review is a filter that catches what it's able to catch, not an exhaustive correctness guarantee; genuinely subtle bugs, especially ones depending on runtime data or external state, can still slip past any review, human or agent.

Hands-On Exercises

Exercise 1

Explain why a code-review agent is deliberately denied Edit access, even though it would be technically capable of fixing many of the issues it finds.

📄 View solution

Exercise 2

A review agent reports the finding "the error handling in this file could probably be better." Explain what's missing from this finding, and rewrite it in this chapter's own structured format with a concrete failure scenario.

📄 View solution

Exercise 3

A review agent returns zero findings on a piece of code, and the developer concludes the code is definitely bug-free. Using this chapter's own warning box, explain what's wrong with that conclusion.

📄 View solution

Chapter 6 Quick Reference

A code-review agent finds problems — it never fixes them itself, kept honest by deliberately having no Edit/Write access
A good finding names the file/line, a summary, and a concrete failure scenario — not a vague concern
Rank findings by severity, and distinguish confirmed issues from merely plausible ones
An empty findings list is a valid, good outcome — don't pad findings out to seem thorough
Give it the actual diff, not the whole file, to keep the review focused
Zero findings means nothing was caught — not that the code is proven bug-free