deep-research

ディープリサーチスキル

あるトピックについて、最新の実践者の知見、公式ドキュメント、コミュニティでの議論を調査し、プレイブックを作成または更新します。

ステップ 0：引数を解析する

ユーザーの入力は次のとおりです：$ARGUMENTS

引数がない場合：このヘルプを表示して終了します：

Usage:
  /deep-research swift concurrency
  /deep-research kubernetes cost optimization --file infra-playbook.md
  /deep-research --file existing-playbook.md   (updates all sections)
Playbook is created in your current working directory by default.

解析ルール — 必ず次の順序で適用します。

1. $ARGUMENTS に --file <path> が含まれる場合、ファイルパスとして抽出します。それ以外はすべてトピックです。
2. それ以外の場合、.md で終わるトークン、または / を含むトークンをファイルパスとして扱います。それ以外はすべてトピックです。
3. それ以外の場合、$ARGUMENTS 全体をトピックとして扱います。ファイルパスは、現在の作業ディレクトリ内に <topic-slug>.md として自動生成します（例：「swift concurrency」→ swift-concurrency.md）。

例：

• /deep-research swift concurrency → トピック：「swift concurrency」、ファイル：swift-concurrency.md
• /deep-research kubernetes cost optimization --file infra-playbook.md → トピック：「kubernetes cost optimization」、ファイル：infra-playbook.md
• /deep-research --file docs/playbook.md → 既存ファイルからトピックを推定、ファイル：docs/playbook.md
• /deep-research docs/react-hooks.md state management → トピック：「state management」、ファイル：docs/react-hooks.md

ステップ 0.5：前提を確認する

次のいずれかに該当する場合、続行する前に AskUserQuestion を使用します。

• トピックが曖昧：トピックに複数の一般的な意味がある場合（例：「swift」「python」「spring」「agent」「mercury」）。どの意味かを尋ねます。
• トピックの範囲が広すぎる：焦点を絞らないと十分に調査できないほど広い場合（例：「machine learning」「AI safety」）。重視する側面や対象読者を尋ねます。
• 結果を左右するコンテキストが不足している：トピックから特定のコンテキストが想定されるものの、ユーザーが明示していない場合（例：クラウドプロバイダー、プログラミング言語、対象読者のレベル）。
• トピックなしでの更新モード：既存ファイルから調査の焦点を推定する場合、エージェントを起動する前に、推定した焦点を確認します。

トピックが具体的で曖昧さがない場合は、このステップを省略します。

ステップ 1：プレイブックを読み込むか作成する

対象ファイルが存在する場合：

• ファイルを読み込みます。プレイブックらしい構成か（Sources セクションまたは *Captured:* の日付があるか）を確認します。
• プレイブックらしい構成であれば、すべてのセクション見出し、Sources リスト、文体を記録します。mode = update に設定します。
• そうでない場合は、ユーザーに警告します — 「このファイルは存在しますが、プレイブックのようには見えません。それでも更新しますか？それとも新しいファイルを作成しますか？」

対象ファイルが存在しない場合：

• トピックが指定されていない場合は、ここで終了します：「新しいプレイブックにはトピックが必要です。使用方法：/deep-research <topic>」
• 親ディレクトリが存在しない場合は、作成します。
• mode = create に設定します。構成は調査エージェントが決定します。

ユーザーに次のように伝えます：「<absolute path> にプレイブックを作成しています」または「<absolute path> のプレイブックを更新しています」。

ステップ 2：調査範囲を決める

mode = update（既存のプレイブック）：

タイトルとセクション見出しから、プレイブックの主題を特定します。

トピックあり：プレイブックの主題領域におけるトピックを調査するエージェントを 2〜3 個起動します。各エージェントは、必ず異なる観点から調査します。

1. 公式ドキュメントと権威ある情報源
2. コミュニティでの議論と実践者のブログ
3. （任意）ソーシャルメディアと最新レポート

トピックなし：既存のセクション見出しを 3〜5 個の調査テーマに分類します。プレイブックの *Captured:* の日付以降の更新を調べるエージェントを、テーマごとに 1 個起動します。

mode = create（新しいプレイブック）：

トピック自体を主題とします。異なる側面を担当するエージェントを 3〜5 個起動します。

1. 基本概念と公式ドキュメント
2. ベストプラクティスと一般的なパターン
3. 注意点、落とし穴、トラブルシューティング
4. ツール、ライブラリ、エコシステム
5. （任意）高度なテクニックと新たなトレンド

トピックに合わせて調査項目を調整します。すべてのトピックで 5 項目すべてが必要とは限りません。

ステップ 3：リサーチエージェントを起動する

起動する前に、ユーザーに次の内容を伝えます。

Launching [N] research agents in parallel:
  1. [Agent 1 angle]
  2. [Agent 2 angle]
  ...

Agent toolを使って、エージェントを並行して起動します。各エージェントでは、subagent_type: general-purpose と run_in_background: false を必ず指定してください。

各エージェントへのプロンプトの作成 — 次の内容を必ず含めてください。

1. 対象と具体的な切り口（例：「Swift の async/await のベストプラクティス」や「Claude Code opus 4.7 の公式ドキュメント」）
2. プレイブックのコンテキスト：
   • mode = update：すでに取り上げられている内容をエージェントが飛ばせるよう、既存のセクション見出しを列挙します
   • mode = create：新規プレイブックであることを伝え、調査結果をすべて返すよう指示します
3. 検索の指示：対象とトピックから導いたクエリを使い、WebSearch を使用するようエージェントに伝えます。次のパターンを使います。
   • "[subject] [topic] [current year]"（一般的なウェブ検索）
   • 対象の信頼できるドメインで "[subject] [topic]"
   • "[subject] [topic] blog [current year]"（実践者のブログ）
   • 次に、有望な URL に対して WebFetch を使い、詳細を抽出します
4. 出力形式：各調査結果について、次の内容を返すよう指示します。
   • インサイト：具体的で実行可能な調査結果（1～2 文）
   • ソース URL：直接リンク
   • 推奨セクション：この内容を掲載するセクション（update モードでは正確なセクション名、create モードでは提案するセクション名）
   • 信頼度：高（公式ドキュメント／複数の情報源）または中（実践者による単一の報告）
5. ルール：実際のソース URL がある調査結果のみを必ず返すよう指示します。ソースのない調査結果は絶対に返さないようにしてください。マーケティングではなく、実践者の知見（実際に人々が行っていること）を重視します。一般的なアドバイスより、具体的な手法、数値、注意点を優先します。

エージェントが結果を返さなかった場合は、諦める前に年の指定を外し、より広い検索語を試します。

ステップ 4：調査結果を統合する

mode = update（既存のプレイブック）の場合：

各リサーチエージェントの結果について、次の手順を実施します。

1. フィルタリング：ソース URL がないもの、または既存の内容と重複するものを除外します
2. 配置箇所の特定：各調査結果に該当するプレイブック内の正確なセクションを特定します
3. 編集：Edit tool を使って、調査結果を既存のセクションに統合します
   • プレイブックで使われている文体に必ず合わせます。執筆前に数段落を読み、文体を把握してください。トーンの違い：
     • 悪い例：「パフォーマンス向上のために、キャッシュの実装を検討することが一般的に推奨されます。」
     • 良い例：「積極的にキャッシュしてください。共有状態には Redis、頻繁に使う処理にはインメモリを使います。まずプロファイルを取得してください。」
   • 形式：[インサイトのテキスト]。 — [ソース名](URL)（ソースの前にスペース、全角ダッシュ、スペース）
   • 既存の段落、表、箇条書きに追加します。既存のセクションで扱われていないトピックで、かつ 3 つを超える箇条書きが必要な場合を除き、新しい小見出しは絶対に作成しないでください
4. ソース一覧：新しいソース URL があれば、末尾の Sources 一覧に追加します

統合ルール：

• 独立した「新しい調査結果」や「更新」セクションは絶対に作成しないでください。既存の構成に統合します
• ソース URL のない主張は絶対に追加しないでください
• 文体は絶対に変えず、プレイブックで使われているスタイルに合わせてください
• 信頼度が高い調査結果が既存の内容と矛盾する場合は、既存の内容を更新し、読者が変遷を確認できるよう古いソースも新しいソースと併記します
• 信頼度が中の調査結果だけが既存の内容と矛盾する場合は、置き換えるのではなく、別の見解として追加します
• 信頼度が高いソースによって明示的に置き換えられる場合を除き、既存の内容は必ず保持します

mode = create の場合（新しいプレイブック）：

1. フィルタリング：ソース URL がない項目はすべて除外します
2. グループ化：調査結果をテーマごとに論理的なセクションに分類します（5～10 セクションを目安にします）
3. 作成：Write ツールを使ってファイルを作成します。構成：

   # [Title derived from topic]
   
   [Sections — group related insights under clear headings]
   
   ---
   ## Sources
   
   [All source URLs from research]
   
   ---
   *Captured: YYYY-MM-DD*
   

   各セクションでは：
   • 調査結果を統合した簡潔な要約の段落を書き、その後に重要な知見を箇条書きにします
   • すべての主張に必ず出典を付けます：[知見] — [出典名](URL)
   • 文体：率直で簡潔、実務に役立つ内容にします。余計な表現や曖昧な表現は避けます
4. 出典一覧：すべてのソース URL を末尾の Sources セクションにまとめます

フィルタリング後に調査結果が何も残らなかった場合は、ユーザーに次のように伝えます："このトピックに関する出典付きの調査結果は見つかりませんでした。より広い、または具体的なトピックをお試しください。"

ステップ 5：検証と報告

すべての編集が完了したら：

1. プレイブックを読み、次の点を確認します：

   • 追加したすべての主張にソース URL が付いている
   • 重複した項目がない
   • セクションの流れに一貫性があり、新しい内容が不自然に付け加えられていない
   • Sources 一覧にすべての URL が含まれている

2. ユーザーに報告します：

   ## Playbook [Created | Updated]
   
   **File**: [absolute file path]
   **Mode**: [create | update]
   **Topic**: [what was researched]
   **Agents launched**: [N]
   
   ### Sections [created | modified]:
   - **Section Name** — [brief description of content]
   - ...
   
   ### Sources: [count]
   ### Findings integrated: [count]
   ### Findings dropped (no source / duplicate): [count]