Agent Teams in Claude Code: When 5 Agents Beat 1

Introduction

I spent an entire weekend testing Claude Code’s Agent Teams. Not on a toy project: on a real enterprise development, with DDD architecture, multiple layers (Domain, Application, Infrastructure), multiple repositories, and dozens of business rules to respect.

The results surprised me. Enough that I needed to write about them.

Where before I had to guide Claude step by step — “now the tests”, “check the endpoints”, “document it with the data from the manual runs” — with Agent Teams I got a complete implementation from a single prompt. With a good specification, mind you.

But it is not all magic. It is worth understanding when it makes sense and when it does not, because the token cost multiplies by 7-10x.

The problem: guiding step by step

When you work with Claude Code in a normal session, exploration is sequential. Claude investigates, implements, and moves to the next step. For 90% of cases it works well.

But in complex developments with multiple layers, the dynamic changes. You need someone to design the architecture, someone else to implement the domain, someone else the infrastructure, someone else the tests, someone else to review the code — and it all has to fit together.

In my earlier single-session work, the process went like this: I explained what to implement and it did it. Fine. But then I had to say “now write the tests”. And then “test the endpoints”. And then “document the endpoints with the real responses from the tests”. Multiple sessions, multiple prompts, losing context in between.

What if you could have all those roles working in parallel, coordinating with each other? That is Agent Teams.

What Agent Teams is

Agent Teams is an experimental Claude Code feature. It lets you coordinate multiple Claude instances working in parallel as a real team.

The difference from the subagents you already know:

Subagents: the main agent delegates a task, the subagent executes it in isolation and returns the result. There is no communication between subagents.

Agent Teams: teammates send messages to each other, share a common task list, and challenge and coordinate autonomously. The team lead orchestrates but does not centralise all communication.

It is the difference between having freelancers working in silos and having a real team that collaborates.

The team I set up

For the proof of concept I set up a team of 7 agents, each with its own configuration file, its own tools and its own model:

Architect (Opus): proposes the DDD structure before anyone writes code. Bounded Context, Aggregates, relationships between entities, type of migrations. It only reads and designs; it does not implement.

Domain Developer (Sonnet): implements the heart of the business. Entities, Value Objects, repositories, finders, domain exceptions, application services, commands and queries.

Infrastructure Developer (Sonnet): connects the domain to the outside world. ORM, Doctrine repositories, controllers, FormTypes, migrations, permissions, translations in 5 languages.

Unit Tester (Sonnet): 100% coverage of the Application layer. Every service, every handler, every possible path. Mutation testing to make sure the tests are genuinely useful.

Documenter (Sonnet): documents each endpoint once it has been tested. It generates the technical documentation with the real requests and responses from the tests, and updates the Bruno collection so the frontend team has everything ready.

Code Reviewer (Opus): final review against all project rules. PHPStan, regression tests, adherence to conventions.

Devil’s Advocate (Opus): tries to break everything. Challenges design decisions, hunts for vulnerabilities, validates domain invariants, edge cases, concurrency.

Each agent has detailed instructions on what it can and cannot do. The Domain Developer does not touch infrastructure. The Infrastructure Developer does not touch the domain. The Architect does not write code. This is key to avoiding conflicts.

Model choice matters: Opus for the roles that need judgement (architect, reviewer, devil’s advocate) and Sonnet for the ones that need speed (developers, tester). It optimises cost without sacrificing quality where it counts.

The implementation flow

The team lead reads the technical specification and orchestrates:

It launches the Architect to propose the structure
In parallel, Domain Developer and Infrastructure Developer implement their layers
Unit Tester writes the tests
The endpoints are tested and the Documenter documents each one with real data from those runs
Code Reviewer validates quality and regression
Devil’s Advocate hunts for problems

Independent tasks run in parallel. Those with dependencies run sequentially. Domain before Infrastructure. But within each layer, independent entities go at the same time.

And all of this starts with a single prompt that includes the path to the specification. A single prompt.

The results

This is where it gets interesting.

Before (single session): multiple sessions, guiding step by step. Implement, then tests, then endpoints, then documentation. I had to stay on top of it, reviewing each step and asking for the next. If I lost context between sessions, things had to be re-explained.

Now (Agent Teams): complete development from a single prompt. Code, migrations, tested endpoints, documentation, unit tests, code review. All of it.

And what surprised me most: in the code review I did not have to adjust anything. The implementation came out far more accurate than in single sessions. The Devil’s Advocate found edge cases that slip through in a normal session. The Code Reviewer caught rule violations I was missing.

The key was not Agent Teams itself. It was the combination of well-defined agents + a detailed specification + clear project rules. Without those three ingredients, Agent Teams would be just as mediocre as a badly configured single session.

Enabling it

Agent Teams is experimental. There are two ways to enable it:

Environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

In your settings.json (recommended):

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "language": "Español",
  "alwaysThinkingEnabled": true
}

The settings.json lives at ~/.claude/settings.json. Once configured, start Claude Code normally. The feature will be available, but you have to explicitly ask it to create a team.

The real cost

I am not going to fool anyone: Agent Teams is expensive.

Metric	Single session	Agent Teams	Multiplier
Tokens consumed	~20,000-25,000	~150,000-200,000	7-10x
Setup time	0 min	15-30 min	-
Perspectives	1 generalist	7 specialised	7x

If you pay $15 per million input tokens and $75 per million output tokens (Opus 4.6 rates), a complex development with Agent Teams can cost you $15-20 versus $2-3 in a single session.

The question is: does it pay off?

It depends. If the development saves you 3-4 rounds of back and forth fixing things, yes. If the code quality comes out right the first time and you do not have to review as much, yes. If it is a simple task that takes 5 minutes, obviously not.

Coordination, not automation

Agent Teams is not “launch and forget”. As team lead, you have to supervise:

Monitor each teammate’s progress
Step in when someone gets stuck
Make pragmatic decisions (sometimes you have to shut down an agent that is taking too long)
Resolve coordination conflicts

Concurrent file editing

Several agents may try to edit the same file at once. There is no file locking. The solution is to assign clear ownership: the Domain Developer does not touch Infrastructure, the Infrastructure Developer does not touch Domain.

If you define the roles well, conflicts are minimal. In my weekend test, I had none. Each agent knew which files were its own and which were not.

Experimental status

Agent Teams is experimental. APIs can change, there are bugs, and unexpected behaviour is part of the game. I have had sessions where teammates went out of sync or where messaging failed. If you are going to try it, keep that in mind.

Anthropic’s C compiler

To put the potential of multi-agent coordination in perspective, Anthropic published an extreme case: 16 parallel Claude instances implemented a complete C compiler from scratch.

Project numbers:

16 parallel instances, ~2,000 Claude Code sessions over 2 weeks
100,000 lines of Rust generated
Cost: $20,000 in API calls (2B input tokens, 140M output tokens)
Result: it compiles the Linux 6.9 kernel, QEMU, FFmpeg, SQLite, PostgreSQL and Redis
99% success on the GCC torture test suite

What I find most relevant in the article is that the author says most of his effort went into designing the environment around Claude: high-quality tests, thorough documentation and feedback mechanisms. Not the agents themselves.

That matches my experience: the quality of the specs and the project rules is what makes the difference, not the number of agents you launch.

When YES, when NO

Use Agent Teams when:

Multi-layer development: you need to implement Domain, Application, Infrastructure, tests and documentation in a coordinated way
Parallel exploration: multiple hypotheses to investigate at once (complex debugging)
Independent tasks: work that can be split without many dependencies
Specialised expertise: each agent brings a differentiated perspective
The budget allows it: the 7-10x multiplier is justified
You have good specs and rules: without these, Agent Teams does not add much

Do NOT use Agent Teams when:

Simple tasks: a small change, a straightforward bugfix
Everything depends on everything: if each step needs the previous one, there is no possible parallelisation
You have no clear rules: if your agents do not know what to do, the result will be chaotic
First time: explore with a single session first, understand the problem, and only then scale up

Practical rule: if you are not sure, start with a single session. Scale to Agent Teams when you have evidence that parallelisation adds value.

Practical tips

Fewer agents, better defined

Do not create 10 agents. 3-5 well-defined ones are more effective than 10 mediocre ones. Each with a clear role, differentiated expertise, and defined file ownership.

Define clear flows

Before launching the team, document the order: who goes first, who waits for whom, what can be parallelised. Without a clear workflow, the agents fall out of sync and duplicate work.

Invest in specs and rules

The quality of Agent Teams’ output is directly proportional to the quality of your specifications and project rules. I have had dozens of rules in .claude/rules/ tuned over months. That is what lets the agents do the job right the first time.

Use different models per role

Opus for the ones that need judgement. Sonnet for the ones that need implementation speed. This optimises cost without sacrificing quality where it matters.

Conclusion

Agent Teams is not for everything. It is for that 5-10% of cases where the development is complex, multi-layered, and a single session falls short.

What surprised me most over the weekend was not the speed (though that too), but the quality. When each agent has a specialised role and clear rules, the result is better than a generalist session. The Devil’s Advocate finds things you miss. The Code Reviewer catches violations you would not see.

The key? It is not the agents. It is the specs, the rules and the role definitions. Agent Teams is the tool, but without the preparation behind it, it does not work.

And one more thing: if you have been using Claude Code for months, you probably already have your rules tuned. Agent Teams is the natural next step to get more out of them.

P.D.: If you are testing Agent Teams or have experiences to share, you can find me on Twitter as @lm_martinbar. And if you want the specification discipline that makes these teams actually work, read SDD with OpenSpec.