Splitting Work with Subagents

What subagents solve

Long sessions hit these inefficiencies:

• Search results and log dumps eat the main context’s token budget
• Self-review by the main agent is biased — it tends to agree with its own work
• Independent tasks run sequentially, wasting wall-clock time

Subagents are helper agents in their own context. Only the result returns to the main conversation, keeping context clean. They also run in parallel.

Define a subagent

~/.claude/agents/<agent-name>.md or agents/<agent-name>.md inside a plugin:

---
name: code-reviewer
description: |
  Use after a logical chunk of code is written to review it against
  the original plan and project coding standards.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. Given a recent change set, identify:
1. Bugs and logic errors
2. Security vulnerabilities
3. Deviations from project conventions

Report only high-confidence issues. Skip stylistic nitpicks.

Frontmatter fields

Field	Purpose
name	Identifier used to invoke
description	Auto-invocation conditions (same role as a Skill’s description)
tools	Tools this agent may use (defaults to main’s set)
model	sonnet, opus, haiku (defaults to main’s model)

How to invoke

Auto-invocation

When the description matches the situation, the main agent calls the subagent automatically via the Agent tool.

Explicit

Use the code-reviewer agent to review src/auth/

Parallel

Issue multiple Agent calls in one message and they run concurrently:

In parallel:
- code-reviewer on src/auth/
- security-auditor on dependency vulnerabilities
- test-coverage-analyzer on missing test areas

You get all three reports together.

When to use vs skip

Good fit	Skip
Code reviews (independent perspective)	Next step in main work
Broad search/exploration	Needs user interaction
Security or perf audits	Needs shared progress
Concurrent multi-area analysis	Short, simple questions
Isolating long output from main context	Output drives main decisions immediately

Writing a good description

Auto-invocation depends on description quality.

Good

description: |
  Use after writing or modifying code in a logical chunk
  (a feature, a bugfix, a refactor) to review the change against
  the original plan and project coding standards. Reports
  high-confidence issues only.

Bad

description: Reviews code  # too vague — won't trigger reliably

Restrict tools

The tools field limits what a subagent may use:

tools: Read, Grep, Glob   # read-only — cannot modify code

Review and audit agents typically run safest as read-only.

Patterns

Pattern 1: protect main context

For long search results or logs, delegate to a subagent and only get the summary back.

Use the explore agent to find 'authentication' across src/ and report the locations and patterns in 200 chars.

Pattern 2: independent review

Self-review introduces bias. Ask a subagent for an independent take.

Use the code-reviewer agent to independently assess if my recent migration is safe. Don't agree with my analysis — judge on its own.

Pattern 3: parallel analysis

In parallel:
- agent-A on X
- agent-B on Y
- agent-C on Z

Next steps

• Superpowers — bundles well-designed agents like code-reviewer
• Code Review, PR Review — review-focused agent collections
• Build a Skill — standardize subagent invocation via Skills