在多智能体团队中建立通信规范时，用消息类型选择…

适用于新建 agent 团队、需要选择私信/广播/关闭请求、审批 implementer 计划、优雅关闭团队或排查队友协作异常的场景。

适用场景

解决思路

1. 建立新团队通信规范时，默认使用 `message` 私信；仅在关键共享资源变更或全员阻塞时使用 `broadcast`；关闭时使用 `shutdown_request`。
2. 选择 `message`（私信）作为默认消息类型：发给单个指定队友，JSON 包含 type=message、recipient、content、summary；用于任务更新、协调、提问、集成通知。
3. 谨慎使用 `broadcast`：仅用于影响所有人的关键阻塞、共享资源重大变更；JSON 包含 type=broadcast、content、summary；因为每次广播会按团队人数发送 N 条独立消息，消耗 API 资源。
4. 使用 `shutdown_request` 优雅终止队友：JSON 包含 type=shutdown_request、recipient、content；队友以 `shutdown_response` 批准或给出理由拒绝。
5. 避免广播例行更新：广播会浪费资源、制造噪音；应改为私信给受影响的队友。
6. 避免发送 JSON 状态消息：这类消息不是为结构化数据设计的；应使用 `TaskUpdate` 更新任务状态。
7. 在集成点主动沟通：否则队友会基于过时接口开发；当你的接口就绪时发消息通知相关队友。
8. 不要通过消息进行微观管理：会淹没队友、拖慢工作；应在里程碑检查，而不是每一步都检查。
9. 使用队友名称而不是 UUID：UUID 难读且易错；消息和任务分配始终使用 `name`。
10. 不要忽略空闲队友：会浪费容量；应分配新工作或关闭。
11. 计划审批流程：当队友以 `plan_mode_required` 启动时，队友先用只读探索工具创建计划。
12. 队友创建计划后调用 `ExitPlanMode`，向 lead 发送 `plan_approval_request`。
13. Lead 收到后审查计划。
14. Lead 用 `plan_approval_response` 批准：JSON 包含 type=plan_approval_response、request_id、recipient、approve=true。
15. Lead 用 `plan_approval_response` 拒绝并反馈：JSON 包含 type=plan_approval_response、request_id、recipient、approve=false、content（例如 "Please add error handling for the API calls"）。
16. 优雅关闭顺序第 1 步：Lead 向每个队友发送 `shutdown_request`。
17. 优雅关闭顺序第 2 步：队友接收带 type=shutdown_request 的 JSON 消息。
18. 优雅关闭顺序第 3 步：队友回复 `shutdown_response`：approve=true 表示保存状态并退出；approve=false 加理由表示继续工作。
19. 优雅关闭顺序第 4 步：Lead 处理拒绝，等待队友完成当前任务，然后重试关闭请求。
20. 优雅关闭顺序第 5 步：所有队友关闭后，调用 `TeamDelete` 移除团队资源。
21. 处理关闭拒绝：检查理由（通常是仍在处理任务），等待当前任务完成，重试关闭请求；若紧急，用户可强制关闭。
22. 发现队友：读取配置文件 `~/.claude/teams/{team-name}/config.json`。
23. 配置文件中 `members` 包含 `name`、`agentId`、`agentType`。
24. 消息和任务分配始终使用 `name`；绝不直接使用 `agentId`、角色名或不带后缀的别名；若队友以 `team-lead-2` 启动，就发给 `team-lead-2` 而不是 `team-lead`。
25. 排查队友不响应：检查任务状态；若空闲，可能已完成任务，等待分配新工作或关闭；若仍活跃，可能正在执行，会在当前操作完成后处理消息。
26. 排查队友看不到 SendMessage：检查该 agent 的 `tools:` frontmatter；使用受限工具白名单时，必须显式列出 Agent Teams 通信工具 `SendMessage`、`TaskList`、`TaskGet`、`TaskUpdate`。
27. 排查 lead 对每个状态更新都发广播：这是常见反模式；广播昂贵，每次 N 条消息；点对点更新用 type=message 私信；广播保留给关键共享资源变更，例如更新接口契约。
28. 排查队友意外拒绝关闭：队友仍在工作；检查 `shutdown_response` 的 content 字段中的拒绝理由，等待工作完成，再重试；绝不要强制终止有未保存工作的队友。
29. 排查 `plan_approval_request` 缺少 `request_id`：队友调用 `ExitPlanMode` 时缺少必要请求上下文；让队友重新进入计划模式，完成探索，再次调用 `ExitPlanMode`；`request_id` 由计划模式系统自动生成。
30. 排查两个队友互相等待且都无进展：这是死锁；lead 应向其中一个队友发送私信，附带 stub 或部分结果，使其解除阻塞并继续。
31. 建立通信规范前，可参考 `team-composition-patterns` 选择 agent 类型和团队规模；并行功能开发中可用本协议协调集成交接。

适用边界 · 注意事项

• 未使用 Claude Code Agent Teams 或缺少 `SendMessage`、`TaskUpdate`、`ExitPlanMode`、`TeamDelete` 等工具时，不适用本协议。
• 团队只有单个 agent、没有并行协作或集成交接需求时，不需要这些通信协议。
• 当团队规模很大且 API 资源敏感时，不适用大量广播；应改用私信或任务更新。