agent-teams

Agent 团队协调

概述

Claude Code Agent Teams 通过基于文件系统的协调协议，让多个 Claude CLI 进程能够协作完成共享工作。每位队友都在 tmux 窗格中作为独立的 claude 进程运行，通过由 fcntl 锁保护的 JSON 文件进行通信，无需数据库、守护进程或网络层。

本技能提供有效编排 Agent 团队的模式。

适用场景

• 跨多个文件或模块并行实现
• 多 Agent 代码审查（一位 Agent 负责审查，另一位负责实现修复）
• 需要协调多个子系统变更的大规模重构
• 具有天然并行性、能够从并发 Agent 中受益的任务

不适用场景

• 单文件变更或小型任务（协调开销超过收益）
• 需要严密顺序推理的任务（Agent 之间的协调较松散）
• 无法使用 claude CLI 或未安装 tmux 时

先决条件

# Verify Claude Code CLI
claude --version

# Verify tmux (required for split-pane mode)
tmux -V

# Enable experimental feature (set by spawner automatically)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

协议架构

~/.claude/
  teams/<team-name>/
    config.json            # Team metadata + member roster
    inboxes/
      <agent-name>.json    # Per-agent message queue
      .lock                # fcntl exclusive lock
  tasks/<team-name>/
    1.json ... N.json      # Auto-incrementing task files
    .lock                  # fcntl exclusive lock

设计原则：

• 文件系统即数据库：使用 JSON 文件，通过 tempfile + os.replace 原子写入
• fcntl 锁定：防止收件箱和任务发生并发读写损坏
• 编号任务：自动递增 ID，并按顺序命名文件
• 松散耦合：Agent 轮询各自的收件箱；无推送通知

快速入门

1. 创建团队

# Programmatic team setup (via MCP or direct API)
# Team config written to ~/.claude/teams/<team-name>/config.json

团队配置包含：

• name、description、created_at（毫秒时间戳）
• lead_agent_id、lead_session_id
• members[]：LeadMember 和 TeammateMember 对象数组

2. 启动队友

每位队友都是使用身份标志启动的独立 claude CLI 进程：

claude --agent-id "backend@my-team" \
       --agent-name "backend" \
       --team-name "my-team" \
       --agent-color "#FF6B6B" \
       --parent-session-id "$SESSION_ID" \
       --agent-type "general-purpose" \
       --model sonnet

有关 tmux 窗格管理和颜色分配，请参阅 modules/spawning-patterns.md。

3. 创建带依赖关系的任务

{
  "id": "1",
  "subject": "Implement API endpoints",
  "description": "Create REST endpoints for user management",
  "status": "pending",
  "owner": null,
  "blocks": ["3"],
  "blocked_by": [],
  "metadata": {}
}

有关状态机和依赖管理，请参阅 modules/task-coordination.md。

4. 通过消息进行协调

{
  "from": "team-lead",
  "text": "API endpoints are ready for integration testing",
  "timestamp": "2026-02-07T22:00:00Z",
  "read": false,
  "summary": "API ready"
}

有关消息类型和收件箱操作，请参阅 modules/messaging-protocol.md。

协调工作流

1. agent-teams:team-created：初始化团队配置和目录
2. agent-teams:teammates-spawned：在 tmux 窗格中启动 Agent
3. agent-teams:tasks-assigned：创建带依赖关系的任务并分配负责人
4. agent-teams:coordination-active：Agent 认领任务、交换消息并标记完成
5. agent-teams:team-shutdown：通过审批协议优雅关闭

团队角色

每位团队成员都有一个决定其能力和任务兼容性的 role。定义了五种角色：implementer（默认）、researcher、tester、reviewer 和 architect。角色会限制 Agent 可处理的风险等级。有关完整的能力矩阵和角色—风险兼容性表，请参阅 modules/crew-roles.md。

团队组建

有关任务级团队规模，请使用 references/team-formation.md 中的团队组建规则。该文件定义了：

• 角色定义：协调者（任务负责人）、Agent（任务负责人）、审查者（对抗性质的质疑者）
• 团队规模规则：简单（1）、中等（2-4）、复杂（5-7）、关键（5-10）
• 团队人数上限：10 位 Agent（协调开销限制）
• 文件所有权规则：明确所有权，避免冲突

有关完整的团队规模指南和团队组建示例，请参阅 references/team-formation.md。

健康监控

可通过心跳消息和认领过期时间监控团队成员的健康状况。负责人每 60s 轮询一次团队健康状况，并使用两阶段停滞检测协议（health_check 探测和等待 30s）。停滞的 Agent 会释放其任务，并按照“替换而非等待”原则重启或替换。有关完整协议和状态机，请参阅 modules/health-monitoring.md。

模块参考

• team-management.md：团队生命周期、配置格式、成员管理
• messaging-protocol.md：消息类型、收件箱操作、锁定模式
• task-coordination.md：任务 CRUD、状态机、依赖环检测
• spawning-patterns.md：tmux 启动、CLI 标志、窗格管理
• crew-roles.md：角色分类、能力矩阵、角色与风险的兼容性
• health-monitoring.md：心跳协议、停滞检测、自动恢复

与 Conjure 集成

Agent Teams 扩展了 conjure 委派模型：

Conjure 模式	Agent Teams 对应项
delegation-core:task-assessed	agent-teams:team-created
delegation-core:handoff-planned	agent-teams:tasks-assigned
delegation-core:results-integrated	agent-teams:team-shutdown
外部 LLM 执行	队友 Agent 执行

首先使用 Skill(conjure:delegation-core)，判断任务适合采用多 Agent 协调，还是委派给单个服务。

那里默认启用委派，因此组建团队要回答的问题是采用哪种委派形式，而不是是否委派。承担执行工作的队友会像单个会话一样进行委派。承担设计工作的队友则会按照相同的 Keep Local 条款自行处理。

如果队友的委派返回 fallback_reason，该队友会自行完成工作，并报告尝试过哪些提供方。它不会向团队发消息要求重新分配：由于注册表是机器级的，因此其他队友没有它所缺少的提供方。

工作树隔离方案（Claude Code 2.1.49+）

对于需要修改文件的并行 Agent，isolation: worktree 提供了一种轻量级替代方案，可替代基于文件系统的协调方式。每个 Agent 都在自己的临时 git 工作树中运行，无需对共享文件使用 fcntl 锁定或通过收件箱避免冲突。

• 优先选择工作树而非 Agent Teams 消息的情况：Agent 会处理重叠文件，但执行期间不需要相互通信
• 优先选择 Agent Teams 消息的情况：Agent 需要协调发现结果，或根据彼此的进展调整计划
• 两者结合使用：使用 Agent Teams 进行协调，并为每个队友设置 isolation: worktree，确保文件系统安全

故障排除

常见问题

未找到 tmux 通过包管理器安装：brew install tmux / apt install tmux

锁文件过期 如果 Agent 在操作中途崩溃，锁文件可能会残留。请手动从 ~/.claude/teams/<team>/inboxes/ 或 ~/.claude/tasks/<team>/ 中删除 .lock 文件。

孤立任务 由崩溃的 Agent 认领的任务会无限期保持 in_progress 状态。使用 modules/health-monitoring.md 进行基于心跳的停滞检测和自动释放任务。健康监控协议会在 60s 内检测到无响应的 Agent，并在 30s 探测窗口后释放其任务以便重新分配。

消息顺序 文件系统时间戳的精度各不相同（HFS+ 的粒度为 1s）。使用编号文件名或按 UUID 排序的名称，避免消息突发时发生冲突。

Bedrock/Vertex/Foundry 上的模型错误（2.1.39 之前） 队友 Agent 在企业级提供方上可能使用错误的模型标识符，导致 400 错误。升级到 Claude Code 2.1.39+，以确保所有提供方的模型 ID 限定正确。

嵌套会话保护（2.1.39+） 如果 claude 拒绝在现有会话中启动，请确保使用 tmux 窗格分割（而非子 Shell 调用）。此保护是有意设置的。详情请参阅 modules/spawning-patterns.md。

退出标准

• 已创建团队及其配置和目录
• 已启动队友并在配置中注册
• 已创建带依赖关系图的任务（无环）
• Agent 正通过收件箱消息进行协调
• 已完成正常关停