agent-teams-guide

Agent Teams 指南

快速参考

命令	描述
Create an agent team...	启动队友并行工作
Clean up the team	平稳关闭所有队友
Delegate mode	启动团队后按 Shift+Tab
Shift+Up/Down	在进程内模式下选择队友

启用 Agent Teams

Agent Teams 处于实验阶段。通过环境变量启用：

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

或者在运行 Claude Code 前，在 shell 中设置环境变量。

创建团队

描述适合从多个角度并行开展的工作，以启动团队：

Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

Claude 会创建：

• 一个团队负责人（你的主会话）
• 多个队友（独立的 Claude Code 实例）
• 一个用于协调的共享任务列表

显示模式

进程内模式（默认）

• 所有队友都在你的主终端中运行
• 按 Shift+Up/Down 选择队友
• 输入消息即可直接联系他们
• 适用于任何终端

分屏模式

• 每个队友都有自己的窗格
• 需要 tmux 或 iTerm2
• 在 settings.json 中设置 teammateMode：

{ "teammateMode": "in-process" }

• 按会话覆盖：claude --teammate-mode in-process

控制队友

分配任务

• 负责人明确分配：告诉负责人每项任务交给哪位队友
• 自行认领：队友会自动选择未分配且未被阻塞的任务

直接沟通

• 进程内：选择队友，输入消息，按 Enter 查看，按 Escape 中断
• 分屏：点击窗格即可直接交互

委派模式

阻止负责人自行执行任务，让其专注于协调：

1. 先启动团队
2. 按 Shift+Tab 切换到委派模式

要求计划审批

对于复杂任务：

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

最佳实践

为队友提供足够的上下文

队友不会继承负责人的对话历史。在启动提示词中加入详细信息：

Spawn a security reviewer teammate with the prompt: "Review the authentication
module at src/auth/ for security vulnerabilities. Focus on token handling,
session management, and input validation..."

合理划分任务规模

• 太小：协调开销超过收益
• 太大：队友长时间工作而没有进度检查
• 恰到好处：独立完整的单元（函数、测试文件、审查）

避免文件冲突

拆分工作，让每位队友负责不同的文件。两位队友编辑同一个文件会导致覆盖。

监控并引导

检查进度、调整工作方向、综合整理发现。不要长时间放任团队不管。

清理

完成后：

Clean up the team

负责人会移除共享团队资源。清理时务必使用负责人，而不要使用队友。

故障排除

问题	解决方案
看不到队友	按 Shift+Down 切换；确认任务确实适合组建团队
权限提示过多	在权限设置中预先批准操作
队友遇到错误后停止	检查输出、提供额外指示，或启动替代队友
负责人过早关闭	告诉负责人继续工作并等待队友
孤立的 tmux 会话	运行 tmux ls，然后运行 tmux kill-session -t <name>

何时使用 Agent Teams

最适合：

• 研究和审查（同时获取多个角度）
• 新模块或功能（彼此独立的部分）
• 基于不同假设进行调试（并行调查）
• 跨层协调（前端、后端、测试）

不太适合：

• 顺序执行的任务
• 修改同一个文件
• 依赖关系繁多的工作

常见模式

并行代码审查

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

基于不同假设进行调查

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk
to each other to try to disprove each other's theories.

限制

• 进程内队友不支持恢复会话
• 任务状态可能滞后于实际完成情况
• 关闭可能较慢（队友会先完成当前请求）
• 每个会话只能有一个团队
• 不支持嵌套团队（队友无法启动自己的团队）
• 团队生命周期内负责人固定
• 分屏需要 tmux 或 iTerm2（不支持 VS Code 终端、Windows Terminal、Ghostty）