Claude Code agent teams vs subagents: which one you actually need

Claude Code now has three ways to run more than one agent, and they are not interchangeable. Subagents return a summary; agent teams are independent sessions that message each other; worktrees are you doing it by hand. What each is for, what an eight-agent pipeline taught us about making multi-agent work reliable, and the enable-flag trap that silently breaks orchestration.

"Claude Code agents" now means three different things, and picking the wrong one is the most common way multi-agent setups turn into a token bonfire. There are subagents, which a session spawns to do a bounded job and report back; agent teams, an experimental mode where several full Claude Code sessions share a task list and message each other; and manual parallel sessions, which is you running claude in several git worktrees. Each is the right tool for a different shape of work.

We have run a multi-agent pipeline on Claude Code for a while (product manager, architect, engineer, QA, reviewer, deployer, plus a debugger that gets routed in when QA fails), so this is written from the operating seat rather than the announcement post. First what each layer is, then what running one daily taught us, then the trap.

Layer 1: subagents, the default

A subagent is a markdown file with frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (personal). Here is one of ours, trimmed:

---
name: qa_engineer
description: Runtime testing and bug finding. Starts the dev server, tests real behavior against PRD acceptance criteria, and reports bugs found.
tools:
  - Read
  - Write
  - Edit
  - Bash
---

The body is the system prompt. When the main session decides a task matches the description (or you name the agent, or @-mention it), Claude Code starts the subagent in a fresh context: its own system prompt, the delegation message, your CLAUDE.md hierarchy, and nothing from the conversation so far. It works, and only its final result comes back to the caller. That isolation is the point: a subagent can read forty files and run a hundred commands, and your main context absorbs one paragraph.

What the frontmatter buys you beyond the prompt: a tools allowlist (a reviewer that cannot edit is a reviewer you can trust), a model override so mechanical work runs on a cheaper model, permissionMode, maxTurns, preloaded skills, and isolation: worktree for subagents that must edit in parallel without colliding. Built-ins cover the common cases already: Explore (read-only, fast codebase search), Plan (the research agent behind plan mode), and general-purpose.

Practical limits worth knowing: 20 concurrent subagents by default, three levels of nesting, and background subagents run with a reduced tool set. Completed subagents can be resumed by name, with their transcript intact, which turns "review the auth module" followed by "now continue into authorization" into one continuous worker rather than two cold starts.

Use subagents when the work is self-contained, only the result matters, and you want to protect the main context. That is most delegation, most of the time.

Layer 2: agent teams, the experiment

Agent teams are off by default and gated behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment or settings.json. With it on, you ask for teammates in plain language ("spawn three teammates to review this PR: one on security, one on performance, one on tests") and the lead session spawns full, independent Claude Code sessions. They each have their own context window, load CLAUDE.md and your project config like any session, share a task list with dependencies and file-locked claiming, and message each other directly through per-agent mailboxes. You can open any teammate from the agent panel and talk to it yourself, and split-pane mode gives each one a tmux or iTerm2 pane.

The difference from subagents is not "more agents"; it is who coordinates. Subagents report to a caller that manages all the work. Teammates self-coordinate: they claim tasks, notify the lead when idle, send findings to each other, and can be required to submit a plan for the lead's approval before editing. The documentation's best example is adversarial debugging: five teammates each holding a hypothesis, told to disprove each other's theories, converging on a root cause a single agent would have anchored past.

The costs are equally real. Every teammate is a separate Claude instance, so tokens scale linearly with team size; coordination overhead grows with it; the lead is fixed for the session; in-process teammates do not survive /resume; and task status can lag, blocking dependents until someone nudges. The guidance to start with three to five teammates on research or review tasks, before trusting a team with parallel implementation, matches our experience exactly.

Use agent teams when the work benefits from agents talking to each other: parallel review with different lenses, competing hypotheses, or cross-layer features where each owner needs to negotiate an interface. If the agents never need to talk, you wanted subagents.

Layer 3: worktrees, by hand

The oldest option is still the most predictable: git worktree add ../app-feature, open a claude session in each, and coordinate in your own head. No shared task list, no messaging, no experimental flag; just the workflow discipline of two real lanes maximum and notifications for finished and blocked. When the tasks are genuinely independent and you want to steer each one, this beats both automated options on reliability per token.

What running a pipeline taught us

Our pipeline is subagents plus a thin orchestrator, and the design choices that survived contact with daily use are the ones worth passing on.

Routing lives in code, not in the model. Each agent ends its run with a structured status block (SUCCESS, FEATURE_COMPLETE, FAILED, BLOCKED, NEEDS_USER_INPUT) and the orchestrator decides what runs next from a fixed table: engineer to QA, QA failed to debugger back to QA, and so on. The model's own suggestion for the next agent is advisory and gets ignored when it disagrees. Letting agents route themselves was the first thing we tried and the first thing we removed; a pipeline that can talk itself into skipping QA will.

Agents are stateless; handoffs are files. Because a subagent starts cold, everything it needs has to be handed to it explicitly. We pass a handoff note (decisions, requirements, artifacts, blockers) written to disk by the previous agent and injected into the next prompt. The same rule that makes skills work applies here: chat is steering, files are state, and an agent that starts from a file is reproducible in a way an agent that starts from scrollback never is.

One feature per run. The engineer implements exactly one unchecked item from the plan, verifies it, and signals FEATURE_COMPLETE so the orchestrator runs it again. Big prompts produce big drift; small runs keep the context short and the failure blast radius small, which is the same lesson as small commits.

Gates are hooks, not hopes. Agent teams ship lifecycle hooks (TeammateIdle, TaskCreated, TaskCompleted) that can reject a completion with feedback, and subagents can carry their own hooks in frontmatter. A TaskCompleted hook that exits 2 when the build is red is the multi-agent version of the gates in our hook recipes post: a rule the model cannot forget.

Keep the human gates. Ours pauses after the product spec and after the technical design, and deployment requires an explicit yes. Everything between gates runs unattended; everything at a gate waits. That split is what makes it safe to walk away, and walking away is the entire reason to build the pipeline.

The trap: the flag changes ordinary delegation

One behavior that is easy to miss and expensive to hit: with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 set, any subagent Claude gives a name launches as a teammate, even in delegation you never framed as team work. Teammates report differently: the lead gets an idle notification with no output, instead of the subagent's result. An orchestration that waits on subagent results stalls, quietly. If your pipeline froze after you tried agent teams last week, this is why; set the variable to 0 and Claude Code rereads it on the next spawn without a restart.

How to pick

• Bounded job, only the result matters: subagent. Add a tools allowlist and, for mechanical work, a cheaper model.
• Agents need to argue, negotiate, or split ownership of a feature: agent team, three to five members, research or review first.
• Independent tasks you want to steer personally: worktrees and two sessions.
• A repeatable process with stages and checks: subagents plus an orchestrator with routing in code and files for handoffs. That is the shape that has held up for us.

One last practical note. Every layer above multiplies the wait: three teammates means three sessions worth of turns finishing at different times, and a pipeline run can be fifteen minutes of nothing to type. The multi-agent setup that lasts is the one where the human has decided what those minutes are for, whether that is reviewing the last handoff, steering a teammate, or something you chose on purpose. Parallel agents do not reduce waiting; they change its shape.