{"slug": "claude-code-subagents-build-a-reviewer-you-can-verify", "title": "Claude Code subagents: build a reviewer you can verify", "summary": "A walkthrough published for Claude Code users shows how to build a narrow \"boundary-reviewer\" subagent defined in `.claude/agents/boundary-reviewer.md` with only Read, Glob and Grep tools, then test it against a deliberately wrong `discount.py` function whose contract requires `total_after_discount(1200, 25)` to return 900. The reviewer is expected to flag that the return expression computes the discount amount rather than the remaining total, and the walkthrough verifies the finding independently with Python 3, showing `total_after_discount(1, 0)` returns 0 instead of 1 and `total_after_discount(1, 100)` returns 1 instead of 0. The guide argues a subagent should have a one-sentence job and a checkable result, returning a smallest failing input rather than a list of style preferences.", "body_md": "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.\n\nThis 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.\n\n## Give the reviewer a narrow contract\n\nCreate `.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.\n\n```\n---\nname: boundary-reviewer\ndescription: Inspect one small function for input-boundary bugs and return evidence. Use when explicitly asked for a boundary review.\ntools: Read, Glob, Grep\nmodel: inherit\n---\nReview only the supplied files. Do not change files or run commands.\nFind concrete input/output mismatches, not style preferences.\nFor each finding give the file and line, a smallest failing input,\nexpected versus actual output, and a suggested regression test.\nIf evidence is missing, say what you could not verify.\n```\n\nThree 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.\n\n## Give it a bug with an observable answer\n\nSave this deliberately incorrect function as `discount.py`. The contract is to return the amount left to pay, in cents, after applying the discount.\n\n``` python\ndef total_after_discount(cents, percent):\n    if not 0 <= percent <= 100:\n        raise ValueError(\"percent must be between 0 and 100\")\n    return round(cents * percent / 100)\nUse the boundary-reviewer agent to inspect discount.py.\nContract: total_after_discount(1200, 25) must return 900.\nDo not edit files. Return the smallest failing input, expected output,\nactual output, and one regression test.\n```\n\nRun 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.\n\nYou can check this without trusting the reviewer. Run:\n\n``` python\npython3 - <<'CHECK'\nfrom discount import total_after_discount\nprint(total_after_discount(1, 0))    # Actual: 0; expected: 1\nprint(total_after_discount(1, 100))  # Actual: 1; expected: 0\nCHECK\n```\n\nThat 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.\n\n## Keep the handoff short\n\nAsk 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.\n\nIf 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.\n\n## When another subagent will not help\n\nFor 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.\n\nStart 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.\n\n**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.\n\nNext: keep durable project rules in [Claude Code memory](https://somethingbig.ai/work/claude-code-memory), or isolate implementation work with [worktrees](https://somethingbig.ai/work/claude-code-worktrees).\n\n## Sources and version notes\n\nChecked against the current documentation on September 24, 2026. Command availability can vary with your installed version; check `claude --version`.", "url": "https://wpnews.pro/news/claude-code-subagents-build-a-reviewer-you-can-verify", "canonical_source": "https://somethingbig.ai/work/claude-code-subagents", "published_at": "2026-09-24 00:00:00+00:00", "updated_at": "2026-10-22 08:11:08.506360+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Claude Code", "Anthropic", "Python 3", "boundary-reviewer", "discount.py"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/claude-code-subagents-build-a-reviewer-you-can-verify", "markdown": "https://wpnews.pro/news/claude-code-subagents-build-a-reviewer-you-can-verify.md", "text": "https://wpnews.pro/news/claude-code-subagents-build-a-reviewer-you-can-verify.txt", "jsonld": "https://wpnews.pro/news/claude-code-subagents-build-a-reviewer-you-can-verify.jsonld"}}