Multi-Agent Workflows

Claude Code can spawn subagents — independent Claude instances that work on focused tasks in parallel. This multi-agent system lets Claude break large requests into smaller pieces, execute them concurrently, and merge the results.

The Task Tool

The Task tool is Claude's mechanism for delegating work. When a request involves multiple independent operations, Claude creates subagents using the Task tool. Each subagent gets its own context window and works on a specific piece of the problem.

Main Agent
  |-- Task: Update authentication module
  |-- Task: Refactor database queries
  |-- Task: Add API endpoint tests

Subagent Types

Claude selects the appropriate subagent type based on the work being done:

When Claude Spawns Subagents

Claude uses subagents when it determines that:

• The request involves multiple independent files that can be edited in parallel.
• Different skill sets are needed (e.g., one agent reads code while another writes tests).
• The task benefits from isolated context so each agent focuses on its own scope.
• A divide-and-conquer approach will complete the work faster and more reliably.

Parallel Task Execution

Subagents run concurrently. If you ask Claude to add error handling to five different modules, it can spawn five agents that each handle one module at the same time, rather than processing them sequentially.

User: "Add error handling to all API route handlers"

Main Agent spawns:
  [Agent 1] --> routes/users.ts    (parallel)
  [Agent 2] --> routes/posts.ts    (parallel)
  [Agent 3] --> routes/comments.ts (parallel)
  [Agent 4] --> routes/auth.ts     (parallel)

The Swarm Pattern

For very large tasks, Claude can use a swarm pattern where a planning agent first analyzes the codebase, then delegates specific changes to multiple worker agents. The planner coordinates results and handles any conflicts.

1. Planner agent reads the codebase and creates a task list.
2. Worker agents each take one task and execute it independently.
3. Main agent reviews all changes and resolves any overlaps.

Best Practices

• Write clear requests. The more specific your prompt, the better Claude divides work.
• Trust the orchestration. Claude decides when subagents help — you do not need to ask.
• Review merged results. After parallel edits, verify that changes are consistent.
• Use for large refactors. Multi-agent shines when touching many files with a pattern.
• Keep files independent. Parallel editing works best when files do not depend on each other.

Multi-agent workflows are what make Claude Code effective at scale. A single prompt can orchestrate dozens of coordinated changes across your entire project.