AI 原生开放教材

外观

Claude Code Ultimate Guide工程手册·英文原文 ↗原件 ↓仓库 ↗

2. Architecture Deep-Dive ​

Lead-Teammate Architecture ​

┌─────────────────────────────────────────────────┐
│         Team Lead (Main Session)                │
│  - Breaks tasks into subtasks                   │
│  - Spawns teammate sessions                     │
│  - Synthesizes findings from all agents         │
│  - Coordinates via shared task list + mailbox   │
└─────────────────┬───────────────────────────────┘
                  │
        ┌─────────┴─────────┐
        │                   │
┌───────▼────────┐  ┌───────▼────────┐
│  Teammate 1    │◄─┼────────────────►│  Teammate 2    │
│                │  │ Peer-to-peer    │                │
│ - Own context  │  │ messaging via   │ - Own context  │
│   (1M tokens)  │  │ mailbox system  │   (1M tokens)  │
│ - Claims tasks │  │                 │ - Claims tasks │
│ - Messages     │  │                 │ - Messages     │
│   team/peers   │  │                 │   team/peers   │
└────────────────┘  └─────────────────┘────────────────┘

Git-Based Coordination ​

How it works:

  1. Task claiming: Agents write lock files to shared directory (.claude/tasks/)
  2. Work execution: Each agent works independently in its context
  3. Continuous merge: Agents pull/push changes to shared git repository
  4. Conflict resolution: Automatic merge (with limitations, see §6)
  5. Result synthesis: Team lead collects findings and presents unified response

Example lock file structure:

.claude/tasks/
├── task-1.lock        # Agent A claimed
├── task-2.lock        # Agent B claimed
└── task-3.pending     # Not yet claimed

Communication Architecture ​

Key distinction from sub-agents: Agent teams implement true peer-to-peer messaging via a mailbox system, not just hierarchical reporting.

Architecture components (Source: Addy Osmani, Feb 2026):

  1. Team lead: Creates team, spawns teammates, coordinates work
  2. Teammates: Independent Claude Code instances with own context (1M tokens each)
  3. Task list: Shared work items with dependency tracking and auto-unblocking
  4. Mailbox: Inbox-based messaging system enabling direct communication between agents

Communication patterns:

  • Lead → Teammate: Direct messages or broadcasts to all
  • Teammate → Lead: Progress updates, questions, findings
  • Teammate ↔ Teammate: Direct peer-to-peer messaging (challenge approaches, debate solutions)
  • Final synthesis: Team lead aggregates all findings for user

Example messaging flow:

Team Lead: "Review this PR for security issues"
├─ Teammate 1 (Security): Analyzes → Messages Teammate 2: "Found auth issue in line 45"
├─ Teammate 2 (Code Quality): Reviews → Messages back: "Confirmed, also see OWASP violation"
└─ Team Lead: Synthesizes findings → Presents unified response to user

What this enables:

  • ✅ Agents actively challenge each other's approaches
  • ✅ Debate solutions without human intervention
  • ✅ Coordinate independently (self-organization)
  • ✅ Share discoveries mid-workflow (via messages, not context)

Limitation: Context isolation remains. Agents don't share their full context window, only explicit messages.

Built-in navigation:

  • Shift+Down: Cycle through teammates in in-process mode
  • tmux/iTerm2: Split pane mode with teammateMode: "tmux" (requires tmux or iTerm2 with it2 CLI)
  • Direct takeover: You can take control of any agent's work when needed

Example:

bash
# Terminal 1: Team lead (with env var set)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

# Claude spawns teammates automatically
# You can navigate with Shift+Down to cycle through teammates (in-process mode)

Context Management ​

Per-agent context:

  • Each agent has 1M token context window (Opus 5)
  • ~30,000 lines of code per session
  • Context isolation: Agents don't share their full context window
  • Communication: Via mailbox system (peer-to-peer + team lead synthesis)

Total context capacity (3 agents example):

  • Team lead: 1M tokens
  • Teammate 1: 1M tokens
  • Teammate 2: 1M tokens
  • Total: 3M tokens across team (context isolated, but communicating via messages)

Important distinction:

  • ❌ Context NOT shared: Agent 1's full 1M token context invisible to Agent 2
  • ✅ Messages ARE shared: Agents send explicit messages via mailbox (findings, questions, debates)