April 20, 2026Samarth at CLSkillsclaude codeagent teamssubagents

Agent Teams vs Subagents in Claude Code: When to Use Which (Honest Decision Framework)

Claude Code now has both subagents (fan-out) and Agent Teams (multi-session coordination). They look similar and do different things. Here's a decision framework based on real usage — with the failure modes nobody's documenting.

Agent Teams vs Subagents: Two Features, Different Problems

If you use Claude Code, you now have two overlapping-sounding primitives: subagents (which have been around for months) and Agent Teams (experimental, rolled out March-April 2026). Both involve multiple Claude instances working on your task. They solve different problems. Picking wrong costs you tokens and clarity.

After a week of using both on real work, here's the honest decision framework.

TL;DR Decision Matrix

Situation	Use
Single narrow subtask needs a specialist context	Subagent
3+ parallel research questions on independent subsystems	Agent Teams
You want a report back, then main Claude continues	Subagent
Teammates need to message each other mid-task	Agent Teams
Quick one-off analysis ("summarize this file")	Subagent
Multi-hour refactor across 5+ files	Agent Teams
You want to cap context blow-up from a deep-dive	Subagent
Competing hypotheses that need adversarial cross-check	Agent Teams
Task under 20 minutes	Neither — just use one Claude

Rule of thumb: subagents are function calls, Agent Teams is threads with shared memory. If that distinction maps to your task, the answer is usually obvious.

How The Two Actually Differ

Subagents (established)

Main Claude spawns a subagent with a focused prompt.
Subagent has its own context window, limited to that task.
Subagent does the work, returns a report.
Subagent disappears. Main Claude synthesizes.
No peer-to-peer messaging. Subagents don't know each other exist.
No shared state. Each subagent is isolated.
Best for: protecting main context, delegating narrow specialized work.

Agent Teams (new, experimental)

You define a team of 2-5 teammates, each with a role.
Every teammate has its own context window, but they persist for the full task.
Teammates send direct messages to each other via a mailbox system.
Shared task list (.claude/team/tasks.json) with basic file-locking.
Teammates self-claim tasks.
You cycle between teammates in one terminal (Shift+Down) or split into tmux panes.
Best for: parallel work with coordination, competing hypotheses, long-running multi-component tasks.

Full setup walkthrough for Agent Teams is in my deep-dive guide.

Five Real Scenarios, Mapped

These are actual tasks I or people in my circle have done in the last 2 weeks. Worked examples beat abstract rules.

Scenario 1: "Write tests for this 400-line file."

Winner: Subagent.

One narrow task, well-bounded, no coordination needed. Spawn a subagent with the test-writing skill, let it return the test file, main Claude reviews and commits. Agent Teams here is 3-4x overhead for zero benefit.

Scenario 2: "Migrate auth from NextAuth v4 to v5 — 12 files affected."

Winner: Agent Teams.

Each teammate owns a subsystem (middleware, callbacks, session handling, types). They message each other when one subsystem's changes affect another ("I changed the session shape, the middleware needs to adapt"). The shared task list tracks what's in-flight. This is the canonical Agent Teams use case.

Could you do it with subagents? Yes, but the main Claude becomes the bottleneck — every cross-subsystem question has to flow through it.

Scenario 3: "Debug why 8% of API requests return 502 under load."

Winner: Agent Teams.

Multiple competing hypotheses (connection pool, timeout config, upstream rate limits, memory pressure). Each teammate owns one hypothesis, runs independent experiments, reports findings. The team lead aggregates. Works because the hypotheses are parallel, not sequential.

Subagents would serialize this — you'd test one hypothesis, return, test the next, etc. Slower and you lose the cross-hypothesis insight that comes from comparing results.

Scenario 4: "Summarize these 15 blog posts and find the common theme."

Winner: Subagent (batched).

Classic fan-out / fan-in. Spawn a subagent per batch of posts, get summaries back, main Claude does the synthesis. Agent Teams adds no value — there's no coordination during the summarization, only at the end. And subagents protect your main context window from 15 full blog posts.

Scenario 5: "Review this PR for architecture + security + performance + test coverage."

Winner: Depends on complexity.

Small PR (< 200 lines): one Claude session with multiple prompt codes in sequence. Don't overcomplicate.

Medium PR (200-800 lines): subagents — spawn one per review dimension, collect reports, synthesize. Each subagent has focused context.

Large PR (800+ lines) with cross-cutting concerns: Agent Teams — the architecture reviewer needs to check something with the security reviewer before finalizing ("this change exposes the key to the client — confirm it's not a vector I'm missing"). That cross-talk only works in a team.

The Failure Modes

When subagents fail you

Subagent outputs contradict each other and main Claude has to arbitrate without context on how each reached its conclusion. Agent Teams prevents this because teammates can argue it out.
Main context saturates anyway because you had 8 subagents each returning 3KB reports. Subagent isolation protects against one deep-dive; 8 shallow dives still add up.
Synthesis quality degrades at the main Claude level when too many subagent outputs pile up. Main Claude starts skimming.

When Agent Teams fails you

Teammates don't message each other unless you explicitly prompt them to. The feature is there; the discipline to use it isn't automatic. New users often end up running 3 parallel Claudes who never talk, which is worse than 1 Claude.
Token costs balloon. 4 teammates at Opus 4.7 pricing on a 2-hour task is real money. If the task didn't need coordination, you just paid 4x for nothing.
/resume doesn't work on Agent Teams yet (known limitation). If your session dies, teammates die. Task list survives in .claude/team/tasks.json but context windows don't.
Race conditions in the shared task list are rare but happen — I saw one in 8 runs. Two teammates claimed the same task in a ~50ms window. Spot-check the task list.

How To Decide In 10 Seconds

Ask three questions about the task:

Can it be parallelized? If no → one Claude. If yes → keep going.
Do the parallel parts need to talk to each other mid-task? If no → subagents. If yes → Agent Teams.
Is it worth 3-5x the token cost for coordination? If no → subagents. If yes → Agent Teams.

That's the decision. Most tasks fall into "one Claude is fine." A meaningful fraction fall into "subagents." A smaller but real fraction genuinely benefit from Agent Teams.

What Prompt Patterns Actually Matter For Each

From my own testing over the last month (methodology here):

For subagents:

Give each subagent an explicit success criterion. "Return a report of X, Y, Z in this shape." Vague goals produce vague reports and main Claude can't act on them.
Use CRIT on main Claude AFTER it synthesizes subagent reports — catches synthesis errors before they cascade.

For Agent Teams:

Force at least one cross-teammate message per major task. Prompt: "Before marking the task done, message at least one other teammate with something you learned that affects their work."
Role-lock the teammates. "The reviewer teammate never proposes solutions, only critiques." Prevents convergence where all teammates become generic Claudes again.
Use /blindspots on a dedicated "auditor" teammate whose only job is surfacing what others missed.

Full library of tested prompt patterns is in the Cheat Sheet. Pro tier has the Agent Teams-specific combo strategies.

My Prediction

Agent Teams is rough around the edges right now — experimental flag, no resume, one team per session. But the primitive is the right primitive. 12 months from now this will be the default way serious Claude Code users work on non-trivial tasks. Subagents will still exist but become the "lightweight narrow task" tool.

Start getting intuition now. The learning curve is real.

Questions about a specific Agent Teams vs subagents decision? Reply on the newsletter — I answer every email.

Want the full research library?

120 tested Claude prompt codes with before/after output and token deltas.

See the Cheat Sheet — $15