一句话总结：Claude Code 不再是一个"超级程序员"单打独斗，而是一套可编排的工程小队操作系统——有队长、有队员、有任务看板、有内部信箱，甚至能跨机器部署。

---

一、架构全景：四大核心组件

Claude Code 的多 Agent 体系由四个紧密协作的组件构成，全部通过本地文件系统实现协调（无 WebSocket、无 gRPC，极简）：

组件	角色	持久化位置
👑 Team Lead	主会话，负责任务拆解、团队创建、结果汇总	会话期间
👥 Teammates	独立的 Claude Code 实例，各持独立上下文窗口	显式关闭前持续
📋 Shared Task List	共享任务板，支持状态追踪与依赖自动解锁	~/.claude/tasks/{team-name}/
📬 Mailbox	点对点消息系统，Agent 间直接通信	~/.claude/teams/{team-name}/inboxes/

💡 设计哲学：整个协调层是去中心化的。Team Lead 只是另一个 Claude 会话，拥有额外工具（TeamCreate、SendMessage）。没有后台守护进程，协作完全通过共享文件访问自然涌现。

---

二、Coordinator Mode：从写代码到做决策

在 Coordinator Mode 下，Claude 的角色发生了根本性转变：

传统模式：你 ↔ Claude（一个会话，所有事情自己干）
           ↓
Coordinator 模式：你 ↔ Team Lead（只决策、不编码）
                         ├── 拆解需求 → 子任务 A/B/C
                         ├── 启动 Worker Agent 并行执行
                         └── 收集结果 → 质量判断 → 向你汇报

Coordinator 的核心职责

职责	说明
🧩 规划任务	将大需求拆解为可并行的小需求
📤 分配 Worker	通过 AgentTool 启动子 Agent 执行具体工作
📥 汇总结果	收集子 Agent 反馈，做质量判断，向用户汇报

动态工具权限

getCoordinatorUserContext 会动态生成 Worker 可用工具集：

• 基础三件套：Bash、Read、Edit

• 异步 Agent 工具：允许特定工具调用

• MCP 服务器工具：扩展能力边界

---

三、三层隔离：从轻量到完全隔离

Claude Code 提供了三种 Agent 执行后端，隔离强度逐级递增：

1. 🟢 InProcessTeammate — 同进程队友

• 特点：与 Leader 共享同一进程、同一份 AppState、同一个 React 渲染树
• 通信：无进程 fork、无 tmux、无网络——在当前进程内多跑一个 runAgent() 循环
• 代价：共享内存。曾出现 2 分钟内拉起 292 个 Agent，内存冲到 36.8GB 的事故（因每个 teammate 在 task.messages 中存了一份完整对话副本）。现已加 TEAMMATE_MESSAGES_UI_CAP = 50 上限
• 适用：Team 协作里的简单队友

2. 🟡 LocalAgentTask — 本地独立 Worker

• 特点：同进程，但隔离层级更"重"
• 能力：可前台 ↔ 后台切换、独立隔离资源、独立输出落盘、可并行
• 定位：Coordinator 模式里的 Worker——可以脱离前台、独立跑到底的后台 Agent
• 适用：Coordinator 派出去的独立编码任务

3. 🔴 RemoteAgentTask — 远程云端 Agent

• 特点：唯一真正"完全隔离"——Agent 不在你的进程、不在你的机器上跑
• 执行体：通过 Teleport API 发到 Anthropic 远程云端 Session 执行
• 本地状态：只是远程的镜像，本地只能观察，碰不到本地文件/凭据
• 支持任务：remote-agent / ultraplan / ultrareview / autofix-pr / background-pr
• 适用：长时间运行、高安全、PR/CI 类任务

隔离强度对比：

InProcessTeammate  ──  同进程，最轻量，共享内存（292→36GB 的教训）
                         适合：简单协作队友

LocalAgentTask     ──  同进程，独立资源，可并行/前后台切换
                         适合：独立编码 Worker

RemoteAgentTask    ──  离开本机，Anthropic 云端执行
                         适合：长时任务、高安全、PR/CI

---

四、Mailbox：点对点通信（不是层级汇报）

传统多 Agent 架构是星型拓扑——所有 Worker 只能和 Coordinator 通信，Worker 之间互不可见。

Claude Code 的设计更灵活：Mesh 网络。

通信能力

• 点对点：任何 Agent 可通过 SendMessageTool 直接给任何 Agent 发消息
• 广播：Team Leader 可广播消息给所有 Teammate
• 系统消息：Mailbox 可传递系统级消息——申请工具权限、请求网络访问、请求关闭 Agent、审批执行计划、分配任务、修改权限模式

并发安全

当多 Agent 同时给同一 Agent 发消息时：

1. 目标 Agent 先锁住信箱文件
2. 读取最新消息
3. 加入新消息
4. 保存文件并解锁

📂 文件实现：每个 Agent 有自己的信箱文件 ~/.claude/teams/{team}/inboxes/{name}.json，基于 flock() 文件锁实现并发安全。

实战通信示例

Frontend Agent ──mailbox──▶ Backend Agent
  "UserProfile 组件需要 /api/user 返回 'lastLogin' 字段"

Backend Agent ──mailbox──▶ QA Agent  
  "GET /api/user 已添加 'lastLogin'，请补集成测试"

QA Agent ──shared task list──▶ All
  "✓ 12/14 测试通过，2 个被缺失的 auth 中间件阻塞"

---

五、Task List：共享任务看板

核心机制

• 存储位置：~/.claude/tasks/{team-name}/
• 任务状态：pending → in progress → completed
• 依赖追踪：Task A 完成后自动解锁 Task B
• 主动认领：Teammate 会主动认领下一个"未阻塞、无人认领"的任务
• 文件锁：.lock 文件使用 flock() 保证并发任务认领安全

任务类型全景

src/tasks/
├── DreamTask/              # Auto Dream 记忆巩固任务
├── InProcessTeammateTask/  # 进程内 Teammate（最轻量）
├── LocalAgentTask/         # 本地异步 Agent 任务
├── LocalMainSessionTask.ts # 本地主会话任务
├── LocalShellTask/         # 本地 Shell 命令任务
├── LocalWorkflowTask/      # 本地工作流任务
├── MonitorMcpTask/         # MCP 服务器监控任务
├── RemoteAgentTask/        # 远程云端 Agent 任务
├── types.ts                # TaskState 联合类型
├── pillLabel.ts            # 任务状态标签
└── stopTask.ts             # 任务终止逻辑

---

六、Agent Teams vs Subagents：怎么选？

这是最关键的选择题：

维度	Subagents	Agent Teams
协作模式	单会话内顺序调用	多会话并行，Lead 协调
通信方式	只能向父 Agent 汇报	Teammate 间直接通信（Mailbox）
协调机制	主 Agent 管理一切	共享 Task List + 自协调
上下文	独立窗口，结果返回调用者	完全独立实例，不继承 Lead 对话历史
适用场景	聚焦任务，只要结果	复杂工程，需要讨论与协作
Token 成本	中等（结果摘要回传）	高（每个 Teammate 独立消费 Token）

🧠 类比：Subagent 像快递员——完成任务、回来汇报。Agent Teams 像工程小队——前端可以直接问后端：“API 契约改了，你那边同步了吗？”

---

七、实战：如何启用 Agent Teams

1. 开启实验功能

确保 Claude Code ≥ v2.1.32，在 settings.json 中添加：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

2. 创建团队

用自然语言描述：

create an agent team with 3 teammates to refactor these modules in parallel

或更具体的角色分配：

I'm designing a CLI tool. Create an agent team:
  - one teammate on UX
  - one on technical architecture  
  - one playing devil's advocate

3. 交互操作

• 切换 Teammate：Shift+Down 循环切换
• 分屏显示：tmux / iTerm2 自动分 pane
• 观察文件系统（极客玩法）：

watch -n 0.5 'tree ~/.claude/teams/ 2>/dev/null; echo "---"; tree ~/.claude/tasks/ 2>/dev/null'

4. 预定义角色库

在 .claude/agents/*.md 中预定义可复用的 Teammate 角色（系统提示词、写入范围、模型选择、工具权限），Claude 会根据任务自动挑选合适的角色 spawn。

---

八、成本、安全与边界

💰 成本现实

• 每个 Teammate 是独立的 Claude 实例，各自消耗 Token
• Anthropic 内部测试：用 16 个 Agent Team 构建 C 编译器，消耗约 20 亿美元 API 费用、20 亿输入 Token、1.4 亿输出 Token，产出 10 万行 Rust 代码成功编译 Linux 6.9 内核
• 建议：简单任务用 Subagent，复杂跨模块协作才上 Agent Teams

🔒 权限继承

• Teammate 默认继承 Lead 的权限设置
• 如果 Lead 用 --dangerously-skip-permissions，所有 Teammate 也跳过
• 可在 spawn 后单独修改某个 Teammate 的权限模式

⚠️ 已知限制

• 实验性功能，需显式开启环境变量
• 无法为单个 Teammate 设置 spawn 时权限（只能 spawn 后改）
• 并发消息存在文件锁竞争（设计如此，但需注意）
• 292 Agent → 36GB 内存的教训说明：不要无节制 spawn

---

九、总结：从"提示工程"到"管理工程"

Claude Code 的多 Agent 架构标志着 AI 辅助开发的一次范式转移：

阶段	模式	你的角色
1.0	单会话问答	写更好的 Prompt
2.0	Subagent 委派	设计任务并等待结果
3.0	Agent Teams 协作	工程经理——定方向、做决策、审质量

你不再是在和一个"超级程序员"对话，而是在管理一支可编排的 AI 工程小队。这支小队有队长、有分工、有通信、有任务板——甚至能在云端独立运行。真正的瓶颈不再是模型的代码能力，而是你的架构设计与管理能力。

---

📌 延伸阅读：如果你对源码级实现感兴趣，Claude Code 的 Agent Teams 协议完全基于磁盘文件契约（~/.claude/teams/ 和 ~/.claude/tasks/），任何能读写这些文件的进程都可以作为 Teammate 接入——这也是 claude-anyteam 等项目能让 Codex、Gemini 等外部 Agent 以"一等公民"身份加入 Claude Code 团队的原因。