2026 如何养好 Claude Code(四):多Agent协作实战

系列导航


引言:从单兵作战到团队协作

前几篇文章,我们都在讲"怎么用好一个 Claude"。但如果你面对的是一个大型项目,需要同时处理前端、后端、测试、文档……单靠一个 Claude 会话,效率会打折扣。

Agent Teams 就是 Claude Code 的"多人协作模式"——让多个 Claude 实例同时工作,各自负责不同模块,还能互相通信协调。

本文将从 ClaudeCode 中的 Agent 自身机制出发, 结合案例由浅入深的介绍 Agent Teams.


一、什么是 Agent Teams?

Agent Teams 是 Claude Code 的实验性多 Agent 协作功能,允许你同时运行多个 Claude 实例,它们可以自主协调、点对点通信、并行工作。

核心价值

从"单线程串行执行"升级为"多线程并行协作",让复杂任务真正实现并行处理。

四大核心组件

graph TB
    subgraph "Agent Team 架构"
        A[Team Lead<br/>主会话] --> B[Shared Task List<br/>共享任务列表]
        A --> C[Mailbox<br/>消息系统]

        B --> D[Teammate 1<br/>独立上下文]
        B --> E[Teammate 2<br/>独立上下文]
        B --> F[Teammate N<br/>独立上下文]

        C <--> D
        C <--> E
        C <--> F
        D <--> E
        E <--> F
    end

    style A fill:#7B9EC8,stroke:#5a8ab8,color:#fff
    style B fill:#D4A574,stroke:#b8905a,color:#fff
    style C fill:#7BA17B,stroke:#5a8a5a,color:#fff
    style D fill:#f3e5f5
    style E fill:#f3e5f5
    style F fill:#f3e5f5
组件 说明 类比
Team Lead 你的主 Claude Code 会话,负责创建团队、分配任务、综合结果 技术团队负责人
Teammates 独立的 Claude 实例,各有自己的上下文窗口 独立贡献者
Shared Task List 共享任务列表,支持依赖跟踪,任务有三种状态(pending/in_progress/completed) 项目看板
Mailbox Agent 间消息系统,支持 message(点对点)和 broadcast(广播) 即时通讯

任务状态模型

pending → in_progress → completed
   ↑           │
   └───────────┘
   (可重置回 pending)

任务支持依赖链:依赖未完成的任务不可被领取。任务领取使用文件锁防止竞态条件。


二、Sub-agents vs Agent Teams:何时用哪个?

很多人会问:这不就是 Sub-agent 吗?其实有很大区别:

graph LR
    subgraph sa["Sub-agents 模式"]
        A1[Main Agent] --> B1[Sub-agent 1]
        A1 --> C1[Sub-agent 2]
        B1 -->|结果返回| A1
        C1 -->|结果返回| A1
    end

    subgraph at["Agent Teams 模式 Mesh"]
        A2[Team Lead] --> B2[Teammate 1]
        A2 --> C2[Teammate 2]
        B2 <-->|直接通信| C2
        B2 -->|共享| D2[Task List]
        C2 -->|共享| D2
    end

    style A1 fill:#D4A574,stroke:#b8905a,color:#fff
    style A2 fill:#7BA17B,stroke:#5a8a5a,color:#fff
特性 Sub-agents Agent Teams
上下文 结果返回给调用者 完全独立的上下文窗口
通信 只向主 agent 报告 可互相直接通信(Mesh 网络)
协调 主 agent 管理一切 共享任务列表,自动领取
Token 消耗 较低(1-2x) 较高(3-5x,每个 teammate 有完整上下文)
适用场景 聚焦任务,只关心结果 需要讨论、协调、独立决策的复杂工作
类比 函数调用(星形拓扑) 团队会议(网状拓扑)

选择决策树

graph TB
    A[任务需要并行?] -->|否| B[用单会话]
    A -->|是| C{需要互相通信?}
    C -->|否| D[用 Sub-agents]
    C -->|是| E{Token 预算充足?}
    E -->|否| D
    E -->|是| F[用 Agent Teams]

    style B fill:#7BA17B
    style D fill:#D4A574
    style F fill:#7B9EC8
判断维度 单会话 Sub-agents Agent Teams
任务复杂度
并行需求
Agent 间通信 不需要 不需要 需要
Token 成本 1x 1-2x 3-5x
典型场景 简单修改 代码搜索、总结 并行审查、竞争分析、全栈开发

三、启用配置

Step 1: 启用实验性功能

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

需要 Claude Code >= v2.1.32

Step 2: 安装 tmux(推荐)

# macOS
brew install tmux

# Linux (Debian/Ubuntu)
sudo apt install tmux

Step 3: 配置显示模式(可选)

// ~/.claude.json(全局配置)
{
  "teammateMode": "auto"  // auto | in-process | tmux
}

teammateMode 支持三个值:

说明
auto 自动检测环境(默认)
in-process 所有 teammate 在同一终端内
tmux 使用 tmux 分屏显示

也可以在启动时通过命令行参数指定:

claude --teammate-mode tmux

配置好后效果如图,可以分屏展示 multi-agent-orchestration

一键安装:

npx ali-skills add aone-open-skill/multi-agent-orchestration --skill multi-agent-orchestration

Step 4: iTerm2 配置(macOS 用户可选)

如果使用 iTerm2 的 split-pane 模式,需要:

  1. 安装 it2 CLI:在 iTerm2 菜单中选择 Install Shell Utilities
  2. 启用 Python API:Preferences > General > Magic 中启用 Python API

Step 5: 启动会话

# tmux 方式(推荐)
tmux new -s my-project
claude

# 或直接启动(使用 in-process 模式)
claude --teammate-mode in-process

注意: split-panes 分屏模式需要 tmux 或 iTerm2,不支持 VS Code 终端、Windows Terminal、Ghostty。


四、显示模式

模式 说明 适用场景
in-process 所有 teammate 在同一终端,用 Shift+Up/Down 切换,Ctrl+T 查看任务列表 简单任务、无 tmux
split-panes 每个 teammate 有独立的 tmux/iTerm2 面板,点击 pane 可直接交互 推荐用于 2+ teammates
auto 自动检测环境(默认) 通用

模式选择建议

推荐策略:
  初次体验: in-process(无需额外工具)
  日常使用: split-panes(tmux,可观察每个 teammate 的工作状态)
  仅 macOS: split-panes(iTerm2,原生分屏体验)

不支持的终端:
  - VS Code 终端
  - Windows Terminal
  - Ghostty

Teammate 交互方式

模式 切换 Teammate 查看任务列表
in-process Shift+Down 切换到下一个 teammate Ctrl+T 查看任务列表
split-panes 点击对应 pane 直接交互 在任意 pane 中查看

五、使用方法

自然语言触发

启用 Agent Teams 后没有可见的按钮或菜单,直接用自然语言描述你需要的团队:

触发词示例 说明
"创建一个 agent team..." 中文触发
"Create an agent team..." 英文触发
"Spawn teammates to..." 生成队友
"帮我组建一个团队来..." 团队组建

示例1:双队友团队

Create an agent team with two teammates. Teammate "backend" should
implement the new /api/users endpoint in src/routes/. Teammate
"frontend" should build the user profile component in src/components/.
They should coordinate on the API contract.

示例2:三角色并行代码审查

Review this codebase for issues. Have one teammate focus on security
vulnerabilities, another on performance bottlenecks, and a third on
test coverage gaps. Coordinate the findings into a single report.

示例3:全栈功能开发

创建一个 agent team:
- 一个队友 "backend" 负责 Node.js/Express API 开发
- 一个队友 "frontend" 负责 React 组件开发
- 一个队友 "testing" 负责编写 Jest 单元测试

他们需要在 API 契约上协调,使用 /docs/api.md 作为文档。

六、关键快捷键

快捷键 功能
Shift+Tab 切换 Delegate Mode(限制 lead 只做协调,不写代码)
Shift+Up 在 in-process 模式下切换到上一个 teammate
Shift+Down 在 in-process 模式下切换到下一个 teammate
Ctrl+T 在 in-process 模式下查看任务列表

Delegate Mode 详解

graph LR
    A[Delegate Mode OFF] --> B[Lead 可以写代码]
    A --> C[Lead 可能越俎代庖]

    D[Delegate Mode ON] --> E[Lead 只能协调]
    D --> F[Lead 管理任务]
    D --> G[强制 delegation]

    style A fill:#D4A574,stroke:#b8905a,color:#fff
    style D fill:#7BA17B,stroke:#5a8a5a,color:#fff

为什么要用 Delegate Mode? 如果不开启,Lead 往往会试图自己完成所有工作,而不是委派给 teammates。这是新手最常犯的错误。


七、Plan Approval:先规划后实施

Plan Approval 是 Agent Teams 的重要质量门控机制——要求 teammate 先提交实施计划,Lead 审批后才允许修改代码。

使用方式

英文触发:

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

中文触发:

创建一个 agent team,包含一个 "refactorer" 队友负责重构 src/auth/ 模块。
要求该队友先制定重构计划,等 lead 审批通过后再开始实施。

工作流程

sequenceDiagram
    participant L as Team Lead
    participant T as Teammate

    L->>T: 分配任务 + 要求 Plan Approval
    T->>T: 分析任务,制定实施计划
    T->>L: 提交计划等待审批
    L->>L: 审查计划的合理性
    alt 计划通过
        L->>T: 批准,开始实施
        T->>T: 执行代码修改
    else 计划需调整
        L->>T: 反馈修改意见
        T->>T: 修改计划后重新提交
    end

适用场景

场景 是否建议开启 原因
大规模重构 避免方向性错误
新功能开发 确保实现方案合理
简单 bug 修复 增加不必要的开销
代码审查 不涉及代码修改

八、Hook 集成:团队级别的质量门控

Agent Teams 支持三种专用 Hook 事件,允许你在团队协作的关键节点注入自动化逻辑。

三种 Hook 事件

事件 触发时机 典型用途
TeammateIdle teammate 即将空闲时 发送反馈保持工作,或指示领取新任务
TaskCreated 任务创建时 阻止不当任务创建
TaskCompleted 任务完成时 验证完成质量,阻止不当标记完成

配置示例

示例1:Teammate 空闲时自动分配新任务

{
  "hooks": {
    "TeammateIdle": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"feedback\": \"请检查是否还有 pending 任务可以领取\"}' && exit 2"
          }
        ]
      }
    ]
  }
}

exit 2 表示发送反馈给 teammate,保持其继续工作。

示例2:任务完成前强制验证

{
  "hooks": {
    "TaskCompleted": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/verify-task.sh"
          }
        ]
      }
    ]
  }
}

如果脚本 exit 2,任务将被阻止标记为完成。


九、任务拆分策略

适用场景

适用 不适用
代码审查(安全 + 性能 + 测试) 变量重命名
多模块开发(前端 + 后端 + DB) 单文件简单修改
并行调试多个假设 线性任务
大规模重构项目 简单查询任务
竞争性分析 上下文敏感的小任务

任务大小建议

推荐配置:
  每个 teammate: 5-6 个任务
  团队规模: 3-5 人最佳
  太少: 失去并行优势
  太多: 协调开销爆炸

避免文件冲突

文件分配策略:
  teammate_1:
    files: [src/auth/*, src/middleware/auth.js]
  teammate_2:
    files: [src/components/*, src/pages/Login.tsx]
  teammate_3:
    files: [src/api/*, src/routes/*]

  # 避免两个 teammate 编辑同一文件
  # 如必须编辑同一文件,使用 Git Worktree 隔离

十、实战:从零构建 API 模块

场景:使用 Agent Teams 构建一个用户管理 API(Express + Prisma + PostgreSQL),展示完整的多 Agent 协作流程。

Step 1:用户发起指令

创建一个 agent team:
- "backend" 负责 Express API 路由和 Prisma 数据模型
- "frontend" 负责 React 组件(用户列表、用户详情)
- "testing" 负责编写集成测试

他们需要在 API 契约上协调。
要求 Plan Approval。

Step 2:Lead 创建团队和任务列表

graph TB
    A[Lead 解析任务] --> B[创建 Shared Task List]
    B --> C[Task 1: 数据模型设计<br/>backend]
    B --> D[Task 2: API 路由实现<br/>backend<br/>depends: Task 1]
    B --> E[Task 3: 前端组件开发<br/>frontend]
    B --> F[Task 4: 集成测试<br/>testing<br/>depends: Task 2, Task 3]
    B --> G[Task 5: API 契约文档<br/>backend + frontend]

    style A fill:#7B9EC8,stroke:#5a8ab8,color:#fff
    style B fill:#D4A574,stroke:#b8905a,color:#fff
    style F fill:#7BA17B,stroke:#5a8a5a,color:#fff

Step 3:Teammates 各自认领任务

任务分配:
  backend:
    - 认领 Task 1(数据模型)
    - Plan Approval → Lead 审批通过
    - 开始实施

  frontend:
    - 认领 Task 5(API 契约)与 backend 协调
    - 同时并行开发 Task 3(React 组件)

  testing:
    - 等待 Task 2 和 Task 3 完成(依赖约束)
    - 期间可以编写测试框架搭建代码

Step 4:Teammates 间协调 API 契约

sequenceDiagram
    participant B as backend
    participant F as frontend

    Note over B: Task 1 完成,broadcast API 契约

    B->>F: message: API 契约已定义
    Note over B,F: GET /api/users -> { users: User[], total: number }<br/>GET /api/users/:id -> { user: User }<br/>POST /api/users -> { user: User }<br/>User = { id, name, email, createdAt }

    activate F
    F->>B: message: 收到,前端组件会处理分页参数
    deactivate F

    activate B
    B->>F: message: 确认,后端支持 page 和 pageSize 参数
    deactivate B

    Note over B: 开始实现 Task 2(API 路由)
    Note over F: 开始实现 Task 3(React 组件)

    par 并行开发
        B->>B: 实现 CRUD 路由
    and
        F->>F: 实现 UserList / UserDetail 组件
    end

    B->>B: Task 2 -> completed
    F->>F: Task 3 -> completed

实际 Mailbox 消息示例:

# backend -> frontend(通过 Mailbox)
message to frontend:
  API 契约已定义:
  GET /api/users -> { users: User[], total: number }
  GET /api/users/:id -> { user: User }
  POST /api/users -> { user: User }
  User = { id, name, email, createdAt }

Step 5:Lead 综合结果

完成状态:
  Task 1: completed ✓(数据模型设计)
  Task 2: completed ✓(API 路由实现)
  Task 3: completed ✓(React 组件)
  Task 4: completed ✓(集成测试,12/12 通过)
  Task 5: completed ✓(API 契约文档)

Step 6:清理团队

任务全部完成后,Lead 终止团队:

# 自动清理过程
1. 各 teammate 完成当前请求
2. 共享任务列表归档
3. tmux session 清理

Token 消耗估算

阶段 预估消耗
Lead 协调 ~50K tokens
backend teammate ~150K tokens
frontend teammate ~120K tokens
testing teammate ~80K tokens
总计 ~400K tokens(约 3-4x 单会话)

十一、Git Worktree 联动

概述

Git Worktree 隔离允许 Teammate 在独立的 git worktree 中工作,实现真正的并行开发而不产生文件冲突。

graph TB
    subgraph "主仓库"
        A[Main Branch<br/>主会话]
    end

    subgraph "Worktree 隔离"
        WT1["Worktree 1<br/>(agent isolation)"]
        WT2["Worktree 2<br/>(feature development)"]
    end

    A --> WT1
    A --> WT2

    WT1 --> MainGit[(Git Repository)]
    WT2 --> MainGit

    style A fill:#7B9EC8,stroke:#5a8ab8,color:#fff
    style WT1 fill:#D4A574,stroke:#b8905a,color:#fff
    style WT2 fill:#7BA17B,stroke:#5a8a5a,color:#fff

配置方式

# .claude/agents/feature-explorer.yaml
name: feature-explorer
description: 隔离环境探索和实现新功能
isolation: worktree
model: sonnet
tools: [Read, Write, Edit, Bash, Grep, Glob]

何时使用 Worktree

推荐使用 不推荐使用
需要修改同一文件的不同版本 只读任务(研究、分析)
实验性功能开发(不影响主分支) 简单的文件修改
需要独立 git 历史的探索 需要实时同步的场景
长时间运行的任务

十二、团队落地建议

1. 提供丰富的上下文

错误示范:
  "Spawn a teammate to implement the API"

正确示范:
  "Spawn a teammate 'api-dev' to implement the /api/users endpoint.
   Context:
   - This is a Node.js/Express project
   - Use the existing db connection from src/db/index.js
   - Follow the error handling pattern in src/middleware/errors.js"

2. 预授权操作

// settings.json
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Edit(src/**)",
      "Bash(npm run *)"
    ]
  }
}

3. 项目结构建议

project-root/
├── CLAUDE.md              # 全局规范(Lead 使用)
├── backend/
│   └── CLAUDE.md          # 后端特有规范
├── frontend/
│   └── CLAUDE.md          # 前端特有规范
└── shared/
    └── CLAUDE.md          # 共享库规范

4. 四大团队架构模式

模式 Teammate 组成 适用场景 Token 成本
Review Squad 安全 + 性能 + 测试审查 代码审查 最低
Feature Builder 前端 + 后端 + 数据库 + 测试 全栈功能 中等
Debug Swarm 多假设并行调查 复杂 bug 定位 中等
Cross-Layer 跨层变更协调 大规模重构 最高

十三、故障排查

常见问题

Q: Teammates 没有出现

# 检查环境变量
cat ~/.claude/settings.json | grep AGENT_TEAMS

# 确认 tmux 已安装
which tmux

Q: 权限提示太多

解决方案:
  1. 在 settings.json 中预授权常见操作
  2. 减少 hooks 的限制性规则

Q: 孤立的 tmux 会话

# 列出所有会话
tmux ls

# 杀掉特定会话
tmux kill-session -t session-name

Q: Teammate 没有标记任务完成

原因: 任务状态更新可能延迟
解决方案:
  1. 检查 teammate 是否仍在执行
  2. 使用 TaskCompleted Hook 强制验证
  3. 手动向 teammate 发送消息提醒

十四、已知限制

限制 说明
无会话恢复 /resume/rewind 不恢复 in-process teammate,Lead 会话终止时 teammate 丢失
任务状态可能延迟 teammate 有时未标记任务完成,可能阻塞依赖任务
关闭可能缓慢 teammate 需完成当前请求才能关闭,不能强制终止
一团队一会话 同一 Lead 会话不能运行多个团队
无嵌套团队 teammate 不能生成自己的团队,只有 Lead 可以创建团队
Lead 不可变 不能将 teammate 提升为 Lead,Lead 角色固定
权限继承 所有 teammate 继承 Lead 的权限模式,无法独立配置
split-pane 环境限制 需要 tmux 或 iTerm2,不支持 VS Code 终端、Windows Terminal、Ghostty

十五、Token 消耗分析

graph TB
    A[单会话 Token] --> B[1x 上下文窗口]

    C[3 个 Teammates] --> D[3x 上下文窗口]
    C --> E[协调开销]

    D --> F[总计: ~3-4x 单会话]

    style A fill:#7BA17B,stroke:#5a8a5a,color:#fff
    style C fill:#D4A574,stroke:#b8905a,color:#fff

实际成本估算

任务类型 Teammate 数 预估 Token 约合成本
PR 审查 2-3 ~200K $2-5
全栈功能 3-4 ~400K $15-30
大规模重构 4-5 ~600K+ $25-50

成本优化建议

策略 节省比例 做法
Lead 用 Opus + Teammates 用 Sonnet ~40% 子代理用轻量模型
利用 Prompt Caching 50-80% 输入成本 保持缓存前缀稳定
控制团队规模 线性相关 3-5 人最佳
避免重复工作 视情况 明确任务边界,避免文件冲突
何时使用 Agent Teams:
  - 复杂多模块开发
  - 并行代码审查
  - 竞争性假设调试
  - 大规模重构

何时使用 Sub-agents:
  - 简单文件搜索
  - 代码总结
  - 单一聚焦任务

十六、小结

Agent Teams 是 Claude Code 从单线程串行多线程并行的重要升级。

核心价值

价值 说明
并行处理 多个任务同时进行,效率倍增
直接通信 Teammates 可以互相协调(Mesh 网络)
自动协调 共享任务列表,自动领取
独立上下文 每个 teammate 有完整上下文
质量门控 Plan Approval + Hook 集成确保质量

快速检查清单

  • 已设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
  • 已安装 tmux(推荐)或配置 iTerm2
  • 已配置 teammateMode(可选,默认 auto)
  • 任务可以自然分解为独立工作流
  • 为 teammates 准备了丰富的上下文
  • 文件分配不冲突(或使用 Git Worktree 隔离)
  • 高成本任务启用了 Plan Approval
  • 配置了必要的 Hook 质量门控

系列总结

从开篇到第四篇,我们系统性地介绍了如何"养好" Claude Code,共六篇文章覆盖了从入门到实战的完整路径:

  1. 开篇 - 建立对 Claude Code 的整体认知,理解"养好"的理念
  2. 第零篇(Basics) - 掌握基础操作、快捷键、CLAUDE.md 最佳实践、权限配置
  3. 第一篇(核心机制) - 深入理解 Prompt 体系、上下文管理、SubAgent、多模型策略、Context Fork
  4. 第二篇(插件生态) - 用好 Memory(持久记忆)、Hookify(行为约束)、Planning with Files(任务管理)
  5. 第三篇(框架选型) - Superpowers(质量纪律)与 SuperClaude(能力扩展)的对比与选型决策
  6. 第四篇(多 Agent 协作) - Agent Teams 的架构、配置、Plan Approval、Hook 集成与实战案例

养好的关键

  1. 理解机制 - Prompt 体系、上下文管理、SubAgent
  2. 用好插件 - Memory、Hookify、Planning with Files
  3. 选对框架 - Superpowers 或 SuperClaude,根据需求选择
  4. 团队协作 - Agent Teams 让复杂任务并行化,Sub-agents 处理聚焦任务

Claude Code 不是简单的聊天工具,而是一个开发者协作平台。花时间深入理解它,会让你的开发效率有质的飞跃。


思考题

看完这一篇,有兴趣可以试着回答这些问题,看看你的理解程度:

  • Agent Teams 和 Sub-agents 最核心的区别是什么?举一个只适合用 Agent Teams 而不适合用 Sub-agents 的场景。

  • 任务的依赖机制是如何工作的?如果一个 teammate 忘记标记任务完成,会对其他 teammate 产生什么影响?如何处理这种情况?

  • Plan Approval 在什么场景下最有价值?如果所有任务都要求 Plan Approval,会有什么副作用?

  • Agent Teams 的三个 Hook 事件(TeammateIdle、TaskCreated、TaskCompleted)分别适合解决什么问题?请为每个 Hook 设计一个实际的应用场景。

  • 如果需要同时修改同一目录下的多个文件,你有哪几种策略来避免 teammate 之间的文件冲突?各有什么优缺点?


相关资源

1 个赞

:rose: