Claude Code Agent Teams: Architecture Deep Dive and Production Patterns (2026)

Most coverage of Claude Code Agent Teams focuses on how to start a team and what prompts to write. That’s useful, but it leaves a gap: once you’re past the basics, you need to understand the mechanics well enough to design tasks that actually benefit from parallelism, diagnose failures when coordination breaks down, and keep costs from spiraling.

This article goes deeper. We cover the full architecture — team lead, teammates, shared task list, mailbox messaging — alongside five production patterns with concrete examples, Hooks integration for quality gates, and an honest cost analysis. If you’ve already shipped something with agent teams (or tried to), this is the reference you’ll want.

Why Agent Teams Matter in 2026

The context window problem hasn’t gone away. You can fit more in a single session than you could two years ago, but large codebases, multi-layer refactors, and cross-cutting investigations still hit limits. The common workaround — breaking work into sequential steps in a single session — has a ceiling: each step builds on the previous, so the context grows, the model slows down, and the whole chain becomes fragile.

Agent teams take a different approach. Instead of serializing work to fit one context window, you distribute it across multiple independent context windows. Each teammate has its own fresh context, works on an isolated piece of the problem, and communicates with other agents through a structured coordination layer. The team can proceed in parallel on genuinely independent work streams.

The practical impact is significant for certain problem shapes: a three-teammate code review runs in roughly a third of the wall-clock time of sequential review. A five-agent debugging investigation explores competing hypotheses simultaneously instead of anchoring on the first plausible theory. A full-stack feature can split cleanly into frontend, backend, and test layers that each run independently.

It is not a universal speedup. Coordination overhead is real, token costs scale with team size, and sequential or highly coupled work sees no benefit. But when the problem genuinely parallelizes, agent teams are the most effective tool Claude Code offers for tackling it.

Architecture Overview

An agent team has four structural components. Understanding each one is prerequisite to writing good team prompts and diagnosing failures.

┌─────────────────────────────────────────────────────────┐
│                     AGENT TEAM                          │
│                                                         │
│  ┌──────────────┐    ┌──────────────────────────────┐  │
│  │  TEAM LEAD   │◄──►│         TASK LIST            │  │
│  │              │    │  ┌──────────────────────────┐│  │
│  │ Coordinates  │    │  │ [pending]  Task A         ││  │
│  │ work, spawns │    │  │ [claimed]  Task B → TM-1  ││  │
│  │ teammates,   │    │  │ [claimed]  Task C → TM-2  ││  │
│  │ synthesizes  │    │  │ [done]     Task D         ││  │
│  │ results      │    │  └──────────────────────────┘│  │
│  └──────┬───────┘    └──────────────────────────────┘  │
│         │                                               │
│    ┌────┴─────────────────────────────┐                 │
│    │         MAILBOX                  │                 │
│    │  (async message delivery)        │                 │
│    └────┬────────────┬───────────────┘                 │
│         │            │                                  │
│  ┌──────▼──────┐ ┌───▼──────────┐                      │
│  │ TEAMMATE-1  │ │ TEAMMATE-2   │  (up to N teammates) │
│  │ Own context │ │ Own context  │                      │
│  │ Own tools   │ │ Own tools    │                      │
│  └─────────────┘ └──────────────┘                      │
│                                                         │
│  Team config: ~/.claude/teams/{name}/config.json        │
│  Task store:  ~/.claude/tasks/{name}/                   │
└─────────────────────────────────────────────────────────┘

Team Lead

The team lead is the Claude Code session that received your original request. It creates the team, decides how many teammates to spawn (or follows your explicit instruction), assigns tasks, and synthesizes results when the team finishes. The lead is not a lightweight coordinator — it runs as a full Claude instance with its own context window, reading project files, making decisions, and sometimes doing work itself alongside teammates.

One important constraint: the lead is fixed for the lifetime of a team. You cannot promote a teammate to lead, and you cannot transfer leadership to another session. If your lead crashes or gets into a bad state, you need to clean up and start fresh.

Teammates

Teammates are independent Claude Code instances. Each has its own context window, loads CLAUDE.md, MCP servers, and skills from your project at spawn time, and receives a spawn prompt from the lead that describes their specific assignment. The lead’s conversation history does not carry over to teammates — they start fresh.

This isolation is the point. It prevents teammates from being anchored to the lead’s reasoning, gives each one a clean context for its specific domain, and means a failure in one teammate doesn’t corrupt others.

The practical implication: teammates won’t know things your lead knows unless you explicitly put them in the spawn prompt or CLAUDE.md. This is one of the most common failure modes — the lead spawns a teammate without including key context (an API contract, a coding convention, a file that needs to be respected), and the teammate produces work that’s technically correct but incompatible with the rest of the system.

Shared Task List

The task list is a shared store of work items located at ~/.claude/tasks/{team-name}/. Tasks have three states:

• Pending: available to be claimed
• In progress: claimed by a specific teammate (file locking prevents race conditions)
• Completed: done, potentially unblocking dependent tasks

Tasks support dependency relationships. A task can declare that it cannot start until other tasks are complete. When a teammate finishes work, the system automatically evaluates whether blocked tasks can now be unblocked — you don’t manage this manually.

Task claiming uses file locking. When two teammates race to claim the same task, only one succeeds. The other sees the lock, skips that task, and moves to the next pending item. This is what makes parallel execution coherent rather than duplicated.

A practical heuristic: aim for 5-6 tasks per teammate. Too few tasks means teammates idle while waiting for the lead to reassign work. Too many means context switching overhead. If you have 15 independent refactoring tasks, 3 teammates with 5 tasks each is typically more effective than 6 teammates with 2-3 each.

Mailbox

The mailbox is the messaging layer between agents. When a teammate sends a message, it arrives at the recipient automatically — the lead doesn’t poll for updates. Teammates can message each other directly by name without routing through the lead, which is the key architectural difference from subagents.

Messages are delivered per-recipient. If you want to reach all teammates, you send one message per recipient; there’s no broadcast primitive. The lead assigns names to teammates at spawn time, and you can specify those names in your prompt to get predictable references for later messages.

Idle notifications work through the mailbox too. When a teammate finishes its work and goes idle, it sends an automatic notification to the lead. The lead uses this to track team progress and decide when to synthesize results or assign more work.

Subagents vs. Agent Teams

The difference matters for task design. Using the wrong model leads to either unnecessary overhead (agent teams for sequential work) or missing capabilities (subagents when inter-agent coordination is needed).

SUBAGENTS (hub-and-spoke)           AGENT TEAMS (mesh)

     Lead                             Lead
    / | \                           /   \
  SA  SA  SA                      TM-1  TM-2
   \  |  /                          \   /
    \ | /                           TM-3
    (results)                   (peer messages + shared tasks)

The decision heuristic: if your workers need to share findings, challenge each other’s conclusions, or unblock each other — use agent teams. If they just need to execute tasks and return results — use subagents.

A code review where each reviewer applies a different lens is a team problem: the security reviewer’s finding about a shared utility might affect what the performance reviewer recommends. A batch of independent file migrations is a subagent problem: each migration is self-contained and results can be summarized.

Enabling and Configuration

Agent teams are off by default. Enable them in settings.json or in your shell environment:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or in your shell profile:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Requires Claude Code v2.1.32 or later. Verify with claude --version.

Teammate model selection

Teammates do not inherit the lead’s model selection by default. To configure:

# In your spawn prompt
Create a team with 3 teammates. Use Sonnet for each teammate.

# Or set the default in /config
# Navigate to: Default teammate model → Default (leader's model)

For most production workloads, Sonnet is the right choice for teammates. Opus costs significantly more per token, and the coordination tasks teammates handle — implementing a defined scope, applying a specific review lens — don’t require the added reasoning depth Opus provides. Reserve Opus for the lead when the orchestration itself is complex.

Plan approval mode

For risky changes, you can require teammates to submit a plan before touching code:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

The teammate operates in read-only mode, explores the codebase, drafts a plan, and sends it to the lead for approval. The lead either approves or rejects with feedback. If rejected, the teammate revises and resubmits. Once approved, implementation begins.

The lead makes approval decisions autonomously. You control the criteria in your spawn prompt: “only approve plans that include test coverage” or “reject plans that modify the database schema” are both interpretable by the lead.

Display Modes

In-process mode

All teammates run inside your main terminal. Navigation:

• Shift+Down: cycle through teammates
• Enter: view a teammate’s current session
• Escape: interrupt a teammate’s current turn
• Ctrl+T: toggle the task list view

In-process mode works in any terminal. It’s the default unless you’re already inside a tmux session.

Split-pane mode

Each teammate gets its own terminal pane, visible simultaneously. You can click into any pane to interact directly. Requires tmux or iTerm2.

// ~/.claude/settings.json
{
  "teammateMode": "tmux"
}

Or per-session:

claude --teammate-mode in-process

The "auto" default detects your environment: if you’re inside tmux, split panes activate; otherwise, in-process mode runs. For tmux with iTerm2, use tmux -CC as the recommended entry point.

Split-pane mode is not supported in VS Code’s integrated terminal, Windows Terminal, or Ghostty.

Five Production Patterns

These are the patterns that consistently deliver value in production. Each includes the exact prompt structure and the specific reason it works.

Pattern 1: Parallel PR Review with Distinct Lenses

Problem: A single reviewer tends to gravitate toward one category of issue. Security problems get missed when someone is focused on performance. Conversely, reviewer context switching between domains produces shallower findings in each.

Solution: Split review criteria into independent, non-overlapping domains and assign each to a dedicated reviewer.

Review PR #142. Create an agent team with three reviewers:

Teammate 1 (Security Reviewer):
- Focus exclusively on: auth/authorization issues, input validation, 
  SQL injection vectors, secrets handling, dependency vulnerabilities
- Report each finding with: file, line, severity (critical/high/medium), 
  and specific remediation

Teammate 2 (Performance Reviewer):
- Focus exclusively on: N+1 queries, unbounded loops, memory allocations,
  unnecessary network calls, caching opportunities
- Include measured impact estimates where possible

Teammate 3 (Test Coverage Reviewer):
- Focus exclusively on: untested edge cases, missing error paths, 
  test isolation issues, flaky test patterns
- Flag any changes that lack corresponding test updates

After all three complete, synthesize findings into a prioritized action list.

Why it works: The constraint is real. Each reviewer applies a genuine filter, not a checklist. The lead’s synthesis pass catches cross-cutting issues that arise when findings from multiple lenses interact.

Token cost: ~3x a single-session review. The payoff is reviewers that go deeper in their domain because they’re not context-switching.

Pattern 2: Full-Stack Feature Development

Problem: Frontend, backend, and test code for a feature share a contract (API shape, error codes, data model) but are otherwise independent. Serializing them means each layer waits for the previous one, and the developer spends time as a messenger between concerns.

Solution: Agree on the contract first, then parallelize implementation across layers.

Implement the user notification preferences feature. The API contract is:
- GET /users/{id}/notifications → NotificationPreferences
- PATCH /users/{id}/notifications → Updated NotificationPreferences
- NotificationPreferences: { email: bool, push: bool, sms: bool, digest: "daily"|"weekly"|"never" }

Create an agent team with three teammates:

Teammate 1 (Backend):
- Implement the REST endpoints in src/api/notifications/
- Add the database migration for the preferences table
- Write unit tests for the service layer

Teammate 2 (Frontend):
- Implement the preferences settings page in src/components/Settings/
- Wire up the API calls using the existing apiClient
- Handle loading and error states

Teammate 3 (Integration Tests):
- Write end-to-end tests covering the full user flow
- Include edge cases: concurrent updates, invalid values, missing users
- Ensure tests run against the real database schema

All teammates: respect existing conventions in CLAUDE.md.
Backend must finish migration before Integration Tests run their tests.

Why it works: The contract makes teammates genuinely independent. Backend and Frontend can build against the same spec without waiting for each other. The dependency declaration (backend migration before integration tests) handles the one real sequencing constraint.

Token cost: ~3x single-session. Wall-clock time roughly halves compared to sequential implementation.

Pattern 3: Bug Investigation with Competing Hypotheses

Problem: Single-agent debugging anchors. The first plausible hypothesis gets explored, evidence is interpreted to fit it, and alternatives get insufficient attention. This is especially costly for intermittent bugs or issues with multiple plausible root causes.

Solution: Assign competing hypotheses to different teammates and structure the investigation as an adversarial debate.

Users report the app exits after processing one message instead of
staying connected. The issue is intermittent and hard to reproduce locally.

Create an agent team with 5 investigators, each responsible for a 
different hypothesis:

Teammate 1 (Connection Management): Investigate whether the WebSocket 
connection closes prematurely — check keepalive settings, timeout configs,
connection pool exhaustion.

Teammate 2 (Error Handling): Look for unhandled exceptions that might 
cause silent exits — check catch blocks, promise rejections, and crash 
handlers in the message processing pipeline.

Teammate 3 (State Machine): Examine whether the connection state machine 
has invalid transitions — map all states and transitions, look for paths 
that reach a closed/terminal state unexpectedly.

Teammate 4 (Memory/Resource): Investigate resource leaks that could cause 
the process to crash after the first message — memory growth, file descriptor 
leaks, buffer exhaustion.

Teammate 5 (Race Conditions): Look for concurrent write bugs — check shared 
state accessed from multiple goroutines/threads, lock contention, and 
ordering issues in the message handler.

Each teammate should:
1. Investigate their hypothesis thoroughly
2. Actively look for evidence that DISCONFIRMS their hypothesis
3. Communicate findings to other teammates when relevant
4. Challenge other teammates' theories with evidence

Update docs/debugging/connection-exit-investigation.md with consensus findings.

Why it works: The adversarial framing is the key mechanism. Teammates are explicitly asked to look for disconfirming evidence and challenge each other. This counteracts the anchoring bias that makes single-agent debugging slow. The theory that survives peer challenge is much more likely to be the actual root cause.

Pattern 4: Code Migration at Scale

Problem: Migrating a large codebase (API version, framework upgrade, dependency replacement) involves hundreds of similar transformations across many files. A single agent works sequentially through the list; teammates can partition the work and run in parallel.

Solution: Define the transformation rule once, partition the target files, and assign partitions to teammates.

Migrate the codebase from the v1 Logger API to v2. 

Migration rules:
- Replace: logger.log(level, msg) → logger[level](msg)  
- Replace: logger.setLevel(x) → logger.configure({ level: x })
- Replace: import Logger from 'logger-v1' → import { Logger } from 'logger-v2'
- Remove: logger.init() calls (no longer needed)
- Add: error handling where logger calls are in hot paths (see v2 migration guide)

Create an agent team to migrate in parallel:

Teammate 1: Migrate src/api/**/*.ts
Teammate 2: Migrate src/services/**/*.ts  
Teammate 3: Migrate src/workers/**/*.ts
Teammate 4: Migrate src/lib/**/*.ts and src/utils/**/*.ts

Each teammate should:
1. Apply all migration rules consistently
2. Run TypeScript compiler after each file to catch type errors
3. Note any ambiguous cases in docs/migration-log.md

Lead: After all teammates complete, run the full test suite and report failures.

Why it works: The transformation is well-defined and the file partitions are non-overlapping. Teammates cannot conflict with each other because they own different directories. The parallel speedup scales linearly with team size for this pattern.

Caveat: If the migration involves shared utility files that multiple partitions import, sequence those first in the lead or use task dependencies to order them correctly.

Pattern 5: Documentation Generation

Problem: Documentation tasks are often deferred because they’re tedious and sequential. A single agent generating docs for an entire codebase spends most of its time in read-only exploration, which parallelizes cleanly.

Solution: Assign each teammate a documentation domain and have them work concurrently.

Generate comprehensive API documentation for the payments module.

Create an agent team with 4 teammates:

Teammate 1 (REST API Reference):
- Document all endpoints in src/api/payments/
- For each endpoint: method, path, request schema, response schema, error codes
- Output: docs/api/payments-endpoints.md

Teammate 2 (Data Model Reference):  
- Document all types, interfaces, and database schemas in src/models/payments/
- Include field descriptions, validation rules, and relationships
- Output: docs/api/payments-models.md

Teammate 3 (Integration Guide):
- Write a step-by-step integration guide for the payments module
- Cover: authentication, webhook setup, error handling, testing in sandbox
- Output: docs/guides/payments-integration.md

Teammate 4 (Code Examples):
- Write working code examples for the 5 most common payment flows
- Cover: charge, refund, subscription, dispute, webhook verification
- Use TypeScript. Examples must be runnable.
- Output: docs/examples/payments-examples.ts

All teammates: maintain consistency in terminology. Use the glossary at
docs/payments-glossary.md as the canonical source.

Why it works: Documentation domains are independent. None of the teammates need each other’s output to complete their section. The shared glossary instruction ensures consistent terminology without requiring inter-agent coordination.

Hooks Integration for Quality Gates

Hooks give you programmatic control over three points in the agent team lifecycle:

TeammateIdle Hook

Runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working — this is how you implement automated quality checks.

// settings.json
{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/teammate-quality-check.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# teammate-quality-check.sh
input=$(cat)
teammate=$(echo "$input" | jq -r '.teammate_name')

# Run tests against the teammate's changes
cd "$(echo "$input" | jq -r '.working_directory')"
test_result=$(npm test -- --coverage 2>&1 | tail -20)

coverage=$(echo "$test_result" | grep -oP 'Lines\s*:\s*\K[\d.]+')

if (( $(echo "$coverage < 80" | bc -l) )); then
  echo "Quality gate failed for $teammate: test coverage is ${coverage}%, minimum is 80%."
  echo "Add tests before marking work complete."
  exit 2
fi

exit 0

When the hook exits with code 2, the message is delivered to the teammate as feedback, and the teammate continues working instead of going idle. The lead receives the event too.

TaskCreated Hook

Runs when a task is being created. Use this to enforce task quality standards before work is assigned.

#!/bin/bash
# Prevent tasks without acceptance criteria
input=$(cat)
description=$(echo "$input" | jq -r '.description')

if ! echo "$description" | grep -q "Acceptance criteria:"; then
  echo "Task rejected: missing acceptance criteria. Add 'Acceptance criteria:' section."
  exit 2
fi

exit 0

TaskCompleted Hook

Runs when a task is being marked complete. Use this for automated verification.

#!/bin/bash
# Verify TypeScript compiles before marking complete
input=$(cat)
working_dir=$(echo "$input" | jq -r '.working_directory')

cd "$working_dir"
if ! npx tsc --noEmit 2>&1; then
  echo "Task completion blocked: TypeScript compilation errors detected. Fix errors before marking complete."
  exit 2
fi

exit 0

Hook Architecture in Teams

Hooks run in the context of the agent that triggered them. A TaskCompleted hook triggered by a teammate runs in that teammate’s environment. A TeammateIdle hook sees the teammate’s context. This means hooks have access to the same working directory and environment variables as the agent that triggered them.

The lead also has access to all hook events, which lets you implement team-level oversight in addition to per-teammate checks.

Cost Analysis

Agent teams use significantly more tokens than single sessions. The exact multiplier depends on team size, task complexity, and whether you use plan approval mode.

Token scaling

Base model: each teammate is a full Claude instance with its own context window. Token usage is roughly linear with team size — a 3-teammate team uses approximately 3x the tokens of a single session for the same scope of work.

With plan approval mode enabled, costs increase substantially. The official docs note that agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because the planning phase is a full read-only exploration of the codebase before any implementation begins.

Single session:   1x tokens
3-teammate team:  ~3x tokens (proportional)
5-teammate team:  ~5x tokens (proportional)
Plan mode (3-TM): ~7x tokens (read-only planning adds significant overhead)

What you get for the tokens

The value proposition depends on what you’re parallelizing:

The cost is worth paying when the quality or speed improvement from parallelism outweighs the token multiplier. It is not worth paying for sequential work just because agent teams are available.

Cost control strategies

Use Sonnet for teammates. The capability ceiling for coordination tasks is lower than for architectural decisions. Sonnet is the right model for 90% of teammate work.

Keep spawn prompts focused. Spawn prompts become part of every teammate’s context from the start. A 500-token spawn prompt across 5 teammates adds 2,500 tokens before any work begins. Include what’s necessary; avoid recapping shared context that’s already in CLAUDE.md.

Clean up when done. Active teammates consume tokens even when idle. When the team is done, run cleanup explicitly:

Clean up the team

Start small. Three focused teammates with clear task definitions typically outperform five with vague assignments. Start with the minimum team size and scale up only if work remains after the initial team finishes.

Monitor with /usage. In-session token tracking shows current usage. For team sessions, /usage shows a breakdown by teammate.

Common Failure Patterns and Mitigations

Failure: Teammates doing the same work

Symptom: Two teammates edit the same file, producing conflicting changes.

Root cause: Task definitions overlap, or teammate scope wasn’t clearly partitioned.

Fix: Define file-level or module-level ownership in your spawn prompts. “Teammate 1 owns src/api/” is clearer than “Teammate 1 handles the API layer.”

Failure: Teammate spawned without key context

Symptom: Teammate produces technically correct work that doesn’t match the rest of the system — wrong API conventions, missing error handling, incompatible data model.

Root cause: Teammates don’t inherit the lead’s conversation history. If the lead knows about an important constraint that isn’t in CLAUDE.md, teammates don’t know about it.

Fix: Be explicit in spawn prompts. Don’t assume teammates know things the lead knows. If there’s an API contract, include it. If there’s a coding convention, mention it. Key architectural decisions belong in CLAUDE.md so all teammates load them automatically.

Failure: Lead does work instead of delegating

Symptom: You asked for a team, but the lead is handling tasks itself instead of assigning them to teammates.

Fix: Tell the lead explicitly:

Wait for your teammates to complete their tasks before proceeding.
Delegate the implementation to teammates; your role is coordination and synthesis.

Failure: Stuck tasks blocking progress

Symptom: A task is marked as in-progress but no teammate is actively working on it. Dependent tasks can’t start.

Root cause: The teammate that claimed the task stopped working without updating the task status.

Fix: In in-process mode, press Shift+Down to check the claiming teammate’s state. If it’s stuck, give it a direct message or spawn a replacement. You can manually update the task status if the work is actually done:

Tell the lead: Task B is complete. Update the status and unblock dependent tasks.

Failure: Orphaned sessions after cleanup

Symptom: tmux sessions persist after the team ends.

Fix: List and kill manually:

tmux ls
tmux kill-session -t <session-name>

Always run cleanup through the lead, not a teammate — teammate cleanup may not resolve the team context correctly.

Failure: Permission interrupts breaking flow

Symptom: Teammate permission requests bubble up to the lead constantly, interrupting work.

Root cause: Common operations (file writes, test runs, git commands) require approval because they weren’t pre-approved.

Fix: Pre-approve common operations in settings.json before spawning teammates. If teammates will write files, run tests, and use git, those should be approved at the start.

Failure: Session resumption breaks team state

Symptom: After /resume, the lead tries to message teammates that no longer exist.

Root cause: /resume and /rewind do not restore in-process teammates. This is a known limitation.

Fix: Tell the lead to spawn new teammates for any work that wasn’t completed in the previous session. Alternatively, use split-pane mode (tmux) which has different resumption behavior.

FAQ

Q: How many teammates should I spawn for a given task?

Start with 3-5. Each teammate should have 5-6 tasks to keep them productive without excessive context switching. If you have 15 independent tasks, 3 teammates is a better starting point than 15 teammates with one task each. Scale up only when the work genuinely requires more parallel streams.

Q: Can I change which model a teammate uses after it’s been spawned?

You can change individual teammate modes after spawning, but you can’t change the model mid-session. Set the model in your spawn prompt: “Spawn a security reviewer teammate using Sonnet.”

Q: What happens when a teammate encounters an error?

The teammate attempts to recover on its own. If it can’t, it stops and the lead is notified via the mailbox. You can then give the teammate direct instructions (Shift+Down to navigate to it) or spawn a replacement for the remaining work.

Q: Can teammates spawn their own subagents?

Yes. Teammates are full Claude Code sessions and can use subagents for focused delegated work within their scope. However, teammates cannot spawn their own teammates — only the lead manages the team.

Q: How do I prevent teammates from touching files they shouldn’t?

Use explicit file-level ownership in spawn prompts: “Do not modify files outside of src/api/.” For higher-confidence enforcement, the TaskCreated hook can validate that task descriptions comply with scope rules before work begins.

Q: Can I use subagent definitions (AGENTS.md) for teammates?

Yes. Reference a subagent type by name in your spawn instruction: “Spawn a teammate using the security-reviewer agent type.” The teammate honors that definition’s tools allowlist and model, with the definition’s body appended to the system prompt. Note that skills and mcpServers from the subagent definition are not applied when running as a teammate — these load from project and user settings instead.

Q: Agent teams are experimental — how stable are they in production?

Stable enough for real workloads as of Claude Code v2.1.32+, but with genuine rough edges: no session resumption for in-process teammates, task status can lag, shutdown can be slow, and split-pane mode requires tmux or iTerm2. The most common production issue is task status drift — check in on teammates periodically rather than letting a team run unattended.

Putting It Together

Agent teams are a structural solution to a structural problem: some work genuinely benefits from multiple independent perspectives operating in parallel, and a single context window can’t capture all of them simultaneously.

The architecture is built around that constraint. The task list prevents coordination becoming a bottleneck. The mailbox enables peer communication without routing everything through a lead. The hook system gives you programmatic quality gates at the right points in the workflow.

The patterns that work are the ones where parallelism is real — where teammates can genuinely work independently and where the combination of results produces something better than sequential execution. Parallel review, competing-hypothesis debugging, and contract-defined feature development fit this profile. Sequential refactoring and highly coupled work don’t.

Cost scales linearly with team size, so the question for each use case is whether the quality or speed benefit outweighs the token multiplier. For investigation and review work, it almost always does. For routine execution, a single session is more cost-effective.

Related Articles

• Claude Code Hooks Complete Reference (2026) — Full reference for all hook types including TeammateIdle, TaskCreated, and TaskCompleted
• Claude Code MCP Complete Guide (2026) — How MCP servers are loaded and available to teammates
• How to Write Claude Code Skills (2026) — Defining reusable agent types with subagent definitions for use in teams