Subagents: what changes when you stop working alone
Up to this point, Claude Code is a single agent talking to you. When the task grows — a refactor touching 20 files, investigating code you've never seen, reviewing a large diff — that model starts to crack. The context window fills up, responses slow down, and the agent loses track of what the original goal was.
Subagents are the structural fix. Instead of doing everything in the same process, you fire secondary agents in isolated contexts. Each one has its own context window, its own tool set, and returns only what matters to the main agent: a summary, a patch, a verdict.
The practical result: you can run three investigations in parallel while the orchestrator keeps its context clean for decisions. You claw back meaningful time on medium-sized tasks — not because the model got faster, but because you stopped wasting context on delegable work.
If you landed here without the big picture, go back to the definitive guide to Claude Code — subagents make more sense after you understand the other six layers.
The mechanism: Task tool + subagent_type
You fire a subagent through the Task tool. A typical call:
Task({
description: "Audit auth middleware for token leaks",
subagent_type: "security-auditor",
prompt: "Review src/middleware/auth.ts for..."
})
Three important parts:
description— 3-5 words that show up in the orchestrator's transcript.subagent_type— which type of agent to run (Explore,Plan,debugger,code-reviewer,general-purpose, etc.).prompt— the full briefing. The subagent does not see your conversation; the prompt must be self-contained.
When the subagent finishes, it returns a single message to the orchestrator. All the intermediate context (the files it read, the greps it ran, the ideas it discarded) stays inside its own window — never reaches the orchestrator. That asymmetry is what protects the main context.
The default catalog
Claude Code ships with a built-in subagent catalog that covers 80% of real cases:
general-purpose— generic agent for multi-step research and open-ended tasks.Explore— fast codebase search, tuned for finding files and symbols without bloating context.Plan— software architect, drafts implementation plans.code-reviewer— senior reviewer, checks quality before merge.debugger— root-cause analyst for errors, test failures and unexpected behavior.test-writer— test engineer, writes high-value tests.security-auditor— audits code for vulnerabilities.refactorer— code structure specialist, reduces duplication.doc-writer— technical documentation specialist.
The rule of use is simple: delegate to the right type instead of always reaching for general-purpose. A code-reviewer runs with a different system prompt than a debugger — it has been tuned to look for typical review issues (naming, duplication, edge cases), not to trace a stack trace.
To build your own types when the catalog doesn't match your routine, jump to Creating custom Subagents step by step.
Three patterns that pay off
1. Parallel exploration before planning. When you receive a large task in a codebase you don't know, don't have the orchestrator read files one by one. Fire 2-3 Explore agents in parallel, each with a different angle: "where does the auth logic live?", "which tests cover that route?", "which components consume this hook?". The orchestrator receives three summaries and starts thinking with a map in hand — without having spent context reading file by file.
2. Independent validation. After implementing a sensitive change — a migration, an auth change, a refactor of a critical module — fire a code-reviewer with the diff and minimum context. Because it did not see the original conversation, it doesn't inherit your rationalizations. That "cold read" catches problems the orchestrator can no longer see because it has already talked itself into its own reasoning.
3. Parallel work alongside yours. Not every subagent needs to block. You can fire a test-writer in the background while you keep implementing the feature; when it finishes, the orchestrator is notified. You gain time without losing focus.
Those three cover the basics — more advanced patterns (fan-out/fan-in, supervisors, chained delegation, using worktrees for filesystem isolation) are in Multi-agent orchestration patterns in Claude Code.
Common anti-patterns
Delegating what you don't understand. The forbidden phrase in a subagent prompt is "based on your findings, solve the problem". That pushes the synthesis work — which was yours — onto the subagent. The result comes back vague, because the subagent made decisions without your context. Delegate execution or research — never understanding.
Prompt that's too small. Subagents don't see your conversation. If you write "review the diff", it doesn't know which diff, which file, which goal. A good prompt has three parts: what to do, the minimum context (files, lines, relevant history) and the expected answer format (short bullet list, yes/no verdict, diff patch).
Subagent for a trivial task. Firing a subagent to read a file you already know you need to read is pure overhead — you pay startup latency and lose the direct interaction. Use a subagent when the work is parallel, context-isolated, or needs independent perspective.
Ignoring the result. The orchestrator only sees the final message. If you don't synthesize what came back — if you don't read, extract the useful parts, and integrate them into your next step — the subagent was wasted. Delegate only when you're going to use the output.
Security and restricted tools
Every subagent type carries a specific tool set. A security-auditor may only have Read, Grep, Glob, Bash(grep *) and Bash(find *) — no Edit, Write, curl. That restriction is deliberate: it limits the blast radius of what an agent can do if it misinterprets the prompt.
When you build custom subagents, inherit that discipline. The rule is least privilege: give the subagent only the tools it needs for its function. A reviewer should not be able to edit. A test generator should not be able to run git push. For the full reasoning on authorization, worktree isolation and defensive practices with Claude Code, see Security and best practices with Claude Code.
Next steps
The natural next step after understanding the concept is watching subagents solve a real problem. Two paths: if your priority is building your own types, go to Creating custom Subagents step by step. If the priority is debugging a hard failure, read Debugging with the debugger agent — it's the use case where subagents shine the most, because debugging context is exactly the kind of thing you don't want polluting the orchestrator. When you take all of this to CI and team integrations, close the loop with Claude Code in your daily development workflow.
