How to Use Claude Code Agent Teams for Complex Projects

Sarah Walker · Senior AI Research Editor · March 26, 2026 · 15 min read

TL;DR — When to Use What

If you are not sure, start with subagents. Upgrade to agent teams when you find yourself wishing you could work on multiple things simultaneously without waiting.

Table of Contents

1. The Problem Agent Teams Solve
2. Subagents: The Lightweight Option
3. Agent Teams: Full Parallel Execution
4. Worktrees: The Isolation Layer
5. Orchestration Patterns
6. Real Project Examples
7. Cost Management
8. Common Mistakes and How to Avoid Them
9. Frequently Asked Questions

The Problem Agent Teams Solve {#the-problem}

I hit the wall with single-session Claude Code on a project last month. The task was straightforward on paper: migrate a monolithic Express API to a modular architecture, add comprehensive test coverage, update the Terraform infrastructure, and rewrite the CI/CD pipeline. Four workstreams. All needed to happen in the same repository.

In a single Claude session, this meant working sequentially. Refactor the API, then write tests, then update Terraform, then fix the pipeline. Each step took 20-40 minutes. Total elapsed time: about three hours of active Claude work, plus my review time between each step.

With agent teams, those four workstreams ran simultaneously. Four agents, each in its own worktree, each focused on one workstream. Total elapsed time: about 50 minutes, including the merge at the end.

That is the promise. But getting there requires understanding when parallel execution actually helps, when it creates more problems than it solves, and how to coordinate agents that are modifying the same codebase.

Subagents: The Lightweight Option {#subagents}

Before reaching for agent teams, understand subagents. They solve a different problem and are the right choice more often than most people think.

What Subagents Are

A subagent is a child Claude session spawned by your current session using the Task tool. The parent agent delegates a focused subtask, the subagent executes it, and returns a result to the parent.

Parent Agent: "I need to refactor this API. Let me spawn a subagent to write the tests while I restructure the routes."

→ Subagent spawned: "Write unit tests for the user authentication module"
→ Subagent works in the same directory
→ Subagent returns: "Tests written. 14 test cases covering login, signup, token refresh, and logout."

Parent Agent: "Good. Now let me integrate those tests with the refactored routes."

How Subagents Work Technically

When Claude spawns a subagent, several things happen:

1. The subagent gets a focused prompt — a single, well-defined task
2. It inherits the project context (CLAUDE.md, skills, MCP servers)
3. It works in the same working directory as the parent
4. It has its own conversation context (it cannot see the parent's full chat history)
5. It returns a text result to the parent when done

The shared directory is both the strength and the limitation. The subagent can read the same files the parent is working on — which is great for tasks that need project context. But if the parent and subagent edit the same file simultaneously, you get conflicts.

When to Use Subagents

Subagents shine when:

• The task is well-defined and self-contained. "Write tests for this module," "Generate documentation for these API endpoints," "Create a migration script for this schema change."
• The subtask needs project context but will not conflict with the parent's work. The subagent reads existing code but writes to different files.
• You want to parallelize within a single session without the overhead of worktree setup and branch management.
• The task is quick — under 5 minutes of Claude work. Subagents are lightweight and should be treated as such.

When Not to Use Subagents

Subagents are the wrong choice when:

• Both agents need to edit the same files. This creates race conditions.
• The subtask is large enough to need its own conversation context. Subagents get a focused prompt, not your full conversation history.
• You need more than 2-3 parallel workstreams. Subagents share resources with the parent session and do not scale well beyond light parallelism.

Agent Teams: Full Parallel Execution {#agent-teams}

Agent teams are what you reach for when subagents are not enough. Multiple independent Claude Code sessions, each in its own isolated environment, working on the same project simultaneously.

Spawning an Agent Team

The cleanest way to launch an agent team is through the --worktree flag combined with task-specific prompts:

# Terminal 1: Lead agent (orchestrator)
claude

# Terminal 2: Agent working on API refactor
claude --worktree "Refactor the Express routes into modular controllers"

# Terminal 3: Agent working on tests
claude --worktree "Write comprehensive tests for the auth and user modules"

# Terminal 4: Agent working on infrastructure
claude --worktree "Update Terraform configs for the new microservice architecture"

Each --worktree invocation creates a new git worktree — a full copy of the repository in a separate directory with its own branch. The agents cannot interfere with each other's file changes.

The Lead Agent Pattern

In practice, you want one agent coordinating the others. I call this the Lead Agent pattern. The lead agent:

1. Breaks the project into parallel workstreams
2. Spawns worker agents with specific instructions
3. Monitors progress (via git branch status)
4. Merges results when workers finish
5. Resolves conflicts if branches touch overlapping files

You can run this manually (you are the lead, managing multiple terminal windows) or semi-automatically (the lead agent in Terminal 1 uses subagents to check on worker progress).

Isolation Modes

Agent teams support different levels of isolation:

Full worktree isolation (recommended for most cases): Each agent gets its own directory and branch. Changes are completely independent until merge.

claude --worktree "task description"

Shared directory with branch isolation: Agents work in the same directory but on different branches. Cheaper (no directory duplication) but riskier — file-level conflicts can occur if agents work simultaneously.

# Not recommended for teams — use worktrees instead

Container isolation (for infrastructure work): Each agent runs in its own Docker container. Maximum isolation, useful when agents are executing infrastructure commands that might affect the host system.

# Requires Docker and custom setup
docker run -v $(pwd):/workspace claude-agent "task description"

For most software projects, full worktree isolation is the right default. The disk space overhead is minimal (git worktrees use hard links for the .git directory), and the safety guarantees are worth it.

Worktrees: The Isolation Layer {#worktrees}

Worktrees are the foundation that makes agent teams safe. If you have not used git worktrees before, here is what you need to know.

How Git Worktrees Work

A git worktree is a linked copy of your repository that shares the same .git directory but has its own working tree and branch. Think of it as a lightweight clone that does not duplicate the git history.

# Standard Claude Code worktree creation
claude --worktree

# What happens behind the scenes:
# 1. git worktree add ../your-repo-worktree-abc123 -b claude/worktree-abc123
# 2. Claude starts in the new directory
# 3. All changes happen on the new branch
# 4. When done, changes are merged or the worktree is cleaned up

For a deep dive into worktree mechanics, branch management, and cleanup workflows, see our complete worktrees guide.

Why Worktrees Beat Branches for Agent Teams

You might wonder: why not just have agents work on different branches in the same directory? The answer is practical. Git only lets you have one branch checked out per working directory. If Agent A is on feature/api-refactor and Agent B needs to switch to feature/test-coverage, Agent B's checkout would blow away Agent A's uncommitted changes.

Worktrees solve this completely. Each agent has its own directory, its own checked-out branch, and its own uncommitted changes. They are physically incapable of interfering with each other.

Worktree Lifecycle for Agent Teams

Here is the typical lifecycle:

1. Lead agent identifies parallel workstreams
2. Each workstream gets a worktree: claude --worktree "task"
3. Agents work independently (10-60 minutes)
4. Agents commit their changes to their branches
5. Lead agent merges branches into main (or a staging branch)
6. Conflict resolution if needed (usually minimal with good task decomposition)
7. Worktrees cleaned up: git worktree remove <path>

The key insight is step 6. Good task decomposition means agents work on different files, so merges are clean. Poor task decomposition means agents edit the same files, creating conflicts that eat up any time savings.

Orchestration Patterns {#orchestration-patterns}

After running agent teams on dozens of projects, I have identified four orchestration patterns that cover most use cases.

Pattern 1: Parallel Independent

When to use: Tasks that touch different parts of the codebase with minimal overlap.

Lead Agent
├── Agent A: Frontend components (src/components/)
├── Agent B: API routes (src/api/)
├── Agent C: Database migrations (prisma/)
└── Agent D: Test suite (tests/)

This is the simplest pattern. Each agent works on a different directory. Merges are almost always conflict-free. Works best for feature development where frontend, backend, and tests can be built independently.

Pattern 2: Pipeline Sequential

When to use: Tasks where later stages depend on earlier stages, but within each stage there is parallelism.

Stage 1 (parallel):
├── Agent A: Scaffold new module structure
├── Agent B: Design database schema
│
Stage 2 (parallel, after Stage 1 merges):
├── Agent C: Implement API endpoints (needs schema from B)
├── Agent D: Build frontend (needs module structure from A)
│
Stage 3 (sequential):
└── Agent E: Integration tests (needs C and D)

This pattern maximizes parallelism while respecting dependencies. The lead agent manages stage transitions — waiting for Stage 1 to complete before launching Stage 2.

Pattern 3: Specialist Roles

When to use: When you want agents with different skills working on different aspects of the same feature.

Lead Agent (Orchestrator)
├── Code Agent: Implements the feature (has Superpowers skill)
├── Test Agent: Writes tests (has Testing Best Practices skill)
├── Infra Agent: Updates deployment (has Terraform Mastery skill)
└── Docs Agent: Writes documentation (has Technical Writing skill)

Each specialist agent can be configured with different skills in its worktree's .claude/skills/ directory. The Code Agent gets Superpowers, the Infra Agent gets Terraform and Kubernetes skills, the Docs Agent gets writing-focused skills. This is the closest analog to how real engineering teams work.

Pattern 4: Review and Iterate

When to use: When quality matters more than speed.

Round 1:
└── Agent A: Implements the feature

Round 2 (parallel):
├── Agent B: Reviews Agent A's code, files issues
├── Agent C: Writes tests against Agent A's implementation

Round 3:
└── Agent A: Addresses review feedback and test failures

This pattern uses agents adversarially. Agent B's job is to find problems. Agent C's job is to write tests that expose edge cases. Agent A then improves based on their feedback. It takes longer than single-pass development but produces significantly more robust code.

Real Project Examples {#real-examples}

Example 1: Full-Stack Feature Build

Project: Adding a team collaboration feature to a Next.js + Convex application.

Team composition:

• Agent 1 (Frontend): Built the team invitation UI, member management page, and role-based access components
• Agent 2 (Backend): Wrote Convex functions for team CRUD, invitation flow, and permission checks
• Agent 3 (Tests): Created Playwright end-to-end tests and Convex function unit tests
• Agent 4 (Infrastructure): Updated Vercel environment configs and added team-scoped analytics

Time comparison: Single session would have taken roughly 3 hours of sequential Claude work. The agent team completed it in 55 minutes with one merge conflict (both the frontend and backend agent modified the shared types file — resolved in 2 minutes).

Example 2: Monorepo Migration

Project: Splitting a monolithic Node.js application into a Turborepo monorepo.

Team composition:

• Agent 1: Extracted the API into apps/api/
• Agent 2: Extracted the web frontend into apps/web/
• Agent 3: Extracted shared utilities into packages/shared/
• Agent 4: Created the Turborepo configuration, root package.json, and CI/CD pipeline
• Agent 5: Updated all import paths and created backwards-compatible re-exports

Time comparison: Single session estimate was 4+ hours. Agent team completed it in 1 hour 20 minutes. Agent 5 had the most conflicts because import path changes touched files that other agents had also modified. The lead agent resolved these by running Agent 5 last, after merging the first four.

Example 3: Multi-Cloud Infrastructure

Project: Deploying a disaster recovery setup across AWS (primary) and GCP (failover).

Team composition:

• Agent 1: AWS primary infrastructure (VPC, ECS, RDS, CloudFront)
• Agent 2: GCP failover infrastructure (VPC, Cloud Run, Cloud SQL, Cloud CDN)
• Agent 3: Cross-cloud networking (VPN tunnels, DNS failover, health checks)
• Agent 4: Monitoring and alerting (Datadog dashboards, PagerDuty routing, status page)

Time comparison: This was a case where agent teams provided more than just speed. Each agent had a different cloud-specific skill installed, so the AWS agent produced better AWS configs than a single agent switching between cloud contexts would have.

Cost Management {#cost-management}

Agent teams consume more tokens than single sessions. This is unavoidable — more agents means more model invocations. But the cost structure is manageable if you are strategic.

Token Usage by Pattern

Cost Optimization Strategies

Use subagents for small tasks. Do not spawn a full worktree agent for something that takes 2 minutes. If a task does not need file isolation, a subagent is cheaper and faster.

Front-load context in CLAUDE.md. Every agent reads your project's CLAUDE.md at session start. A well-written CLAUDE.md means agents need fewer clarifying reads of the codebase, which saves tokens. Include architecture decisions, key file locations, and conventions.

Kill idle agents. If an agent finishes its task early, end that session. Agents that sit idle still consume context window if you interact with them later.

Use the right plan. On the Claude Max plan, the 5x usage tier ($100/month) comfortably supports daily use of 4-agent teams. The 20x tier ($200/month) is only necessary if you are running agent teams continuously or working on very large codebases where each agent ingests significant context.

Batch related changes. Instead of running four separate agent team sessions for four features, batch related work into one session. The worktree setup, context loading, and merge overhead are amortized across more output.

Common Mistakes and How to Avoid Them {#common-mistakes}

Mistake 1: Using Agent Teams for Sequential Work

If task B depends on task A's output, running them in parallel wastes tokens. Agent B will either work with stale context (producing incorrect results) or block waiting for Agent A (wasting time).

Fix: Use subagents or the pipeline sequential pattern. Only parallelize genuinely independent work.

Mistake 2: Poor Task Boundaries

Giving two agents overlapping file ownership — both Agent A and Agent B need to modify src/utils/helpers.ts — guarantees merge conflicts.

Fix: Decompose by directory or module, not by feature layer. If two tasks need to touch the same file, make them sequential or assign one agent ownership of that file.

Mistake 3: Skipping the Lead Agent

Launching four agents without coordination and hoping the merges will "just work" is a recipe for wasted time.

Fix: Always have a lead agent (either you or a dedicated Claude session) that defines task boundaries, monitors progress, and handles merges.

Mistake 4: Over-Parallelizing

Running 8 agents when the project only supports 3 independent workstreams means 5 agents are either idle, duplicating work, or creating conflicts.

Fix: Start with 2-3 agents. Add more only when you have identified genuinely independent workstreams that would benefit from parallelism.

Mistake 5: Ignoring Worktree Cleanup

Worktrees accumulate. After a week of agent team usage, you might have 20+ stale worktree directories consuming disk space.

Fix: Clean up after every session:

# List all worktrees
git worktree list

# Remove stale worktrees
git worktree prune

# Remove a specific worktree
git worktree remove ../your-repo-worktree-abc123

For a detailed cleanup workflow, see the cleanup section of our worktrees guide.

Getting Started: Your First Agent Team Session

If you have never used agent teams before, here is a low-risk way to try them:

1. Pick a project with clear separation. A full-stack app with distinct frontend and backend directories is ideal.
2. Identify two independent tasks. Something like "add input validation to the API" and "build the error handling UI."
3. Open two terminals.
4. In Terminal 1: claude — this is your lead agent. Tell it the plan.
5. In Terminal 2: claude --worktree "Add input validation to all API endpoints" — this is your worker agent.
6. In Terminal 1: Work on the error handling UI yourself with the lead agent.
7. When both finish: Merge the worktree branch into your main branch.
8. Review the result. Was it faster? Were there conflicts? What would you decompose differently next time?

Two agents is enough to learn the patterns. Scale to 4-5 once you are comfortable with worktree merges and task decomposition.

For more on the parallel development model that underpins agent teams, read our complete guide to Claude Code worktrees. And to equip your specialist agents with the right knowledge, browse the skills directory for role-specific skills.

Frequently Asked Questions {#faq}

What is the difference between Claude Code subagents and agent teams?

Subagents are lightweight child agents spawned by a parent Claude session to handle focused subtasks. They share the same working directory and context. Agent teams are multiple independent Claude Code sessions running in parallel, typically in separate git worktrees, coordinated by a lead agent. Subagents are for task decomposition within a session; agent teams are for parallel execution across isolated environments.

How many Claude Code agents can run in parallel?

Anthropic supports up to 8 concurrent agent sessions on the Max plan. In practice, 4-5 parallel agents is the sweet spot for most complex projects — it provides significant speedup while keeping coordination overhead manageable and staying within typical rate limits. Each agent runs in its own worktree with its own branch, so there are no file conflicts.

How much does running Claude Code agent teams cost?

Each agent in a team consumes tokens independently. A typical agent team of 4 agents working for 30 minutes might use 500K-2M tokens total, depending on task complexity and codebase size. On the Max plan ($100/month for 5x usage, $200/month for 20x), this is covered by the subscription. On API pricing, expect $5-20 per complex multi-agent session. Cost management strategies include using subagents for simple tasks and reserving full agent teams for genuinely parallel work.

Do agent teams work with Claude Code skills and MCP servers?

Yes. Each agent in a team inherits the project's CLAUDE.md, skills from .claude/skills/, and MCP server configurations. Global skills from ~/.claude/skills/ are also available to every agent. This means specialized skills like Terraform Mastery or Kubernetes Operations apply consistently across all agents in the team.

When should I use agent teams instead of a single Claude session?

Use agent teams when your project has genuinely independent parallel work — such as building a frontend and backend simultaneously, writing tests while implementing features, or migrating multiple modules at once. If tasks are sequential (each step depends on the previous one), a single session with subagents is more efficient. The rule of thumb: if you would assign the tasks to different human developers, agent teams make sense.