Claude Code Subagents: A Practical Guide (2026)

A subagent is a Claude session you spawn from inside another Claude session, with its own context window, its own tool set, and its own job. The host agent dispatches work to it via the Agent tool, the subagent runs to completion, and the host gets back a single message describing the result. Used well, a subagent shields the host's context from a noisy search, parallelizes independent reads, or applies a specialist's framing (review, audit, exploration) the host would handle in a sloppier way.

Used badly, subagents add latency, fragment context, and produce reports the host trusts when it shouldn't.

When to delegate

Three patterns earn their keep:

Wide exploration the host doesn't need to remember. "Find every file that references X" returns a result you act on once. The grep output does not need to live in your context.
Independent work you can run in parallel. Reviewing three unrelated PRs, auditing three sibling repos, or running three flaky-test investigations all benefit from concurrent subagents. The wall-clock saving is real.
Specialist framing. A code-review subagent reads with a "find bugs" lens; a security-audit subagent reads with a "find leaks" lens. The host running through the same files would interleave concerns and miss things.

When NOT to delegate

The friction shows up when the subagent's startup tax exceeds the saving. Two patterns burn time:

One-call lookups. Reading one file? Use the Read tool. Grepping one pattern? Use the Grep tool. Spawning a subagent for a single tool call costs more than it saves.
Open-ended implementation where you'll need to re-validate everything. If you're going to read every file the subagent edited and rewrite half of them, you would have been faster doing it yourself.

How to brief a subagent tightly

Subagent prompts pay no cache amortization across launches -- every spawn is fresh tokens, fresh setup. A bloated prompt restating the agent's own definition costs you twice: once in the host's prompt, once in the subagent's loaded definition. Brief the delta, not the job description.

Bad (~2700 bytes):

Do a full-pass review of crypto-utils.ts. Read every file end to
end. Do not skim. Report as Solid / Fragile / Worth fixing now /
File for later. ASCII only, no em-dashes. Do not credit any rule.
[... 2400 more bytes restating the skill body ...]

Good (~600 bytes):

Full-pass src/crypto-utils.ts + its test. Cross-reference:
settings-manager.ts:114-127 calls encryptValue without a
startsWith('enc:') guard -- the migration at :140 has the guard.
I need to know: is encryptValue idempotent on already-encrypted
input? Direct yes/no with file:line evidence. Cap 500 words.

Same information, ~75% smaller, the subagent gets the report format from its own definition.

Parallel vs sequential

If the subagent calls are independent, dispatch them in one message with multiple Agent tool uses -- they run concurrently. If they depend on each other, dispatch sequentially so each prompt can use the previous result.

Three independent reviews? Parallel. Three review rounds on the same diff (round 2 builds on round 1's findings)? Sequential.

Trust but verify the report

A subagent's summary describes what it intended to do, not necessarily what it did. The agent says "updated all 18 call sites" -- six were touched in a half-finished way and the report does not mention it. The summary is not the diff.

When a subagent writes or edits code, check the actual changes before reporting work as done. git diff the result. Read the files you delegated. This sounds like overhead; in practice it catches the gap between intent and result that produces the "but the test fails" moment ten minutes later.

Custom subagents

Subagent definitions live in ~/.claude/agents/<name>.md with YAML frontmatter declaring the agent's name, description, and (optionally) which tools it has access to. The body is the prompt the agent runs with -- shorter and tighter than the host's prompt, focused on the one job this agent is for.

Worth shipping: a review agent (read-only, framed for bug-finding), a full-pass agent (read everything end-to-end before reporting), an explorer agent (broad search, doesn't need write access). Skip: agents that duplicate built-ins, agents you would invoke once, agents that take the same shape as a skill (use the skill).

Want the patterns?

Claude Code in Production Chapter 5 covers the agent menagerie, the briefing pattern in depth, parallel-vs-sequential heuristics, and the trust-but-verify discipline -- with worked examples of where each one earns its keep.

Claude Code in Production

The Claude Code book and practitioner's guide. Twelve chapters. PDF + EPUB. Free updates. $39 one-time, secure checkout.