Claude Code Agent Teams: The Practical Guide to Multi-Agent Parallel Development

Agent Teams is not the same thing as subagents, and conflating the two leads to confusion about what each is actually for.

Subagents are delegated workers — you spin one up to do a focused task in isolation, it returns a result, and it’s done. The orchestration is top-down. You control the assignments.

Agent Teams is a different model. You describe a goal, specify how many agents you want, and the team figures out task distribution itself. Agents claim work, commit changes, merge continuously, and resolve conflicts. The coordination is lateral, not hierarchical. The result is something closer to how a real engineering team works than a single developer delegating to assistants.

As of 2026, Agent Teams is still marked experimental. That means behavior can change between Claude Code releases, and there are genuine rough edges covered at the end of this article. That said, it is stable enough for real workloads, and the productivity gains for parallelizable work are significant.

What Agent Teams Actually Does

The core mechanic is git-based coordination. Each agent in a team:

1. Gets its own git worktree (isolated file system, separate branch)
2. Claims tasks from a shared task list
3. Does the work independently
4. Merges back to a shared integration branch
5. Repeats until all tasks are claimed and completed

“Task claiming” is how agents avoid stepping on each other. Before starting a unit of work, an agent creates a claim marker — typically a file or git note — that signals to other agents that this task is taken. Other agents skip claimed tasks and pick unclaimed ones. This is the mechanism that makes parallel work coherent rather than chaotic.

You do not have to orchestrate any of this manually. The team self-organizes based on what you describe.

Enabling Agent Teams

Agent Teams requires an environment variable to activate:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Set this in your shell profile to make it persistent:

# In ~/.zshrc or ~/.bashrc
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Reload your shell or source the file:

source ~/.zshrc

Once the variable is set, the agent teams functionality becomes available in Claude Code sessions.

Your First Agent Team

With the environment variable set, you can describe a team in plain language:

Create an agent team with 3 teammates to refactor the authentication module in parallel.
Each teammate should handle one of these: (1) token validation logic, (2) session management, (3) password hashing and storage.

Claude Code parses this, creates the team structure, and begins coordinating. You do not need to write any configuration upfront for basic usage.

A more explicit invocation gives the team clearer boundaries:

Create an agent team with 4 teammates.
Scope: migrate all API endpoints in /src/api/ from express to fastify.
Split the work by subdirectory: routes/, middleware/, controllers/, and utils/.
Each teammate owns one subdirectory.
After completing their subdirectory, teammates should run the test suite for their scope and fix any failures.

The explicitness matters. Vague task descriptions lead to overlap and wasted work. The more precisely you define what each agent owns, the less coordination overhead the team needs.

Prompt Templates for Common Team Configurations

Rather than describing teams from scratch each time, keep a set of prompt templates for recurring patterns. Store these in your project’s CLAUDE.md or as separate files you reference.

Review Team

Create an agent team with 3 teammates for a parallel code review.
Teammate 1: Security review — check for injection vulnerabilities, auth bypasses, and insecure data handling.
Teammate 2: Performance review — identify N+1 queries, unnecessary allocations, blocking operations.
Teammate 3: Correctness review — check for logic errors, edge cases, and missing error handling.
Each teammate should produce a findings file in /review-output/ named security.md, performance.md, and correctness.md respectively.
Do not modify any source files — read only.

Implementation Team

Create an agent team with 4 teammates to implement the feature described in SPEC.md.
Teammate 1: Database schema changes and migrations.
Teammate 2: Backend service layer and business logic.
Teammate 3: API endpoints and request/response handling.
Teammate 4: Unit tests for all new code.
Integration order: schema first (Teammate 1 must complete and merge before others proceed), then 2 and 3 in parallel, then 4.

Research Team

Create an agent team with 3 teammates to research migration options.
Teammate 1: Research ORMs compatible with our stack — evaluate Prisma, Drizzle, and TypeORM. Output to /research/orm-comparison.md.
Teammate 2: Research the migration risk for each ORM — breaking changes, data integrity concerns. Output to /research/migration-risk.md.
Teammate 3: Build a minimal proof-of-concept with the leading candidate. Output to /research/poc/.

Save these as reusable files and reference them:

# In CLAUDE.md
## Agent Team Templates
- Review team: .claude/templates/review-team.md
- Implementation team: .claude/templates/implementation-team.md
- Research team: .claude/templates/research-team.md

Optimizing CLAUDE.md for Agent Teams

This is the most impactful change you can make to improve agent team performance. Here is why.

When a solo Claude Code session starts, it spends time exploring the repository — reading the structure, understanding conventions, finding relevant files. That exploration cost hits once per session, and you do not notice it much.

With Agent Teams, every teammate goes through the same exploration independently. If you have four agents and each spends 3-5 minutes (and hundreds of tokens) mapping the codebase, you have multiplied that overhead by four. With a well-structured CLAUDE.md, you eliminate most of that overhead for every teammate simultaneously.

Module boundaries: make them explicit

Instead of letting agents discover the architecture through exploration:

## Architecture

This is a monorepo with four packages:
- packages/api — Express REST API, Node 20, TypeScript
- packages/web — Next.js 14 frontend
- packages/shared — Shared types and utilities (no runtime dependencies)
- packages/workers — Background job processors (BullMQ)

Cross-package imports: web and api may import from shared. No other cross-package imports.
API ↔ web communication: REST only. No shared state, no direct function calls.

Verification commands: one per module

Agents need to know how to verify their own work without asking. Provide explicit commands:

## Verification Commands

Before merging any changes, run the relevant check for your scope:
- API changes: `cd packages/api && npm test && npm run type-check`
- Frontend changes: `cd packages/web && npm test && npm run build`
- Shared package changes: `npm run test:all` (runs all packages)
- Database changes: `npm run db:migrate:dry-run` before committing migrations

A teammate's work is not done until its verification command passes.

Naming conventions: prevent style conflicts

When four agents write code independently, they will produce inconsistent style unless you specify it upfront:

## Conventions

- File naming: kebab-case for files, PascalCase for components and classes
- Function naming: camelCase, async functions must be suffixed with Async (e.g., fetchUserAsync)
- Error handling: never throw raw strings, always throw Error instances with descriptive messages
- Imports: named imports only, no default imports from internal modules
- Test files: co-located with source, named *.test.ts

Task claiming protocol: explicit is better

For teams that need fine-grained task tracking:

## Task Claiming Protocol

When starting a task:
1. Create a file at .tasks/claimed/<your-task-id>.lock with content: agent=<branch-name>, started=<timestamp>
2. Begin work only after the lock file exists

When completing a task:
1. Ensure verification command passes
2. Commit all changes with message: "complete: <task-id>"
3. Move the lock file to .tasks/completed/<your-task-id>.lock

Do not start a task if a lock file already exists for it.

Git Coordination in Practice

Each agent in a team works on its own branch. The default naming convention follows the pattern agent-team/<session-id>/agent-<N>. You can see the active branches during a team session:

git branch | grep agent-team
# agent-team/abc123/agent-1
# agent-team/abc123/agent-2
# agent-team/abc123/agent-3

Agents merge to an integration branch as they complete work. Claude Code handles the merge mechanics, but it helps to understand what happens when conflicts arise.

Conflict resolution order of operations:

1. An agent attempts to merge its branch into the integration branch
2. If there are no conflicts, the merge proceeds automatically
3. If there are conflicts, the agent has three options based on task type:
   • Additive changes (new files, new functions): usually resolvable automatically
   • Modifications to the same file: the agent reads the current integration branch state and re-applies its changes on top
   • Incompatible modifications: the agent stops, documents the conflict, and surfaces it to you for resolution

The practical implication: design task boundaries to minimize shared files. If two agents both need to modify config.ts, that is a coordination problem you should solve in the task description, not something to leave to conflict resolution.

Structure tasks to minimize conflicts:

# This will cause conflicts
Teammate 1: Add caching to the user service
Teammate 2: Add rate limiting to the user service

# This won't
Teammate 1: Implement the caching layer as a standalone middleware in /middleware/cache.ts
Teammate 2: Implement rate limiting as a standalone middleware in /middleware/rate-limit.ts
Teammate 3: Wire both middlewares into the user service routes
# (Teammate 3 starts after 1 and 2 have merged)

Agent Teams vs Subagents vs Manual Multi-Instance

These are not competing approaches — they address different problems.

Use regular subagents when:

• You have well-defined, sequential delegatable tasks
• You want precise control over what each step does and when
• The subtasks do not benefit from parallelization
• You need to pass context between steps in a controlled way

# Typical subagent pattern in CLAUDE.md
## api-docs-writer
description: Generates OpenAPI documentation from TypeScript source. Use when updating API routes.
tools: read, write

Use Agent Teams when:

• You have a large body of work that is clearly parallelizable
• Task boundaries can be defined cleanly (different files, different modules, different concerns)
• You want the team to self-organize rather than micromanage assignments
• The work can be verified independently by each agent before merging

Use manual multi-instance (separate terminal sessions) when:

• You need full control over each session
• You are running exploratory or research tasks where coordination would be noise
• Agent Teams behavior is causing unexpected results and you need to debug by isolating sessions

# Manual multi-instance: three separate terminals, three separate tasks
# Terminal 1
cd ~/project && git checkout -b feat/auth-refactor && claude

# Terminal 2
cd ~/project-worktree-1 && git checkout -b feat/api-refactor && claude

# Terminal 3
cd ~/project-worktree-2 && git checkout -b feat/db-migrations && claude

The manual approach gives you the most control at the cost of most of the automation.

Limitations and Gotchas

Experimental means unstable API. The environment variable, team invocation syntax, and coordination behavior are all subject to change. Pin your Claude Code version if you are building workflow tooling on top of Agent Teams.

Teams are not magic for poorly scoped work. If you describe a vague goal to four agents, you get four agents doing overlapping work in incompatible ways. Agent Teams amplifies both good and bad task descriptions. Invest time in the prompt.

Shared state is the enemy. Agents are isolated at the file system level, but they are not isolated from shared external resources: databases, third-party APIs, environment variables, shared config files. If four agents each try to run database migrations independently, you have a problem. Either serialize the shared-resource steps or handle them outside the team.

Token consumption scales with team size. Each agent in a team consumes tokens independently. A four-agent team running in parallel roughly quadruples your token usage versus a single session doing the same work sequentially. The time savings are real, but so is the cost. Use Max plan or budget carefully if you are running large teams frequently.

CLAUDE.md exploration cost is the multiplier that matters most. A poorly written CLAUDE.md that forces each agent to spend time exploring the codebase will cost you proportionally to team size. Invest in a well-structured CLAUDE.md before scaling up team size.

Merge conflicts require manual intervention in complex cases. For straightforward conflicts, Claude Code resolves them automatically. For conflicts involving semantic incompatibilities — two agents that both modified the same business logic in incompatible ways — you will need to step in. This is not a bug, it is a fundamental constraint of parallel work.

The Practical Case for Agent Teams

The clearest wins are on tasks with these characteristics:

• Large scope, low coordination dependency (migrating 50 API routes to a new framework)
• Well-understood conventions where independent style is not a problem
• Work that fits cleanly into distinct file or module boundaries
• High verification confidence (comprehensive test suites that agents can run themselves)

The weakest case for Agent Teams is highly coupled work where every change has downstream implications for every other change. For that kind of work, sequential execution with a single well-contextualized agent is usually faster and less error-prone than a team that spends half its cycles on conflict resolution.

The subagents guide covers the single-agent delegation model in detail — the two approaches complement each other. For large, parallelizable workloads, Agent Teams is the right tool. For sequential, context-dependent delegation, subagents remain the better fit.