Subagents — delegate like a senior developer
Hand off focused tasks to specialized Claude instances
⏱ Est. ~6 min
01 · Read
Senior developers don't do everything themselves — they delegate. When a junior asks a senior to investigate a bug, the senior doesn't drop their current work. They send someone to investigate and report back.
Subagents let you do the same thing in Claude Code. Instead of one giant conversation trying to handle everything — reading files, running tests, investigating architecture — you can hand focused tasks to specialized subagents that work in their own context window.
The key benefit: subagents keep your main conversation clean. A subagent might read 50 files to understand your auth system, but only a short summary comes back into your context window.
💡 Picture thisThink of a subagent like sending a research assistant to the library. You don't go yourself and stack books on your desk — they go, read everything, and come back with a one-page summary. Your desk stays clear for the important work.
Key points
- Subagents run in a separate context window from your main conversation
- They investigate, analyze, and execute tasks independently
- Only summaries come back to your context — not every file they read
- Your main conversation stays focused on implementation
02 · Read
Claude Code has a few built-in subagent types, each designed for specific tasks:- Explore — Read-only research. Searches files, reads code, answers questions about the codebase. Can't edit. - Plan — Architecture design. Explores the codebase and proposes implementation plans. Read-only until you approve. - Bash — Command expert. Runs terminal commands. Use it for running tests, builds, and system checks.
Claude spawns subagents automatically when it recognizes a task that should be isolated — like investigating a large codebase or running a test suite. You can also explicitly ask for one.
Key points
- Explore: read-only research and codebase analysis
- Plan: architecture design and implementation planning
- Bash: terminal commands and system operations
- Claude spawns subagents automatically when appropriate
03 · Code example
You can ask Claude directly to use a subagent. Below is a prompt that triggers subagent delegation.
Prompt that triggers a subagent
"Use a subagent to investigate how auth works in this codebase"
"Explore the database schema and summarize what tables we have"
"Run the test suite and report which tests fail"
"Analyze the API routes and list all endpoints"
When you ask Claude to "investigate," "explore," "analyze," or "run tests," it often delegates to a subagent automatically. The subagent does the heavy lifting in its own context and summarizes back to your conversation concisely.
04 · Read
You can build your own custom subagents by writing a SKILL.md with YAML frontmatter. This defines a specialized agent with its own instructions, tool restrictions, and model choice.
Custom agents are powerful because you can limit capabilities. A code reviewer only needs to read files — it shouldn't edit or run commands. A test runner needs Bash but not Edit. Tool restrictions make agents safer and more focused.
Key points
- Custom agents are defined in a SKILL.md with YAML frontmatter
- The tools: field restricts what the agent can do
- A reviewer needs Read/Grep/Glob — not Edit or Bash
- Restrictions make agents safer and more focused
05 · Code example
Here's how to build a custom code-reviewer subagent. The YAML frontmatter configures its behavior.
.claude/skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Expert code review specialist. Use after code changes.
tools: Read, Grep, Glob
model: sonnet
---
Review code for:
1. Bug risks and logic errors
2. Security vulnerabilities (injection, auth bypass)
3. Performance issues (N+1 queries, unnecessary loops)
4. Style inconsistencies with the existing codebase
Provide specific line references and severity ratings.
This agent can only read code — it can't edit files or run commands. The tools: Read, Grep, Glob restriction ensures it stays focused on review. model: sonnet means it uses Sonnet (fast, cost-effective) instead of the model your main conversation uses.
06 · Quiz
You're implementing a new feature and need to understand how the existing auth system works. It involves reading 20+ files. What's the most context-efficient approach?
- Read all 20 files yourself in the main conversation
- Ask Claude to explain auth without reading files
- Open a new Claude session for the investigation
- Use a subagent to investigate and return a summary
07 · Match
Match each subagent type to its best use.
(This section is interactive — please enable JavaScript.)
Other lessons in this chapter
⚠ The full interactive experience needs JavaScript. Please enable it and reload.
※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.