Subagent
The main agent hands off a contained job, such as searching a codebase, reading a long log or reviewing a diff. The subagent works with its own instructions and tools, and the main agent receives only its summary. Claude Code's subagent documentation says each subagent runs in its own context window with a custom system prompt, specific tool access and independent permissions. That isolation keeps the main context clean, which helps against context rot.
Subagents are a form of the supervisor-worker pattern. They help when a side task produces a lot of text you won't need again, or when several independent tasks can run in parallel. They use more tokens in total, and they know only what you tell them, so the hand-off has to state the goal, the inputs and the shape of the answer (agent handoff). Qurtoo's article on sub-agent delegation prompts covers when to spawn one and when to keep the work in the main thread.
Example
Task for a subagent:
Goal: Find every place in this repository that reads the SMTP_PASSWORD setting.
You may use: search_code, read_file. Don't edit anything.
Return: a list of file paths with line numbers, and one sentence on how each place uses the value.
Keep the answer under 150 words. Don't include file contents.When to use it
- Side tasks that read a lot but return a little (search, log review, research)
- Independent pieces of work that can run in parallel
- Work that needs different tools or tighter permissions than the main agent
When not to use it
- Small tasks the main agent can finish in a step or two
- Work that depends on details only the main conversation holds, unless you pass them along
- Tight token budgets
Articles that use this
- The Conductor Prompt: Ten Specialist Roles, Five Workers in FlightAgentic
- Background Agents and Parallel Execution: Run Eight Tasks at Once Without ConflictsAgentic
- When to Use Subagents: Delegation Prompts That Keep a Long-Context Agent FocusedAgentic
- The Supervisor-Worker Pattern: One Strong Model Plans, Cheaper Models ExecuteAgentic
- Reasoning Effort: How to Set Thinking Depth Instead of Writing "Think Step by Step"Techniques

