Subagents

Subagents are a powerful feature that lets Claude delegate tasks to separate instances. This preserves your main context while getting work done.

What Are Subagents?

When Claude encounters a task that would:

Fill up context with irrelevant details
Require isolated execution
Benefit from parallel processing

It can spawn a subagent - a fresh Claude instance with focused context.

Main Agent (your conversation)
├── Subagent 1: Research task
├── Subagent 2: Code generation
└── Subagent 3: Test writing

Why Use Subagents?

1. Context Preservation

Your main conversation stays clean:

# Without subagents
> research all the authentication libraries and their tradeoffs
[10,000 tokens of research flood your context]
> now implement login
[Claude has less room for implementation]

# With subagents
> research auth libraries using a subagent
[Main agent receives summary only]
> now implement login
[Full context available for implementation]

2. Task Isolation

Subagents have their own context, so failures don’t pollute your conversation:

> use a subagent to experiment with three different implementations
> report back which one is cleanest

3. Parallel Work

Multiple subagents can work simultaneously:

> spawn subagents to:
> - write unit tests for auth module
> - write integration tests for API
> - update documentation

Using Subagents

Automatic Delegation

Claude automatically uses subagents for certain tasks:

> research the best practices for rate limiting in Python

Claude may spawn a subagent to do the research and return a summary.

Explicit Request

Ask Claude to use a subagent:

> use a subagent to refactor the database module
> keep my context clean - just give me the summary when done

Task Agent Pattern

For complex tasks:

> create a task agent to:
> 1. Read all files in the auth/ directory
> 2. Identify security issues
> 3. Propose fixes
> 4. Report findings to me

Best Practices

1. Define Clear Tasks

# Good: Clear scope
> use a subagent to write pytest tests for app/services/user.py
> test all public methods
> include edge cases

# Bad: Vague scope
> use a subagent to help with testing

2. Request Summaries

> spawn a subagent to analyze the codebase architecture
> return a one-paragraph summary, not the full analysis

3. Use for Research

> use a subagent to research:
> - What's the current best practice for Python dependency injection?
> - Compare at least 3 approaches
> - Recommend one for our project

# Main agent gets recommendation without research polluting context

When to Use Subagents

✅ Good Use Cases

Task	Why Subagent
Research	Keeps findings out of main context
Test writing	Isolated, can be parallelized
Refactoring	Complex diffs don’t clutter context
Documentation	Generate docs without filling context
Code review	Analysis stays separate

❌ Poor Use Cases

Task	Why Not
Quick questions	Overhead not worth it
Single-file edits	Main context handles fine
Interactive work	Need back-and-forth
Debugging	Need full context visibility

Built-in Subagent Types

Claude Code includes specialized subagents optimized for different tasks:

Type	Tools	Best For
Explore	Read, Grep, Glob	Fast codebase searches, understanding structure
Plan	Read, Grep, Glob, WebSearch	Research and implementation planning
General	All tools	Complex tasks requiring modification

# Examples
Use Explore to find all authentication-related files
Use Plan to design the database migration strategy
Implement the user authentication feature end-to-end

Custom Subagents

Create specialized agents in .claude/agents/ using Markdown with YAML frontmatter:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: [Read, Grep, Glob]
context: fork  # Optional: isolated context
---

You are a security-focused code reviewer.

Check for: SQL injection, XSS, auth issues, data exposure.

Report: File:line, Severity, Issue, Fix. Never modify files.

Frontmatter options:

name (required): Unique identifier
description (required): Agent purpose
model (optional): Specific Claude model
tools (optional): Allowed tools (defaults to all)
context: fork (optional): Isolated context for research tasks