agent-messaging

エージェント間のメッセージング

概要

エージェント間のコミュニケーションの不備は、マルチエージェントの破綻のほとんどの根本原因です。肥大化したコンテキストは焦点をぼやけさせ、不正確なプロンプトは誤った結果を生み、雑な引き継ぎは重要なデータを失わせます。

基本原則： エージェントには、必要なコンテキストだけを過不足なく与えてください。すべてのメッセージは送信者ではなく、受信者に合わせて構成してください。

最優先の指針

NO AGENT DISPATCH WITHOUT A STRUCTURED BRIEF

コンテキストを整理していなければ、エージェントは意図を読み解くためにトークンを浪費します。

使用する場面

適用対象：

• サブエージェント向けのプロンプト作成（Agent ツールによるディスパッチ）
• チームメンバーへのメッセージ送信（SendMessage）
• 呼び出し元やチームリーダーへの報告の構成
• エージェント間での作業の引き継ぎ（実装担当者からレビュー担当者へ、調査担当者からリーダーへ）
• 含めるコンテキストと除外するコンテキストの判断

併用するもの：

• godmode:delegated-execution — 実装担当者／レビュー担当者のサブエージェント向けプロンプト設計
• godmode:parallel-execution — 並行調査向けのプロンプト設計
• godmode:team-orchestration — チーム連携向けのメッセージ設計

受け入れプロトコル

BEFORE dispatching any agent or sending any message:

1. RECIPIENT: Who receives this? (subagent, teammate, team lead)
2. OBJECTIVE: What must they DO? (implement, investigate, review, report)
3. CONTEXT: What must they KNOW? (only what is relevant to their task)
4. DELIVERABLE: What must they RETURN? (format, content, detail level)
5. CONSTRAINTS: What must they NOT do? (scope limits, file restrictions)

Skip any step = unfocused agent, wasted tokens

サブエージェント向けプロンプトの設計

コンテキストを絞る原則

サブエージェントは無関係なコンテキストに気を取られます。コンテキストは多ければよいというものではありません。

digraph context_decision {
    "Task follows existing pattern?" [shape=diamond];
    "Task depends on other tasks?" [shape=diamond];
    "Lean context" [shape=box style=filled fillcolor=lightgreen];
    "Full context" [shape=box];

    "Task follows existing pattern?" -> "Lean context" [label="yes - supply pattern ref"];
    "Task follows existing pattern?" -> "Task depends on other tasks?" [label="no"];
    "Task depends on other tasks?" -> "Full context" [label="yes"];
    "Task depends on other tasks?" -> "Lean context" [label="no - standalone"];
}

絞り込んだコンテキスト（独立したタスクのデフォルト）：

You are implementing: [1-2 sentence description]

File to modify: [exact path]
Pattern to follow: [reference to existing function/test]
What to implement: [specific requirement]
Verification: [exact command to run]

十分なコンテキスト（依存関係のあるタスクや複雑なタスク向け）：

You are implementing Task N: [task name]

## Task Description
[FULL TEXT of task - paste it, do not make the subagent read a file]

## Context
[Where this fits, what preceded it, architectural decisions]

サブエージェントに計画ファイルを読ませてはいけません。 関連する内容を直接貼り付けてください。ファイルを読ませると、無関係なセクションにトークンと注意力を費やすことになります。

サブエージェント向けブリーフのテンプレート

すべてのサブエージェント向けブリーフには、次のセクションを含めてください。

セクション	目的	必須
役割	エージェントが何をするのか	はい
タスク	実行する具体的な作業	はい
コンテキスト	タスクを理解するために必要な情報のみ	はい
ファイル	作業対象の正確なパス	はい
制約	してはいけないこと、スコープの境界	はい
検証	成功を確認する方法	はい
成果物の形式	報告内容の形式	はい
質問	開始前に質問する許可	推奨

効果的なブリーフと効果的でないブリーフ

効果的でない — 曖昧すぎて、構造がない：

Fix the tests in the auth module. They're failing.

効果的でない — コンテキストが多すぎる：

[Paste entire 500-line plan file]
Your task is Task 7, which is about auth tests.

効果的 — 構造化され、焦点が絞られている：

You are resolving 3 failing tests in src/auth/session.test.ts.

Failures:
1. "should reject expired sessions" - expects 401, gets 200
2. "should renew valid sessions" - timeout after 5s
3. "should handle concurrent sessions" - race condition

Context: Session management was refactored in commit def456.
The validateSession() function now returns a Promise instead of sync.

Files:
- Fix: src/auth/session.test.ts
- Reference: src/auth/session-manager.ts (the refactored code)
- Do NOT modify: src/auth/session.ts (production code is correct)

Verification: npm test -- --testPathPattern=session.test

Report: Root cause per test, what you changed, test results.

チーム向けメッセージの設計

ピア間のメッセージ

直接連携するには、type "message" を指定して SendMessage を使用してください。

メッセージは次のように構成してください：

[WHAT] - One line summary of the point
[DETAIL] - Supporting information (if needed)
[ACTION] - What you need from the recipient (if anything)

効果的：

SendMessage -> backend teammate:
"The profile API needs a PUT /profile/preferences endpoint.
Frontend needs to update preferences without replacing the full profile.
Can you add this to the contract before implementing?"

効果的でない：

SendMessage -> backend teammate:
"Hey, I was working on the frontend and I noticed we need
some changes. The profile page has this preferences feature where
users can update without replacing everything and I think we need
a new endpoint for that. What do you think? Also I noticed..."

ブロードキャストとダイレクトメッセージ

digraph message_type {
    "Who needs this information?" [shape=diamond];
    "Entire team?" [shape=diamond];
    "broadcast (expensive)" [shape=box];
    "SendMessage to specific teammate" [shape=box style=filled fillcolor=lightgreen];

    "Who needs this information?" -> "Entire team?";
    "Entire team?" -> "broadcast (expensive)" [label="yes - convention change, critical blocker"];
    "Entire team?" -> "SendMessage to specific teammate" [label="no - most cases"];
}

ブロードキャストを使うのは次の場合のみ：

• すべてのチームメンバーに影響する規約やパターンの変更
• すべての進行を止める重大なブロッカー
• 共有リソースの競合

それ以外はすべてダイレクトメッセージ（状況報告、質問、調査結果、調整）にしてください。

チームリーダーへの報告

タスクを完了したら、次の内容を報告してください。

COMPLETED: [task name]
RESULT: [one-line summary]
FILES CHANGED: [list]
FINDINGS: [anything the lead or other teammates should know]
CONCERNS: [anything that might affect other tasks]

引き継ぎ形式

実装担当者からレビュー担当者へ

## What Was Built
[Summary - what changed and why]

## Files Changed
[Exact paths, one per line]

## Test Results
[Pass/fail counts, any notable results]

## Self-Review Notes
[Issues found and resolved during self-review]
[Remaining concerns]

## Verification Command
[Exact command to run]

レビュー担当者から実装担当者へ（修正依頼）

## Issues Identified
[List each issue with file:line reference]

## Priority
- Blocking: [must resolve before approval]
- Important: [should resolve]
- Suggestion: [consider for improvement]

## Scope Boundaries
[Do not refactor while fixing — stay focused]

調査担当者からリーダーへ（デバッグ／調査）

## Hypothesis Under Test
[What was being investigated]

## Evidence
- Supporting: [evidence favoring the hypothesis]
- Contradicting: [evidence against the hypothesis]

## Confidence
[High/Medium/Low with reasoning]

## Recommendation
[Next steps based on findings]

## Cross-Cutting Discoveries
[Anything that affects other investigations]

コンテキスト管理

含める内容

• 正確なファイルパス（必ず絶対パスを指定し、概略で済ませない）
• エラーメッセージは原文のまま記載する（言い換えない）
• 関連するコードスニペット（ファイル全体ではなく）
• 参照先の具体的な行番号
• コピーしてすぐ実行できる検証コマンド
• 依存関係と前提条件

除外する内容

• 計画ファイル全体（関連するタスクのみを貼り付ける）
• 完了済みタスクの詳細（依存関係がある場合を除く）
• タスクに関係のないプロジェクトの履歴
• 却下された代替アプローチ
• 明らかなパターンについての冗長な説明

コンテキスト予算のガイドライン

エージェントの種類	対象コンテキスト	理由
実装担当者	タスク + パターン + ファイル	構築に集中する
レビュアー	仕様 + 差分 + チェックリスト	検証に集中する
調査担当者	仮説 + 証拠の場所	発見に集中する
チームメイトへのメッセージ	必要なアクション + 最小限のコンテキスト	相手のコンテキストウィンドウを尊重する

エスカレーション

エージェントが解決できない問題に遭遇した場合：

digraph escalation {
    "Agent hits obstacle" [shape=box];
    "Can resolve independently?" [shape=diamond];
    "Resolve it" [shape=box];
    "Affects only own task?" [shape=diamond];
    "Report to lead at task completion" [shape=box];
    "Message lead immediately" [shape=box];
    "Affects other teammates?" [shape=diamond];
    "Message affected teammates" [shape=box];

    "Agent hits obstacle" -> "Can resolve independently?";
    "Can resolve independently?" -> "Resolve it" [label="yes"];
    "Can resolve independently?" -> "Affects only own task?" [label="no"];
    "Affects only own task?" -> "Report to lead at task completion" [label="yes"];
    "Affects only own task?" -> "Affects other teammates?" [label="no - blocks others"];
    "Affects other teammates?" -> "Message affected teammates" [label="yes"];
    "Affects other teammates?" -> "Message lead immediately" [label="no - requires lead decision"];
}

エスカレーションメッセージの形式：

BLOCKED: [what is blocked]
CAUSE: [why it is blocked]
ATTEMPTED: [what was tried]
NEED: [what would unblock - decision, information, or fix]

認知上の落とし穴

正当化	真実
"コンテキストは多いほど役に立つ"	コンテキストが多いほど、気が散ります。独立したタスクでは、コンテキストを絞るほどよい結果が得られます。
"何が関連するかは自分で判断できる"	エージェントは、関係のない情報の解析にトークンを浪費します。相手に渡すコンテキストを選別しましょう。
"計画ファイルを読んでもらえばよい"	計画ファイルにはすべてのタスクが含まれています。エージェントは他のタスクに気を取られます。該当箇所だけを貼り付けましょう。
"形式を決めずに気軽に説明すればよい"	構造化されていないプロンプトからは、構造化されていない結果が生まれます。テンプレートを使いましょう。
"短いメッセージはそっけなく見える"	簡潔なメッセージは、相手のコンテキストウィンドウを尊重します。
"見つけたことをすべて報告しよう"	実行に移せる内容を報告しましょう。送る前に不要な情報を取り除きます。

ガードレール

禁止事項：

• サブエージェントに計画ファイルを読ませること（代わりに内容を貼り付ける）
• 構造化されていないプロンプトを送ること（「テストを修正して」など）
• 関係のないコンテキストを含めること（「これまでの経緯をすべて説明すると……」など）
• 定例の更新に一斉送信を使うこと
• 成果物の形式に関するセクションを省略すること（エージェントは何を報告すべきかわかりません）
• これまでに試したことを明示せずにエスカレーションすること

必須事項：

• すべてのプロンプトを、役割、タスク、コンテキスト、制約、成果物の形式で構成する
• ファイルを参照する代わりに、内容を直接貼り付ける
• 実装プロンプトに検証コマンドを含める
• 一斉送信よりダイレクトメッセージを使う
• 引き継ぎのたびにファイルパスを含める
• 複数の関係者に影響する発見を、影響を受ける関係者に報告する

連携

利用先：

• godmode:delegated-execution — 実装担当者とレビュアーへのプロンプト
• godmode:parallel-execution — 並行して作業するエージェントへのプロンプト
• godmode:team-orchestration — チーム内のコミュニケーションパターン

補完するもの：

• godmode:fault-diagnosis — デバッグ調査レポートの構成
• godmode:quality-gate — レビュー依頼の構成
• godmode:completion-gate — 完了報告の構成