Subagents

Subagents are Claude’s ability to fork parallel investigation threads. Each thread runs independently, explores its assigned area, and reports back to the main conversation. Think of it as dispatching junior engineers to investigate different parts of a system simultaneously.

When to use subagents

Use subagents when you have two or more independent areas to investigate. The key word is independent — if investigation B depends on the results of investigation A, subagents will not help.

Good candidates:

• Exploring an unfamiliar codebase (map services, data layer, and API surface in parallel)
• Bug triage (check recent changes, search for error patterns, trace request flow simultaneously)
• Architecture review (analyze each service boundary independently)
• Pre-migration research (inventory all usages of a deprecated API across multiple modules)

Built-in subagent types

Claude Code includes three built-in subagents that Claude uses automatically:

Claude selects the right type based on the task. You can also create custom subagents with specific roles — see Custom Agents.

Managing subagents

Run /agents to view, create, edit, and delete subagents interactively. From the command line, claude agents lists all configured subagents grouped by source.

The parallel investigation pattern

Before (sequential, slow):

Look at the auth module.
→ [wait for response]
Now look at the database layer.
→ [wait for response]
Now look at the API routes.
→ [wait for response]
OK, now synthesize all three.

Three round trips. Each one takes 15-60 seconds. You are sitting idle between each step.

After (parallel, fast):

Use subagents to investigate in parallel:
1. The auth module in src/auth/ — how are tokens validated and refreshed?
2. The database layer in src/db/ — what queries touch the sessions table?
3. The API routes in src/routes/ — which endpoints require authentication?
Synthesize what you learn from all three into a summary of how auth works
end-to-end.

One round trip. All three investigations happen simultaneously. Claude synthesizes the results automatically.

Strategy templates

Bug investigation

Investigate this bug using parallel subagents:
- Subagent 1: Check git log for recent changes to [relevant modules]
- Subagent 2: Search the codebase for error patterns matching "[error message]"
- Subagent 3: Trace the request flow from [endpoint] through all middleware
- Subagent 4: Check configuration files and environment for [relevant settings]
Correlate the findings and propose a root cause.

Architecture analysis

Analyze this system using subagents:
- Subagent 1: Map all external API calls and third-party dependencies
- Subagent 2: Analyze the database schema, indexes, and query patterns
- Subagent 3: Map service boundaries and inter-service communication
- Subagent 4: Review error handling, retry logic, and resilience patterns
Produce a system overview with a focus on failure modes.

Migration impact assessment

We are replacing [old library] with [new library]. Use subagents to:
- Subagent 1: Find every import/require of [old library] and list the files
- Subagent 2: Identify all API calls to [old library] and their signatures
- Subagent 3: Check test files for mocks or stubs of [old library]
- Subagent 4: Search for configuration that references [old library]
Produce a migration checklist ordered by risk.

The delegation pattern

For large repetitive tasks, delegate sub-work to subagents:

I need to add structured logging to all API endpoints. Use subagents to:
1. Find all route handler files in src/routes/
2. For each file, add structured logging at entry, exit, and error points
3. Use the logging pattern in @src/routes/users.ts as the template
4. After making changes, verify each file still has valid syntax

When NOT to use subagents

• Simple, targeted questions: “What does this function do?” — just ask directly.
• Sequential dependencies: When step 2 depends on step 1, subagents add overhead without benefit.
• Deep single-file analysis: You want Claude’s full attention on one thing, not spread across many.
• Small codebases: If the entire project fits in context easily, the parallelism overhead is not worth it.

Tips

• Name each subagent’s task clearly so you can trace findings back to their source.
• Keep subagent tasks roughly equal in scope — one massive task and three tiny ones defeats the purpose.
• Ask Claude to synthesize results after all subagents complete, not just list raw findings.
• Combine with worktrees for fully isolated parallel work on separate branches.