Inside Claude Code subagents: context, control, and common mistakes

Context: How Isolation Works

A common misconception is that subagents are mini-experts — smaller, specialized Claudes that know more about a topic than the main thread. In reality, Claude already has all the knowledge in every context window. Subagents don’t add capability. They add isolation.

When you launch a subagent, it runs in a separate context window. It receives a task, explores independently — reading files, searching code, running commands — and returns only a summary. All intermediate work stays in the subagent’s context and is discarded when it finishes.

Why does this matter? Context windows are finite. Every file read, every tool call, every intermediate result fills your main thread’s context. As it fills, the conversation degrades — the agent loses track of earlier decisions, makes contradictory choices, and produces worse output. Subagents are a pressure valve: they offload exploratory work so the main thread stays clean.

This reframes how you should think about subagent design. Don’t design them around expertise. Design them around what work you don’t need to see.

Control: The Description Field

Every subagent has a description field in its config. Most people treat it as metadata — a label for what the subagent does. It’s actually the highest-leverage control surface you have.

The description plays two roles. First, it controls when the main agent launches the subagent. The name and description of every available subagent are included in the main agent’s system prompt — this is how it decides which subagent to use and when.

Second — and this is the non-obvious part — the description shapes what instructions the main agent writes when it delegates a task. When the main agent launches a subagent, it composes an input prompt. It uses the description as guidance for writing that prompt. So the description doesn’t just control triggering — it programs the parent agent’s delegation behavior.

Use this agent
for code review.

You must tell the
agent precisely which
files you want it to
review. Return sources
that can be cited.

The generic version leaves the main agent to figure out scope on its own — it will write a vague delegation prompt like “use git diff to find the current changes.” The steering version causes the main agent to write a specific prompt that lists actual files and requests citable output. The description text steered the parent’s behavior.

Common Mistakes: Three Anti-Patterns

”Expert” personas

Naming a subagent “Senior Staff Engineer” or “Python Expert” adds zero capability. Claude already has that knowledge in every context window. There is nothing a so-called expert subagent can do that your main thread can’t do directly. Personas don’t unlock new abilities — they just add noise to the system prompt.

Test runners

This one is counterintuitive: test runner subagents are empirically the worst-performing pattern. When tests fail, you need the full output to diagnose the issue. A subagent that returns “3 tests failed” forces you to build additional tooling just to get information that would have been visible in direct output. Testing has shown this pattern performed worse among all subagent configurations.

Sequential pipelines

A three-agent pipeline — reproduce bug → debug → fix — sounds clean on paper. It fails in practice because information degrades at every handoff. Bug fixing almost always depends on discoveries from the previous step: the specific error message, the stack trace, the unexpected state. Each summarization boundary loses critical context. If steps depend on each other, keep them in the main thread.

What Actually Works

Structured output creates stopping points

The single most impactful improvement for any subagent is a defined output format in its system prompt. Without one, subagents don’t know when they’re done. They lack internal stopping criteria and tend to keep researching, reading more files, exploring more paths — running far longer than necessary.

A structured format solves this by creating a checklist. Once every section is filled in, the subagent knows it can stop. It also ensures the summary that returns to the main thread is actually usable.

Return your review as:

## Summary
## Critical Issues
## Major Issues
## Minor Issues
## Recommendations
## Approval Status
## Obstacles Encountered

Obstacle reporting prevents knowledge loss

When a subagent discovers a workaround during its work — a dependency quirk, a command that needs a special flag, an environment issue — those details need to appear in its summary. If they don’t, the main thread has to rediscover the same solutions on its own. That’s wasted time and wasted tokens.

The fix is simple: add an explicit “Obstacles Encountered” section to the output format. This surfaces setup issues, workarounds, commands needing special flags, and dependency problems reliably.

The Decision Rule

When deciding whether to use a subagent, there’s one question that matters: does the intermediate work matter to your main thread?

If the answer is no — you just need the result and don’t care about the journey — delegate it. A research subagent can read dozens of files, trace function calls, and explore code paths. All that exploration stays in the subagent’s context. Your main thread gets a clean answer.

If the answer is yes — you need to see and react to what happens along the way — keep it in the main thread.

Delegate

• Research — “Where is JWT validated in this codebase?”
• Code review — A fresh context window catches things the main thread misses because it wrote the code
• Custom system prompts — Styling agents that pre-load design system files, copywriting agents with tone guidelines

Keep in main thread

• Debugging — You need the full error context to diagnose
• Test runs — Failure output must be visible, not summarized away
• Sequential workflows — Each step depends on what the previous step discovered

One special case worth noting: code review. Claude reviews code more effectively when presented in a separate context from where it was written. If you built a feature over many turns in your main thread and then ask that same thread to review it, the feedback tends to be weak — it was involved in creating the code and has trouble seeing it with fresh eyes. A reviewer subagent sees the changes in a clean context, free from the history of how they were written.