Claude Code Subagents Explained: When and How to Use Them

If you have used Claude Code for more than a week, you have probably hit the same wall: a long session that starts crisp and gets muddier with every tool call. You searched the codebase, read fifteen files, tried an approach that did not work, backed out of it, and now the model is dragging all of that history into every new decision it makes. Subagents exist to fix exactly this problem. They are not a productivity gimmick bolted onto Claude Code — they are a context management primitive, and once you understand them that way, the question of "when should I use a subagent" stops being a matter of taste and starts being a matter of engineering judgment.

This is a practitioner's walkthrough, not a feature tour. We will cover what subagents actually are under the hood, why isolating context is the whole point, when fanning out work pays off and when it is just overhead, how to write a subagent brief that produces useful output on the first try, and three patterns — reviewer-fixer pairs, parallel independent research, and swarm migrations — that cover most of the real use cases you will run into.

What a subagent actually is

A subagent in Claude Code is a separate agent invocation with its own context window, its own tool access, and a single job. When your main session dispatches a subagent, it hands over a task description — a brief — and the subagent starts fresh. It does not inherit the conversation history of the main session. It reads whatever files it needs to read, does whatever searching or editing the task requires, and then reports back a result. That result is what returns to your main conversation, not the subagent's internal scratch work.

This matters more than it sounds like it should. In a normal Claude Code session, everything you do accumulates in the context window: every file read, every grep result, every failed attempt, every piece of stack trace you pasted in to debug something three turns ago. The model has to hold all of that to reason about your next request, and past a certain point the accumulated noise measurably degrades the quality of its reasoning — not because the model gets "confused" in some vague sense, but because relevant signal gets diluted by irrelevant history, and the model has to spend attention re-deriving what actually matters right now.

A subagent sidesteps this by design. It gets a clean slate, does the work, and only the distilled output comes back. If you ask a subagent to find every place in a monorepo that calls a deprecated API, it might read forty files and produce ten thousand tokens of intermediate exploration — but what lands back in your main session is a short list of file paths and line numbers. The forty files it read never touch your context. This is the core mechanical benefit, and everything else about subagents follows from it.

Why context isolation is the actual point

It is tempting to think of subagents as a way to "parallelize" work, and that is a real benefit, but it is secondary. The primary benefit is that your main conversation — the one where you are making decisions, reviewing diffs, and steering the overall direction of a task — stays clean. Clean context means the model's attention stays focused on what you are actually trying to decide, not on the debris of how you got there.

Think about what happens without this. You ask Claude Code to investigate why a test suite is flaky. It reads the test files, greps for timing-related code, checks CI logs, reads three unrelated modules to understand a shared fixture, and eventually finds the answer: a race condition in a setup hook. In a single unbroken session, all of that exploration — the dead ends, the modules that turned out to be irrelevant, the CI log dumps — is now sitting in your context window. When you ask a follow-up question ten minutes later, the model has to wade through that. When you ask it to now go fix a completely unrelated bug, the flaky-test investigation is still there, still costing you attention and tokens, still capable of leaking into the reasoning for something it has nothing to do with.

Dispatch that same investigation to a subagent, and you get back: "The race condition is in setup.ts line 42 — the mock server starts asynchronously but the test runner does not await it." One sentence. The exploration happened, but it happened somewhere your main thread never has to look. This is why experienced Claude Code users describe subagents as a pollution firewall as much as a parallelism tool. You are not just saving wall-clock time — you are protecting the quality of every subsequent turn in your main session.

There is a second, quieter benefit: subagents can be given narrower tool access than your main session. A subagent whose only job is to review a diff does not need write access to the filesystem. A subagent doing research does not need permission to run arbitrary shell commands. Scoping tool access down to what the task requires is good practice independent of context isolation, but subagents are the natural place to enforce it, because each one is defined with its own tool list.

When to fan out to a subagent vs. just handle it inline

Not everything should go to a subagent. The overhead of dispatching one — writing a clear brief, waiting for it to spin up, parsing its report — is real, and for small, tightly-coupled tasks it is not worth paying. Here is the practical line, drawn from what actually changes the outcome:

• Handle it inline when the task is small, when you need to see intermediate results to decide the next step, or when the work is tightly interleaved with a decision only you (or the calling model) can make. If you are editing three lines in a file you already have open, there is no context to protect — just make the edit.
• Dispatch to a subagent when the task involves reading a lot of material relative to the size of the answer. Searching a codebase for a pattern, reading through documentation to answer a specific question, reviewing a large diff, or scanning logs for an error signature are all "high exploration, low output" tasks — exactly the shape that benefits from isolation.
• Dispatch to a subagent when the task is independent of other work you are doing right now and could run concurrently. If you have three unrelated modules that each need the same mechanical change, there is no reason to do them one after another in a single thread when three subagents can do them at the same time.
• Dispatch to a subagent when you want a second, less-biased pass on something. A subagent reviewing code it did not write has no attachment to the approach and will catch things the original author — human or model — glossed over. This is the whole premise of reviewer-fixer pairs, covered below.
• Handle it inline when the task requires a long back-and-forth with you, the user. Subagents report back once; they are not built for a running dialogue. If you expect to iterate rapidly on something with a human in the loop, keep it in the main session.

A rough heuristic that holds up in practice: if you can describe the task in one or two sentences and the deliverable is small — a list, a yes/no answer, a fix to a bounded set of files — it is a good subagent candidate. If the task is "figure out what we should build," that is not delegation, that is thinking, and thinking should happen where you can watch it happen.

Writing a subagent brief that works on the first try

The single biggest determinant of subagent output quality is the brief you write. A subagent has no memory of your conversation, no sense of why the task matters, and no ability to ask you a clarifying question mid-task the way a human colleague would tap you on the shoulder. Everything it needs has to be in the brief, up front.

A good brief has four ingredients:

1. The goal, stated plainly. Not "look into the auth module" but "find every place that reads the SESSION_SECRET environment variable directly instead of through the config loader, so we can migrate them."
2. Context the subagent cannot infer. If you already ruled out an approach, say so — otherwise the subagent will waste its own context rediscovering the dead end. If there is a file that is the known entry point, name it.
3. The shape of the expected output. Tell it whether you want a file-and-line-number list, a short prose summary, a patch, or a pass/fail verdict. Subagents that are not told what shape to return in tend to over-explain, which defeats the purpose of dispatching them in the first place.
4. Explicit boundaries. What should it NOT do? If you want research only, say "do not edit any files." If you want a fix but only within one directory, say that. Boundaries prevent scope creep, which is the main way a "quick subagent task" turns into an hour of unsupervised wandering.

Here is a brief that hits all four, for a research task:

Task: Determine whether our current rate-limiting middleware
(server/middleware/rateLimit.ts) is applied before or after
authentication in the request pipeline.

Context: We suspect unauthenticated requests are being rate-limited
using the same bucket as authenticated ones, which would explain
the 429 spikes reported in ticket ENG-4521. Do not assume — trace
the actual middleware registration order in server/app.ts.

Output: A short report (under 150 words) stating the actual order,
quoting the relevant registration lines, and a one-line verdict on
whether the suspicion in ENG-4521 is correct.

Boundaries: Read-only. Do not modify any files. Do not fix the
issue even if you find it — just report.

Notice what this brief does not do: it does not ask the subagent to "look around and see what you think." It names a hypothesis, names the file where the answer will be found, and constrains the output length. A subagent given this brief comes back with something you can act on immediately. A subagent given "can you check our rate limiting" will come back with a much longer, much less useful report, because it had to guess at what you actually wanted to know.

Pattern one: the reviewer and fixer pair

One of the most reliable subagent patterns is splitting a single unit of work into a writer and a reviewer, run as two separate subagents (or a subagent reviewing the main session's own work). The logic is simple: a model reviewing its own just-written code shares the same blind spots that produced the code in the first place. It is still anchored to its own reasoning. A fresh subagent, with no attachment to the implementation, looks at the diff cold.

The pattern in practice: your main session (or a subagent) implements a change. Then you dispatch a second subagent with a brief like "review this diff for correctness bugs, edge cases the tests do not cover, and any place error handling was skipped — do not praise what is good, only report problems, cite file and line for each." That subagent comes back with a list. You (or a third "fixer" subagent) address the list.

The reason this works better than asking the same context to "double check your work" is context isolation again: the reviewer subagent has never seen the reasoning that led to the implementation, so it is not primed to agree with it. It only sees the end state — the diff — the same way a human reviewer on your team would. This is also why code review tooling built on top of Claude Code tends to spin up a dedicated review pass rather than just asking the implementing session to self-critique.

A variant of this pattern extends to three roles: an implementer, a reviewer, and a fixer that only applies the reviewer's findings without re-litigating them. Splitting fixing from reviewing keeps the fixer focused and prevents it from "fixing" things the reviewer did not actually flag as broken.

Pattern two: parallel independent research

The clearest case for subagents is when you have several questions that do not depend on each other's answers. If you are evaluating a new library, you might want to know: does it handle streaming responses, what is its bundle size impact, how does its error handling compare to what you have now, and are there known issues with the framework you are using. These four questions do not need to be answered in order, and none of them benefits from being answered in the same context as the others — the bundle-size research does not need to see the streaming research's intermediate exploration, and vice versa.

Dispatching four subagents at once, each with one of these questions as its brief, gets you four independent, isolated investigations running concurrently. Each one reads whatever it needs to read, and each one reports back a short answer. Your main session ends up with four clean paragraphs instead of the combined, tangled context of four sequential investigations.

Conceptually, dispatching that fan-out looks like this:

Dispatch subagent A: "Does library X support streaming responses
out of the box, or does it require a wrapper? Answer in 3 sentences
with a citation to the relevant doc section."

Dispatch subagent B: "What is library X's minified+gzipped bundle
size, and how does it compare to our current dependency (name it
in your answer)? Answer in 3 sentences."

Dispatch subagent C: "Search our codebase for how we currently
handle retry-on-failure for HTTP calls. Report the pattern used
and which files implement it, in under 100 words."

Dispatch subagent D: "Are there open GitHub issues on library X's
repo describing incompatibility with our framework's SSR mode?
List any found with issue numbers, or state none found."

# All four run concurrently. Main session waits for all four
# reports, then synthesizes a single recommendation from the
# four short answers — none of the four investigations' raw
# exploration ever entered the main context.

The synthesis step at the end is important and is not itself a subagent task — that decision-making belongs in your main session, where you have the full picture and are the one accountable for the recommendation. Subagents gather; you decide.

Pattern three: the swarm for mechanical migrations

The third pattern is for large, repetitive, mechanical changes — the kind where the same transformation needs to happen in fifty files and the risk is not that any single change is hard, it is that doing fifty of them in sequence in one context will bloat that context past the point of being useful, and a tired context makes mistakes on file forty-eight that it would not have made on file three.

A swarm pattern breaks the fifty files into batches — sometimes one subagent per file, sometimes one subagent per logical group of files — and dispatches them concurrently, each with an identical brief that differs only in which files it targets. Because the transformation is mechanical (rename an import, update a deprecated API call, add a standard header), each subagent's job is narrow enough that it does not need much context to do it correctly, and the isolation means subagent twelve does not get slower or sloppier because of what happened in subagent eleven.

The practical caveats matter here. First, only use a swarm when the change really is mechanical and well-specified — if the transformation requires judgment that varies file to file, a swarm will apply inconsistent judgment across files with no way to reconcile it, because the subagents cannot see each other's decisions. Second, batch size matters: too many concurrent subagents editing an overlapping set of files invites merge conflicts and race conditions in version control, so it is worth partitioning by file or directory so no two subagents touch the same file. Third, always run a verification pass after a swarm — a subagent or a script that checks all fifty files ended up in the same shape — because a swarm optimizes for throughput, and throughput without a final consistency check is how you end up with forty-nine correct changes and one file that a subagent silently skipped.

Common mistakes with subagents

A few failure modes show up often enough to call out directly. The first is over-delegating trivial work — dispatching a subagent to change one line in a file you already have open. This adds latency and a parsing step for no benefit; the file was already in view, there was nothing to isolate.

The second is under-specifying the brief and then being surprised the subagent did something unexpected. A subagent that is told "clean up this module" will make judgment calls you did not ask it to make, because you left room for judgment. If you do not want scope creep, say so explicitly in the brief, as covered above.

The third is expecting a subagent to carry state between dispatches. Each subagent call is a fresh start unless you are explicitly continuing a specific prior subagent — you cannot dispatch one subagent, and then dispatch a second one later assuming it remembers what the first one found, unless you put that information in the second brief yourself. The isolation that makes subagents useful also means they do not accumulate shared memory automatically; your main session is the one place that persists across dispatches, so it is on you to carry forward what matters.

The fourth is treating subagent reports as ground truth without spot-checking. A subagent's summary describes what it believes it found, not necessarily an infallible account. For anything load-bearing — a security-relevant finding, a migration that touches production code — verify the specific claim before acting on it at scale, the same way you would not merge a human contributor's PR purely on the strength of their own description of it.

Building the instinct

The skill that separates people who get real leverage from subagents from people who just occasionally invoke one is not knowing the mechanics — dispatching a subagent is one tool call. It is developing the instinct for which tasks are "high exploration, low output" and therefore worth isolating, writing briefs precise enough that a subagent with zero shared history can execute them correctly, and knowing when a reviewer-fixer pair or a parallel fan-out or a swarm is the right shape for the work in front of you. That instinct comes from doing it enough times to see where it pays off and where it is just ceremony — and from paying attention to what comes back, not just what you sent out.

If you want a structured, hands-on path through this rather than accumulating the instinct one messy session at a time, that is exactly what our Claude Code Subagents course on teachyou.ai walks you through — real briefs, real migrations, real reviewer-fixer setups, taught by Pramod Dutta and Ira Menon, built for engineers who want to use Claude Code like a lead who delegates well, not like someone doing everything in one long, cluttered thread.