When to Use Subagents, and When Not To

Part of the Agent Engineering Playbook.

Subagents are where a lot of people first feel like they are doing "real" agent engineering. One thread becomes several. Specialized helpers appear. Work starts moving in parallel. The model feels less like a pair programmer and more like a tiny organization.

That can be powerful. It can also become theater very quickly.

Anthropic's subagent docs describe subagents as specialized AI assistants with their own system prompt, tools, and separate context window. That last part is the real reason they matter. A subagent is not just a different prompt. It is a different working memory.

Why Separate Context Is Valuable

Claude Code sessions get noisy for the same reason human projects do. Research, implementation, debugging, architecture discussion, and review all compete for the same working memory. Once enough of those modes pile into one thread, quality drops.

Subagents give you a way to split those modes apart.

This is useful when the delegated task is self-contained and has a clear output shape. It is especially useful for research, code review, focused debugging, or any bounded exploration that would otherwise clutter the main thread with transcripts, dead ends, and local detail.

In practice, the best subagent tasks have three properties:

They have a narrow goal. They need a distinct toolset or prompt style. And the parent agent can make progress once the result comes back as a summary rather than a giant dump of intermediate reasoning.

The Wrong Use Case: Delegating Unclear Thinking

If you are confused about the task, subagents rarely save you.

This is the pattern I see too often: the main agent receives a vague request, has no stable plan, and immediately starts spawning helpers. One subagent explores files. Another guesses at the fix. A third runs tests. Nobody owns the actual decision. The result looks busy and feels advanced, but it usually costs more tokens to get to the same confusion.

Delegation works best after the main thread has already identified the task boundary.

Think of it this way: the parent agent should keep responsibility for problem framing, sequencing, and integration. The subagent should own a bounded slice of execution or investigation. If you reverse that, you are not decomposing. You are outsourcing clarity.

How Claude Code Wants You to Define Them

Anthropic supports custom subagents in Markdown files with YAML frontmatter, stored either at .claude/agents/ for project-level agents or ~/.claude/agents/ for user-level agents. The essential fields are small: name, description, and optionally tools.

That simplicity is a hint.

A good subagent is not a giant persona document. It is a very explicit contract. The description tells Claude when it should delegate. The prompt tells the subagent how to behave inside that task boundary. The tool list constrains what it can touch.

The docs also recommend starting with the /agents interface, which is sensible. It lowers the friction of creating agents while making tools and permissions visible. But the design work still happens in the prompt and the boundary definition.

A Good First Subagent

My favorite starter subagent is a reviewer.

Why? Because review is naturally bounded, it benefits from a different tone than implementation, and it should not inherit every emotional commitment of the code-writing thread. A reviewer can inspect diffs, call out risks, and return a clean summary. It does not need to remember the full backstory of the feature unless the parent thread gives it that context explicitly.

That makes review a strong example of how subagents should feel: focused, separate, and easy to evaluate.

Debuggers are the next good category. Researchers can work well too, especially for large codebases. Broad "general engineer" subagents are usually a smell. If the role is that wide, it is often not actually a role.

When Not to Use One

Do not use a subagent if the parent thread is going to need every small decision anyway. Do not use one if the work requires constant back-and-forth context from the main conversation. Do not use one if the task boundary is so small that the overhead of delegation exceeds the work itself.

And definitely do not use one just because parallelism feels productive.

The real cost of a subagent is not only tokens. It is integration. Every delegated task creates a second problem: bringing the result back into the main flow without losing quality or duplicating work. If the result is hard to verify, hard to merge, or tightly coupled to another in-flight task, the subagent may have made the system slower rather than faster.

The Practical Rule

I use a simple rule now. A task is subagent-worthy if I can state it in one paragraph, define what "done" looks like, and describe the output format I want back.

For example:

"Inspect the authentication flow under src/auth, identify where refresh-token retries happen, and tell me whether a failed refresh can leave the UI in a partially logged-out state. Return file references and the most likely failure path."

That is a subagent task.

"Figure out everything wrong with our login system and fix it" is not.

Subagents Are a Step Toward Orchestration, Not the End of It

Once you have more than one subagent and more than one phase of work, you are already moving into orchestration, whether you call it that or not. Someone has to decide ordering, ownership, merge discipline, and verification. Someone has to manage handoffs.

That "someone" is often still the human. Sometimes it is the parent agent. In bigger systems it becomes a dedicated orchestration layer.

That is the next chapter. Read Orchestration Patterns for Real Agent Work when you are ready to think about the system above the subagent.