Using Agents & Subagents
Orchestrate parallel work with Claude Code's agent system — dispatch subagents for independent tasks and synthesize results.
What Are Subagents?
Claude Code can spawn subagent instances to work on independent tasks in parallel. The main agent orchestrates high-level decisions; subagents execute focused subtasks. This dramatically speeds up complex work.
When to Use Subagents
Use subagents when tasks are:
- Independent — don't depend on each other's output
- Parallel — can safely run at the same time
- Focused — small enough to complete in one context window
Examples:
- Audit security, performance, and code style simultaneously
- Write unit tests for three different modules in parallel
- Research three competing libraries at once
Dispatching a Subagent
Spawn a subagent to: audit src/lib/auth.ts for security issues.
Report back with a ranked list of findings.
The subagent receives a fresh context, executes the task, and returns results to the main agent.
Fan-Out Pattern
Send the same task to multiple specialized subagents:
Dispatch three subagents in parallel:
1. Security reviewer — analyze the API routes for vulnerabilities
2. Performance reviewer — identify N+1 queries and slow operations
3. Type safety reviewer — find any use of 'any' or missing types
Each agent focuses on its specialty. You get three expert analyses simultaneously.
Synthesizing Results
After subagents complete, ask the main agent to synthesize:
Combine the three review reports into a prioritized action list,
grouping related issues and ordering by severity.
Context Isolation
Subagents don't share context with the main agent by default. This is a feature — it prevents one agent's confusion from polluting another's work. Be explicit about what context a subagent needs:
Spawn a subagent with this context: [paste relevant background].
Task: write a comprehensive test suite for the payment module.
Cost Awareness
Each subagent uses tokens. For expensive operations, estimate cost first:
Before spawning, estimate how many tokens this audit will use and
whether it's worth doing as a subagent vs. sequential analysis.