Using Agents & Subagents

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.