agent-teams

协调由 2-3 个 Claude Code Agent 组成的团队，让它们并行处理同一代码库。每个 Agent 都在自己的终端、自己的 git worktree 和自己的上下文窗口中运行。团队负责人（负责协调的 Claude）拆解工作，为 Agent 编写重点明确的提示词，监控进度并协调合并。

关键原则： 每个 Agent 都是全新的 Claude 会话，不共享任何记忆。所有协调都通过文件（WORKTREE_TASK.md、共享契约）和 git（分支、PR）完成。Agent 之间没有运行时通信。

<quick_start> 设置环境变量（仅需一次）：

export AGENT_TEAMS_MAX=3  # M1/8GB safe default

启动一个由 2 个 Agent 组成的团队：

"Set up a team: Agent 1 builds the API endpoints, Agent 2 builds the React components.
They share this contract: POST /api/tasks returns { id, title, status }."

执行流程：

1. 团队负责人通过 worktree-manager 创建 2 个 worktree
2. 为每个 worktree 写入包含重点提示词和契约的 WORKTREE_TASK.md
3. 在各自的 Ghostty 终端中启动每个 Agent
4. Agent 独立工作，团队负责人监控并合并 </quick_start>

<success_criteria> 团队会话成功的标准：

• 每个 Agent 都在自己的 worktree 中完成分配的任务
• Agent 分支之间没有合并冲突（或冲突可以轻松解决）
• 每个 Agent 的上下文都保持聚焦（没有冗余，不必重新阅读无关代码）
• 合并后，所有 Agent 的工作都能通过项目的测试套件
• 总耗时短于顺序执行所需的时间 </success_criteria>

前置条件

必备技能： worktree-manager — agent-teams 将所有 worktree 创建、端口分配和终端启动工作委托给 worktree-manager。请先安装它。

建议： 项目包含 .claude/ 目录和 CLAUDE.md（开发命令、约定）。如果项目还包含 .claude/agents/（自定义子 Agent）或 .claude/settings.json（钩子/权限），这些内容会自动同步到每个 Agent 的 worktree。

环境检查：

# Agent teams config
echo "Max agents: ${AGENT_TEAMS_MAX:-3}"

# Worktree manager available?
ls ~/.claude/skills/worktree-manager/ 2>/dev/null && echo "worktree-manager: OK" || echo "worktree-manager: MISSING"

# Running agents (approximate)
pgrep -f "claude.*--model" | wc -l | xargs echo "Active Claude processes:"

# Memory pressure
vm_stat | grep "Pages free" | awk '{print "Free pages:", $3}'

<current_state> 活动 Agent： !pgrep -f "claude.*--model" 2>/dev/null | wc -l | tr -d ' ' 个 Claude 进程正在运行

Worktree 注册表： !cat ~/.claude/worktree-registry.json 2>/dev/null | jq -r '.worktrees[] | select(.status == "active") | "\(.project)/\(.branch)"' | head -5

内存： !memory_pressure 2>/dev/null | head -1 || echo "Unknown"

Git 状态： !git status --short --branch 2>/dev/null | head -3 </current_state>

硬件限制（M1/8GB）

资源	预算	每个 Agent	系统预留
RAM	8 GB	~1.5 GB	2 GB
CPU 核心	8	共享	—
最大 Agent 数	3	—	—

经验法则： 如果 memory_pressure 报告为“WARN”或更高，请将 Agent 数量减至 2 个。

<when_to_use>

何时使用 Agent 团队

适用情况：

• 任务可以自然拆分为 2-3 个独立的工作流
• 每个工作流涉及不同文件（冲突风险低）
• 时效比令牌效率更重要
• 组件之间有明确的契约（API 结构、共享类型）

不适用情况：

• 任务高度耦合（每项更改都会涉及相同文件）
• 电池电量低于 30%，且正在使用电池供电（Agent 会快速耗电）
• 内存压力已经很高（请检查 memory_pressure）
• 代码库没有测试（盲目合并风险很大）

决策启发式：

Can I describe each agent's task in <50 words?
  YES → Good candidate for agent teams
  NO  → Break it down more, or do it sequentially

轻量级替代方案： 如果任务中的 Agent 不需要文件隔离（处理不同文件、只读或代码审查），请改用 subagent-teams。它使用 Claude 的原生 Task 工具在会话中并行运行 Agent，启动更快，也不需要 worktree。另请参阅下方的 Native Teams API 部分。

</when_to_use>

架构

┌──────────────────────────────────────────────────┐
│                   TEAM LEAD                       │
│            (this Claude session)                  │
│                                                   │
│  Responsibilities:                                │
│  • Decompose task into agent assignments          │
│  • Create worktrees (via worktree-manager)        │
│  • Write WORKTREE_TASK.md for each agent          │
│  • Monitor progress (git log, file checks)        │
│  • Coordinate merges back to main                 │
└─────────┬───────────────┬───────────────┬────────┘
          │               │               │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │  AGENT 1  │   │  AGENT 2  │   │  AGENT 3  │
    │           │   │           │   │           │
    │ Worktree: │   │ Worktree: │   │ Worktree: │
    │ ~/tmp/wt/ │   │ ~/tmp/wt/ │   │ ~/tmp/wt/ │
    │ proj/br-1 │   │ proj/br-2 │   │ proj/br-3 │
    │           │   │           │   │           │
    │ Terminal: │   │ Terminal: │   │ Terminal: │
    │ Ghostty 1 │   │ Ghostty 2 │   │ Ghostty 3 │
    └───────────┘   └───────────┘   └───────────┘
         │               │               │
         └───── git branches ─────────────┘
                     │
               [main branch]

上下文隔离

每个 Agent 都是完全独立的 Claude 会话。Agent：

• 无法读取彼此的上下文窗口
• 无法互相发送消息
• 只能通过文件系统和 git 共享状态
• 启动时从 WORKTREE_TASK.md 读取任务

### 通过文件进行协作

文件	用途	写入者	读取者
WORKTREE_TASK.md	Agent 的任务分配和上下文	Team lead	Agent
CONTRACT.md	共享 API/接口定义	Team lead	所有 Agent
.agent-status	Agent 自行报告进度	Agent	Team lead
.claude/CLAUDE.md	项目约定、开发命令	项目	Agent（自动加载）
.claude/settings.json	Hooks（自动格式化）、权限	项目	Agent（自动加载）
.claude/agents/*.md	自定义子 Agent 定义	项目	Agent（派发时）
Git 提交	工作成果	Agent	合并时由 Team lead 查看

<display_modes>

显示模式

模式	终端	方式
in-process	任意终端	所有队友都在主终端中。按 Shift+Down 循环切换，按 Ctrl+T 查看任务列表。
split-pane	仅限 tmux 或 iTerm2	每位队友使用自己的窗格。点击窗格即可交互。

配置：在 ~/.claude/settings.json 中设置 "teammateMode": "auto"。CLI：claude --teammate-mode in-process。Ghostty 需要通过 tmux 封装程序使用分屏模式。

分屏设置

tmux： 当设置了 $TMUX 时会自动检测。每位队友都会获得一个分屏窗格。使用 Ctrl+B + 方向键导航。

iTerm2： 使用 AppleScript 自动化。队友会在当前标签页中以分屏窗格打开。

限制： Ghostty 不支持以编程方式分割窗格，需使用 tmux 封装程序：ghostty -e "tmux new-session"。建议最多使用 4 个窗格（负责人 + 3 位队友）。每个窗格需要约 120 列。

</display_modes>

<team_hooks>

团队 Hooks

TeammateIdle Hook

当队友完成当前轮次并进入空闲状态时触发。在 settings.json 中配置：

{
  "hooks": {
    "TeammateIdle": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'echo \"Teammate idle — check TaskList for unassigned work\" >&2'"
      }]
    }]
  }
}

适用场景： 自动分配下一个任务、记录空闲时间、触发清理。退出代码 2 会阻止进入空闲状态（让队友继续工作）。不支持匹配器——对所有队友触发。

TaskCompleted Hook

通过 TaskUpdate 将任务标记为完成时触发。可用于自动分配流程：

{
  "hooks": {
    "TaskCompleted": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'echo \"Task completed — assigning next unblocked task\" >&2'"
      }]
    }]
  }
}

退出代码 2 会阻止任务完成（让任务保持 in_progress 状态）。不支持匹配器。

计划审批流程

以 mode: "plan" 启动的队友，必须先获得计划审批才能开始实施：

1. 队友调用 ExitPlanMode → 向 team lead 发送 plan_approval_request
2. Team lead 审核 → 发送 plan_approval_response（批准，或拒绝并提供反馈）
3. 批准后：队友退出计划模式，开始实施
4. 拒绝后：队友收到反馈并修改计划

// Approving a teammate's plan
SendMessage({
  type: "plan_approval_response",
  request_id: "abc-123",  // from plan_approval_request
  recipient: "architect",
  approve: true
})

</team_hooks>

工作流

工作流	用途
1. 启动团队	拆分任务 → JSON 路线图 → worktrees → 任务文件 → 启动 → 监控
2. 编写 WORKTREE_TASK.md	上下文、任务分配、文件边界、契约、验证、完成协议
3. 监控进度	检查各分支的 git log 和 .agent-status
4. 合并 Agent 的工作	按计划顺序合并，每次合并后测试，使用 --no-ff
5. 异步交接	对耗时任务使用 GitHub PR 上的 @claude 机器人
6. 计划模式	在确定任务拆分前，以只读方式探索代码库
7. 原生 Teams API	使用 TeamCreate + TaskCreate + SendMessage，为会话内团队提供无需 worktrees 的协作方式
8. 计划审批	使用 mode: "plan" 的队友在实施前提交计划，等待负责人审批

原生模式与 Worktree 的选择： 文件不同 → 原生 Teams API。文件相同 → Worktrees。需要实时消息 → 原生模式。长时间运行的流程 → Worktrees。

参阅 reference/workflows-detailed.md，了解分步说明、WORKTREE_TASK.md 模板、合并协议和原生 Teams API 示例。

<use_cases>

团队模式

并行开发功能

2-3 个 Agent 同时开发互相独立的功能，冲突风险最低。 最适合： Sprint 式并行功能开发。 参阅： reference/prompt-templates.md#feature-parallel，查看启动提示词。

前端 / 后端

一个 Agent 构建 API，另一个构建 UI。两者通过共享契约连接。 最适合： API 和 UI 可以明确拆分的全栈功能。 参见： reference/prompt-templates.md#frontend-backend，查看启动提示词。

测试 / 实现（TDD 配对）

Agent 1 先编写测试，然后提交并推送。Agent 2 拉取测试并实现功能，直到测试通过。 最适合： 注重测试覆盖率的高质量代码。 参见： reference/prompt-templates.md#test-implement，查看启动提示词。

审查 / 重构

Agent 1 重构代码。Agent 2 审查重构后的代码并编写改进建议。 最适合： 能从第二种视角中获益的大型重构任务。 参见： reference/prompt-templates.md#review-refactor，查看启动提示词。

</use_cases>

<best_practices>

最佳实践

• 为每个 Agent 隔离上下文 — 仅在 WORKTREE_TASK.md 中保留相关信息，将任务控制在 <50 个字以内
• 使用外部状态 — .agent-status、git 提交、WORKTREE_TASK.md（Agent 之间没有共享记忆）
• 将指令前置 — 将最重要的信息放在任务文件的顶部
• 契约优先 — 启动 Agent 之前，先在 CONTRACT.md 中定义共享 API 的结构
• 合并顺序很重要 — 先合并基础部分（API），再合并使用方（UI），每次合并后都进行测试，并使用 --no-ff
• 继承项目配置 — 自动复制 .claude/ 目录后，Agent 会获得 CLAUDE.md、hooks、权限和自定义子 Agent
• 团队 hooks — TeammateIdle 和 TaskCompleted hooks 使用退出代码 2 来继续工作 / 阻止完成

有关上下文工程、会话框架模式、权限模型和 hook 配置的详情，请参见 reference/best-practices-full.md。

限制

M1/8GB 约束

• 最多 3 个 Agent — 超出此数量会造成内存压力，导致系统频繁换页
• 不支持 GPU Agent — 所有 Agent 都是受 CPU 限制的 Claude 会话
• 启动时间 — 每个 Agent 需要 5-10 秒进行初始化

协调限制

• 无法实时通信 — worktree Agent 不能互相发消息（但原生 Teams API Agent 可以，参见工作流 7）
• 文件冲突 — 如果两个 Agent 编辑同一个文件，需要手动解决冲突
• 没有共享上下文 — 每个 Agent 启动时都只有 WORKTREE_TASK.md，其他内容均为全新上下文
• 顺序依赖 — 如果 Agent 2 需要 Agent 1 的输出，Agent 2 必须等待

原生 Agent Teams 的约束

Claude Code 原生 Agent Teams 的已知约束：

限制	详情
无法恢复会话	/resume 不会恢复进程内的队友。只有主 Agent 会恢复。
不支持嵌套团队	队友不能创建子团队。团队层级只有一级。
每个会话只能有一个团队	启动新团队前，先清理当前团队（TeamDelete）。
主 Agent 固定	会话期间无法晋升队友或转交领导权。
启动时设置权限	队友权限在启动时设置。创建后可以逐个调整，但不能在启动过程中调整。
关闭可能较慢	队友会先完成当前请求，再关闭。请预留时间以便平稳结束。

此技能不是什么

• 不是 CI/CD 流水线 — 使用 GitHub Actions 进行自动化测试
• 不是子 Agent 框架 — 子 Agent（Claude 内置的 Task 工具）在单个会话中运行。此技能协调的是彼此独立的会话。
• 不支持自动扩缩容 — 团队规模和任务分配需要手动决定

故障排除

Agent 未读取 WORKTREE_TASK.md

原因： Agent 启动时未使用 --dangerously-skip-permissions，或任务文件不在 worktree 根目录中。 解决方法： 确保 worktree-manager 将任务文件写入 worktree 根目录。

Agent 之间发生合并冲突

原因： 尽管有文件边界说明，Agent 仍编辑了重叠的文件。 解决方法：

1. 检查 WORKTREE_TASK.md 中的边界是否明确
2. 在 main 上手动解决冲突
3. 下次采用更严格的文件边界

Agent 用尽上下文

原因： Agent 的任务范围过大，导致它读取了太多文件。 解决方法： 将任务拆分成更小的部分。每个 Agent 应处理少于 10 个文件。

内存压力／系统变慢

原因： Agent 数量超出可用 RAM 的承载能力。 解决方法：

1. 减少到 2 个 Agent
2. 关闭非必要的应用程序
3. 启动 Agent 前检查 memory_pressure

Agent 已完成，但结果有误

原因： WORKTREE_TASK.md 中的验证步骤不足。 解决方法： 添加明确的验证命令：

## Verification
1. Run: npm test -- --filter auth
2. Run: npx tsc --noEmit
3. Manually test: curl localhost:8100/api/auth/login

参考文件

需要更深入的指导时，按需加载：

参考资料	加载时机
reference/workflows-detailed.md	需要分步了解启动、监控、合并、异步交接、Native Teams API 时
reference/best-practices-full.md	需要了解上下文工程、会话框架、契约优先、钩子配置时
reference/context-engineering.md	需要设计 Agent 提示词、优化上下文用量、了解委派模式时
reference/worktree-integration.md	需要与 worktree-manager 协作、分配端口、制定终端策略时
reference/prompt-templates.md	需要 4 种团队模式的现成启动提示词时

写入结果旁文件

最后一步，将内容写入 ~/.claude/skill-analytics/last-outcome-agent-teams.json：

{"ts":"[UTC ISO8601]","skill":"agent-teams","version":"1.2.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"agents_spawned":[n],"tasks_delegated":[n],"merges_completed":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果部分阶段失败但已产出结果，请使用状态 "partial"。只有在未生成任何输出时，才使用 "error"。