Claude Code Subagents: What They're For, and When They Make Things Worse

Subagents are the most misused feature in Claude Code. Used right, they are how one session reads a fifty-file codebase without drowning its own context, and how four independent jobs run in the time of one. Used wrong, they are a way to pay tokens for a worse answer and then wait longer for it. The difference is not subtle, and it comes down to one question: does the parent need the work, or just the conclusion?

What a subagent actually is

A subagent is a second Claude instance spawned by your session with its own, empty context window. The parent writes it a task prompt; the subagent works alone — reading files, running commands, whatever its tools allow — and everything it reads and does piles up in itscontext, not the parent's. When it finishes, exactly one thing crosses back: its final report. The parent never sees the forty file dumps behind that report.

A subagent is a context firewall. The work stays on one side; only the conclusion crosses.

That is the entire economic case. A context window is a budget, and everything the session reads spends it. A search across a big repo can burn six figures of tokens in file contents. Delegate the search, and the parent pays only for the answer.

When to spawn one

• Fan-out reads.“Find where retries are configured across the codebase” — the search must read broadly, the parent needs three file paths. Perfect delegation.
• Independent parallel work. Three subsystems need auditing and no result depends on another. Spawn three at once, in one go — sequential spawning of independent work is just waiting three times.
• Dirty work you don't want in the parent's head. Log spelunking, dependency tree dumps, a build that prints two thousand lines. Let a subagent eat the output and summarize.
• A different standard of judgment.A reviewer agent with a review checklist in its definition applies that checklist fresh, unanchored by the parent's belief that the code it just wrote is fine.

When it makes things worse

• The task needs the parent's context. A subagent starts empty. If the job only makes sense with the last hour of conversation in mind, the parent either writes it all into the prompt (expensive, lossy) or the subagent guesses (worse). Do those in the main session.
• Single-fact lookups. You know the file, you want one value. Spawning an agent to read one file is pure overhead — just read it.
• Sequential edits to shared state. Two subagents editing the same files in parallel is a merge conflict you ordered on purpose. Parallelize reads freely; parallelize writes only on disjoint files — the coordination rules are the hard part of running multiple agents on one machine.
• Delegation theater.One subagent, given the parent's whole task, verbatim. Now the same work happens with less context and an extra hop. If you are delegating everything, you are delegating nothing.

Defining reusable subagents

Ad-hoc delegation needs no setup — Claude Code decides to delegate on its own, or you tell it to. But the durable version is a named agent definition: a markdown file with YAML frontmatter, in .claude/agents/ for the project or ~/.claude/agents/for your whole machine. The body of the file is the subagent's system prompt.

---
name: code-reviewer
description: Reviews diffs for correctness, security and style.
  Use proactively after any significant code change.
tools: Read, Grep, Glob, Bash
---
You are a code reviewer. You do not fix code; you report.
Review the diff against these gates, in order:
1. Correctness: does the change do what the task claims?
2. Security: secrets, injection, unsafe file operations.
3. Tests: is new behaviour covered?
Report findings as a ranked list, worst first, with file:line.

• description is the routing surface. The main agent reads it when deciding whom to delegate to — write when to use this agent into it, not just what it is.
• tools is a permission boundary. A reviewer with no Edit or Writecannot “helpfully” fix what it was asked to judge. Least privilege applies to agents, not just users.
• Manage them with the /agents command, or edit the files directly.

The failure modes nobody warns you about

The report is the only channel — and reports lie

The parent sees a summary written by the worker about its own work. “Done, all tests pass” from a subagent has exactly the reliability of “done” from any agent— which is to say: verify it. Ask for receipts in the task prompt (“name the files changed, paste the failing→ passing test output”) and spot-check against the actual repo state.

Mid-flight steering is limited

A subagent cannot tap you on the shoulder to ask a clarifying question the way the main session can. Underspecified tasks do not get rescued — they get completed wrong, confidently. The task prompt has to carry everything: goal, constraints, what done looks like, what to return.

Parallelism is bounded by the machine, not the model

Every concurrent subagent is a real process doing real reads and builds. Ten parallel agents on one laptop discover the disk, the port space, and each other. Parallel reads scale; parallel builds and dev servers collide.

The decision on one screen

DELEGATE when…                      DON'T when…
─ broad reads, narrow conclusion    ─ task needs the conversation so far
─ N independent jobs, no overlap    ─ one known file, one fact
─ output is huge, answer is small   ─ writes to shared files in parallel
─ fresh judgment wanted (review)    ─ you'd hand over your whole task as-is

ALWAYS in the task prompt: goal · constraints · deliverable ·
"return receipts: files touched, commands run, outputs"

Reference: Anthropic's subagents documentation. For what to hand to agents in the first place — and what to keep for yourself — see what to delegate to AI agents.