Lesson 457 of 2116
Subagents: When To Delegate vs Do It Yourself
Claude Code can spawn isolated subagents for parts of a task. The trick is knowing when delegation actually helps — and when it just doubles your context bill.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1What subagents are
- 2subagent
- 3context isolation
- 4parallelism
Concept cluster
Terms to connect while reading
Section 1
What subagents are
A subagent is a fresh Claude session spawned by the main agent for a scoped task. It gets its own context window, its own tool calls, and returns a summary back to the parent. The parent does not see the subagent's full transcript — it sees the result.
When subagents help
- 1Searching a large codebase: subagent reads many files, returns a focused summary
- 2Parallel exploration: spawn 3 subagents to investigate 3 hypotheses in parallel
- 3Wide refactors where each module is independent and self-contained
- 4Repeated, scoped work (apply the same change in 12 places, each in its own subagent)
- 5When the parent's context is too valuable to spend on a sub-task
When subagents don't help
- Tightly coupled work where the parent needs to see the actual code
- Tasks that are short enough to do inline (under 5-10k tokens of effort)
- Work where the subagent's context is the same as the parent's anyway
- Anything the parent can do faster than spinning up a new agent
- Quality-sensitive work where you want to read the full reasoning trace
The delegation prompt
Compare the options
| Bad spawn prompt | Good spawn prompt |
|---|---|
| 'Look at the auth code' | 'Read every file under src/auth/. Identify any place we trust user-supplied input. Return a list with file:line and the exact line.' |
| 'Refactor this' | 'Apply the renamed-field migration in src/server/users.ts only. Update tests. Return the diff.' |
| 'Investigate why tests fail' | 'Run pnpm test. Read the failure output. Return the failing test names with one-line root-cause guesses.' |
Apply: delegate one task today
- 1Pick a wide read task in a codebase you're learning
- 2Write a precise spawn prompt with a defined return shape
- 3Run it as a subagent
- 4Compare what came back to what you'd have done yourself
- 5Refine the prompt for next time
Key terms in this lesson
The big idea: subagents are great when a task can be cleanly scoped and the return value can be summarized. Otherwise they're just expensive parallelism.
End-of-lesson quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “Subagents: When To Delegate vs Do It Yourself”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Creators · 11 min
Multi-Soul Orchestration: When To Split, How To Hand Off
One Soul that does everything is a junior generalist. A team of Souls is closer to how real organizations work — but only if you design the handoff and the shared memory carefully. The fix is not a bigger model; it's specialization.
Creators · 40 min
Claude Code Workflows: Beyond Single-Session Coding Help
Claude Code shines when used as a structured workflow, not a single-session helper. Repeatable workflows for code review, refactoring, and incident investigation produce 10x leverage.
Creators · 45 min
Structured Outputs: Make the Model Return Data You Can Trust
For production apps, pretty prose is often the wrong output. Learn when to use structured outputs, function calling, and schema validation.