Claude Code Agent Teams 学习笔记1

基于官方文档整理。

主文档: https://code.claude.com/docs/en/agent-teams

一、Agent Teams 是什么

Agent Teams 让你协调多个 Claude Code 实例协同工作。一个会话作为 Team Lead（领队），负责协调、分配任务和综合结果；其他 Teammates（队友） 各自在独立的上下文窗口中工作，并可以直接互相通信。

与 Subagents（子智能体） 的关键区别：

二、启用方式

Agent Teams 默认禁用，需要手动启用：

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

或设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。

三、最佳使用场景

适合用 Agent Teams 的场景：

• 研究与审查：多个队友同时调查问题的不同方面
• 新模块/功能开发：每个队友负责一个独立模块
• 竞争假设调试：队友并行测试不同理论，互相挑战
• 跨层协调：前端、后端、测试各由不同队友负责

不适合的场景：

• 顺序任务、同文件编辑、高度依赖的工作 → 用单会话或 Subagents

四、核心操作

1. 启动团队

用自然语言描述任务和团队结构：

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

2. 显示模式

• In-process（默认）：所有队友在主终端内运行，用 Shift+Up/Down 选择队友
• Split panes：每个队友在独立窗格中，需要 tmux 或 iTerm2

// settings.json
{ "teammateMode": "in-process" }

或启动时指定：claude --teammate-mode in-process

3. 与队友直接对话

• In-process 模式：Shift+Up/Down 选择队友，直接输入消息
• Enter 查看队友会话，Escape 中断其当前轮次
• Ctrl+T 切换任务列表

4. 任务管理

共享任务列表有三种状态：pending → in progress → completed，支持任务依赖。

• Lead 可显式分配任务
• 队友完成当前任务后会自动认领下一个未分配、未阻塞的任务
• 使用文件锁防止竞争条件

5. 要求计划审批

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

队友会先制定计划等待 Lead 审批，被拒绝则修改后重新提交。

6. 委托模式（Delegate Mode）

按 Shift+Tab 启用，Lead 只做协调（派发、消息、管理），不直接写代码。

7. 关闭与清理

Ask the researcher teammate to shut down   # 关闭单个队友
Clean up the team                           # 清理所有资源（先关队友）

重要：始终由 Lead 执行清理。

五、Hooks（生命周期钩子）

• TeammateIdle：队友即将空闲时触发。退出码 2 = 发送反馈让队友继续工作
• TaskCompleted：任务被标记完成时触发。退出码 2 = 阻止完成并发送反馈

六、架构

存储位置：

• 团队配置：~/.claude/teams/{team-name}/config.json
• 任务列表：~/.claude/tasks/{team-name}/

队友权限继承 Lead 的权限设置，派生后可单独调整。

七、最佳实践

1. 给队友足够上下文：队友不继承 Lead 的对话历史，在 spawn prompt 中包含具体细节
2. 合理划分任务粒度：每个队友 5-6 个任务最佳；太小则协调开销大于收益，太大则风险高
3. 避免文件冲突：确保每个队友编辑不同的文件
4. 定期监控：检查队友进度，重定向不理想的方向
5. 从研究/审查开始：新手建议先用不涉及写代码的任务（PR 审查、库调研、bug 调查）

八、已知限制

• /resume 和 /rewind 不能恢复 in-process 队友
• 任务状态有时会滞后
• 关闭队友可能较慢
• 一个会话只能管理一个团队
• 不支持嵌套团队（队友不能再派队友）
• Lead 不可转移
• VS Code 集成终端、Windows Terminal、Ghostty 不支持 split pane 模式

参考来源

• https://code.claude.com/docs/en/agent-teams
• https://code.claude.com/docs/en/sub-agents
• https://code.claude.com/docs/en/hooks
• https://code.claude.com/docs/en/settings