Claude Code Subagents — Role Splitting via the Task Tool

Claude Code's strength most users adopt last is subagents (the Task tool). Doing everything in one session fills the parent's context fast, and big jobs are bottlenecked on a single thread. Treat subagents as a layer of abstraction — Explorer searches and summarizes, Reviewer only sees the diff — and you handle twice as much work in the same time.

This guide targets Claude Code 1.x. It pushes daily workflow one level higher beyond Claude Code setup and hooks.

TL;DR

1. Parent handles direct edits + builds/tests — short, fast work
2. Explorer subagent — "Where is X in this codebase?" Searches/summarizes. Doesn't pull big results into parent
3. Plan subagent — Returns only a step-by-step plan for big changes
4. Reviewer subagent — Second-opinion review of parent's diff
5. Specialist — Domain-specific subagents like claude-api / security-review

Core principle — context protection + parallelism.

Prerequisites

• Claude Code 1.x installed — Claude Code setup
• Project basics in place: CLAUDE.md + .claude/settings.json
• (Optional) hooks baseline — some parent hooks apply to subagents too

1. Task Tool Calling Model

Inside Claude Code, the Task tool spawns a new agent with a single prompt. The subagent has its own context window — doesn't share messages with parent, and only the final result message returns.

Parent agent
   │
   ├─ Task("Explore", "find token-validation logic in src/auth/; return only function names + file paths")
   │   ↓ (separate context, up to 100k tokens free)
   │   ↑ "validateToken: src/auth/verify.ts:42"  ← parent receives result only
   │
   └─ Task("Reviewer", "scan the last commit's diff for security issues")
       ↓
       ↑ "1 finding: src/api/user.ts:88 — possible SQL injection"

Only one final summary is added to the parent's context. The subagent may have read 200 files; the parent receives a one-liner.

2. Four Core Patterns

2.1 Explorer — Isolate Big Search Results

The most common. Delegate "where is X defined?" questions to a subagent.

"Delegate to an Explorer subagent:
'Find the useAuth hook definition + all usages in src/. Return
- def: file:line
- usages: file:line × all
Limit to a 30-line summary. Don't include code bodies.'"

Parent gets 30 lines. Done directly, it would have eaten 5–20k tokens via grep + multi-file reads.

When to use:

• Just entered a new codebase
• "Where is this feature?"
• "How are we using this library?"
• Dependency impact analysis

Bad use:

• Tiny searches — parent can grep in one line
• Results you need to read in full — parent reading directly is faster

2.2 Plan — Step-by-Step Only for Big Changes

For 5+ file changes / new modules / architecture changes — Plan subagent does research + tradeoff analysis and returns the plan only.

"Delegate to a Plan subagent:
'Return a step-by-step execution plan only.
Requirement: expand seeds from ~7/category to 10.
Constraints: build under 1 min, verify:assets 100%.
Output: category · topic · has-asset · estimated lines table + writing order.
Do not write code.'"

Parent receives the plan; execution happens in the parent or is split among other subagents.

2.3 Reviewer — Second Opinion

A different-context agent reviews parent's diff. Fresh eyes catch what the parent misses.

"Delegate to a Reviewer subagent:
'Review the diff of commit 4d2f0 from a security angle.
Specifically: SQL injection, XSS, hardcoded secrets, race conditions.
Output: N findings + file:line + 1-line note each. Or "clean".'"

Parents miss issues in their own code because they know it. Reviewer sees the same prompt from a different vantage.

2.4 Specialist — Domain-Specific

Subagents for specific areas (claude-api, security-review, code-reviewer, build-validator, etc.) with rich domain knowledge and area-appropriate output formats.

"Delegate to security-review:
'Comprehensive security assessment of the current branch's changes.
Scope: authn / authz / input validation / secrets / sessions / CSRF.'"

Specialists usually have system prompts tuned for their area — higher result quality.

3. Writing the Delegation Prompt

The subagent doesn't see the parent's context. The prompt must be self-contained.

Good Prompt

"Find these patterns in src/:
- `fetch(...)` calls where baseURL is hardcoded
- Result: file:line + 1 code line + inferred baseURL domain
- Limit 30; if more, append '+N more'
- Don't attach code bodies — line only"

Bad Prompts

"Review that fetch thing earlier"   ← no context, vague

"Find all fetch calls"   ← no output format, risk of huge output

Authoring Checklist

• Goal — what do you want to know
• Scope — where (dir/file/range)
• Output format — table / line-level / summary length
• Exclusions — what NOT to return (code bodies, big diffs)
• Stop condition — N findings, then stop
• Unknown case — "if you don't know, say so; no guessing"

4. Parallel Execution — Send Independent Delegations Together

Independent work can go in a single response with multiple Task calls. Claude Code spawns them in parallel.

"Three delegations at once:
1) Explorer — summarize where auth files live
2) Explorer — summarize db migration history
3) Reviewer — security review of last 5 commits

After receiving all three, do an integrated analysis."

Parent gets all three back simultaneously. Time / 3.

Don't parallelize:

• A's output is B's input — sequential
• Two tasks editing the same file — race risk

5. Context Management — Delegate vs Direct

Rule of thumb: if the task would consume 20% of parent's context, consider delegating.

6. Real Scenarios

A. Entering a New Codebase

1. Explorer — folder structure + 5 key modules summary
2. Explorer — README + CLAUDE.md (if any) key takeaways
3. Explorer — last 10 commits summary
↓
4. Parent — synthesize into "one paragraph about this repo"

B. 5+ File Change

1. Plan — change scope + steps + risk table
2. Parent — review plan, proceed step by step
3. After each step, Reviewer — diff review
4. Before final commit, Reviewer — full-change second opinion

C. Debugging

1. Parent — define error log + repro path
2. Explorer — trace related code paths (from stack trace)
3. Parent — hypothesize + attempt fix
4. Parent — verify with build/test

D. Right Before PR Merge

1. Reviewer — diff security/performance review
2. Reviewer — convention consistency with existing code
3. Specialist (security-review) — comprehensive assessment
4. Parent — consolidate findings into PR comments or fixes

7. Combining With Hooks

Claude Code hooks' PreToolUse can intercept Task calls too.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "/bin/bash -lc 'echo \"[delegate] $(jq -r .tool_input.description)\" >> ~/.claude/delegate.log'"
          }
        ]
      }
    ]
  }
}

Logging delegation counts and content lets you review what was delegated vs done directly. Useful for cost tracking and pattern learning.

8. Antipatterns — Misusing Delegation

8.1 Delegating Everything

"Delegate even a 1-file edit"   ← only adds overhead

Subagent calls have token/time cost. Converting a 1-second job into a 30-second delegation is a loss.

8.2 Parent Re-Searches After Delegation

"Explorer summarizes auth file locations → parent then greps the same files itself"

→ Delegation is pointless. Trust the result and move to the next step.

8.3 Asking For Too Much Output

"Bring each file's full code + 5-line explanation + usage bodies"

→ Delegation doesn't reduce parent context. Cap output size in the prompt.

8.4 Parallel Delegation With Dependencies

"A's result feeds B, but both delegated at the same time"

→ B doesn't know A's result. Wrong assumptions ensue. Sequential is correct.

9. Distribution Matrix — Who Does What

Next Steps

• Claude Code setup — parent agent foundation
• Claude Code hooks — log/validate delegations
• Multi-agent workflow — multi-tool/agent integration scenarios
• Agent runner — autonomous runs + subagents combined

References

• Claude Code official — Task tool
• Anthropic — Agent design patterns — general principles

Changelog

• 2026-05-12 — Initial draft (devAlice M3 seed expansion)