Focused helpers with their own context
Subagents are specialized assistants Claude Code delegates tasks to. Each runs in its own context window, does its work, and returns a summary to the main thread — the file reads, searches, and tool calls stay isolated and never clutter your main conversation.
Key concept · Why they matter, and the built-ins
Your main context is finite; every tool call and file read fills it. A subagent spins up a separate window, receives a custom system prompt (its role) plus a task description (written by the parent agent), works independently, returns only a summary, then its conversation is discarded. Your main context stays clean — the tradeoff is you lose visibility into how it got there. Claude Code ships with built-ins: General purpose (multi-step explore + act), Explore (fast codebase search), and Plan (research during plan mode). You can also create custom subagents with the /agents command.
Four patterns that make subagents effective
A poorly configured subagent wanders, runs too long, or returns output the main agent can't use. Four fixes solve most of it.
Key concept · Descriptions, output format, obstacles, tool limits
Specific descriptions. The name and description control both when the main agent launches the subagent and what it's told to do (the parent uses the description to write the input prompt) — so "tell the agent precisely which files to review" beats a vague brief. Defined output format. The single biggest improvement: a structured format (Summary, Critical/Major/Minor issues, Recommendations, Approval status…) gives natural stopping points and stops the subagent running too long. Obstacle reporting. Add an "Obstacles Encountered" section so workarounds, environment quirks, and special flags come back — otherwise the main thread rediscovers them. Limited tool access. Give only the tools the job needs: research/read-only → Glob, Grep, Read; a reviewer → those plus Bash for git diff; only a modification agent gets Edit/Write.
Where subagents shine — and where they hurt
The overhead (lost visibility, findings compressed to a summary) only pays off when the subagent does something the main thread can't.
| Subagents shine | Subagents hurt (anti-patterns) |
|---|---|
| Research & exploration — you need the answer, not the play-by-play | "Expert" personas ("you are a Python expert") — add nothing Claude can't already do |
| Code review — a fresh context reviews changes without the author's bias | Sequential pipelines where each step depends on the last — info is lost in the handoff |
| Custom system prompts — e.g. a copywriting or styling agent with different voice/rules | Test runners — they hide the full output you need to debug failures |
Key concept · The decision rule
Ask one question: does the intermediate work matter? If no — you just need the final result — delegate it to a subagent. If yes — you need to see and react to what's happening along the way — keep it in your main thread. Code review is a special case worth remembering: Claude reviews more effectively when the code reads as someone else's work, so a fresh reviewer subagent catches what the original session talked itself past.
Chapter 17 quiz
Thirteen questions on what subagents are, designing them, and when to use them. Answer first, then expand Show answer.
Part A · Multiple choice
A subagent runs in:
- A Its own context window, returning a summary to the main thread
- B The same context as the main thread
- C A database
- D The terminal only
Show answer
A. Intermediate work stays isolated.
What two things does a subagent receive?
- A A custom system prompt (its role) and a task description from the parent
- B A password and an API key
- C Two files
- D Nothing
Show answer
A.
Which is a built-in subagent?
- A Explore
- B Compactor
- C Deployer
- D Linter
Show answer
A — Explore. Also General purpose and Plan.
The single biggest improvement you can make to a subagent is:
- A Defining an output format in its system prompt
- B Making it longer
- C Removing its description
- D Giving it every tool
Show answer
A. It creates stopping points and prevents over-running.
What tools should a research/read-only subagent get?
- A Glob, Grep, Read — no Edit/Write
- B All tools
- C Edit and Write
- D None
Show answer
A. So it can't accidentally modify files.
The decision rule for using a subagent is:
- A Does the intermediate work matter? If no, delegate; if yes, keep it in the main thread
- B Always delegate
- C Never delegate
- D Delegate only long tasks
Show answer
A.
Why is a subagent good for code review?
- A A fresh context reviews the changes without the author's bias
- B It's faster to type
- C It skips the diff
- D It has more tools
Show answer
A. The main session that wrote the code gives weaker feedback.
Part B · True or false
A subagent's description shapes both when it launches and what it's told to do.
Show answer
True. The parent uses it to write the input prompt.
An "Obstacles Encountered" output section keeps the main thread from rediscovering workarounds.
Show answer
True.
"You are a Python expert" personas make subagents meaningfully better.
Show answer
False. Claude already has that knowledge — an anti-pattern.
Sequential subagent pipelines work well when each step depends on the last.
Show answer
False. Info is lost in the handoff; they work only for truly independent tasks.
Test-runner subagents can hide the full output you need to debug.
Show answer
True. They performed worst in testing.
Part C · Short answer
Name the four characteristics of an effective subagent.
Show answer
Specific descriptions, structured output format, obstacle reporting, and limited tool access.