10 Powerful Subagent Patterns for Claude Code

Claude Code’s subagent feature lets you run independent tasks in a separate context from your main conversation. This article shares 10 practical patterns you can use today.

What are Subagents?

Subagents are independent worker tasks that run without polluting the main conversation context. They are ideal for long research, large file exploration, or anything that would otherwise burn through your token budget.

Pattern 1: Parallel Research

Investigate multiple directories simultaneously.

Spawn 3 subagents in parallel and investigate:
1. Component list under src/components/
2. Routing structure under src/pages/
3. Utility functions under src/lib/

Only the summaries return to the main context, saving significant tokens.

Pattern 2: Large File Exploration

Delegate huge log file or codebase analysis to a subagent.

Investigate production.log and aggregate the error patterns
and frequency from the past 24 hours. Use a subagent.

Even with tens of thousands of lines, the main context only sees the summary. See also Claude Code Hooks Guide for related techniques.

Pattern 3: Test Execution & Analysis

Run the entire test suite and extract only the failures.

Run npm test and analyze the cause of failures.
Output gets long, so use a subagent and return a summary.

Pattern 4: Parallel Code Review

Review multiple files at once.

Review these 3 files in parallel using separate subagents:
- src/auth/login.ts
- src/auth/logout.ts
- src/auth/refresh.ts

Each review should evaluate Security, Performance, and Readability.

Pattern 5: Documentation Generation

Delegate large generation tasks to subagents.

Investigate every endpoint under src/api/
and generate OpenAPI documentation.

Pattern 6: Migration Planning

Investigate legacy code and create a migration plan.

Investigate the old auth system (src/legacy/auth/) and create
a migration plan to the new system (src/auth/).
List affected files and the work order.

Pattern 7: Dependency Audit

Check all packages in package.json for latest versions and vulnerabilities.

const prompt = `
Investigate package.json dependencies:
1. Check the latest version of each
2. Check for known vulnerabilities
3. Rate update priority as High/Medium/Low

Use a subagent for efficient investigation.
`;

Pattern 8: Multi-file Edit Preparation

Survey impact before a large refactor.

I want to refactor useState to useReducer.
List components that use useState across the project,
and rate each by complexity (state count, update pattern count).

Combined with CLAUDE.md Best Practices, you can lock down refactoring direction.

Pattern 9: Parallel Translation

Subagents shine for multilingual projects.

Translate all docs under docs/en/ into
Japanese, Chinese, and Korean.
Run one subagent per language in parallel.

This pattern is essential for running a 10-language site. See Claude Code i18n Implementation for details.

Pattern 10: Performance Analysis

Delegate profiling result analysis to subagents.

node --prof app.js
node --prof-process isolate-*.log > profile.txt

# Pass to Claude Code
cat profile.txt | claude -p "Identify bottlenecks and propose fixes"

When profile.txt is huge, route it through a subagent to summarize and prioritize.

Tips for Working with Subagents

1. Split tasks clearly

Tell subagents exactly what to do and what to return. Vague instructions lead to vague results.

2. Think in parallel

Independent tasks can run in parallel. Throwing them out and waiting beats sequential execution every time.

3. Limit data returned to main

Have subagents summarize before returning. Pull details only when needed.

Conclusion

• Subagents are a powerful tool for context savings and parallelism
• They shine for research, testing, reviewing, doc generation, and many other tasks
• Clear task definition and parallel thinking double your output

See the official Claude Code docs. Master subagents and unlock Claude Code’s true power.