Claude Code subagents: build a reviewer you can verify

A useful Claude Code subagent has a job you can describe in one sentence and a result you can check. Start with a reviewer that looks for input-boundary bugs in one function. Keep implementation in your main session, and make the reviewer return a failing example instead of a long list of preferences.

This walkthrough builds that reviewer, gives it a deliberately wrong discount function, and checks its conclusion independently. You need Claude Code and Python 3. Use a small scratch project so the exercise stays separate from work you care about.

Give the reviewer a narrow contract

Create .claude/agents/boundary-reviewer.md in your project. The tool list supplies reading and search tools; it does not give this agent a shell or an editing tool. The description explains when to choose it. The body defines the evidence you want back.

---
name: boundary-reviewer
description: Inspect one small function for input-boundary bugs and return evidence. Use when explicitly asked for a boundary review.
tools: Read, Glob, Grep
model: inherit
---
Review only the supplied files. Do not change files or run commands.
Find concrete input/output mismatches, not style preferences.
For each finding give the file and line, a smallest failing input,
expected versus actual output, and a suggested regression test.
If evidence is missing, say what you could not verify.

Three details matter here. “Input-boundary bugs” is narrower than “improve this code.” A smallest failing input makes the result reproducible. “Do not change files” keeps the review separate from deciding which fix to accept. A tool restriction is stronger than merely asking an agent to be careful, but this setup is still a review workflow, not a complete security boundary.

Give it a bug with an observable answer

Save this deliberately incorrect function as discount.py. The contract is to return the amount left to pay, in cents, after applying the discount.

def total_after_discount(cents, percent):
    if not 0 <= percent <= 100:
        raise ValueError("percent must be between 0 and 100")
    return round(cents * percent / 100)

Use the boundary-reviewer agent to inspect discount.py.
Contract: total_after_discount(1200, 25) must return 900.
Do not edit files. Return the smallest failing input, expected output,
actual output, and one regression test.

Run that prompt inside your project. A useful finding points at the return expression: the code calculates the discount amount rather than the remaining total. At a zero-percent discount, a one-cent item should still cost one cent; the current expression returns zero. At a 100-percent discount, it returns the original amount instead of zero.

You can check this without trusting the reviewer. Run:

python3 - <<'CHECK'
from discount import total_after_discount
print(total_after_discount(1, 0))    # Actual: 0; expected: 1
print(total_after_discount(1, 100))  # Actual: 1; expected: 0
CHECK

That pair of endpoints is more useful than a claim that the function “looks wrong.” It tells the implementer which behavior to fix and gives the team a stable test to keep afterward. A corrected implementation also needs a stated rounding policy and input validation; changing one multiplication is not a complete production money-handling library.

Keep the handoff short

Ask the reviewer to return findings in this order: location, input, expected output, actual output, proposed test. Then give your main session only the accepted finding and the test. Do not paste the entire exploratory transcript back into the main conversation; that recreates the context clutter you delegated away.

If the reviewer cannot establish a concrete failure, “no verified bug found” is an acceptable result. It is not proof that the function is correct. Add a second case the reviewer has not seen, and run the tests yourself after the implementation changes.

When another subagent will not help

For a two-line question, delegation can be overhead. For changes that repeatedly depend on decisions in the main conversation, a separate worker may spend its time reconstructing context. Use the reviewer when its inputs can be named precisely: a file, a diff, a contract and a bounded question.

Start with one reviewer before building a team. If its findings are vague, repair the contract or the evidence format. Adding more agents that all give vague feedback does not make the result easier to ship.

Next: keep durable project rules in Claude Code memory, or isolate implementation work with worktrees.

Sources and version notes

Checked against the current documentation on September 24, 2026. Command availability can vary with your installed version; check claude --version.

• Anthropic: custom subagents, tool lists and project scope
• Anthropic: CLI agent selection