Claude Code Subagents: When They Help, When They Hurt

Claude Code subagents are usually explained as a way to run work in parallel. That is the smaller half of the story. The bigger one is context: a subagent reads twenty files, explores three dead ends, and hands back six lines. Your main conversation never sees the other nineteen thousand tokens.

Once you think of them as context firewalls rather than as extra workers, it becomes obvious which tasks they suit and which ones they make worse.

What Claude Code subagents actually are#

A subagent is a separate agent run with its own context window, its own tool access and its own instructions. It receives a prompt from the main agent, does a scoped job, and returns a report.

Three consequences follow, and all three matter:

It cannot see your conversation. Only what you put in the prompt. It does not know the decisions you made an hour ago.

Its exploration stays contained. Every file it opened, every wrong turn, every long tool output lives in its context and dies with it.

It costs tokens twice. Once for its own work, once for you reading the summary. That is the price of the isolation, and for small tasks it is not worth paying.

The three jobs they do well#

Wide search. "Where is this behaviour implemented across the codebase?" A subagent greps, opens candidates, discards the wrong ones and returns three file paths. The alternative is your main context filling with files you will never mention again.

Independent review. Reviewing your own work is weak because the reasoning that produced the code also produced the blind spot. A subagent with only the diff and the standards has no such anchor. This is where I get the most genuine value.

Fan-out on independent work. Several unrelated pieces of work, running at once, each reporting back. Real wall-clock savings when the pieces genuinely do not depend on each other.

The shared shape: reads a lot, reports a little, needs no ongoing conversation.

When they make things worse#

Small, well-specified tasks. If you know the file and the change, a subagent adds startup cost, exploration you did not need and a summary you have to read. Just do it.

Anything needing back and forth. A subagent cannot ask you a question mid-task. Work that requires clarification produces a confident answer to the wrong question.

Tasks depending on unstated context. The most common failure by a wide margin. The subagent does not know you already rejected that approach, so it proposes it again, with reasons.

Work with side effects, fanned out. Several agents editing the same area at once produces conflicts that cost more to untangle than the parallelism saved.

Write the return contract first#

Before the prompt, decide what comes back. This one habit fixes most disappointing results.

Be specific: file paths with line numbers, a list of findings with severity, a yes or no with evidence. "Look into X and tell me what you find" returns an essay you then have to read and judge.

The briefing itself should read like instructions to a competent contractor who has never seen the project:

• What the project is, in two lines.
• The specific question, scoped so it can be answered.
• Constraints and decisions already made, especially the rejected ones.
• The exact shape of the answer you want.
• What not to touch.

Vague prompts are where the token cost stops being worth it.

How this fits with the rest of Claude Code#

Subagents are one of several ways to control context and behaviour, and they are often not the right one.

CLAUDE.md carries the standing context that every run needs: conventions, commands, what not to touch. That is cheaper than briefing a subagent about it each time.

Claude Code hooks enforce rules deterministically. If you want tests run or formatting applied every time, a hook does it reliably and a subagent does it when it remembers.

Claude Skills package a repeatable procedure. If you find yourself writing the same long subagent prompt weekly, it should be a skill.

Claude skills vs subagents vs MCP covers the choice between all four properly.

Reading what comes back#

A subagent report is a claim, not a result. It was produced by a run you did not watch, from files you did not see it open, and it is sometimes confidently wrong in the specific way a well-written summary hides.

Three habits keep this honest.

Check the anchors. If it reports file paths and line numbers, open one. If the anchor is wrong, treat the rest with suspicion rather than spot-checking forever.

Watch for hedging. Phrases like "appears to" and "likely" in a report that was supposed to return a definite answer usually mean the subagent could not find what you asked for and reconstructed something plausible instead.

Prefer negative findings. A subagent that reports "I could not find any implementation of this" is more useful than one that names a file with low confidence, and you only get that answer if your prompt explicitly permits it. Say so: tell it that finding nothing is an acceptable result.

A practical rule#

Delegate when the answer is worth more than the reading. That is the whole heuristic.

If a task means opening fifteen files to produce one sentence, delegate. If it means opening one file to make one edit, do not. If you need three independent opinions on the same diff, run three subagents with different briefs and compare.

And when a subagent returns something that contradicts what you know, the fault is almost always the briefing. Add the missing context and run it again rather than arguing with the output.

The short version#

Subagents are context firewalls that happen to also run in parallel. Use them for wide searches, independent reviews and genuinely parallel work. Write the return contract before the prompt. Brief them as if they know nothing, because they do.

If you want the whole workflow, how to use Claude Code covers the fundamentals and my Claude Code course covers building this into a system you use every day.