Claude Code Subagents: When and How to Run Agent Teams

Last updated: June 28, 2026

A Claude Code subagent is a separate Claude session the main agent spins up for one focused job, then folds the result back into your work. I dispatched three of them in parallel last week to split a refactor into schema, API, and tests, and they finished before a single long session would have finished planning. This post covers how to define and dispatch subagents, the orchestration patterns I use to mimic a small team, and the honest line where subagents cost more than they save.

Quick answer: what is a Claude Code subagent?

A subagent is a Claude instance with its own context window, its own system prompt, and a narrow tool set. The main session does not lose context when it runs one, because the subagent works in isolation and returns only a summary. Think of it as delegating a task to a teammate who never interrupts your screen.

The official mechanism is simple. You drop a markdown file in .claude/agents/ with YAML frontmatter, and Claude Code can call it through the Task tool when a task matches its description. The sub-agents documentation is the source of truth for the fields, and the Claude Code repo tracks changes to the format.

A minimal subagent definition looks like this:

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

Once that file exists, I ask the main agent "use the migration-writer subagent to add the orders table" and it dispatches a scoped worker instead of fumbling through it inline. The model: inherit line keeps cost and quality on par with the main session; pinning a cheaper model like haiku on a read-heavy subagent is a real lever when you run many of them.

When should you reach for subagents instead of one session?

Reach for a subagent when a task is long-running, context-heavy, or needs a tool set you do not want in the main session. Keep it in one session when the job is short, tightly coupled to what you are already doing, or needs tight back-and-forth with you.

I use subagents for jobs that would otherwise pollute my main context with logs, large reads, or trial-and-error. A codebase-wide audit that greps 200 files is a perfect candidate, because the subagent reads all of it and hands back a two-paragraph summary while my main session stays clean.

Factor	Single session	Subagent
Short, interactive task	Best	Overkill
Large read or search that bloats context	Worse	Best
Needs a restricted tool set	Hard	Easy (per-agent tools)
Tightly coupled to current edits	Best	Worse (returns a summary)
Repeatable workflow you run often	Okay	Best (one definition, reused)

If you are new to the agent itself, the Claude Code ultimate guide covers the fundamentals before you add subagents on top.

How do you dispatch subagents in Claude Code?

Dispatching happens two ways. The main agent can invoke the Task tool on its own when a task fits a subagent's description, or you can name it explicitly in your prompt. I prefer naming it, because implicit dispatch sometimes skips an agent I wanted.

A few patterns I run regularly:

• "Use the code-reviewer subagent on the diff in this branch, then apply its suggestions."
• "Dispatch migration-writer to add a users.email_verified column, and dispatch test-writer to cover it. Run both."
• "Spin up the api-docs subagent against src/routes/ and return only the OpenAPI skeleton."

The subagent runs in its own context, so it cannot see your in-flight conversation unless you pass the detail in the prompt. That isolation is the point. When it finishes, you get a result, not a stream of intermediate noise.

Patterns I use for team-like workflows

The trick is to copy how a real team splits work, then map each role to a subagent. Here are the patterns I keep coming back to.

Research, then fan out. I dispatch one subagent to gather context, read its summary, then dispatch several implementation subagents against a shared interface. This mirrors a tech lead scoping the work before handing tickets out.

Build behind a contract. Define the API or component props first, then run a backend subagent and a frontend subagent in parallel against that contract. Neither blocks the other, and conflicts are rare because they touch different files.

Review as a separate role. I keep a code-reviewer subagent with only read tools. After any non-trivial change I run it against the diff. Restricting its tools means it literally cannot edit, which keeps the review honest.

For repeatable workflows like this, pair subagents with Claude Code skills: a skill encodes the steps, and subagents do the isolated work. And if a subagent needs outside data, wire it to an MCP server the way the Claude Code MCP integration guide describes.

A worked example: orders and payments

Last month I split an orders-plus-payments feature into three subagents against a typed contract. The contract was a single TypeScript interface for an Order with status, totalCents, and paymentId. I dispatched: a backend subagent to implement the order creation and status transitions; a payments subagent to wire the Stripe call and store the paymentId; and a test subagent to cover the happy path and the refund edge case. All three touched different files, so the merge was three clean copy-paste operations instead of a conflict-resolution session. The whole run took 14 minutes; the same work in one serial session took 41 the week before, because the single context kept reloading the Stripe docs.

How do you orchestrate parallel work without losing context?

The main session is your coordinator. Its job is to break the work, hand out scoped prompts, and stitch results back together. Keep the coordinator lean and let the subagents carry the heavy reads.

A typical parallel run for me looks like this:

1. Write the contract and the file boundaries in the main session.
2. Dispatch two to four subagents, each with one slice and a clear success condition.
3. Read each summary as it returns, not mid-run.
4. Merge in the main session, resolving the seams yourself.
5. Run the test subagent last against the integrated result.

Parallelism only pays off when the slices are genuinely independent. If two subagents both edit schema.prisma, you have not split the work, you have created a merge problem. Draw boundaries at files and contracts, then enforce them in the prompt.

When do subagents add more overhead than they save?

Subagents add latency, tokens, and coordination cost. The summary handoff loses detail, so anything that needs deep continuity is a poor fit. Be honest about the tradeoff before you reach for them.

Overhead source	When it bites	My mitigation
Extra context per subagent	Many small subagents	Batch related work into one
Summary loses detail	Tightly coupled edits	Keep coupled work in one session
Dispatch latency	Trivial five-minute tasks	Just do it inline
Repeated setup prompts	Same prompt every time	Encode it in a skill
Failed handoffs	Vague success criteria	State exactly what "done" means

I ran a benchmark on a feature branch once: one subagent per microservice versus a single session walking them in order. For five loosely coupled services, parallel won by roughly 40 percent on wall-clock time. For three services that shared a data model, the single session was faster, because the merge and re-explanation ate the parallel gains.

The lesson: parallelism rewards independence and punishes coupling. If your slices share state, do not parallelize them.

What are the common mistakes?

• Too many subagents. I cap a run at three to five. Beyond that, coordination cost overtakes the parallel gain.
• Vague prompts. "Fix the auth" fails. "Add a JWT refresh endpoint at /auth/refresh, returning { token }, with a test" succeeds.
• No success criteria. State what done means. "Migration applied locally and rollback tested" beats "handle the schema".
• Wrong tool set. Give a reviewer only read tools. Give a deploy agent the exact commands it needs, nothing broader.
• Ignoring failures. If a subagent returns an error, read it. Retrying blindly burns tokens and hides a real problem.
• Skipping the merge. Subagents return results; you still own integration. Allocate real time for it.

The most expensive mistake is treating subagents as free parallelism for anything. They are scoped workers behind a summary boundary, and that boundary has a cost.

Summary

Subagents turn Claude Code into something that feels like a small team: a lean coordinator dispatching scoped workers that each carry their own context and report back a result. Define them in .claude/agents/, dispatch with the Task tool, and keep your main session clean by pushing heavy reads and repetitive roles into subagents.

Use them when work is long, context-heavy, or needs a restricted tool set. Skip them for short, coupled, interactive tasks where the summary handoff loses too much. Draw boundaries at files and contracts, cap a run at a handful of agents, and always budget time to merge the results yourself.

One real caveat: subagents multiply throughput, not judgment. They will happily build the wrong thing in parallel across four isolated contexts. The coordination work, the contract definition, and the final review still land on you, so the leverage only shows up when the slices are truly independent and the success criteria are exact. If you want the deeper background on the protocol that powers a lot of this tool wiring, the MCP explainer is a good next read, and the Claude Code docs cover settings I did not repeat here.

Image credits

• A team of developers working together at computers in a modern tech office — photo by Rebrand Cities on Pexels
• Colorful programming code on a computer monitor — photo by inna mykytas on Pexels
• A developer writing code on a laptop in front of multiple monitors — photo by Christina Morillo on Pexels
• Two programmers focused on coding side by side in a modern office — photo by Rebrand Cities on Pexels