agent-coordination

エージェント間の連携

価値観： 敬意を持ちましょう。他のエージェントにも、中断されずに考え、作業する時間が必要です。メッセージを大量に送ったり、状況を何度も確認したり、時期尚早に停止させたりすることは、相手の自律性を軽視し、全員のリソースを無駄にします。

目的

複数のエージェントが連携するワークフローで、干渉せずにエージェント同士が連携する方法を説明します。メッセージの連投、アイドル通知の誤解、ポーリングループ、時期尚早な停止、複数のエージェントが協働するときに生じる競合状態といった問題を解決します。

実践方法

最重要ルール：メッセージを1通送ったら待つ

必要な情報をすべて含めたメッセージを1通送り、返信を待ちます。返答を受け取る前に、追加のメッセージを送ってはいけません。

唯一の例外は、ユーザーからエージェントの状況を確認するよう明示的に頼まれた場合です。

実践すること：

• 必要な情報をすべて1通のメッセージに含めます
• ほかの内容を送る前に、返信を待ちます
• 受信者がメッセージを受け取ったと信頼します

してはいけないこと：

• 「ちょっと確認ですが」や「まだいますか？」というメッセージを送る
• 「十分な時間が経った」という理由でメッセージを再送する
• メッセージを送った直後に訂正を送る。まず返信を待ちます

アイドル通知はハートビートです

アイドル通知は、エージェントが稼働中で処理を続けていることを意味します。これはアラームではなく、ハートビートです。原則として、アイドル通知に対しては何もしません。

次の3つの条件がすべて満たされた場合に限り、対応が必要です。

1. タスクの想定所要時間を超えて長くアイドル状態が続いている
2. そのエージェントの出力を待っている、具体的な成果物がある
3. ユーザーから調査を依頼されている

いずれかの条件が満たされていない場合は、何もしません。ほとんどのアイドル通知には、まったく応答する必要がありません。

ポーリングループを使わない

while not done: sleep; check のように書いてはいけません。タイマーで状況を繰り返し確認してはいけません。イベント駆動で連携します。メッセージを送り、返信を待ちます。ハーネスがタスク完了通知を提供する場合は、それを使います。

実践すること：

• リクエストを送り、返信イベントを待ちます
• ハーネスが提供するネイティブの完了シグナル（Agent ツールのコールバック、サブエージェントの結果）を使います
• 作業が完了したらシステムから通知されると信頼します

してはいけないこと：

• while True: sleep(30); check_status() のようなループを書く
• ファイルが変更されたかどうかを確認するため、定期的に読み直す
• 任意のタイムアウトを設定し、それを過ぎたら「状況を確認する」

介入の基準

対応する場合と待つ場合の明確なルールです。

対応するケース：

• 明示的なエラーメッセージや失敗通知
• 成果物の完成シグナル
• エージェントの状況確認や、エージェントとのやり取りを求めるユーザーからの依頼
• ハーネスからのブロックまたは失敗したタスクの通知

対応してはいけないケース：

• アイドル通知（上記を参照）
• 返信が遅いこと
• 「十分な時間が経った」こと
• 助けたいという気持ちや、進捗が不安であること
• 沈黙（沈黙は作業中を意味し、行き詰まっているわけではありません）

エージェントの応答を捏造しない

エージェントを起動したら、生成を停止し、ハーネスから応答が届くのを待ちます。実際のエージェントの応答は、システムが挿入するイベント（Agent ツールの完了出力、タスク完了コールバックなど）を通じて届きます。自分で応答を生成してはいけません。

ルール： ハーネスから応答イベントが届いていなければ、応答は受け取っていません。それだけです。

これが失敗する理由： エージェントを起動した後には、もっともらしい出力を予測できるだけの情報（読み取ったファイル、分析したコード）がすでに手元にあります。失敗の原因は、実際のシステムイベントを待たずに、期待されるワークフロー（起動、受信、処理）をパターン補完してしまうことです。その結果、説得力はあるものの、完全に捏造された「調査結果」が作られ、トークンを浪費し、ユーザーを欺くことになります。

実践すること：

• エージェントを起動するかメッセージを送ったら、そこで停止します。システムからイベントが届くのを待ちます
• 返信が届かない場合は、ユーザーに正直に伝えます

してはいけないこと：

• 「[Xからメッセージを受信]」など、別のエージェントの応答を表すテキストを書く
• 別のエージェントのものとして「調査結果」を生成する
• 起動や送信の後、ハーネスのイベントを待つべきときに、実質的な出力の生成を続ける

エージェントの逐次起動

複数のエージェントを作成する場合は、一度に1つずつ起動してください。次のエージェントを起動する前に、各エージェントから確認応答があるまで待ってください。これにより、エージェントが共有リソース（ファイル、ポート、データベースの状態）を奪い合う競合状態を防止できます。

**例外：**共有状態がなく、本当に独立しているエージェントは並行して起動できます。「独立」とは、共有ファイル、共有データベース、共有ネットワークポート、共有の Git 作業ツリーがないことを意味します。

エージェントのライフサイクル管理

エージェントを早まって終了させてはいけません。未配信の作業があるエージェントを終了させてはいけません。

終了プロトコル：

1. 適切なハーネスの仕組みを通じて終了リクエストを送信します
2. エージェントから確認応答があるか、保留中の作業が完了するまで待ちます
3. エージェントが終了を拒否した場合は、その拒否を尊重し、ユーザーに報告します
4. ユーザーが明示的に依頼しない限り、エージェントを強制終了してはいけません

エージェントの作業が完了したかどうかわからない場合は、推測せずにユーザーに尋ねてください。

結果の受け渡し

オーケストレーターは各サブエージェントの結果を収集し、関連するコンテキストを次のサブエージェントへのプロンプトに渡します。これは本質的にハブ・アンド・スポーク型（オーケストレーターがハブ）であり、サブエージェントモデルでは正しい方法です。

実施すること：

• 前のサブエージェントから得た関連する結果をすべて、次のサブエージェントのプロンプトに含めます
• コンテキストを絞り込み、次のサブエージェントが必要とする情報だけを渡します
• 再起動するのではなく、Agent ツールの resume パラメーターを使って、追加のコンテキストとともにサブエージェントの作業を続行します

実施しないこと：

• 互いに直接やり取りする必要があるサブエージェントを起動しません
• 次のサブエージェントが作業するうえで必要な前の結果を省略しません

ハーネス固有の連携パターンについては、references/ を参照してください。

適用に関する注記

すべてのモードで推奨事項です。最重要ルールとアイドル通知の規律は自己管理してください。メッセージの連投や早まった終了を防ぐ仕組みはありません。

厳守事項：

• エージェントの応答を捏造してはいけません：[H]
• 未配信の作業があるエージェントを早まって終了させてはいけません：[RP]

制約

• 最重要ルール（メッセージを1つ送ったら待つ）：別のエージェントにメッセージを送信した後、応答を受け取るまで、そのエージェント宛て、またはそのエージェントについての出力を一切してはいけません。「もう1つだけ追加します」は2通目のメッセージです。エージェントが何をしているかを推測して説明することは捏造です。規律は、送信したら沈黙することです。
• 「本当に独立しているエージェントは並行して起動できます」：「本当に独立している」とは、共有ファイル、共有状態、順序依存関係がなく、マージの競合が起こり得ないことを意味します。エージェントの成果をいずれ統合する必要がある場合（ブランチのマージだけの場合も含む）、依存関係があります。独立とは、互いに連絡を取らない2人で作業を完了できることです。
• 「長時間のアイドル状態」：「長時間」かどうかは、想定されるタスクの所要時間に照らして判断します。数秒で済むはずのタスクで2分間アイドル状態なら長時間です。10分かかるはずのタスクで2分間アイドル状態なら通常の範囲です。「長時間」を絶対的な時間で定義してはいけません。

検証

このスキルに沿った作業を終えた後、次の項目を確認してください。

• 別のエージェントへの各メッセージに完全なコンテキストが含まれていた（「状況確認だけ」などではない）
• 返信を受け取る前に追加のメッセージを送信していない
• アイドル通知だけを根拠に行動していない
• ポーリングループやスリープして確認するパターンを使っていない
• 各エージェントを逐次起動し、次のエージェントを起動する前に確認応答を受け取った
• 別のエージェントの応答を表したり模擬したりするテキストを生成していない
• 起動または送信のたびに生成を停止し、システムイベントを待った
• エージェントを早まって、または未配信の作業がある状態で終了させていない
• 適切なリクエストと応答のプロトコルを使って終了した
• ユーザーによる中断後、ユーザーの指示を待たずにエージェントを再起動していない

いずれかの項目を満たしていない場合は、該当する手順を見直してから続行してください。

依存関係

このスキルは単独で動作します。ワークフローを強化するため、以下と連携します。

• ensemble-team： ドライバーのローテーションとレビュアーの管理を伴う、チームベースのワークフロー向けの調整規律
• pipeline： ファクトリーモードでの TDD ペアおよびレビューチームとのコントローラー調整
• memory-protocol： エージェント間の調整セッションをまたいだ作業状態の永続化

依存関係が不足していますか？以下でインストールできます：

npx skills add jwilger/agent-skills --skill ensemble-team