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.
What we checked: In Claude Code 2.1.281, one read-only CLI run using this agent definition identified the reversed discount formula and both one-cent endpoint failures. We independently evaluated those inputs in Python. We selected the reviewer with --agent; this checks the configured reviewer, not automatic delegation or a general bug-finding success rate.
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.