Claude Code Multi-Agent Collaboration: How to Choose Between Subagents and Agent Teams

Wed, 22 Apr 2026 21:35:52 +0800

When people talk about multi-agent collaboration in Claude Code, the easiest two concepts to mix up are Subagents and Agent Teams. They both sound like “spin up several agents to work together,” but they are meant for different kinds of work. In short, the former is better for splitting off independent tasks, while the latter is better when several agents need to collaborate around the same problem and cross-check each other over time.

If you have used Skills before, this framing also helps:

A Skill defines the workflow and rules
A Subagent or Agent teammate does the actual execution

So the real question is not which one is “more advanced,” but what kind of collaboration problem you are solving.

Subagents: split off side tasks

Subagents are closer to temporary worker copies launched from the current session. Each one gets its own context window, and when it finishes, it returns only a summary of the result. The main conversation stays cleaner because it does not have to absorb all the intermediate logs and output.

That gives Subagents a few very practical strengths:

The main thread stays clean instead of being flooded by test logs, search results, or long output
Independent research or execution tasks can run in parallel
They work well for tasks where “just bring me the result” is enough

The original article notes that Claude Code comes with three built-in kinds of Subagents:

Explore: read-only, useful for quickly searching a codebase
Plan: read-only, useful for gathering information in the background during plan mode
General-purpose: can read and write, suitable for tasks that mix exploration and editing

Custom Subagents

If the built-in options are not enough, you can define your own Subagent. The mechanism is simple: write a Markdown file in one of these locations:

.claude/agents/: only active in the current project
~/.claude/agents/: active across all your projects

The file format looks like this:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:

1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:

- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:

- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

The key field here is description. Claude uses it to decide when this Subagent should be called, so the more precise the description is, the more reliable the trigger tends to be.

A few other common configuration fields are also worth knowing:

tools: limits which tools the Subagent can use
model: chooses between sonnet, opus, haiku, or inherit
permissionMode: controls edit permissions and permission prompt behavior
memory: gives the Subagent a cross-conversation memory directory

If you only need a Subagent temporarily, you can also define it through the CLI:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

When Subagents fit best

Subagents are usually the best fit for tasks like these:

Running tests and returning only the failure summary instead of flooding the main thread with thousands of log lines
Investigating several unrelated modules in parallel
Splitting “find the issue” and “fix the issue” into a simple pipeline

For example:

`1`	`Research the authentication, database, and API modules in parallel using separate subagents`

`1`	`Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them`

But if a task needs constant back-and-forth adjustments, shares a lot of context across stages, or concentrates changes in only one or two files, handling it directly in the main conversation is often simpler than spinning up a Subagent.

Agent Teams: multiple independent sessions working together

Agent Teams operate at a different level. Instead of launching worker copies inside one session, they start multiple fully independent Claude Code instances that collaborate around a shared task list and can also message one another directly.

That makes an Agent Team feel more like a real small team than a simple side-task worker setup.

The article notes that this is currently an experimental feature and needs to be enabled first:

{
    "env": {
        "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
    }
}

Once this is added to settings.json, you can ask Claude to organize a team around a specific goal. For example:

1
2
3

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

What an Agent Team consists of

An Agent Team mainly includes three parts:

Team lead: the main session you are using, responsible for organizing, assigning, and summarizing
Teammates: multiple independent Claude Code instances
Task list and Mailbox: the shared task list and communication channel

The biggest difference from Subagents is that teammates can communicate directly with one another instead of routing everything through the lead. Tasks usually move through states such as pending, in progress, and completed, and once a teammate finishes one task, it can pick up the next one.

When Agent Teams fit best

When a task needs several perspectives, active discussion, conflicting hypotheses, or parallel work across modules, Agent Teams are a better fit.

The article gives several representative examples:

Several reviewers inspect the same PR in parallel, each focusing on a different dimension
Multiple agents investigate the same bug with competing explanations and challenge each other’s conclusions
Frontend, backend, and testing move forward in parallel on different parts of the project

For example, parallel code review:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

And for debate-style debugging:

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

The common pattern here is that you do not just want one answer. You want several agents to exchange judgments, challenge assumptions, and gradually converge on a stronger conclusion.

How to choose between them

If you want a quick rule of thumb, use this:

If you just need the result, use Subagents
If the work requires discussion and cross-validation, use Agent Teams

Expanded a bit further, the main differences are:

Communication style: Subagents mainly report results back to the main session, while Agent Teams members can talk directly to one another
Coordination model: Subagents depend more on the main conversation to orchestrate them, while Agent Teams work from a shared task list that members can claim themselves
Token cost: Subagents are cheaper, while Agent Teams cost more because each teammate is an independent instance
Best-fit tasks: Subagents are better for independent, result-oriented work, while Agent Teams are better for discussion-heavy and cross-check-heavy work

Practical cautions

Agent Teams are more powerful, but that does not mean every task deserves a full team. The article specifically calls out a few practical concerns:

token usage is noticeably higher
if multiple teammates edit the same file at once, overwrite conflicts become very likely
adding too many teammates increases coordination cost without guaranteeing better results

A safer default is usually:

start with 3 to 5 teammates
split tasks by module or file to avoid edit conflicts
if the lead starts doing teammate work too early, explicitly tell it to wait for the others first

The current experimental version also has a few limitations, such as:

no support for /resume and /rewind for in-process teammates
task status can lag and sometimes needs manual correction
one lead can manage only one team at a time
teammates cannot spawn child teams of their own

Short conclusion

These two features are not substitutes for one another. They solve two different collaboration problems.

If your goal is “parallelize side tasks and keep the main context clean,” start with Subagents. If your goal is “let several agents work like a small team, discuss, and cross-check each other,” then Agent Teams are the better tool.

Trying both in a real task usually makes the distinction obvious very quickly: one is optimized for context isolation and result collection, and the other is optimized for multi-perspective collaboration and ongoing interaction.

Original article: https://cloud.tencent.com/developer/article/2652960

Subagent on KnightLi Blog