Claude Code Subagents: When and How to Delegate Work
By Tyler Cyert
Claude Code subagents are lightweight worker agents that the main Claude Code session spawns to handle focused tasks in parallel. Instead of doing everything sequentially in one context, you delegate specific work to subagents that run independently and report back.
Subagents solve two problems at once: they speed up work by running tasks in parallel, and they protect your main context window from getting cluttered with intermediate results. A subagent explores a part of the codebase, runs a research task, or performs an analysis — then returns a concise summary. The raw output stays out of your main conversation.
How Subagents Work
When Claude Code spawns a subagent, it creates a new Claude session with its own context. The subagent:
- Receives a prompt describing its task
- Has access to the same tools (Read, Edit, Bash, etc.)
- Runs independently from the main session
- Returns a result summary when finished
The main session continues working while subagents run in the background. When a subagent finishes, its result gets incorporated into the main session's context.
When to Use Subagents
| Use Case | Why Subagents Help |
|---|---|
| Codebase exploration | Keeps search results out of main context |
| Research tasks | Parallel investigation of multiple angles |
| File analysis | Reading large files without cluttering context |
| Test running | Parallel test execution with summarized results |
| Code review | Multiple reviewers checking different aspects |
When NOT to Use Subagents
- Simple, directed searches. If you know the file or function name, use Grep or Glob directly.
- Sequential tasks. If step B depends on step A's result, subagents add overhead without benefit.
- Quick lookups. Spawning a subagent to read one file is slower than reading it directly.
The rule of thumb: use subagents when the task is broad enough to benefit from parallel exploration, or when you want to keep verbose output out of your main context.
Subagents vs. Agent Teams
Both let you parallelize work, but they operate differently:
| Subagents | Agent Teams | |
|---|---|---|
| Scope | Within a single session | Across multiple sessions |
| Communication | Report back to main agent only | Can coordinate with each other |
| Persistence | Temporary, disappear when done | Can have ongoing tasks |
| Setup | No configuration needed | Requires agent definitions in .claude/agents/ |
| Best for | Quick parallel tasks | Complex multi-role workflows |
Subagents are the lightweight option — no setup, no agent definitions, just spawn and go. Agent teams are the heavyweight option for workflows that need coordination between multiple roles.
Subagent Types
Claude Code supports specialized subagent types:
| Type | Purpose |
|---|---|
| general-purpose | Default. Research, search, multi-step tasks |
| Explore | Fast codebase exploration. Find files, search code, answer questions |
| Plan | Design implementation strategies. Returns step-by-step plans |
The Explore type is optimized for speed — use it for codebase questions like "how do API endpoints work?" or "find all components that use this hook." The Plan type is for architecture decisions before you start coding.
How Subagents Fit Into Your Workflow
Subagents work best as part of a layered approach:
- CLAUDE.md gives every session (and subagent) the project context
- Rules activate when subagents touch matching files
- Permissions control what subagents can access
- Subagents handle the parallel and exploratory work
Subagents inherit the project's configuration. They read CLAUDE.md, follow rules, and respect permissions — they are not unsupervised.
Practical Patterns
Parallel Code Review
Spawn three subagents to review different aspects of a changeset simultaneously: one checks security, one checks performance, one checks test coverage. Each returns a focused report.
Codebase Research
Before a refactor, spawn subagents to explore different parts of the codebase in parallel — one maps the data flow, one identifies all callers of a function, one checks for similar patterns elsewhere.
Investigation and Fix
Spawn an Explore subagent to investigate a bug while you continue working on something else. When it reports back with the root cause, you have the context to make the fix.
Building Subagent-Ready Projects with DotBox
Subagents work out of the box — they do not need special configuration. But they benefit from a well-structured project: clear CLAUDE.md, focused rules, and organized working directories that subagents can navigate efficiently. DotBox helps you define the custom subagents themselves — draw each one with its role, tools and model, and the setup prompt writes them to .claude/agents/ along with a CLAUDE.md that tells the main session which subagent handles what.