team-communication-protocols

团队沟通协议

Agent 队友之间有效沟通的协议，包括消息类型选择、计划审批工作流、关闭流程以及应避免的常见反模式。

何时使用本技能

• 为新团队建立沟通规范
• 在消息类型（message、broadcast、shutdown_request）之间进行选择
• 处理计划审批工作流
• 管理团队的优雅关闭
• 发现队友的身份和能力

消息类型选择

message（私信）— 默认选择

发送给单个特定队友：

{
  "type": "message",
  "recipient": "implementer-1",
  "content": "Your API endpoint is ready. You can now build the frontend form.",
  "summary": "API endpoint ready for frontend"
}

用于：任务更新、协调、提问、集成通知。

broadcast — 谨慎使用

同时发送给所有队友：

{
  "type": "broadcast",
  "content": "Critical: shared types file has been updated. Pull latest before continuing.",
  "summary": "Shared types updated"
}

仅用于：影响所有人的关键阻塞问题、共享资源的重大变更。

为什么要谨慎使用？：每次广播会发送 N 条独立消息（每位队友一条），消耗的 API 资源与团队规模成正比。

shutdown_request — 优雅终止

请求队友关闭：

{
  "type": "shutdown_request",
  "recipient": "reviewer-1",
  "content": "Review complete, shutting down team."
}

队友以 shutdown_response 响应（批准或附带原因拒绝）。

沟通反模式

反模式	问题	更好的做法
广播常规更新	浪费资源、产生噪音	向受影响的队友发私信
发送 JSON 状态消息	并非为结构化数据而设计	使用 TaskUpdate 更新任务状态
在集成点不进行沟通	队友基于过时的接口开发	接口就绪时发消息通知
通过消息进行微观管理	让队友不堪重负、拖慢工作	在里程碑处检查，而非每一步
使用 UUID 而非名字	难以阅读、容易出错	始终使用队友名字
忽视空闲队友	浪费容量	分配新工作或将其关闭

计划审批工作流

当队友以 plan_mode_required 方式启动时：

1. 队友使用只读探索工具创建计划
2. 队友调用 ExitPlanMode，向负责人发送 plan_approval_request
3. 负责人审查计划
4. 负责人以 plan_approval_response 响应：

批准：

{
  "type": "plan_approval_response",
  "request_id": "abc-123",
  "recipient": "implementer-1",
  "approve": true
}

附带反馈拒绝：

{
  "type": "plan_approval_response",
  "request_id": "abc-123",
  "recipient": "implementer-1",
  "approve": false,
  "content": "Please add error handling for the API calls"
}

关闭协议

优雅关闭流程

1. 负责人向每位队友发送 shutdown_request
2. 队友接收请求，形式为带 type: "shutdown_request" 的 JSON 消息
3. 队友响应 shutdown_response：
   • approve: true — 队友保存状态并退出
   • approve: false + 原因 — 队友继续工作
4. 负责人处理拒绝 — 等待队友完成，然后重试
5. 所有队友关闭后 — 调用 TeamDelete 以移除团队资源

处理拒绝

如果队友拒绝关闭：

• 查看其原因（通常是"仍在处理任务"）
• 等待其当前任务完成
• 重试关闭请求
• 如情况紧急，用户可强制关闭

发现队友

通过读取配置文件查找团队成员：

位置：~/.claude/teams/{team-name}/config.json

结构：

{
  "members": [
    {
      "name": "security-reviewer",
      "agentId": "uuid-here",
      "agentType": "team-reviewer"
    },
    {
      "name": "perf-reviewer",
      "agentId": "uuid-here",
      "agentType": "team-reviewer"
    }
  ]
}

发送消息和分配任务时始终使用 name。切勿直接使用 agentId、角色名称或未加后缀的别名。如果队友以 team-lead-2 启动，请发送给 team-lead-2，而不是 team-lead。

故障排查

某个队友没有回复消息。 检查该队友的任务状态。如果处于空闲状态，它可能已完成任务，正在等待分配新工作或被关闭。如果仍处于活动状态，它可能正在执行中，将在当前操作完成后处理消息。

某个队友说它看不到 SendMessage。 检查该队友 Agent 的 tools: frontmatter。当 Agent 使用受限的工具允许列表时，必须显式列出 Agent Teams 通信工具，例如 SendMessage、TaskList、TaskGet 和 TaskUpdate。

负责人为每次状态更新都发送广播。 这是一种常见的反模式。广播的开销很高 —— 每次广播都会发送 N 条消息。对于点对点更新，请使用直接消息（type: "message"）。仅在关键共享资源变更（例如更新接口契约）时才使用广播。

某个队友意外拒绝了关闭请求。 该队友仍在工作。检查 shutdown_response 内容字段中的拒绝原因，等待工作完成后重试。切勿强制终止尚有未保存工作的队友。

收到了 plan_approval_request，但缺少 request_id。 该队友在缺少所需请求上下文的情况下调用了 ExitPlanMode。让该队友重新进入计划模式，完成探索，然后再次调用 ExitPlanMode。request_id 由计划模式系统自动生成。

两个队友互相等待，双方都没有进展。 这是死锁：双方都被阻塞，等待对方先完成。负责人应向其中一个队友发送一条直接消息，附上桩代码或部分结果，使其解除阻塞并继续推进。

相关技能

• team-composition-patterns — 在建立沟通规范之前，选择 Agent 类型和团队规模
• parallel-feature-development — 使用通信协议协调并行实现者之间的集成交接