チームコミュニケーションプロトコル

エージェントチームメンバー間の効果的なコミュニケーションのためのプロトコル。メッセージタイプの選択、プラン承認ワークフロー、シャットダウン手続き、および一般的なアンチパターンを含みます。

このスキルを使用する場面

• 新しいチームの通信規範を確立するとき
• メッセージタイプ（message、broadcast、shutdown_request）の選択
• プラン承認ワークフローの処理
• チームの段階的なシャットダウン管理
• チームメンバーのアイデンティティと能力の発見

メッセージタイプの選択

message（ダイレクトメッセージ）— デフォルト選択肢

特定の1人のチームメンバーに送信：

{
  "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個の別々のメッセージ（チームメンバー1人につき1つ）を送信し、チームサイズに比例した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. チームメンバーが request を受信 — 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 を直接使用しないでください。

トラブルシューティング

チームメンバーがメッセージに応答しない場合。 チームメンバーのタスクステータスを確認してください。アイドル状態の場合、タスクを完了しており、新しい作業の割り当てまたはシャットダウンを待っている可能性があります。まだアクティブな場合、実行中である可能性があり、現在の操作が完了するとメッセージを処理します。

リーダーがすべてのステータス更新のためにブロードキャストを送信している場合。 これは一般的なアンチパターンです。ブロードキャストは高コスト — 各々はN個のメッセージを送信します。ポイント・ツー・ポイント更新にはダイレクトメッセージ（type: "message"）を使用してください。更新されたインターフェイスコントラクトのような重大な共有リソース変更のためにブロードキャストを予約してください。

チームメンバーが予期せずシャットダウンリクエストを拒否した場合。 チームメンバーはまだ作業中です。shutdown_response コンテンツフィールドで拒否理由を確認し、作業の完了を待ってから再度リトライしてください。保存されていない作業を持つチームメンバーを強制終了しないでください。

plan_approval_request が到着しましたが、request_id がない場合。 チームメンバーが必要なリクエストコンテキスト없이 ExitPlanMode を呼び出しました。チームメンバーにプランモードに再度入り、探索を完了して、ExitPlanMode を再度呼び出させてください。request_id はプランモードシステムにより自動生成されます。

2つのチームメンバーが互いに待機しており、どちらも進捗していない場合。 これはデッドロックです：両者が相手の完了を最初に待つことでブロックされています。リーダーは一方のチームメンバーにダイレクトメッセージで スタブまたは部分的な結果を送信し、ブロック解除して進行できるようにします。

関連スキル

• team-composition-patterns — 通信規範を確立する前にエージェントタイプとチームサイズを選択
• parallel-feature-development — 通信プロトコルを使用して並列実装者間の統合ハンドオフを調整