web-research

Web リサーチ

鋭いリサーチの問いを、並行して動く Web 検索サブエージェントに委任し、引用付きで、調査の抜けも明示した調査結果にまとめます。

成果物は必ずディスク上に作成します。呼び出し元が確認できる調査計画、サブトピックごとの調査結果ファイル、番号付き引用を含む統合レポートを作成します。インラインの文章として結果を返すことはありません。また、URL、タイトル、原文の抜粋がそろっていない主張は、成果物に含めません。

使用する場合

• ユーザーがトピックに関する Web リサーチを依頼した場合（「X を調査して」「Y の情報源を調べて」「Z の根拠を集めて」など）。
• 別の beagle スキルがリサーチの補助として、プログラム経由でこのスキルを呼び出す場合（references/companion-contract.md を参照）。
• 呼び出し元が監査可能な出力を求めている場合。ユーザーが承認した調査計画、サブトピックごとの調査結果ファイル、引用で裏付けられた統合結果を作成します。

使用しない場合

• コードベースの検索（「この関数はどこで定義されていますか」「リポジトリを検索して」など）。代わりにコードベースを検索してください。
• ローカルファイルの検索やドキュメントの抽出。ローカルファイル検索または artifact-analysis を使用してください。
• 2 つの実装の比較評価。llm-judge を使用してください。
• ペイウォールや認証が必要なスクレイピング。対象外です。抽出済みのコンテンツを貼り付けるよう、呼び出し元に依頼してください。
• リサーチの問いの再構成や、問いの立て方に関する助言。それは呼び出し元の役割です。このスキルでは、受け取った問いを確定済みのものとして扱います。

ワークフロー

順番に 4 つのステップを実行します。省略できるステップはありません。

1. plan.md を作成する — メインの問いを一字一句そのまま記載し、重複しないサブトピックを 1～5 件設定します。各サブトピックで明らかにする内容と、調査結果の統合方法も記載します。
2. 計画のレビューゲート — ユーザーに計画を提示して確認を求めます。呼び出し元が auto_proceed: true を渡した場合に限り、省略できます。
3. サブエージェントを起動し、調査結果を統合する — 同時に最大 3 つのサブエージェント（サブトピックごとに 1 つ）を起動し、すべての応答を待ってから report.md を作成します。
4. 返却前に検証する — references/failure-modes.md の検証チェックリストを実行し、想定される成果物がすべて存在し、適切な形式になっていることを確認します。失敗したチェックはすべて Gaps & Limitations に記録します。

厳格なゲート（客観的な合格条件）

直前のゲートに合格した場合にのみ次へ進みます。合格の根拠として必ず、ディスク上のファイル、呼び出し元のフラグ、または構造化エラーのいずれかが必要です。「確認した」という内部判断だけでは不十分です。

ゲート	ブロック対象	合格条件
G0 — ツール	スラッグの導出、output_dir、書き込み全般	Web アクセスが利用可能な場合、Web 検索が機能すること。不合格の場合は references/failure-modes.md の「Fail-fast on missing web tools」に従って JSON を出力します。plan.md やその他の成果物は作成しません。
G1 — 再実行	output_dir への最初の書き込み	output_dir に plan.md も report.md も存在しないこと、または「Re-run protection」の「Re-run protection」に従い、refresh: true を指定して既存の内容をアーカイブ済みであること（references/failure-modes.md を参照）。
G2 — 計画成果物	サブエージェントの起動	plan.md が存在し、「The research plan (plan.md)」にある必須項目をすべて含んでいること。
G3 — レビュー	起動	ユーザーが計画を承認済みであること、または auto_proceed: true が指定されていること。
G4 — 調査結果一式	統合	plan.md の各サブトピックについて、findings/<slug>.md が存在し、status: のフロントマターを含むこと（スタブでも可）。
G5 — 成果物	呼び出し元への成功応答	report.md が存在すること。また、references/failure-modes.md の実行終了時チェックリスト「Verification checklist」を満たすか、失敗した各チェックを Gaps & Limitations に記録していること。

Receive question ──→ Write plan.md ──→ Review gate (unless auto_proceed)
                                      ↓
                                    User confirms
                                      ↓
                                    Dispatch subagents (up to 3 parallel)
                                      ↓
                                    Collect findings/<slug>.md files
                                      ↓
                                    Synthesize report.md
                                      ↓
                                    Return paths to caller

ステップ 1 の前に、Web 検索を利用できる環境であれば、Web 検索が使えることを確認します。検索結果の抜粋よりも多くのページ内容を必要とするサブエージェントには、ページの取得機能があると望ましいですが、必須ではありません。検索のみの環境でも、有用な調査結果を作成できます。Web 検索が利用できない場合は、references/failure-modes.md に従って即座に失敗を通知します。plan.md を作成せず、サブエージェントも起動しないでください。

入力

入力仕様はシンプルで厳格です。

フィールド	型	必須	デフォルト	用途
research_question	string	はい	—	回答する質問です。すでに要点が絞られており、このスキルで形を変えることはありません。
output_dir	絶対パス	いいえ	派生	plan.md、findings/、report.md の保存先です。
auto_proceed	bool	いいえ	false	true の場合、計画レビューのゲートを省略して、すぐにディスパッチします。
refresh	bool	いいえ	false	true の場合、同じ output_dir にある以前の実行結果を上書きできます。

このスキルは、呼び出し元固有の構造を解析しません。呼び出し元は、実行前に概要を明確な質問文ひとつにまとめます。

auto_proceed: true と false の使い分け。 検索に時間を費やす前に、ユーザーがサブトピックの計画を確認できる利点がある場合は、false（デフォルト）を指定します。たとえば、呼び出し元がこのスキルの計画レビューゲートをチェックとして利用したい場合です。呼び出し元がユーザーとのやり取りを通じて「この切り口でよいか」という確認をすでに済ませていて、追加のゲートが手間になるだけの場合は、true を指定します。たとえば、ユーザーが会話の途中で明示的に背景調査を依頼した場合や、呼び出し元が上流で独自のレビューループを実行する場合です。重要なのは、レビューを行うかどうかではなく、どこで行うかです。

出力先

呼び出し元が output_dir を指定した場合は、その値をそのまま使用します。それ以外の場合は、デフォルト値を次のように導出します。

.beagle/research/<YYYY-MM-DD>-<topic-kebab>/

スラッグの導出（同じ質問を同じ日に再実行した場合、常に同じフォルダーに保存されます）。

1. 調査の質問を取得します。
2. 小文字に変換します。
3. 句読点を削除します（文字、数字、空白、ハイフンは残します）。
4. 連続する空白を単一のハイフンに置き換えます。
5. 単語の区切りで60文字に切り詰めます（60文字目より前にある最後のハイフンで切ります）。60文字目より前にハイフンがない場合は、60文字で切ります。
6. YYYY-MM-DD- を先頭に付けます。

再実行時の保護。 ファイルを書き込む前に、output_dir に plan.md または report.md がすでに存在するか確認します。存在し、refresh が true でない場合は、既存のフォルダー名を示して処理を拒否します。refresh: true の場合は、最初に以前の内容を <output_dir>/.archive-<timestamp>/ にアーカイブしてから、新たに開始します。references/failure-modes.md と references/companion-contract.md を参照してください。

実行ごとに個別のフォルダーに保存されるため、呼び出し元は数週間後でもスキルを再実行せずに、計画、調査結果、レポートを読み返せます。

調査計画（plan.md）

計画はサブエージェントの実行前に作成します。検索に時間を費やす前に、呼び出し元が不適切な切り口を見直すための機会となります。

plan.md には次の内容を記載します。

• 調査の質問 — 入力文字列をそのまま記載します。
• サブトピック — 重複しないものを1～5個、それぞれ1行の名前で記載します。
• 各サブトピックで明らかにする内容 — 「Xについてすべて調査する」ではなく、具体的な箇条書きで記載します。
• 統合方法 — 各サブトピックの調査結果をどのように組み合わせて report.md にまとめるかを記載します。
• 予算 — 起動するサブエージェントの数と、それぞれが実行できる検索の数を記載します（下記のデフォルト予算を参照）。

計画レビューゲート。 デフォルトでは、plan.md をユーザーに提示し、ディスパッチ前に確認を待ちます。ユーザーはサブトピックの修正、追加、削除、または切り口全体の却下を行えます。呼び出し元が auto_proceed: true を渡した場合は、ゲートを省略してすぐにディスパッチします。これは、呼び出し元が独自のレビューループを持つプログラム連携向けの経路です。

サブエージェントへの作業分担

最大3つのサブエージェントが同時に実行されます。それぞれに、plan.md から機械的に作成したブリーフが渡されるため、ユーザーが承認した計画とサブエージェントが受け取るブリーフの間で解釈にずれが生じません。ブリーフのテンプレートは references/subagent-brief.md にあります。

各サブエージェントは次の作業を行います。

• 予算内のウェブ検索を実行します（デフォルトでは3～5件）。
• output_dir の下に findings/<subtopic-slug>.md を書き込みます。
• 結果を本文に含めず、オーケストレーターに簡潔なステータス行（パス＋ステータス）を返します。

オーケストレーターはすべてのサブエージェントが完了するのを待ち、統合に進む前に、想定されるすべての調査結果ファイルが存在することを確認します。ファイルがない場合はサイレント障害として記録します。詳しくは references/failure-modes.md を参照してください。

ブリーフの全体像と、各調査結果ファイルに必要なフロントマターについては、references/subagent-brief.md を参照してください。

引用

調査結果ファイルおよび report.md のすべての主張には引用が必要です。形式は references/citation-schema.md に記載されています。概要は次のとおりです。

• 必須フィールド： url、title、excerpt（ページからの一字一句そのままの引用）。
• 任意フィールド： retrieved_at（ISO 日付）、source_type（official-docs / vendor / blog / forum / news / other）。
• メタデータを推測して補ってはいけません。 サブエージェントが取得日を把握していない場合は、そのフィールドを省略してください。捏造してはいけません。

本文中の参照には [^n] の脚注を使い、引用の全情報はレポート末尾の番号付き Sources セクションに記載します。

統合（report.md）

レポートは、次の順序で固定された4つのセクションから構成されます。毎回、すべてのセクションが必要です。

1. ## TL;DR — 重要度の高い調査結果をまとめた箇条書き3～5項目。
2. ## Findings — サブトピックまたはテーマごとに整理します。すべての主張に [^n] の脚注を付けます。
3. ## Gaps & Limitations — 調査で明らかにできなかったこと。失敗したサブエージェントがあれば、それも記載します。
4. ## Sources — 脚注番号に対応する番号付き参考文献一覧。

調査結果が完全に見えても、Gaps & Limitations は必須です。何を検証でき、何を検証できなかったかを正直に記録することも、成果物の一部です。このスキルがコピーする完全なリテラルのひな形は、references/report-template.md にあります。

失敗モード

• 部分的な成功 — 1つ以上のサブエージェントが失敗した場合。スキルは成功した結果を使って続行し、失敗した各サブトピックについて、最後に把握できたブリーフとスタブファイルの理由を含めて Gaps & Limitations に列挙します。実行は中止されません。
• フェイルファスト — ウェブ検索が利用できない場合（ウェブアクセスが利用可能な場合）。ディスクへの書き込み（plan.md を含む）を一切行う前に中止し、references/failure-modes.md に従って構造化 JSON を返します。ページ取得はサブエージェントにとって任意であり、この判定条件には含まれません。
• サイレント障害の検出 — 各サブエージェントは、返答前に少なくとも status: フロントマター（ok、empty、failed）を含むスタブファイル findings/<slug>.md を書き込みます。ディスパッチ後にファイルがない場合はサイレント障害として記録し、Gaps & Limitations に記載します。
• 再実行の防止 — 上記の「出力先」で説明しています。詳細は references/failure-modes.md を参照してください。

すべてのルールと構造化エラーの形式は、references/failure-modes.md に記載されています。

予算のデフォルト値

調整可能な設定値であり、固定された不変条件ではありません。

設定項目	デフォルト
1回の実行あたりのサブトピック数	1-5
並列実行するサブエージェント数	最大3
サブエージェントあたりのウェブ検索数	3-5

より広い範囲または狭い範囲が必要な場合は、呼び出し元がブリーフで上書きできます。検索に時間を費やす前に調整するには、計画レビューのゲートを利用してください。

コンパニオン呼び出し契約

ほかの beagle スキルは、簡潔で文書化された契約に従ってこのスキルを呼び出します。最小限の呼び出しでは research_question のみを渡し、完全な呼び出しでは output_dir、auto_proceed、refresh も追加します。

既知の3つの呼び出し元（prfaq-beagle、brainstorm-beagle、strategy-interview）の具体例と、成功時および即時失敗時の戻り値の形式は references/companion-contract.md に記載されています。呼び出し元は、独自の並行する呼び出し形式を作らず、契約をそのまま遵守することが求められます。

トーン

このスキルは、トーンに左右されない基本機能です。次のことは行いません。

• 質問が適切かどうかについて、呼び出し元に助言する。
• リサーチの質問を組み替えたり、明確化したり、疑問を投げかけたりする。
• 姿勢（徹底的、ソクラテス式、親しみやすいなど）を取る。これは呼び出し元の役割です。
• 調査結果やレポートに論評を加える。

呼び出し元がコーチングスキル（prfaq-beagle、brainstorm-beagle）の場合、コーチングはこのスキルの実行前後に行われます。このスキル内では、質問は確定済みとして扱います。

対象外

• 長時間実行またはスケジュール実行されるリサーチジョブ。
• 情報源の信頼性をLLM-as-judgeで評価すること。比較評価には、すでに llm-judge が対応しています。
• 有料または認証が必要な情報源のスクレイピング。
• リサーチの質問に対するコーチング、異議の提示、または独自の判断による再構成。
• 多言語でのリサーチ。
• 呼び出し間での調査結果のキャッシュまたは重複排除。
• ウェブ以外のリサーチモード（ローカルファイル、プロジェクト文書、データベース）。artifact-analysis を使用してください。

参照ファイル

• references/subagent-brief.md — 各サブエージェントのディスパッチ時に、オーケストレーターが plan.md から機械的に記入するテンプレートです。
• references/citation-schema.md — 必須および任意の引用フィールド、脚注の規則、正しい形式の例です。
• references/report-template.md — 4つの固定セクションをすべて含む、report.md のそのまま使えるひな形です。
• references/failure-modes.md — 部分的な成功、即時失敗、サイレント失敗の検出、および再実行の保護規則です。
• references/companion-contract.md — prfaq-beagle、brainstorm-beagle、strategy-interview の具体例を含む、プログラムによる呼び出し形式です。