deep-research

ディープリサーチスキル

目的

このスキルを使うと、Web 検索機能を備えた OpenAI Responses API を利用して、あらゆるトピックについてインターネットを活用した包括的な調査を行えます（デフォルトモデルは gpt-5.6-sol。--model または DEEP_RESEARCH_MODEL で変更できます）。o3-deep-research と o4-mini-deep-research は 2026-07-23 に提供終了が予定されており、デフォルトではなくなりました。対話形式の確認質問を通じてユーザーの調査プロンプトを適切に改善し、再現性を確保するために調査パラメーターを保存したうえで、Web 検索機能を最大限に活用したディープリサーチを実行します。

このスキルを使う場合

次の場合にこのスキルを使用してください。

• ユーザーが特定のトピックについて調査を依頼したとき
• ユーザーが分析、調査、または包括的な情報収集を依頼したとき
• ユーザーがWeb検索と推論を用いたテーマの探究を希望したとき
• ユーザーが、内容を具体化できる簡潔な調査クエリを提示したとき
• ユーザーが、ある分野の現状、トレンド、または比較について知りたいとき

ユーザーからの依頼例：

• 「ベンチマーク性能の高い、最も効果的なオープンソースのRAGソリューションを調査してください」
• 「2025年の最新のAI動向を教えてください」
• 「分散データベースシステムについて包括的に分析してください」
• 「ベクトル検索を実装する際のベストプラクティスを調べてください」
• 「AIがソフトウェアエンジニアリング業界にどのような影響を与えているか調査してください」

ワークフローの概要

User Input
    ↓
Assessment: Prompt too brief?
    ↓
YES → Ask Enhancement Questions → Collect Answers
    ↓                               ↓
    └───────→ Construct Enhanced Prompt ←──┘
                    ↓
            Save to Timestamped File
                    ↓
            Execute deep_research.py
                    ↓
            Output Report + Sources
                    ↓
            Present to User

Claude がこのスキルを使用する方法

トークン効率に関する重要事項： ディープリサーチには 10～20 分、またはそれ以上かかります。ランナーはバックグラウンドモードで実行され、15 秒ごとに静かにポーリングします。コマンドは実行が終わるまでブロックされるため、Claude がステータスを確認する必要はありません。Claude は次の手順を実行します。

1. 調査を開始する
2. 完了を待つ（サブプロセスは自動的にブロックされます）
3. 完了したら最終結果を提示する

実行中に定期的にポーリングしたり、ステータスを報告したりする必要はありません。

ステップ 1：調査依頼を受け取る

ユーザーから調査プロンプトを受け取ります。簡潔なもの（「最新のAI動向」）から、詳細なもの（「2024～2025年に焦点を当てた、言語モデルが開発者の生産性に与える影響」）まで、さまざまな内容が含まれます。

ステップ 2：オーケストレーションスクリプトを実行する

ユーザーの調査プロンプトを指定して、このスキルのメインオーケストレーションスクリプトを実行します。

python3 scripts/run_deep_research.py "Your research prompt here"

スクリプトは、スキルのインストール先にある scripts/run_deep_research.py に配置されています。

ステップ 3：スクリプトの実行フロー

スクリプトは次の処理を自動的に行います。

1. プロンプトの具体性を評価する：プロンプトが短すぎる、または一般的すぎる（15 語未満、あるいは「what is」「how to」などで始まる）かどうかを確認します。

2. 確認質問をする（必要な場合）：

   • 調査の種類に関連する、焦点を絞った質問を 2～3 個提示します。
   • キーワードに基づいて、調査が技術的なものか一般的なものかを判定します。
   • ユーザーはあらかじめ用意された選択肢（1～4）から選ぶか、独自のテキストを入力できます。
   • 質問の対象は、範囲／期間、詳しさ、重点分野です。

3. プロンプトを改善する：元のプロンプトとユーザーの回答を組み合わせ、構造化された調査パラメーターを作成します。

4. プロンプトファイルを保存する：改善したプロンプトを research_prompt_YYYYMMDD_HHMMSS.txt に書き込み、再現性を確保します。

5. ディープリサーチを実行する：次の設定で中核となる deep_research.py スクリプトを実行します。

   • モデル：推論レベル high の gpt-5.6-sol（--model、--reasoning、または環境変数 DEEP_RESEARCH_MODEL で設定可能）
   • 最大待機時間：3600 秒／60 分（--timeout で設定可能）
   • ツール：Web 検索はデフォルトで有効です。

ステップ 4：結果をユーザーに提示する

スクリプトは自動的に以下を行います。

• まず生の JSON を保存：research_response_YYYYMMDD_HHMMSS.json には、API レスポンスの正確なバイト列（引用スパン、ウェブ検索のステップログ）が保持されます。実行が作成された時点ですぐに書き込まれ、その後の各ポーリング時にも再度保存されるため、料金が発生した結果が失われることはありません。
• リクエストを保存：research_request_…json（モデル、ツール、プロンプト。キーは含まれません）
• Markdown ファイルを保存：research_report_YYYYMMDD_HHMMSS.md。モデル、レスポンス ID、生のレスポンスファイルを示すフッター行が含まれます。
• ターミナルに出力：Markdown 形式の完全な調査レポート
• 参照したソースを一覧表示：## Sources consulted (web search) には、ウェブ検索の各ステップで検索または開いたすべての URL が表示されます。これらは参照したものであり、引用したものではありません。引用はインラインリンクです。
• 完了を確認：調査ファイルの保存先パス

トークン効率に関する注意：スクリプトはバックグラウンドでポーリングしている間、処理をブロックするため、Claude は 1 つのコマンドの完了を待ちます。

中断された実行：待機を始める前に、レスポンス ID が出力され、保存されます。実行中の処理や、待機がタイムアウトした処理の結果は、python3 assets/deep_research.py --resume <response_id> --output-dir <dir> で取得できます。新たな（有料の）リクエストは送信されません。

ボルトへのインポート：Markdown ではなく、生の JSON を research-runs スキルでインポートしてください。python3 ~/.claude/skills/research-runs/scripts/research_run.py import research_response_….json --vault <vault> --adapter openai-json --provider openai --surface api --prompt research_prompt_….txt。JSON には引用スパンと、参照したものの引用されなかったページが保持されます。

同梱リソース

スクリプト

scripts/run_deep_research.py（メインエントリーポイント）

以下を処理するオーケストレーションスクリプトです。

• プロンプト品質の評価
• 対話形式の改善質問（技術調査と一般調査をスマートに判別）
• プロンプトの保存とタイムスタンプ付与
• コアとなる詳細調査の実行

主な機能：

• スマートな改善：プロンプトが短い、または汎用的な場合にのみ質問します
• テンプレートベースの質問：技術調査と一般調査で異なる質問セットを使用します
• 柔軟な入力：番号付きの選択肢と自由入力に対応します
• エラー処理：deep_research.py が見つからない場合に役立つメッセージを表示します

利用可能なオプション：

python3 run_deep_research.py <prompt> [OPTIONS]
  --no-enhance              Skip enhancement questions
  --model <model>           Model to use (default: runner default, gpt-5.6-sol)
  --timeout <seconds>       Maximum wait in seconds (default: 3600)
  --output-dir <path>       Where to save the prompt, request, raw response, and report

assets/deep_research.py

OpenAI の Deep Research API と連携するコアスクリプトです。以下を処理します。

• OPENAI_API_KEY による API 認証
• リクエストの作成と実行
• Markdown の自動保存：デフォルトでタイムスタンプ付きのレポートファイルを保存します
• 出力の書式設定（レポートとメタデータ付きソース）
• エラー処理と再試行

新しいコマンドラインオプション：

--output-file <path>      Custom output file path
--no-save                 Disable automatic markdown saving

リファレンス

references/workflow.md

以下を含む、ワークフローの詳細なドキュメントです。

• 例を含むスキルの全ワークフロー
• プロンプト改善の戦略
• 調査パラメーターの説明
• Claude との連携に関するガイダンス
• コマンドラインインターフェースのリファレンス
• エラー処理とトラブルシューティング
• 効果的な調査のヒント

主な動作

スマートなプロンプト改善

このスキルは、改善が必要かどうかをインテリジェントに判断します。

• 改善を促す条件：15 語未満のプロンプト、または汎用的な書き出しのプロンプト
• 改善をスキップする条件：詳細で具体的なプロンプト
• ユーザーによる無効化：--no-enhance フラグで無効にできます
• テンプレート対応：技術調査と一般調査で異なる質問を使用します

調査パラメーター

改善されたプロンプトには以下が含まれます。

• 全文脈を含むユーザーの元のクエリ
• 範囲と期間の指定
• 希望する詳細度（要約、技術、実装、比較）
• 具体的な重点分野（パフォーマンス、コスト、セキュリティなど）

これらのパラメーターにより、詳細調査モデルは、より的を絞った関連性の高い結果を返せます。

再現性

調査を実行するたびに、以下が行われます。

• 使用した正確なプロンプトをタイムスタンプ付きのファイルに保存します
• 調査に関する判断を追跡できるようにします
• 同じプロンプト、または変更したプロンプトを使った追加調査を可能にします
• 調査パラメーターの監査証跡を維持します

使用例

簡潔なプロンプトの拡張例

ユーザー: "効果の高いオープンソースのRAGソリューションを調査してください"

スクリプトの動作:

1. 簡潔なプロンプト（12語）と技術キーワード（"opensource"、"RAG"）を検出します
2. 技術調査に関する質問をします:
   • 技術の範囲: オープンソースのみですか？（ユーザー: はい）
   • 主要な指標: パフォーマンス／ベンチマークですか？（ユーザー: 速度と精度）
   • ユースケース: 本番環境へのデプロイですか？（ユーザー: 複数の観点）
3. パラメーターを含む詳細なプロンプトに拡張します
4. 詳細な調査を保存して実行します
5. 比較ベンチマークとソースURLを含む包括的なレポートを返します

拡張なしの詳細なプロンプト

ユーザー: "2024～2025年における大規模言語モデルがソフトウェア開発者の生産性に与える影響を分析し、コード生成ツール、ペアプログラミング、生産性指標に焦点を当ててください。"

スクリプトの動作:

1. 具体的な範囲と焦点を含む詳細なプロンプト（24語）を検出します
2. 拡張に関する質問をスキップします
3. 詳細な調査を保存して、ただちに実行します
4. ユーザーの指定に沿った、焦点を絞った分析を返します

要件

• Python 3.7+
• OpenAI API キー: まず SOPS（~/.claude/skills/secrets.enc.yaml）から読み込み、次に OPENAI_API_KEY または .env ファイルを確認します
• インターネット接続（ウェブ検索用）
• 調査の完了には最大60分かかります（--timeout で設定可能です。それを超える場合は --resume を使用します）

トークン効率の高いワークフロー

長時間実行タスクの最適化

詳細な調査クエリの完了には通常 10～20分 かかります。このスキルは、長時間の待機中にトークン使用量を最小限に抑えるよう最適化されています:

仕組み:

1. 同期実行: スクリプトはブロッキングサブプロセスとして実行されます（バックグラウンドでのポーリングなし）
2. 途中確認なし: Claude はステータス更新なしで完了まで待機します
3. 出力は1回のみ: 結果は最後に一度だけ提示されます
4. 自動保存: Markdown ファイルは自動的に保存されるため、手動での操作は不要です

トークンの節約:

• 従来の方法: 30秒ごとにステータスを確認すると、約40回の確認 × 500トークン = 約20,000トークンが無駄になります
• この方法: 1回待機するだけで、合計約1,000トークンです

ファイルの自動管理

このスキルは、ファイルを自動的に生成して保存します:

生成されるファイル:

• research_prompt_YYYYMMDD_HHMMSS.txt - パラメーターを含む拡張済みの調査プロンプト
• research_request_YYYYMMDD_HHMMSS.json - 送信内容: モデル、ツール、推論、プロンプト（キーは含まれません）
• research_response_YYYYMMDD_HHMMSS.json - 正確な未加工の API 応答: レポート本文、文字範囲付きの url_citation アノテーション、参照したソースを含む web_search_call の手順。正規の記録です。こちらをインポートしてください。
• research_report_YYYYMMDD_HHMMSS.md - 次の内容を含む読みやすいレポート:
  • 本文中の引用リンク
  • ## Sources consulted (web search): 引用の有無を問わず、検索または閲覧したすべてのURL
  • メタデータのフッター（日付、モデル、応答ID、未加工の応答ファイル名）

カスタマイズのオプション:

# Custom output location
python3 deep_research.py --prompt-file prompt.txt --output-file my_research.md

# Disable automatic saving (terminal output only)
python3 deep_research.py --prompt-file prompt.txt --no-save

トラブルシューティング

OPENAI_API_KEY が見つからない

エラー: "Missing OPENAI_API_KEY"

解決方法:

• 環境変数を設定します: export OPENAI_API_KEY="your-key"
• または、作業ディレクトリに OPENAI_API_KEY=your-key を記述した .env ファイルを作成します

deep_research.py が見つからない

エラー: "Could not find deep_research.py"

解決方法:

• アセットを含めてスキルが正しくインストールされていることを確認します
• スクリプトは次の場所を検索します: スキルのアセットフォルダー → 現在のディレクトリ → 親ディレクトリ

調査のタイムアウト

エラー: "Still in_progress after …s. Resume later with: --resume "

解決方法:

• 後で取得します: --resume <id>（追加料金なし）。または --timeout 5400（90分）に設定します
• プロンプトを簡潔にして、調査範囲を縮小します
• API 応答が速くなる可能性があるため、利用の少ない時間帯に実行します