building-agent-team-prompts

エージェントチームのプロンプトを作成する

概要

エージェントチームのプロンプトは自己完結している必要があります。チームメンバーは会話履歴を引き継ぎません。チームメンバーが必要とするコンテキストはすべて、起動時のプロンプトに含めるか、コードベースから確認できるようにしてください。

基本原則： 優れたエージェントチームのプロンプトでは、誰がどのファイルで何を行い、どのように連携し、いつ作業を完了するかを指定します。

プロンプトを作成する前に

そのタスクが本当にエージェントチームの利点を活かせるか確認してください。

• 複数の独立した作業（レビュー、調査、互いに重複しない実装）
• 並行調査によって有益な仮説の競合
• 各レイヤーを独立して担当できる、レイヤーをまたぐ作業

エージェントチームを使わないケース： 順次進めるタスク、少数のファイルに集中した作業、または連携のオーバーヘッドが利点を上回る単純なタスク。代わりにサブエージェントまたは単一のセッションを使用してください。

プロンプトのテンプレート

エージェントチームのプロンプトには、以下のセクションを含めてください。該当しないセクションは省略してください。

1. 目標

チームが達成しようとしていることを、1文で記述します。

2. チーム構成

チームメンバーごとに、次の項目を指定します。

• 名前：役割が分かるケバブケース（security-reviewer、backend-impl）
• 役割：担当内容を1文で説明します
• モデル：定型的な作業や調査には sonnet、複雑な推論には opus を使用します。深い分析が必要なタスクでない限り、デフォルトは sonnet にします。

適切な規模にする： 1つのタスクだけを担当するメンバーを多数配置するよりも、少数のメンバーに多くのタスクを割り当ててください。各メンバーが2つのタスクを担当する6人のチームより、各メンバーが5つのタスクを担当する3人のチームの方が効果的です。独立したコンテキストウィンドウを設けることで作業が本当に有益になる場合に限り、チームメンバーを起動してください。

目安： 起動する前に、チームメンバー1人あたりの作業量を見積もってください。タスクが3つ未満、または作業時間が15分未満になる場合は、その担当範囲を別のメンバーの役割にまとめてください。

3. チームメンバーの起動時プロンプト

各チームメンバーには、以下を含む自己完結したプロンプトを渡します。

• タスクの完全なコンテキスト — CLAUDE.md に記載されていない、知っておく必要のある情報
• 具体的な指示 — 調査、構築、レビューの対象
• ファイルの担当範囲 — 専任で担当するファイルやディレクトリ
• 変更禁止の範囲 — 他のチームメンバーが担当し、変更してはならないファイル
• 成果物の要件 — 形式、構成、結果の出力先

重要： チームメンバーは会話を見ることができません。ユーザーが以前の会話で重要なことを説明していた場合は、その内容を起動時のプロンプトに含めてください。

必ず含めること： 構築やレビューの前に、既存のコードベースのパターンを確認するよう、各チームメンバーに伝えてください。実装の場合は、「新しいコードを書く前に、コードベースで同様の機能がどのように実装されているかを確認し、そのパターンに従ってください。」と伝えます。レビューの場合は、「プロジェクトの規約と既存のパターンを確認し、それを基準にレビューしてください。」と伝えます。

4. タスクの分解

次の項目を含む具体的なタスクを定義します。

• タスクごとに明確な成果物を設定する
• タスク間の依存関係を示す（何が何を妨げるか）
• 特定のチームメンバーに割り当てる
• 目標：チームメンバー1人あたり3～6件のタスク

役割を割り当てるだけではなく、共有タスクリストを使って、進捗を追跡できる単位に作業を分解してください。

5. コミュニケーションのルール

チームメンバーが互いに連絡するタイミングを指定します。

• 調査結果の共有：「Xを発見した場合は、teammate-Y に連絡してください」
• 複数の範囲に関わる懸念事項：「互換性を破る変更があれば、すべてのチームメンバーに知らせてください」
• 対抗的な検証：デバッグでは、チームメンバーが互いの仮説を積極的に反証しようとします

チームメンバー間の連絡が不要な場合は、その旨を明記してください。トークンを節約できます。

6. 調整設定

• 委任モード：リードが調整のみを行い、実装を担当しない場合に使用します。チームメンバーが3人以上の場合や、リードが担当ファイルを取り合うことになる場合に推奨します。
• 計画の承認：チームメンバーが本番コードを変更する場合や、アーキテクチャ上の決定を行う場合に必須とします。読み取り専用の調査やレビューでは省略します。
• 完了の定義：何をもって完了とするかを明記します。

7. 成果物

• 各チームメンバーが作成する成果物（形式を含む）
• チームメンバーの成果物からリードがまとめる内容
• 最終的な出力（レポート、PR のコメント、実装など）

タスクの種類別パターン

コードレビュー

• ファイル数ではなく、ドメインごとにレビュアーの担当範囲を設定します
• 横断的なレビュアー（セキュリティ、テスト）は、ドメイン担当のレビュアーと連携します
• 指摘ごとに構造化された出力を作成します：severity | file:line | description | suggestion
• リードが内容をまとめ、レビューサマリーを1つ作成します

機能の実装

• レイヤーごと（DB／API／フロントエンド／テスト）にチームメイトを1人割り当てます
• 共有インターフェースを明確に定義します。1人のチームメイトがAPIコントラクトを定義し、他のメンバーがそれを利用します
• 実装の前に計画の承認を必須にします
• リードには委任モードを使用します
• ファイルの所有権を厳格に管理します。同じファイルを2人のチームメイトが編集してはいけません

デバッグ／調査

• 仮説ごとにチームメイトを1人割り当てます
• 対立的な構成を使用します。チームメイト同士がメッセージを通じて互いの仮説に異議を唱えます
• バグが断続的に発生する場合は、再現を担当するチームメイトを含めます
• リードは精査を経て残った仮説を追跡し、結論をまとめます

調査／探索

• 調査の切り口ごとにチームメイトを1人割り当てます
• 一般的な知識ではなく、実際のコードベースに基づいて調査結果を示すよう、チームメイトに指示します
• 統合の計画を定めます。最終レポートを誰が、どの形式で作成するかを決めます
• 調査が際限なく続かないよう、範囲の境界を設定します

ファイルの所有権ルール

ファイルの競合は、エージェントチームで無駄な作業が発生する最大の原因です。

1. 変更するファイルには、それぞれ必ず1人だけ所有者を設定します。2人のチームメイトが同じファイルを必要とする場合は、1人が所有者となり、もう1人はメッセージで変更を依頼します
2. 共有する型／インターフェース：1人のチームメイトが定義し、他のメンバーは読み取りのみ行います
3. テスト：テスト対象のコードの所有者が担当するか、ソースコードには触れない専任のテスト担当チームメイトが担当します
4. 設定ファイル：担当者を1人指定します

クイックリファレンス

項目	自問すること
チームの規模	チームメイトを減らして、各自のタスクを増やせませんか？
モデル	Opus が必要ですか、それとも Sonnet で十分ですか？
委任モード	リードは実装を避けるべきですか？（3人以上なら、はい）
計画の承認	チームメイトは本番コードを変更しますか？
コミュニケーション	チームメイト同士で調査結果を共有したり、互いの結果に異議を唱えたりする必要がありますか？
ファイルの所有権	2人のチームメイトが同じファイルを編集する可能性はありますか？
範囲	このチームはいつ「完了」ですか？
成果物	各チームメイトが具体的に作成するものは何ですか？

よくある間違い

間違い	結果	対策
ファイルの所有権を設定しない	チームメイト同士で互いの変更を上書きします	変更するすべてのファイルに所有者を1人割り当てます
成果物が曖昧	出力の品質にばらつきが生じます	チームメイトごとに形式を指定します
全員に Opus を使う	Sonnet で十分なタスクに4倍のコストがかかります	原則として Sonnet を使い、必要に応じて選択的に上位モデルへ切り替えます
コミュニケーション計画がない	縦割りになり、横断的な知見を見逃します	メッセージを送る条件を指定します
リードも実装する	チームメイトとファイルの取り合いになります	委任モードを有効にします
範囲の境界がない	調査がいつまでも続きます	「完了」の条件を明確に定義します
チームメイトが多すぎる	調整の負担がメリットを上回ります	チームメイトを減らし、各自のタスクを増やします
計画の承認がない	不適切なアーキテクチャ上の判断がそのままリリースされます	実装タスクでは承認を必須にします
既存のパターンを確認しない	チームメイトが既存の仕組みを作り直します	類似機能の実装方法を確認するよう指示します