AkaadiAkaadi.me
From prompting to agents · 26 August 2026 · 4 min read

One does, one checks: subagents as a reviewer

Give a second, fresh-context agent only the diff and a checklist — it catches what the builder agent is too invested to see.

builder agent diff reviewer agent (fresh context) findings findings list ranked by severity builder addresses findings, revises diff human reads only the final diff not the back-and-forth that produced it
The builder and reviewer never share context — that separation is what makes the review honest.

An agent that just wrote code is a poor judge of that code. It's committed to its own approach, it remembers why each line seemed reasonable at the time, and it's the same context window that missed the bug in the first place. A second agent, with none of that history, reads the diff cold — the same reason a human code reviewer who wasn't in the room for the implementation catches more than the author re-reading their own patch.

What separation of concerns actually buys you

Claude Code's subagents are built for exactly this: each one "runs in [its] own isolated context window with custom system prompts, specific tool access, and independent permissions," and by default starts with "a fresh, isolated context window" rather than your ongoing conversation (Claude Code subagents docs). That isolation is the entire point. A reviewer subagent that inherited the builder's context would inherit its blind spots too — it would "remember" the same justifications and let the same shortcuts slide.

Define the reviewer with a narrow, read-only tool set so it can't fix anything itself, only report:

---
name: code-reviewer
description: Reviews a diff for correctness and security issues. Use after any non-trivial change.
tools: Read, Grep, Glob, Bash
---
You are a strict reviewer. Read the diff and the surrounding code.
List concrete issues, ranked by severity. No compliments. If you
find nothing wrong, say what input would break this.

Restricting tools to read-only isn't just tidiness — it's what keeps the reviewer from "fixing" its own findings and quietly erasing the evidence.

What to give the reviewer

Give it the diff, not the whole conversation. Give it the files the diff touches, so it can check the change against real neighboring code rather than a description of it. Don't give it the builder's reasoning or your own hopes for the outcome — a reviewer primed with "this should be a simple fix" tends to find only simple problems.

Reading its findings

Treat the output as a list to triage, not a verdict to accept wholesale. A reviewer subagent can be wrong, especially about intent it can't see (a "missing" null check that's actually handled two layers up). The useful discipline is: read every finding, dismiss the ones that are wrong with a one-line reason, and route everything else back to the builder agent — or fix it yourself if it's small. In the figure, the human's only job is the box at the bottom: read the final diff, after two agents have already argued about it.

Try it today

  1. Define a code-reviewer subagent with tools: Read, Grep, Glob, Bash and a description ending in "Use proactively after code changes."
  2. After your next agent-authored change, explicitly invoke it: "use the code-reviewer subagent on this diff."
  3. Read its findings before you read the diff yourself — see if it catches something you would have missed cold.
  4. Route any real finding back to the builder agent to fix, rather than fixing it yourself.
  5. Only then read the final diff end to end, as the last check before you commit.

Where this breaks

  • A reviewer subagent without the surrounding files, only the raw diff text, will flag things that are already handled elsewhere — false positives waste your triage time.
  • Two agents can still share a blind spot if the underlying model has a systematic weakness; a second Sonnet-class review of a Sonnet-class bug won't always help. A different model tier for review is worth testing.
  • This adds latency and cost to every change — reserve it for changes that matter, not every one-line fix.

Next: which model to route each of these jobs to, and why it changes the bill.