Claude Code Agent Teams: A Hands-On Introduction to Multi-Agent Development

AI coding assistants have come a long way, but a single agent can only take you so far. Large-scale refactors, test generation across multiple modules, bulk API migrations — these kinds of tasks tend to spill over a single context window, losing track of earlier context or dropping parts of the instructions along the way. Claude Code Agent Teams is Anthropic's experimental answer to this problem: a system for organizing multiple Claude Code sessions into a collaborating team, ushering in a new paradigm we might call multi-agent development.

This article covers Agent Teams from the basics — how it differs from subagents, the most effective use cases, and the design principles that make it work — drawing on our own experimentation at aduce. It assumes familiarity with the fundamentals of Claude Code, but if you're new to it, reviewing the basics first should be enough to follow along.

What Are Agent Teams? A Multi-Agent Development Overview

Agent Teams is an experimental multi-agent orchestration feature in Claude Code. While a traditional Claude Code session handles everything within one context, Agent Teams lets multiple Claude Code sessions — each with its own independent context window — coordinate as a team.

The structure is simple. One session acts as the "team lead," directing the overall effort, while other sessions serve as "teammates" handling specific tasks. The team lead splits the work and assigns it; each teammate operates independently in its own area of responsibility.

What makes this powerful is that teammates can communicate directly with one another. As we'll see, subagents can only report back to the main session in a one-way fashion, whereas Agent Teams teammates share information and coordinate with each other in real time. If one teammate changes an API interface, another teammate can pick up that change and update the corresponding client code accordingly.

This coordination is built on top of Git. Each teammate learns about the others' work through the state of the Git repository, detecting and resolving conflicts as they go. Because it's built on mechanisms developers already know — the filesystem and version control — its behavior is fairly predictable.

Why Multi-Agent Development Is Needed

Why coordinate multiple agents instead of using one? There are three main reasons.

The first is context window limits. No matter how large context windows become, it's unrealistic to fit an entire large-scale project into one session. Splitting across sessions lets each one focus on its own area, preventing context loss.

The second is speed through parallelism. If you need to apply the same transformation to 100 files, running them in parallel across multiple sessions is dramatically faster than iterating through one session. In our tests, generating tests for 10 files took about three times longer sequentially in a single session than it did across five parallel subagents. The gap only widens as the number of files grows.

The third is separation of concerns. If the same session writes and reviews code, the writer's biases contaminate the review. A separate session brings a fresh perspective. This "Writer/Reviewer" pattern is one of the most common uses of multi-agent development.

The Five Workflow Patterns

Claude Code agent usage breaks down into five major workflow patterns. Agent Teams is one of them, but understanding the full picture helps you pick the right pattern for the job.

Sequential pattern: A single agent handles multiple tasks one after another. Simplest of all; best when tasks have strong dependencies.

Operator pattern: A single agent interacts with external tools or APIs. Integration with MCP servers is the classic example — see our Claude Code × MCP Integration Guide for details.

Split-and-Merge pattern: A task is divided, each subtask runs in parallel, and results are combined. This is the standard subagent use case.

Agent Teams pattern: Multiple agents collaborate as a team, communicating with one another while working. The focus of this article.

Headless pattern: Agents run as background processes without a UI — well suited to CI/CD pipelines or scheduled jobs. For example, automating code review when a PR is opened, or running periodic quality checks.

These patterns aren't mutually exclusive. In practice, a team lead running the Operator pattern might read GitHub Issues, then dispatch them to teammates using the Split-and-Merge pattern.

How Subagents Work

Before diving deeper into Agent Teams, it's worth understanding subagents. Subagents are the precursor to Agent Teams — a mechanism for launching agents with their own context windows from within a single session. They lack some of the flexibility of Agent Teams, but for many use cases they're more than enough and are much simpler to set up.

The Basic Subagent Structure

Subagents are defined as Markdown files in .claude/agents/. They look like this:

The key frontmatter fields: name is the agent's identifier, used when calling it from the main session. description explains the agent's role — Claude Code uses this to decide which subagent to delegate work to. tools is the allowlist for the subagent's tools; excluding unnecessary tools prevents unintended actions. For example, a review-only agent should have no file-editing access — Read, Grep, and Glob are typically enough. model specifies which model to use, so you can optimize cost or pick the right capability level. Sonnet for simple searches and aggregation; Opus for complex design decisions.

Since the filename itself becomes the agent's identifier, use names that make the role obvious at a glance: code-reviewer.md, test-generator.md, investigator.md.

Running Subagents in Parallel

Up to 10 subagents can run in parallel. When the main session launches subagents, each begins work in its own context window. When a subagent finishes, it reports back to the main session, which then decides what to do next.

For example, generating tests across 10 modules in parallel would look like:

1. The main session maps the overall work
2. Subagents are launched in parallel, one per module
3. Each subagent independently generates its test code
4. The main session gathers the results and verifies consistency

The benefit is that each subagent consumes no main-session context. The main session can focus on orchestration without needing to absorb the details of each file.

Typical Subagent Use Cases

Here are scenarios where subagents really shine.

Independent code review: After writing code in the main session, kick off a reviewer subagent. Without the writer's context, it reads with genuinely fresh eyes — more objective than a self-review in the same session. This is the Writer/Reviewer pattern.

Investigation that doesn't pollute the main conversation: Reading through many files consumes a lot of main-session context. Delegating to a subagent returns only a summarized result, keeping the main conversation's flow intact.

Parallel file processing: When applying the same transformation to many files, subagents running in parallel pay off. Type definition updates, import path changes, adding logging — repetitive mechanical work.

That said, subagents have limits. They can't talk to one another directly; everything has to go through the main session. That makes them unsuitable for tasks where agents need to exchange information frequently. That's where Agent Teams takes over.

Agent Teams Use Cases

Agent Teams really comes into its own with complex tasks where multiple agents influence each other. The one-way "report back and stop" model of subagents doesn't cut it in those situations.

Large-Scale Refactoring

A refactor spanning hundreds of files is the most obvious use case. Consider migrating legacy class-based React components to function components with Hooks.

The team lead plans the migration and analyzes component dependencies, then assigns batches of independent components to teammates in parallel. As the migration progresses, if one teammate extracts a shared custom Hook, the others detect that change through Git and migrate their components to use it.

This ability to "see other members' in-flight work" is the decisive difference from subagents. With subagents, you can't extract a shared Hook and consume it in the same parallel pass — you have to extract it first, let the main session confirm the result, then dispatch a fresh set of subagents. Strictly sequential.

Rolling Out Test Coverage at Scale

Adding test coverage to an existing project is another strong fit. The team lead analyzes the module structure and decides on a test strategy. Teammates take on clusters of modules and write tests, coordinating at boundaries for integration tests.

For example, the teammate writing tests for the user-management module and the one writing tests for the auth module can keep their mocks aligned as they go. If the auth side changes the shape of the user object, the user-management tests pick it up immediately — no painful reconciliation afterward.

API Endpoint Migrations

REST-to-GraphQL migrations, API version bumps, switching auth schemes — API migrations tend to have wide blast radius and are hard to keep consistent. Agent Teams lets a server-side teammate and a client-side teammate work in parallel while observing each other's progress.

Concretely, the server-side teammate changes an endpoint's response format; the client-side teammate detects the change through Git and updates the corresponding request handling. The risk of server/client drift drops significantly.

Traditionally, a migration like this proceeds sequentially — finish the server, then update the clients. With Agent Teams they run in parallel, cutting the overall time. Of course, some parts require the server change to land first, but those dependencies are naturally managed through the Git-based coordination.

Bulk Documentation Updates

Updating docs alongside code changes is also fair game. A docs teammate can watch the code teammate's output in real time and generate documentation that reflects the actual changes. README updates, regenerated API references, ChangeLog entries — all done in parallel with the code.

It's an often-overlooked use case but a practical one. When code and doc updates happen at different times, docs reliably drift. Running both in parallel structurally prevents code-doc divergence.

Real Project Experience

Here's how we've actually used Agent Teams and subagents at aduce.

Writer/Reviewer Pattern with Subagents

The first thing we adopted was the Writer/Reviewer pattern with subagents. The setup is just a review agent definition in .claude/agents/:

The effect was better than we expected. Passing main-session code to a reviewer subagent surfaces type mismatches and missing edge cases we didn't notice while writing. Even though both sessions are running the same Claude Code, the difference in context alone changes perspective meaningfully — a crisp demonstration of why the multi-agent approach works.

Investigation Subagents

Another favorite of ours is an investigation-only subagent. If you ask the main session to, say, "find all unused exports in the project," the process of scanning through many files burns context and hampers subsequent work.

Delegating the investigation to a subagent returns a clean summary back to the main session. The main session keeps its context intact and moves smoothly into the next step. As we noted in the Claude Code Usage Guide, managing the context window is one of the most important skills in using Claude Code effectively.

Cross-Module Changes with Agent Teams

For our Agent Teams experiment we picked an API change spanning frontend and backend: unifying response date formats from ISO 8601 to Unix timestamps.

After the team lead analyzed the impact, one teammate worked on the backend response transformation while another updated the frontend display logic, in parallel. When the backend change was committed to Git, the frontend teammate picked it up and updated its date-parsing code.

What struck us was how well Agent Teams' Git-based coordination integrated with normal development workflow. Every agent's output is recorded as a Git commit, so you can audit what changed and in what order.

Lessons from Adoption

A few things we noticed:

First, Agent Teams is experimental. Stability and behavior may change. It's too early to fold it fully into production workflows. We currently limit its use to small-blast-radius tasks and branch-level experiments.

Second, more agents isn't always better. Beyond a certain point, coordination overhead actually reduces efficiency. Three to five teammates feels like a practical upper bound.

Third, if you don't clearly define each teammate's scope, multiple teammates end up editing the same file and conflicts become routine. Upfront task design is what separates success from frustration.

Agent Teams vs. Claude Cowork

A feature with a similar-sounding name is "Claude Cowork." Since people often conflate the two, let's clarify the differences.

Claude Cowork is a file automation workflow feature available through the Claude.ai web interface. It isn't a coding agent — it automates file-based tasks like document generation, transformation, and data processing. See What Is Claude Cowork? for a deeper dive; here we'll focus on the contrast with Agent Teams.

Comparison Table

When to Use Each

Put simply: Agent Teams for changes to a codebase; Claude Cowork for file processing and documentation work outside the codebase.

Refactoring TypeScript type definitions across a project is Agent Teams territory. Generating a meeting summary from transcripts and posting it to Slack is Claude Cowork territory.

The two are complementary, not competing. It's natural to implement a feature with Agent Teams and then generate the release notes with Claude Cowork.

One more technical distinction worth noting: Agent Teams runs locally against your Git repository, whereas Claude Cowork runs in a cloud-based web session. That matters for security. If you're dealing with sensitive source code, Agent Teams' local-first model is preferable. Conversely, if you're collaborating with external stakeholders on documents, Claude Cowork's web accessibility can be a better fit.

Design Principles for Effective Agent Decomposition

The most important — and most difficult — part of adopting Agent Teams or subagents is deciding how to decompose the work. Too coarse and you lose the benefits of parallelism; too fine and coordination costs balloon. Here are the principles we've converged on.

Split by Independence

The single most important principle: partition along lines that minimize shared state. If agent A's work doesn't affect agent B's, they can safely run as independent parallel tasks.

If agents need to exchange data frequently, don't force a split — consolidating in a single agent (or the main session) is usually more efficient. Always weigh the benefit of splitting against the cost of communication.

Consider a frontend component library. Buttons, forms, modals — mutually independent components — can each be assigned to a different agent. A form component and its validation logic, on the other hand, are tightly coupled and should belong to the same agent.

Find the Right Granularity

A handy heuristic is the "15-minute rule." A task that would take a human 15 to 30 minutes to complete manually is about the right size for a single subagent task. Smaller than that, and startup/shutdown overhead dominates. Much larger, and you risk hitting context window limits.

For Agent Teams, each teammate typically handles 30 minutes to 2 hours of work. Because teammates can communicate, you can work at a coarser granularity than with subagents without trouble.

Define Clear Boundaries

The best defense against conflicts is to carve out each agent's scope along file paths or module boundaries:

Splitting responsibility by directory like this minimizes the chance of multiple agents editing the same file. Teammate D, which depends on other teammates' work, is exactly the kind of case where Agent Teams' inter-teammate communication pays off.

Subagents or Agent Teams — Which Do You Need?

Some decision criteria:

Subagents are the right choice when:

• Tasks have no dependencies on each other
• Merging results in the main session is sufficient
• The tasks are relatively small (few files)
• You want minimal setup

Agent Teams is the right choice when:

• Tasks have mutual dependencies
• Coordination between agents is needed mid-work
• The tasks are large and long-running
• Changes span the entire codebase

In practice, subagents suffice for most cases. In our experience, Agent Teams is only really warranted about 20% of the time. Start with subagents, and move to Agent Teams when you find yourself needing inter-agent communication.

Managing Agent Definitions

Store subagent definitions in .claude/agents/ and commit them to the project repository. The whole team ends up with the same agent configuration, and the definitions become review- and version-controlled assets.

Agent definitions evolve iteratively, just like code. Don't aim for perfect definitions upfront — refine them as you use them. We revisit our definitions regularly during sprint retrospectives.

Anti-Patterns in Agent Design

Understanding effective design also means knowing what to avoid.

The omniscient agent: Giving one agent every tool and sweeping instructions. It burns context unnecessarily and yields vague output. Agents are more useful when they "do one thing reliably" than when they "can do anything."

Over-splitting: On the flip side, spinning up a dedicated agent for a five-line change is wasteful. Agent startup has overhead — if the task is faster done manually, don't split it.

Fuzzy boundaries: Coarse divisions like "frontend" vs. "backend" leave ownership of shared files (type definitions, config files) ambiguous, producing frequent conflicts. Define boundaries by concrete directory or filename patterns.

Summary

This article covered Claude Code Agent Teams and subagents as tools for multi-agent development. A quick recap:

Subagents let you launch up to 10 agents in parallel, each with its own context window, from within a single session. Defined as Markdown files in .claude/agents/, they shine in Writer/Reviewer patterns and parallel file processing.

Agent Teams is an experimental feature where multiple Claude Code sessions collaborate as a team. Because teammates communicate directly via Git, it fits tasks that require cross-agent coordination — large-scale refactors, changes spanning modules, and the like.

Claude Cowork is a separate product altogether: a file automation workflow accessible from Claude.ai's web interface. Not for coding, but for document generation and data processing.

The keys to effective decomposition are: split by independence, find the right granularity, and define clear boundaries. Start with subagents, and graduate to Agent Teams as needed — that's the realistic path.

Multi-agent development isn't just about learning new tooling; it tests fundamental software engineering skills in task decomposition and coordination. In that sense, the experience you've built from microservice architecture and team-based development maps directly onto this space.

This area is still evolving, and best practices are being updated constantly. At aduce, we'll keep experimenting and sharing what we learn. If you'd like to discuss how Claude Code or AI tooling could improve your development workflow, feel free to get in touch.

References

• Create custom subagents - Claude Code Docs
• Claude Code Agent Teams Setup & Usage Guide 2026
• 5 Claude Code Agentic Workflow Patterns - MindStudio