Claude Code Subagents: A Practical Orchestration Guide

This is for developers already running Claude Code day to day who keep hitting context limits, watching the model re-explain things it already knows, or waiting on slow serial workflows. If you want to know exactly when spawning a subagent pays off and when it just adds latency, read on.

Claude Code subagents let you hand off a chunk of work to a separate Claude instance with its own context window, its own tool access, and exactly one return message to your main thread. Used well, they cut token usage, keep your primary conversation focused on decisions instead of file contents, and let you run several investigations at once. Used badly, they burn three times the tokens on a task you could have finished inline in thirty seconds. This guide is about telling the two apart.

What Claude Code Subagents Actually Are

A subagent is not a different model or a different product. It is a fresh Claude Code session, spawned through the Task tool, that runs to completion and hands back a single summary. The parent thread never sees the subagent's intermediate tool calls: the file reads, the grep searches, the failed attempts. It only sees the final message.

That's the entire value proposition in one sentence: context compression. If an investigation would take 40 tool calls and 15,000 tokens of file contents to resolve, and you only need the answer, a subagent does the 40 calls in its own window and gives you the answer in 300 tokens.

The Task tool takes a handful of parameters worth knowing precisely:

• description - a 3-5 word label, mostly for logging and UI.
• prompt - the actual brief. This has to be self-contained, because the subagent cannot ask you anything mid-task.
• subagent_type - which agent definition to use (general-purpose, or a custom one from .claude/agents/).
• model - an optional override (for example, dropping to a cheaper/faster model for a mechanical task).
• isolation - "worktree" spins up a separate git worktree so the agent edits an isolated copy of the repo.
• run_in_background - lets the agent run asynchronously while you keep working, notifying you on completion.

When to Delegate vs Stay Inline

The single most common mistake is delegating something you already know how to do directly. If you know the file path, use Read. If you know the exact string to change, use Edit. A subagent adds a full agent-startup cost (reading your CLAUDE.md, re-establishing context, re-orienting in the repo) before it does anything useful, so it only pays off when the task is genuinely open-ended or genuinely parallelizable.

The rule of thumb: subagents earn their keep on search cost and parallelism, not on execution of a task you can already point at directly.

The Built-in Agent Types (and How to Pick One)

Claude Code ships a general-purpose agent by default, and most setups add specialized ones through .claude/agents/*.md files: a reviewer, an explorer, a test runner, a security auditor. Each definition controls three things that matter: which tools the agent can touch, which model it runs on, and what triggers it.

If nothing fits, general-purpose with a tightly scoped prompt beats a half-configured custom agent. Custom agents earn their cost when you run the same shape of task often enough that a fixed tool allowlist and a canned system prompt save you from re-explaining constraints every time.

Parallel Fan-Out: Running Multiple Subagents at Once

This is the part most people miss: subagents only run in parallel if you invoke them in the same assistant turn. Two Task calls in two separate messages run serially, because the second call waits for the first to return before the model even decides to make it. To get real concurrency, batch the invocations into one response.

# Single turn, two independent Task invocations:
Task({
  description: "Security review of auth module",
  subagent_type: "security-scanner",
  prompt: "Audit src/auth/* for missing input validation, exposed
           internal errors, and rate limiting gaps. Report findings only,
           do not fix. Under 300 words."
})
Task({
  description: "Performance review of image pipeline",
  subagent_type: "general-purpose",
  prompt: "Review src/lib/imagePipeline.js for unnecessary re-renders
           and unbounded loops. List concrete line numbers. Under 300 words."
})

Both agents start immediately, run against their own context windows, and return independently. On a real audit this is the difference between 12 minutes of serial waiting and 4 minutes of parallel waiting, because the bottleneck is wall-clock time per agent, not your local CPU.

Two caveats worth internalizing. First, parallel agents that touch overlapping files can produce edits that conflict, so reserve write access for one agent at a time on a given file, or isolate each with isolation: "worktree". Second, more parallelism is not free: each agent independently re-reads shared context (your CLAUDE.md, shared config files), so five agents means five copies of that overhead, not one.

Writing Custom Subagents

A custom agent is a Markdown file with YAML frontmatter, usually under .claude/agents/. The frontmatter controls routing and permissions; the body is the system prompt the subagent operates under.

---
name: code-reviewer
description: Reviews a diff for bugs, security issues, and regressions
  before commit. Use PROACTIVELY after any nontrivial code change.
tools: Read, Grep, Glob, Bash
model: sonnet
color: orange
---

You are a senior reviewer. Given a diff, find concrete defects:
wrong logic, missing null checks, broken error handling, security
gaps. Do not comment on style. Report each finding with file, line,
and a one-sentence failure scenario. If nothing is wrong, say so.

The description field matters more than people expect: it's what the orchestrating model reads to decide whether this agent applies to a given task, so write it as a trigger condition, not a marketing blurb. "Use PROACTIVELY" language genuinely changes how often the model reaches for it unprompted.

Real Patterns That Work

Research fan-out into synthesis

Spawn 3-4 read-only agents to investigate independent parts of a question (how is auth handled, how is state managed, where does data validation happen), then synthesize their reports yourself in the main thread. This is the single highest-leverage pattern for onboarding onto an unfamiliar codebase.

Isolated worktree for risky refactors

For a refactor you're not fully sure will land clean, spawn an agent with isolation: "worktree". It edits a disposable copy of the repo. If it's good, you merge; if not, the worktree is discarded with zero cleanup cost to your working directory.

Background long-running agents

For anything that takes minutes (a full test suite rewrite, a large migration), use run_in_background: true and keep working on something else. You get notified on completion instead of blocking the conversation.

Write-then-verify

One agent implements, a second and independent agent reviews the diff without seeing the first agent's reasoning, only the resulting code. This catches a class of bugs that self-review misses, because the reviewing agent has no attachment to the approach taken. This pairs naturally with a repeatable test harness; see our guide on eval-driven AI development if you want this checked systematically instead of ad hoc.

Common Pitfalls

• Non-self-contained prompts. A subagent cannot ask "which file did you mean?" It has no memory of your conversation. Every prompt has to name file paths, line numbers, and constraints explicitly, the same discipline covered in prompt engineering for business teams applies doubly hard here because there's no back-and-forth to fix a vague ask.
• Trusting the summary over the diff. An agent's final message describes what it intended to do, not necessarily what it did. Always check the actual file changes before treating a delegated task as done.
• Redundant rediscovery. If three agents each independently grep the whole repo for the same pattern, you've tripled a cost you could have paid once by doing the search yourself and handing each agent the result.
• Delegating single-file, known-location edits. This is pure overhead: agent startup cost with no compression benefit, since there was nothing to compress.
• Overlapping writes. Two parallel agents editing the same file is a race condition waiting to happen. Split by file or isolate with worktrees.
• No re-verification after a batch. If you fan out five agents and merge their work without running the actual app or test suite, you've just multiplied your blind spots by five.

Cost and Latency Trade-offs

The pattern to notice: subagents trade token cost and interactivity for context compression and parallel wall-clock time. That trade is worth it exactly when the alternative is either an unmanageable main-thread context or a long serial queue of independent work.

FAQ

What's the difference between a subagent and just asking Claude Code directly?

Asking directly keeps everything in one context window: every file read, every search result, every failed attempt stays visible and grows your context. A subagent runs those same steps in an isolated window and only returns a final summary, so the main thread stays lean. The tradeoff is you lose the ability to redirect the work mid-stream.

Can subagents call MCP servers or only built-in tools?

Yes, a subagent's tool access is whatever its agent definition grants, and that can include MCP-provided tools scoped the same way built-in tools are. See connecting MCP servers to Claude Code for how tool permissions are wired up per agent, since the same allowlist mechanism applies to subagent definitions.

How many subagents can I run in parallel realistically?

There's no hard cap in the tool itself, but practically 3-5 concurrent agents is the sweet spot for most tasks. Beyond that, coordination overhead (merging findings, avoiding file conflicts) usually costs more than the added parallelism saves, and you start hitting per-account rate limits on the API side.

Do subagents remember previous conversations?

No. Each Task invocation starts a fresh session unless you explicitly resume a named agent with a follow-up message. That's why the prompt has to carry all necessary context: file paths, what's already been ruled out, and what "done" looks like.

Is this only for professional developers, or does it matter for less technical teams?

The mechanics are developer-facing, but the decision of when to delegate versus do something directly applies to anyone directing Claude Code, technical or not. If you're managing a team through Claude Code without writing code yourself, start with Claude Code for non-developers and treat this guide as the deeper mechanical layer underneath it.

Should I build custom agents or just use general-purpose every time?

Start with general-purpose and a well-scoped prompt. Only invest in a custom agent definition once you notice yourself writing the same constraints (tool restrictions, tone, output format) in prompt after prompt for the same recurring task. At that point a fixed agent file pays for itself within a week. If you're still comparing Claude Code against other agentic coding tools for your stack, our 2026 vibe coding tools comparison covers where subagent support differs across the field.

Ready to Put This to Work?

If you're building or scaling an AI-assisted workflow and want a second pair of eyes on your agent architecture, book a free 30-minute call. Reach out through the contact form or message directly on WhatsApp.

Sources

• Claude Code documentation
• Claude Code subagents
• Anthropic model overview
• Model Context Protocol specification