team-communication-protocols

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

エージェントのチームメイト間で効果的にコミュニケーションするためのプロトコルです。メッセージタイプの選択、プラン承認ワークフロー、シャットダウン手順、避けるべき一般的なアンチパターンについて説明します。

このスキルを使う場面

• 新しいチームのコミュニケーションの norm を確立するとき
• メッセージタイプ(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"
}

使用するのは次の場合のみ: 全員に影響する重大なブロッカー、共有リソースへの大きな変更。

なぜ控えめにすべきか?: 各 broadcast は N 件の個別メッセージ(チームメイトごとに1件)を送信するため、チームの規模に比例した API リソースを消費します。

shutdown_request — 正常な終了

チームメイトにシャットダウンを要求します:

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

チームメイトは shutdown_response で応答します(承認、または理由を添えて拒否)。

コミュニケーションのアンチパターン

アンチパターン	問題	より良いアプローチ
定型的な更新を broadcast する	リソースを浪費し、ノイズになる	影響を受けるチームメイトにダイレクトメッセージを送る
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 ではなく team-lead-2 に送信してください。

トラブルシューティング

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

チームメイトが SendMessage を認識できないと言います。 チームメイトエージェントの tools: フロントマターを確認してください。SendMessage、TaskList、TaskGet、TaskUpdate などの Agent Teams 通信ツールは、エージェントが制限されたツール許可リストを使用する場合、明示的にリストする必要があります。

リードがすべてのステータス更新に対してブロードキャストを送信しています。 これはよくあるアンチパターンです。ブロードキャストはコストが高く、1 回ごとに N 件のメッセージを送信します。ポイントツーポイントの更新にはダイレクトメッセージ（type: "message"）を使用してください。ブロードキャストは、更新されたインターフェース契約など、重要な共有リソースの変更に限定してください。

チームメイトが予期せずシャットダウン要求を拒否しました。 チームメイトはまだ作業中です。shutdown_response の content フィールドで拒否理由を確認し、作業が完了するのを待ってから再試行してください。未保存の作業があるチームメイトを強制終了しないでください。

plan_approval_request が届きましたが、request_id がありません。 チームメイトが必要なリクエストコンテキストなしで ExitPlanMode を呼び出しました。チームメイトにプランモードへ再び入り、探索を完了してから、再度 ExitPlanMode を呼び出すよう指示してください。request_id はプランモードシステムによって自動的に生成されます。

2 人のチームメイトが互いを待っており、どちらも進行していません。 これはデッドロックです。両方が相手が先に終了するのを待ってブロックされています。リードは、一方のチームメイトにスタブまたは部分的な結果をダイレクトメッセージで送信し、ブロックを解除して進められるようにする必要があります。

関連スキル

• team-composition-patterns — コミュニケーションの規範を確立する前に、エージェントの種類とチーム規模を選択します
• parallel-feature-development — 通信プロトコルを使用して、並行実装者間の統合ハンドオフを調整します