Subagents solve a specific problem: context pollution. Every file Claude reads, every command it runs, every intermediate result it considers — all of it accumulates in a single context window. For small tasks, that’s fine. For anything involving a large codebase, lengthy research, or multiple distinct phases of work, the context fills up fast and quality degrades.
Subagents are Claude Code’s answer to this. They run in their own isolated context window, do focused work, and return a summary. The main agent’s window stays clean.
This guide covers how subagents actually work, how to write effective AGENTS.md entries, and the patterns that consistently outperform naive approaches.
How Subagents Work
When you invoke a subagent, Claude Code spawns a new session. That session has:
- Its own context window (separate from yours)
- A custom system prompt defined in AGENTS.md
- Its own tool permissions (you can restrict what it can access)
- No memory of your current conversation unless you explicitly pass it
The subagent completes its task and returns a result. That result gets injected back into your main session. The thousands of tokens the subagent consumed — browsing docs, reading files, running commands — never touch your context.
This is the core value proposition. A subagent that reads through 200 pages of documentation uses its own token budget, not yours.
AGENTS.md: The Configuration File
Subagents are defined in AGENTS.md files, which follow the same placement rules as CLAUDE.md — they can live at the project root, in a package subdirectory, or globally in ~/.claude/.
A basic entry looks like this:
# agents
## code-reviewer
description: Reviews code for correctness, security issues, and style violations. Use for PR reviews and pre-commit checks.
tools: read, bash
model: claude-sonnet-4-6
## doc-writer
description: Writes and updates technical documentation based on code changes. Use when updating README files, API docs, or inline comments.
tools: read, write
model: claude-sonnet-4-6
## test-generator
description: Generates unit and integration tests for existing code. Use after implementing new features.
tools: read, write, bash
model: claude-sonnet-4-6A few things to notice:
The description field is load-bearing. Claude uses this to decide when to invoke the subagent automatically. Write it as a clear trigger condition, not a general purpose summary. “Reviews code” is vague. “Reviews code for correctness, security issues, and style violations. Use for PR reviews and pre-commit checks” tells Claude exactly when this agent applies.
tools scoping matters. A documentation writer does not need bash. A code reviewer probably does not need write access to your codebase — you want it to flag problems, not fix them silently. Narrow the tool set to the minimum the subagent actually needs.
model is optional but worth specifying. Sonnet is fast and cheap. Opus is better for complex reasoning. Match the model to the task, not the other way around.
Explicit vs Automatic Invocation
Subagents can be invoked two ways.
Automatically: Claude routes tasks to subagents based on their description. This works well once your descriptions are precise, but it can surprise you — Claude might delegate something you wanted to handle yourself.
Explicitly: Reference the subagent by name in your prompt. “Run the code-reviewer subagent on the diff in this PR” leaves no ambiguity.
For production workflows, explicit invocation is more predictable. Automatic invocation is convenient for exploratory work where you’re less concerned about exactly which agent handles what.
To invoke explicitly:
Run the test-generator subagent on src/auth/login.ts. Focus on edge cases for invalid input.Claude will spawn the subagent, pass your instruction plus any context you specify, and return the output.
Parallel vs Sequential Patterns
This is where subagents get genuinely powerful — and where most people leave significant performance on the table.
Sequential (the default everyone uses)
1. code-reviewer → finds issues
2. test-generator → writes tests for found issues
3. doc-writer → updates docsEach step depends on the previous one. This is fine, but it’s slow. Each subagent waits for the last one to complete.
Parallel (what you should be doing for independent tasks)
When tasks don’t depend on each other, run them simultaneously:
In parallel:
- code-reviewer: review src/auth/
- code-reviewer: review src/payments/
- code-reviewer: review src/notifications/Three separate package reviews running at the same time. Claude launches all three tool calls simultaneously. You get the results in roughly the same time as one review, not three.
The rule: if task B does not need the output of task A, they can run in parallel. Map out the dependency graph before you start.
The Fan-Out/Fan-In Pattern
This is the highest-leverage pattern for large research or audit tasks:
- Fan out: spawn multiple subagents, each analyzing a piece of the system
- Fan in: collect their summaries into a synthesis step
Fan-out phase (parallel):
- analyzer-agent: analyze frontend bundle size causes
- analyzer-agent: analyze API response time bottlenecks
- analyzer-agent: analyze database query patterns
Fan-in phase (sequential):
- architect-agent: given the three analysis reports, propose a unified optimization planThe fan-in agent receives small, dense summaries rather than raw analysis. Your main context only sees the final synthesis.
Context Passing: What to Explicitly Send
Subagents start with no knowledge of your current session. This catches people off guard — you spend 20 messages establishing context with Claude, then spawn a subagent and it knows none of it.
You need to explicitly pass what the subagent needs. Options:
Pass file paths, not file contents. The subagent can read files itself. Pasting file contents into your invocation message just duplicates tokens.
Run the code-reviewer subagent on the files in src/payments/.
The payment provider we use is Stripe. The relevant config is in config/stripe.ts.Write context to a file and reference it. For complex context that multiple subagents need, write it to a markdown file and have each subagent read it:
The current architecture decisions are documented in docs/architecture-decisions.md.
Run the test-generator on src/auth/ with that context.Keep summaries short. When a subagent completes, its result comes back into your main context. If it writes a 3,000-word analysis, that’s 3,000 tokens you have to carry. Ask subagents to return dense summaries, with full details written to a file.
The Key Mistake: Over-Delegating
The most common misuse pattern is treating subagents like a catch-all for “things I don’t want to deal with right now.”
Subagents add overhead. Spawning a subagent, passing context, waiting for results, reading the summary — that’s real latency. For a 10-line function change, just doing the work in your main session is faster.
The right mental model: subagents are for tasks where the execution work (reading, searching, analyzing) would consume significantly more context than the result is worth. If a task would add 5,000 tokens of intermediate reasoning to your context for a 200-token answer, that’s a good subagent candidate. If it would add 300 tokens for a 200-token answer, just do it inline.
Rules of thumb:
- Research tasks (reading docs, scanning codebases): good subagent candidates
- Single file edits: keep in main session
- Cross-cutting analysis (reviewing 10+ files): strong subagent candidate
- Quick generation tasks (write one test): keep in main session unless you are already context-constrained
Subagents vs Agent Teams
Agent Teams (released February 2026) are different from subagents in one key way: teammates can communicate with each other directly. Subagents can only report back to the main orchestrator.
Use subagents when:
- Tasks are independent and self-contained
- You want a single orchestrator maintaining control
- The task scope is bounded and predictable
Use Agent Teams when:
- Tasks require coordination between workers
- You need teammates to challenge each other’s output
- You’re running a long-horizon project where teammates need to sync state
For most day-to-day development work, subagents are sufficient. Agent Teams shine for large refactoring projects, complex code migrations, or research that requires multiple perspectives.
A Working AGENTS.md Template
Here is a starting point for a typical full-stack project:
# agents
## researcher
description: Researches documentation, GitHub issues, and external resources to answer technical questions. Use when you need up-to-date information about libraries, APIs, or unfamiliar codebases before writing code.
tools: read, bash, web_search
model: claude-sonnet-4-6
## code-reviewer
description: Reviews staged changes or specific files for bugs, security issues, performance problems, and style violations. Use before committing or when reviewing a PR. Returns a structured list of issues by severity.
tools: read, bash
model: claude-sonnet-4-6
## test-writer
description: Generates unit and integration tests for existing functions and modules. Use after implementing a feature or fixing a bug. Writes tests to the appropriate test directory and runs them to verify they pass.
tools: read, write, bash
model: claude-sonnet-4-6
## doc-updater
description: Updates documentation files (README, API docs, changelogs) to reflect code changes. Use after merging features or before a release. Reads the diff and updates affected docs only.
tools: read, write
model: claude-sonnet-4-6
## security-auditor
description: Audits code for security vulnerabilities including injection risks, authentication flaws, secrets in code, and insecure dependencies. Use on authentication modules, API handlers, and before production deployments.
tools: read, bash
model: claude-opus-4-6Start with two or three agents that solve your actual pain points. More agents means more configuration overhead and more opportunities for misdelegated tasks. Add agents as you identify clear patterns, not preemptively.
Debugging Subagent Issues
Common problems and fixes:
Subagent invoked when it shouldn’t be: Tighten the description trigger condition. Add explicit “do not use when” language if needed.
Subagent not invoked when expected: The description may not match how you’re phrasing tasks. Either rewrite the description or use explicit invocation.
Subagent returns too much: Ask it to write detailed output to a file and return a summary. Specify the format you want in your AGENTS.md description or in the invocation prompt.
Parallel agents producing conflicting edits: Don’t run parallel agents that write to the same files. Structure parallel work so each agent owns distinct files or directories.
The subagent system is powerful but not magic. The configuration work you put into AGENTS.md pays off linearly — better descriptions, better tool scoping, and clearer output format instructions directly translate to better agent behavior.