Subagents and role separation (a detour: /review)
So far the protagonist /debug has, in the current working environment, handled everything from investigation to fixing with a single agent. But as a change grows larger, a different stance is needed. This chapter supplements running multiple agents in parallel, which does not come up with /debug, via a detour into /review.
Keep the one who builds separate from the one who evaluates
The harness has a principle: "do not let the agent that implemented something evaluate its own implementation." This is Generator-Evaluator separation.
The reason is simple: you tend to rate what you wrote yourself as "pretty good" (self-evaluation bias). To avoid this bias, subagents are split by role.
- Generator (the one who builds):
implementer(implementation),refactorer(refactoring) - Evaluator (the one who evaluates):
code-reviewer,architect,test-strategist,infra-reviewer - Both (investigate and fix):
debugger
The debugger subagent, which pairs with /debug, sits in "both" because investigation and fixing are inseparable. Review, on the other hand, sticks strictly to the evaluator role.
Detour: review a large change in parallel from three perspectives
When a change becomes wide-ranging (many files, crossing multiple domains), a single reviewer misses things. So with a configuration called multi-perspective-review, you run three perspectives in parallel. This is a team definition placed under ~/.claude/teams/ (🔧 author's own), describing in a single file which subagents to combine and how. The mechanism that spawns subagents itself is Claude Code standard (📦).
The three review from independent perspectives and integrate their results. Fine implementation bugs go to code-reviewer, design distortions to architect, missing tests to test-strategist—by changing the angle of view, they catch problems a single perspective could not pick up.
Another advantage of a subagent is that it runs in a separate context. If you hand an investigation or review that loads a large amount of code to a subagent, your main conversation does not get filled with that information. The choice between /debug (immediate, in the current environment) and the debugger subagent (in an isolated environment, taking its time) follows the same idea.
Furthermore, in this environment, save-subagent-result.sh (the PostToolUse hook we saw in How hooks work) saves a subagent's final report to disk the moment it completes. Even if the session goes down from a rate limit or a crash, a subagent's long investigation result is not lost.
Contrast with /debug
/debug (protagonist) | /review + multi-perspective (detour) | |
|---|---|---|
| Number of agents | 1 (current environment) | 3 spawned in parallel |
| Role | investigate and fix (both) | stick to evaluation (read-only) |
| Suited situation | local bug fixing | wide-ranging, multi-domain changes |
| Aim | pin down the true cause and fix it | reduce oversights with multiple perspectives |
The single line of /debug and the parallel stance of /review. Both are expressions of the harness's attitude of "not taking a single agent's judgment at face value." /debug doubts itself through iteration; /review sets up a different perspective to doubt. The approach differs, but the aim is the same.
The key points:
- To avoid self-evaluation bias, subagents split into Generator (builds) and Evaluator (evaluates)
- A large change is reviewed by
multi-perspective-reviewin parallel from three perspectives (code-reviewer / architect / test-strategist) - Subagents have, in addition to role separation, the advantage of context isolation
/debug's iteration and/review's multiple perspectives are both stances for not taking a single judgment at face value
Next, in Guide and Sensor pairs, we look at a typical case of the cross-classification via a detour into /grill-me.