research

リサーチ

概要

推奨や実装の前に、出典に裏付けられたリサーチを行います。外部の証拠、リポジトリ内部の証拠、明示的な不確実性を組み合わせ、何が既知で、何が推論で、何が古く、何がまだ不明なのかをユーザーが判断できるようにします。

基本契約

ユーザーが実装や永続的な変更を明示的に依頼しない限り、リサーチは読み取り専用として扱います。

許可される操作：

• ファイル、ドキュメント、設定、ログ、テスト、git 履歴、パッケージメタデータ、生成済みの成果物を読み取ること。
• コードベースや外部ソースを検索すること。
• プロジェクトを意図的に変更しない調査コマンドを実行すること。
• 安全な調査に必要な場合、ワークスペース外の一時的な作業領域を使用すること。
• 計画、判断、トレードオフ、次のステップを提案すること。

明示的な承認がない限り避ける操作：

• ワークスペース内のファイルを編集、作成、削除、フォーマット、生成すること。
• パッケージ、CLI、プラグイン、バイナリ、ブラウザー拡張機能、サービスをインストールすること。
• データベース、キュー、デプロイ済みサービス、課題管理ツール、ダッシュボードへの書き込みを開始すること。
• ステージング、コミット、ブランチ作成、リベース、プッシュ、PR の作成、その他の状態を変更する git 操作を行うこと。

有用なリサーチに変更が必要な場合は、その理由を説明し、続行する前に承認を求めます。

ソースの選定

一次情報、最新情報、ローカルのソースを優先します。

• コードベースのリサーチでは、結論を出す前に AGENTS.md などのローカル指示、オーナーシップドキュメント、パッケージドキュメント、ソースファイル、テスト、スキーマ、ログ、読み取り専用の git 履歴を確認します。
• 外部リサーチでは、利用可能な場合、適切な設定済みリサーチ MCP を、公式ソース、信頼できる一次情報、標準、ベンダードキュメント、論文、変更履歴、リリースノートと併用します。
• ライブラリ、フレームワーク、SDK、API、CLI、クラウドサービスのドキュメントを調べる場合、利用可能であれば適切な設定済みドキュメント MCP を優先します。ユーザーが正確な識別子を指定していない場合は、まずライブラリまたはプロジェクトを特定します。
• より適切なソース特化型のツールが利用できない、または情報が不十分な場合に限り、一般的なウェブ検索を使用します。
• 変化の速い事実については、最新情報を検証し、日付やバージョンを含めます。

一次情報がある場合、要約、抜粋、生成された回答、フォーラムの投稿、記憶を権威ある情報源として扱わないでください。

内部リサーチのワークフロー

1. 結論を出す前に、該当するリポジトリの指示を確認します。
2. ファイル名、シンボル、ルート、設定、ドキュメントなどを高速検索し、関連箇所を特定します。
3. 質問への回答に必要な最小限のソースファイルを調べます。
4. 回答に影響する場合は、テスト、スキーマ、マイグレーション、パッケージのエクスポート、実行時のエントリーポイント、呼び出し元をたどります。
5. 時期、担当者、過去の挙動が重要な場合は、読み取り専用の git 履歴を確認します。
6. 実際の挙動についての質問で、安全な読み取り専用の証拠が得られる場合は、実行時の証拠やログを優先します。
7. 実装済みの挙動と、計画段階、廃止済み、一部のみ、テスト専用、または到達不能な挙動を区別します。

ハーネスでシェルアクセスが利用できる場合は、まず rg などの高速検索を使用します。

外部リサーチのワークフロー

1. 質問、判断事項、情報の鮮度要件、許容されるソースの種類が曖昧な場合は、明確にします。
2. 一次情報や異なる見解を見つけるのに十分な範囲で検索します。
3. 検索結果の抜粋だけに頼らず、関連するソースの箇所を開いて読みます。
4. 重要な場合は、公開日、バージョン、著者またはベンダー、対象範囲の制限を記録します。
5. 金銭、セキュリティ、法的リスク、本番環境のアーキテクチャ、ユーザーの信頼に影響する主張は、独立した複数のソースで照合します。
6. 正確な表現が重要な場合に限り直接引用し、それ以外は言い換えて出典を示します。
7. ソース間の食い違いを記し、どのソースをより信頼すべきか説明します。

オプションの並列エージェント

調査をより完全に、または迅速に進められ、ハーネスが対応している場合は、並列エージェントを使用します。最終的な判断はオーケストレーターが担います。

有効な調査分野：

• 外部ソースと最新の事実。
• 内部コードベースの根拠。
• 公式ドキュメント、またはバージョン固有のライブラリの動作。
• セキュリティ、プライバシー、コンプライアンス、運用上のリスク。
• 代替案、競合、先行事例、トレードオフ。
• 別の調査分野で示された、範囲を絞った主張の検証。

割り当てのガイダンス：

• 各エージェントに、調査対象のファイル、システム、またはソース種別を明確に指定した、範囲限定の読み取り専用タスクを割り当てます。
• 根拠、引用、不確実性、簡潔な推奨事項を求めます。
• 検証に必要な場合を除き、意図する回答をエージェントに示さないようにします。
• 調査分野を読み取り専用にして、書き込みの重複を防ぎます。
• 調査結果を一元的に統合し、予想外の主張を再確認してから、矛盾を解消します。

並列エージェントを利用できない場合や、タスクの範囲が狭い場合は、単一のエージェントとして進めます。そのことが結果に影響する場合に限り、明記します。

根拠台帳

調査中は、簡潔な台帳を維持します。

• 質問：回答する対象を正確に記載します。
• ソース：確認したファイル、コマンド、ドキュメント、URL、日付、バージョン、ログ。
• 調査結果：ソースに裏付けられた事実。
• 推論：事実から導いた結論。
• 未確認事項：不足情報、古い情報、アクセスできないソース、曖昧な挙動。
• 確信度：理由を簡潔に添えて、高・中・低で示します。

完了した範囲を誇張しないでください。質問の一部しか回答できていない場合は、何を確認できたか、何が残っているかを正確に伝えます。

回答形式

必要最小限で役立つ形式を選びます。

• 引用またはファイル参照を添えた直接的な回答。
• 重大度、確信度、または意思決定への影響順に並べた調査結果。
• 現在のコードパスと挙動の対応図。
• 推奨事項とリスクを添えた選択肢の比較。
• 事実、解釈、次のアクションを含む調査概要。

最終回答では、次の点に従います。

• 回答または推奨事項を最初に示します。
• ローカルファイルはパス、外部ソースは可能な場合リンクを添えて引用します。
• 事実と解釈を区別します。
• 正確性に関わる場合は、具体的な日付、バージョン、コマンド、ファイル参照を含めます。
• 実施していない検証、アクセスできなかった情報、情報が古い可能性を明確に述べます。
• 根拠がそろってから、実装を推奨します。