Ask Claude Code to find where rate limiting is implemented in a 400-file codebase and watch your context window. The agent greps, opens eight files, greps again, opens six more. Twenty thousand tokens later you have your answer: it's in middleware/throttle.ts. Those twenty thousand tokens of dead-end file contents? Still in your context. You'll pay for them on every turn for the rest of the session, and the model's attention will wade through them every time it thinks.
Now the same task, dispatched to a subagent: it burns its own context on the search and returns one sentence. Your main session pays for the conclusion, not the exploration.
That's the entire subagent value proposition, and it's the piece most people's Claude Code setup is missing. Everyone has a CLAUDE.md now. Most people have hooks and an opinion on MCP vs. skills. Subagents are the fourth pillar, and they're both the highest-leverage and the easiest to misuse.
The one rule: pay for conclusions, not process
A subagent is a separate agent with its own context window, dispatched for a task, reporting back a summary. The economics only work when the task has a high process-to-conclusion ratio: lots of intermediate reading and tool output, small final answer.
Good dispatches, ranked by how often they pay off for infrastructure work:
| Task shape | Example | Why it wins |
|---|---|---|
| Broad codebase search | "Where do we configure retries for external APIs?" | 30 files read, 2 lines returned |
| Log and output archaeology | "Read this 5,000-line Terraform plan and list destructive changes" | The plan never touches your main context |
| Independent review pass | "Review this diff for security issues" | Fresh eyes, no anchoring on your session's assumptions |
| Parallel fan-out | "Check all 12 services for this deprecated SDK call" | Twelve searches at once, twelve one-line answers |
| Build/test fix loops | "Make the build green, report what you changed" | Error-log churn stays out of your session |
Bad dispatches, which I see constantly:
- Tasks needing your session's context. The subagent starts cold. If the task depends on the last hour of conversation, you'll spend more tokens briefing it than you save. Do it inline.
- Two-minute tasks. Spawn overhead plus a cold start to re-derive context beats reading one file exactly never. If the answer is one Grep away, just grep.
- Write tasks with taste requirements. Exploration parallelizes; authorship doesn't. A subagent that half-understands your conventions produces code you'll rewrite. Explore with agents, then write single-threaded with full context.
The review-pass pattern deserves its own section
The second-best use of subagents, after search, is adversarial review, and the key word is adversarial. A fresh agent with no investment in the session's decisions will flag things the main session literally cannot see, because the main session already believes its own code works.
This is not theoretical for me. I ran an adversarial audit loop against my own site's 86 AI-written tools and it found roughly 60 verified bugs, including inverted SQL logic and a permissions calculator that dropped setuid bits. The main sessions that wrote those tools considered them done. The fresh adversarial passes did not.
Two rules make review passes work:
- The reviewer gets the diff and the goal, not the transcript. Handing over your full conversation transfers your blind spots along with it.
- The reviewer's instruction is "find what's broken," not "check this." Framing determines yield. A reviewer invited to approve will approve.
Fan-out: the pattern that actually needs discipline
Parallel subagents are where the power and the failure modes both live. Dispatching five agents to audit five microservices simultaneously feels like magic the first time. It also quintuples your token burn rate, and runaway agent-loop cost arrives faster in parallel.
The discipline that keeps fan-out sane:
- Fan out on read, converge on write. Parallel exploration is safe because reads don't conflict. Parallel edits to one repo produce merge chaos. Gather findings in parallel; apply changes from one session that sees all of them.
- Give each agent a report format. "Return: file, line, severity, one-line description" turns five rambling essays into a table you can act on. Unstructured reports push the synthesis cost back onto your main session, which defeats the purpose.
- Cap the width. If the task naturally shards into 40 pieces, batch it. Forty concurrent agents is not a workflow, it's an incident. The same budget-and-kill-switch thinking you'd apply to any automation applies here.
- Treat "no findings" with suspicion proportional to stakes. An agent that comes back clean either found a clean service or gave up early. For anything that matters, spot-check one shard yourself.
Where this fits in the context engineering stack
In the context engineering post I mapped context management onto FinOps: audit, right-size, schedule, isolate, monitor. Subagents are the isolate step, and they're the biggest lever on the list. Trimming your CLAUDE.md saves hundreds of tokens per session. Moving exploration into subagents saves tens of thousands.
The full stack, one line each:
- CLAUDE.md: what's always true. Keep it tiny.
- Skills: procedures, loaded on demand.
- MCP: live capability (data, credentials, side effects).
- Hooks: the things that must happen every time, deterministically.
- Subagents: where expensive thinking goes so your main session stays cheap and sharp.
Most sessions still shouldn't spawn anything. Single-threaded with a lean context beats a badly orchestrated swarm every day of the week. But the moment you catch your main session reading its fifteenth file to answer one question, you're paying retail for something a subagent does wholesale.
Send the search out. Keep the thinking home.