Claude Code subagents, explained

The problem subagents solve

A long Claude Code session accumulates context — files read, commands run, false starts, intermediate reasoning — and all of it stays in the conversation whether or not it's still relevant to what you're doing now. Delegate a bounded piece of work to a subagent instead, and that exploration happens in its own separate context: the subagent reads what it needs, does the work, and reports back a result, without every file it opened along the way staying resident in your main session's context for the rest of the conversation.

What makes a task a good fit for delegation

The tasks that benefit most from a subagent are the ones with a large, disposable exploration phase and a small, useful result — searching a large codebase for every place a pattern appears, reading through a stack of related files to answer one specific question, running an independent investigation whose intermediate steps you don't actually need to see. A task where you need to stay closely involved turn by turn, reacting to each step as it happens, is the opposite case — delegating that just adds a layer of indirection between you and work you wanted to watch happen directly.

A subagent with a narrow job description outperforms a general one

A subagent configured with a specific, bounded role — reviewing code for a particular category of issue, researching one specific kind of question — tends to produce more reliable results than one given the same broad instructions as your main session and just told to "help." Scoping a subagent's role narrowly does two things at once: it keeps the subagent's own context focused on exactly what it needs, and it makes the result you get back easier to evaluate, because you know precisely what lens it was applying.

What comes back, and what doesn't

The main session gets the subagent's final report, not a transcript of everything it did along the way. That's the entire mechanism working as intended — the exploration was supposed to be disposable — but it also means a subagent's report needs to actually contain what you need, because you can't retroactively ask it "wait, what did you see in that other file." If a subagent's task is likely to surface something you'll want to follow up on, its instructions should explicitly ask it to report that, rather than assuming you can go back and check.

Parallel subagents versus a sequence of them

Independent pieces of investigation — checking several unrelated parts of a codebase for the same kind of issue, say — can run as separate subagents in parallel rather than one after another, since neither needs the other's result to do its job. Work that's actually sequential — where the second piece depends on what the first one found — doesn't benefit from that and should stay a single subagent, or a sequence of them, rather than being parallelised for the sake of it and producing results that don't actually account for each other.

When a subagent is overhead, not a win

Delegating a task that's small enough to just do directly in the main session adds a round trip for no benefit — the context a tiny task would have added was never the problem delegation solves. Reach for a subagent when the exploration itself is the expensive part, not as a default for anything that could technically be handed off.

Subagents and permission scope

A subagent isn't automatically bound by tighter restrictions than your main session just because it's doing a narrower job — by default it can reach for the same tools your main session can, which means a subagent given a narrow task description can still, in principle, take a broad action if nothing scopes it more tightly than that. If a subagent's job genuinely only needs read access to investigate something, configuring it that way is worth doing explicitly rather than assuming the narrow instructions alone will keep it from doing more than intended.

Debugging a subagent that reported the wrong thing

When a subagent's report doesn't match what you expected, the instinct is to blame the main session's instructions to it — but the more common cause is that the subagent's own task description was underspecified, and it made a reasonable judgment call that wasn't the one you had in mind. Because you don't see its intermediate steps, a vague subagent brief is harder to debug after the fact than a vague instruction in your main session would be, where at least you can watch it go astray in real time and redirect. Write subagent task descriptions more precisely than you might phrase the equivalent request directly, precisely because you'll have less visibility into how it was interpreted.