Here is a scenario I hit constantly. I need Claude to refactor a feature that touches 15 files across three packages. Before Claude can make any changes, it needs to understand the current implementation — how the components connect, where the state lives, what the API contract looks like.
So Claude starts reading. File after file. The component, the hook, the TRPC router, the Zod schema, the database types, the test files, the related utilities. By the time Claude has a mental model of the feature, it has consumed 50-60k tokens of context — and it has not written a single line of code yet.
Now it starts implementing. But the context window is half full of research artifacts. Claude's attention is split between the research it already did and the code it is trying to write. Quality drops. It starts making mistakes it would not make in a clean session.
This is the problem subagents solve.
What a subagent is
A subagent runs in its own isolated context window. It does its work — reads files, runs searches, analyzes code — and then returns a summary to the main conversation. The main context only receives the summary, not all the raw file reads.
Think of it like sending an intern to research a topic. The intern reads 30 documents and comes back with a one-page brief. You get the insight without the overhead.
In Claude Code, you can trigger subagent behavior by asking Claude to dispatch a task. Claude will spawn a separate agent context, run the research there, and bring back the results.
When to use subagents
Subagents shine in four scenarios.
Research tasks
Explore the codebase to understand how a feature works. Read all the files, trace the data flow, map the dependencies. Return a summary of the architecture.
Code review
Read all changed files in a PR. Analyze the diff for logic errors, security issues, and performance problems. Return a list of findings with confidence levels.
Testing
Run a test suite, analyze the results, identify patterns in failures. Return a summary of what passed, what failed, and likely root causes.
Documentation
Read the current code and existing docs. Identify what is outdated. Return a list of changes needed with specific file references.
The common thread: these are all tasks where a lot of information goes in, but a small, focused summary comes out. That asymmetry is where subagents save you the most context.
When NOT to use subagents
Subagents are not free. There is overhead in spawning them and latency in waiting for results. Do not use them when:
- The task involves a single file or a small, localized change
- You need the full context in the main conversation for follow-up questions
- The subagent's summary would lose critical detail that you need for implementation
- The task is simple enough that the research and implementation can happen together
If you need to read 3 files to fix a bug, just read them in the main session. The overhead of spawning a subagent is not worth it for small tasks. Subagents pay off when the research-to-output ratio is high — 30 files in, 1 summary out.
Specialized agent definitions
Generic subagents are useful, but specialized agents are powerful. Instead of telling Claude "use a subagent to research this," you define purpose-built agents with specific roles, constraints, and even model tiers.
---
name: code-reviewer
model: sonnet
tools: [Read, Glob, Grep, Bash]
---
Review changed files. Only report issues with >80% confidence.
Focus on:
- Logic errors that would cause bugs
- Security issues (auth bypasses, injection, data leaks)
- Performance problems (N+1 queries, missing indexes, memory leaks)
Skip:
- Style preferences
- Naming opinions
- Formatting issues
Output format:
- List each issue with file path, line reference, and severity
- Include a confidence percentage for each finding
- End with a summary: total issues found, highest severity
Notice three things about this definition. First, it restricts the tools — the reviewer can read and search, but it cannot edit files. This prevents a review agent from "helpfully" fixing things it finds. Second, it sets a confidence threshold — only report issues above 80% confidence. This filters out the noise of uncertain warnings. Third, it specifies the output format — structured findings that are easy to act on.
The most mature agent setups I have seen run 25+ specialized agents — each one narrowly scoped. A security reviewer that only looks for OWASP Top 10 vulnerabilities. A doc updater on Haiku (cheapest model) that generates documentation. Language-specific reviewers for Go, Python, Rust, and Kotlin, each enforcing idiomatic patterns for that language. The pattern is always the same: restrict tools, pick the right model tier, and define the output format. You do not need 25 agents. But you probably need 3-5: a planner, a reviewer, a build fixer, and maybe a research agent. Start there.
The model tier matters too. Research and review do not need Opus-level reasoning — Sonnet handles them well at a fraction of the cost. Reserve Opus for planning and architecture decisions where depth of reasoning actually changes the outcome.
Iterative retrieval
Subagents do not always find what they need on the first search. Codebases use inconsistent naming. The file you are looking for might be called auth.ts, authentication.ts, session.ts, or middleware.ts depending on who wrote it.
The iterative retrieval pattern handles this by running multiple search cycles.
Dispatch
Start with a broad search. Grep for related terms, glob for likely file patterns. Cast a wide net.
Evaluate
Score the results for relevance. Did the search find the actual implementation, or just references and imports? Are there files that look relevant but were not in the initial results?
Refine
Update the search criteria based on what the first pass revealed. The first cycle often uncovers codebase-specific terminology — function names, module names, patterns — that enable better second-pass searches.
Loop
Run up to 3 cycles. Each cycle narrows the search based on what the previous cycle learned. After 3 cycles, return what you have — diminishing returns set in fast.
I have seen this pattern make the difference between a subagent returning "I could not find the authentication logic" and returning a complete map of the auth flow. The first search found middleware.ts which referenced lib/session.ts which imported from utils/jwt.ts. Three hops, three cycles, complete picture.
Subagents in practice
Here is how I use subagents in a typical development session.
I start a feature. Before writing any code, I dispatch a research subagent: "Understand how the current notification system works. Read all relevant files. Return a summary of the architecture, data flow, and any patterns I should follow."
The subagent reads 20 files. My main context receives a 400-token summary: "Notifications use a pub/sub pattern through a NotificationService class in lib/notifications.ts. Events are defined in types/events.ts. Handlers are registered in lib/handlers/. The pattern for adding a new notification type is: 1) add the event type, 2) create a handler, 3) register in the handler map."
Now I have everything I need to implement. My context is clean. I write the feature with a clear mental model and 50k tokens of free context instead of none.
That is the power of subagents. Not doing more work — doing the same work in the right place.