research-deep

Deep Research — 項目ごとの詳細調査

/research-outline が生成したアウトラインを読み込み、バッチごとにバックグラウンドエージェントを 1 つ起動します。各エージェントは、フィールドスキーマに沿って項目の完全な JSON を作成します。

トリガー

/research-deep

パイプライン内の位置

/research-outline → /research-add-* → ► /research-deep ◄ → /research-report

ワークフロー

ステップ 1 — アウトラインを自動検出

現在の作業ディレクトリから */outline.yaml を Glob で検索します。Read で読み込み、items、execution.batch_size、execution.items_per_agent、execution.output_dir を取得します。

ステップ 2 — 再開時の確認

{output_dir}/*.json を Glob で検索し、すでに完了した項目を見つけます。完了済みの項目はスキップし、まだ JSON がない項目のみを実行対象にします。

ステップ 3 — バッチ実行

• 残りの項目を batch_size 件ずつのバッチにまとめます。
• 各バッチでは、Task ツールを使って、subagent_type: general-purpose（または、プロジェクトに登録されている調査用サブエージェント）と run_in_background: true を指定してエージェントを起動します。エージェントごとの出力は無効にします。エージェントは割り当てられた JSON パスに直接書き込むため、エージェントのやり取りを親コンテキストにストリーミングしてもトークンを消費するだけです。
• 各エージェントは最大 items_per_agent 件を担当します。
• 次のバッチを起動する前に、ユーザーの承認を待ちます（ユーザーが最初のバッチの出力を確認し、品質に問題があれば早期に停止できます）。

項目ごとに取得するパラメーター：

• {topic} — outline.yaml の topic フィールド
• {item_name} — 項目の name フィールド
• {item_related_info} — 項目の YAML 全体（name + category + description + …）
• {output_dir} — outline.yaml の execution.output_dir（デフォルトは ./results）
• {fields_path} — {topic_dir}/fields.yaml の絶対パス
• {output_path} — {output_dir}/{item_name_slug}.json の絶対パス

{item_name_slug} のスラッグ規則： 小文字に変換し、英数字以外の文字が連続する部分を _ に置き換え、先頭と末尾の _ を取り除きます。具体的には、re.sub(r"[^a-z0-9]+", "_", item_name.lower()).strip("_") です。例：GitHub Copilot → github_copilot、Cursor (Anysphere) → cursor_anysphere。

以下のプロンプトをテンプレートとしてそのまま使う理由： サブエージェントは隔離された環境で実行されます。そのプロンプトにはすべてのパラメーターが明示されており、わずかな文言の違いでも実行ごとに JSON の構造にずれが生じます。テンプレートは安定した契約として扱い、{xxx} 変数のみを置き換え、それ以外はそのままにしてください。

プロンプトテンプレート：

## Task
Research {item_related_info}, output structured JSON to {output_path}

## Field Definitions
Read {fields_path} to get all field definitions

## Output Requirements
1. Output JSON according to fields defined in fields.yaml
2. Mark uncertain field values with [uncertain]
3. Add uncertain array at the end of JSON, listing all uncertain field names
4. All field values must be in English

## Output Path
{output_path}

## Validation
After completing JSON output, run validation script to ensure complete field coverage:
python ~/.claude/skills/research-outline/validate_json.py -f {fields_path} -j {output_path}
Task is complete only after validation passes.

実行例（項目 = "GitHub Copilot"）：

## Task
Research name: GitHub Copilot
category: International Product
description: Developed by Microsoft/GitHub, first mainstream AI coding assistant, ~40% market share, output structured JSON to {project_dir}/results/github_copilot.json

## Field Definitions
Read {project_dir}/fields.yaml to get all field definitions

## Output Requirements
1. Output JSON according to fields defined in fields.yaml
2. Mark uncertain field values with [uncertain]
3. Add uncertain array at the end of JSON, listing all uncertain field names
4. All field values must be in English

## Output Path
{project_dir}/results/github_copilot.json

## Validation
After completing JSON output, run validation script to ensure complete field coverage:
python ~/.claude/skills/research-outline/validate_json.py -f {project_dir}/fields.yaml -j {project_dir}/results/github_copilot.json
Task is complete only after validation passes.

ステップ 4 — 待機と進捗確認

• 現在のバッチが完了するまで待ちます（各エージェントは JSON を出力して完了を通知します）。
• ユーザーの許可を得てから、次のバッチを起動します。
• 進捗を表示します（完了した項目数 N/total）。

ステップ 5 — サマリーレポート

すべてのバッチが完了したら、次を出力します。

• 完了した項目数
• 失敗とマークされた項目、または uncertain エントリがある項目の一覧
• {output_dir}/ へのパス

エージェント設定

• バックグラウンド実行：有効（run_in_background: true）
• タスク出力：無効 — 各エージェントの成果物は、エージェントが書き込む JSON ファイルです
• 再開サポート：有効（ステップ 2 で完了済みの項目をスキップ）

注意点

• バリデーターのパス ~/.claude/skills/research-outline/validate_json.py はインストール場所に依存します。 research-outline スキルが ~/.claude/skills/research-outline/ にインストールされていることを前提としています。この場所は claude-code-skills/scripts/link-skills.sh と install-skills.sh によって設定されます。スキルを別の場所（例：プロジェクトローカルの .claude/skills/）にコピーした場合、テンプレート化されたプロンプト内のバリデーターのパスが機能せず、サブエージェントは検証ステップで停止します。標準のインストールパスを維持するか、/research-deep を開始する前に、上記のテンプレート内のバリデーターのパスをインストール先の正しい絶対パスに置き換えてください。
• タスク出力を無効にしたバックグラウンドエージェントでは、問題が起きても早期に気づけません。 これは意図的なトレードオフであり、冗長さよりトークンの節約を優先しています。追加分を承認する前に、最初のバッチの JSON を抜き取り確認してください。
• 再開時の判定はファイル名の一致だけに依存します。 書き込み途中でクラッシュした JSON も、ステップ 2 では「完了」と見なされます。前回の実行が中断された場合は、再実行する前に破損した JSON を削除してください。
• {item_name_slug} の衝突は、通知なく上書きされます。 名前をスラグ化した結果が同じになる 2 つの項目（例：GPT-4 と GPT 4）は互いに上書きされます。衝突が疑われる場合は、項目の category フィールドに識別子を追加し、代わりに {category_slug}_{name_slug} としてスラグ化してください。
• バリデーターの必須フィールドチェックだけが、唯一の事後条件です。 fields.yaml で required: true に指定された項目がなければ、ほとんど空の JSON を返すエージェントも含め、バリデーターはどのような内容でも通過させます。意味のあるチェックを行うには、各カテゴリで少なくとも 1 つのフィールドを required に指定してください。