深層リサーチ

リサーチドキュメント

階層的リサーチを通じて教育用ドキュメントを作成する体系的なアプローチ。

目的

以下のような詳細な説明ドキュメントを作成します:

• 基礎から詳細へと理解を構築する
• 段階的な開示（プログレッシブディスクロージャー）で読者を導く
• すべての情報に完全な引用を付与する
• 情報が密集している部分には視覚的な要約や表を使用する

使用すべきケース

• ユーザーがシステムや機能の包括的な説明を求めた場合
• コンポーネントがどのようにエンドツーエンドで動作するかを文書化する必要がある場合
• アーキテクチャやプロセスに関する教育用コンテンツを作成する場合
• 「Xがどのように動作するか説明して」や「Yプロセスとは何ですか？」といった質問

素早い事実確認が必要な場合は、代わりにfact-findを使用してください。

リサーチモデル: スカウト → 分解 → リサーチ → 組み立て → 検証

リサーチは階層的に行われ、一度にすべてを行うわけではありません。すべての成果物はファイルシステムに保存されます。

┌─────────────────────────────────────────────────────────────────┐
│                      階層型リサーチモデル                        │
└─────────────────────────────────────────────────────────────────┘

     レベル0: スカウト                    レベル1: フォーカスドリサーチ
     ─────────────────                   ────────────────────────
     
     ┌─────────────┐                    ┌─────────────┐
     │   初期の    │                    │ サブクエス │──▶ 引用付き回答
     │   質問      │                    │ チョン     │    (短い)
     └──────┬──────┘                    │ (fact-find)│
            │                           └─────────────┘
            ▼                           ┌─────────────┐
     ┌─────────────┐    分解            │ サブクエス │──▶ 引用付き回答
     │   スカウト  │──────────────────▶ │ チョン     │    (短い)
     │   検索      │                    │ (fact-find)│
     └──────┬──────┘                    └─────────────┘
            │                           ┌─────────────┐
            ▼                           │ サブクエス │──▶ 再帰
     ┌─────────────┐                    │ チョン     │    (独自のスカウト/分解)
     │ 書き出し先: │                    │ (research) │
     │ planning/   │                    └─────────────┘
     │ <スラッグ>/ │                          │
     │ 00-scout.md │                          ▼
     └─────────────┘                    ┌─────────────┐
                                         │  組み立て   │──▶ ドラフト文書
                                         │  ファイル  │
                                         │  から      │
                                         └──────┬──────┘
                                                │
                                                ▼
                                         ┌─────────────┐
                                         │   検証     │──▶ 最終ドキュメント
                                         │   引用     │
                                         └─────────────┘

なぜこれが効果的なのか:

• エージェントはタスクの途中で不確実性を認めるのが苦手です。先にスカウトを行うことで、アウトプットを生成するプレッシャーがかかる前にギャップを特定できます。
• ファイルシステムに書き込むことで、エージェント間の協調（またはシングルエージェントシステムでのコンテキストウィンドウのリセット）が可能になります。
• サブクエスチョンを分類することで、「大きすぎる」質問が浅い扱いになるのを防ぎます。
• 検証により、最終確定前に幻覚や裏付けのない主張をキャッチします。

ワークスペースのセットアップ

すべてのリサーチ成果物は ./planning/<質問のスラッグ>/ に保存されます:

./planning/
└── how-twoliter-builds-kits/
    ├── 00-scout.md           # スカウトの結果 + サブクエスチョン
    ├── 01-kit-structure.md   # サブクエスチョンの回答 (fact-find)
    ├── 02-build-command.md   # サブクエスチョンの回答 (fact-find)
    ├── 03-buildsys/          # 再帰が必要だったサブクエスチョン
    │   ├── 00-scout.md
    │   ├── 01-spec-parsing.md
    │   └── 02-docker-build.md
    └── FINAL.md              # 組み立てられたドキュメント

スラッグの形式: 小文字、ハイフン、説明的 (例: how-twoliter-builds-kits)

マルチエージェントシステム向け

• リードエージェント: スカウトを起動し、スカウトの出力を読み、分解し、組み立て、検証を調整する
• スカウトサブエージェント: フェーズ1を実行（検索、結果をスキミング、00-scout.mdを書き出す）
• リサーチサブエージェント: 各サブクエスチョンがタスクになり、サブエージェントが回答をワークスペースに書き込む
• 検証エージェント: 引用をチェックする軽量エージェント（ツールは不要）
• サブエージェントは、質問が大きすぎる場合に再帰的に起動できます（深さ制限あり）

なぜスカウトを委任するのか: リードエージェントのコンテキストは貴重です。スカウトからの生の検索結果やファイル内容はそれを汚染します。スカウトは構造化された結果を 00-scout.md に書き込みます。リードエージェントはそのファイルのみを読みます。

計画/タスクリストの規律

タスクリスト機能がある場合は、それを使ってワークフローの完了を強制してください:

各フェーズの前に、作業を計画に列挙してください:

• フェーズ2: スカウトからのサブクエスチョンごとに1項目、ターゲットファイル名を添えて
  • 01-kit-structure.md を書く (サブクエスチョン1)
  • 02-build-command.md を書く (サブクエスチョン2)
  • ...
• フェーズ4: 検証する引用ごとに1項目

パターン: 列挙 → 実行 → カウントが一致することを確認

これにより、「すべてを行う」代わりに「一部を行う」ことを防ぎます。計画は契約です。「01-kit-structure.mdを書く」と書いたら、そのファイルを作成する義務があります。

⛔ アンチパターン: スカウト中に回答を集め、FINAL.mdにスキップすること。たとえ答えを「知っている」としても、個別のファイルを書きなさい。それらは検索可能な成果物です。

シングルエージェントシステム向け

階層を順次実行し、ファイルシステムを「メモリ」として使用します:

1. スカウトし、00-scout.mdを書く
2. 各サブクエスチョンをリサーチし、01-*.md、02-*.mdなどを書く
3. すべてのファイルを読み戻し、FINAL.mdを組み立てる
4. 自己チェック引用（信頼性は低いが、それでも価値はある）

これにより、必要に応じてフェーズ間でコンテキストウィンドウをリセットできます。

手順

フェーズ1: スカウト (形状を把握する)

目標: 何が存在するかを発見し、適切な質問を定式化する。結果を 00-scout.md に書き込む。

⚠️ スカウトはリサーチではありません。 あなたは地形をマッピングしているのであって、探検しているのではありません。

mkdir -p ./planning/<質問のスラッグ>

# 関連する領域を見つけるための広範な検索
crumbly search "システム名 概要"
crumbly search "システム名 アーキテクチャ"

上位2〜3の結果を構造についてのみスキミングする（内容は見ない）:

• ファイル名とセクション見出しに注意する
• キーワードとコンポーネント名を特定する
• 詳細情報がどこにあるかを見つける
• 実装の詳細を読んだり、「どのように動作するか」を理解しようとしない

スカウトの出力に含めるべきもの:

• 物の名前（ファイル、関数、概念）
• 答えを探す場所
• 尋ねるべき質問

スカウトの出力に含めるべきでないもの:

• 質問への回答
• 実装の詳細
• コードスニペットや深い説明

スカウトを終えて「答えがわかった」と感じたら、スカウトが深すぎます。目標は「情報に基づいた無知」—自分が何を知らないか、そしてどこでそれを見つけるかを知ることです。

00-scout.md に以下を記録します:

# スカウト: <元の質問>

## 発見された主要な概念
- [概念1]: [簡単な説明]
- [概念2]: [簡単な説明]

## 見つかった関連ファイル
- `path/to/file.md` - [カバーしている内容]
- `path/to/code.rs` - [カバーしている内容]

## 用語
- [用語]: [このコードベースでの定義]

## サブクエスチョン

### 1. [サブクエスチョンのテキスト]
- **タイプ:** fact-find | deep-research
- **理由:** [この分類の理由]
- **主要ファイル:** [この質問に答える可能性が高いファイル]

### 2. [サブクエスチョンのテキスト]
...

サブクエスチョンの分類:

サブクエスチョンが...	タイプ	アクション
具体的で明確な答えがある	fact-find	1〜2段落で回答
「Xとは何か」や「Yはどこか」を尋ねる	fact-find	1〜2段落で回答
「Xはどのように動作するか」を尋ねる	deep-research	再帰（独自のスカウト/分解）
複数のコンポーネントの相互作用を含む	deep-research	再帰
答えるのに3つ以上のソースファイルが必要	deep-research	再帰

再帰チェック: 2つ以上のサブクエスチョンが deep-research タイプの場合、元の質問が広すぎるかどうかを検討してください。

深さ制限: 最大再帰深さは2レベルです。サブサブクエスチョンがそれ自体の再帰を必要とする場合、次のいずれかを行います:

• fact-find として処理することを強制する（より浅い深さを受け入れる）
• 人間のレビュー用にフラグを立てる
• 元の質問を複数のリサーチタスクに分割する

フェーズ2: サブクエスチョンのリサーチ

各サブクエスチョンについて、NN-<スラッグ>.md に書き込みます:

fact-find サブクエスチョンの場合:

# <サブクエスチョン>

<インライン引用付きの直接的な回答>

キットディレクトリには `Twoliter.toml` ファイル <sup>[1]</sup> と、パッケージを依存関係としてリストする `Cargo.toml` が含まれている必要があります <sup>[2]</sup>。

## ソース

<sup>[1]</sup> [`twoliter/README.md`](../twoliter/README.md) - キット要件セクション
<sup>[2]</sup> [`kits/bottlerocket-core-kit/Cargo.toml`](../kits/bottlerocket-core-kit/Cargo.toml) - キットマニフェストの例

deep-research サブクエスチョンの場合:

サブディレクトリを作成し、再帰します:

./planning/how-twoliter-builds-kits/03-buildsys/
├── 00-scout.md
├── 01-....md
└── FINAL.md

サブクエスチョンの FINAL.md が回答になります。

ソースから答えられない場合:

• 「利用可能なソースからは判断できませんでした」と書く
• 何を検索したかをメモする
• 推測しない

フェーズ2 完了ゲート (必須)

⚠️ 停止: このゲートを通過するまでフェーズ3に進まないでください。

FINAL.mdを組み立てる前に、以下を必ず実行してください:

1. ワークスペースファイルを一覧表示:

   ls -la ./planning/<質問のスラッグ>/
   

2. ファイル数がサブクエスチョン数と一致することを確認:

   • 00-scout.md 内のサブクエスチョンの数: N
   • NN-*.md ファイルの数（00-scout.mdを除く）: Nであるべき
   • 数が一致しない場合、サブクエスチョンをスキップしています。戻ってください。

3. 計画/タスクリストに追加:

   • N個のサブクエスチョンファイルが書き込まれたことを確認
   • ファイル一覧: 01-X.md ✓, 02-Y.md ✓, ...

なぜこれが重要なのか: サブクエスチョンファイルが主要な成果物です。FINAL.mdは単なる統合です。個別のQ&Aファイルがなければ:

• 将来のクエリでリサーチが検索可能にならない
• 各回答を個別に検証できない
• ドキュメント作成者がソースマテリアルとして使用できない

一般的な失敗モード: スカウト中にすべての情報を収集し、「もう答えを知っている」という理由でFINAL.mdに直接ジャンプすること。これは目的を無効にします—とにかくファイルを書きなさい。

フェーズ3: ドラフトドキュメントの組み立て

ワークスペースからすべてのサブクエスチョンの回答を読みます。それらを FINAL.md に統合します:

# [システム名]

**キーワード:** キーワード1, キーワード2, キーワード3

## 概要

[視覚的な要約 - システム全体を示す図表や表]

[コンテキストの1〜2文]

## [基礎となるモデル]の仕組み

[基礎に関するサブクエスチョンの回答から統合]

## [メイントピック]

[コアプロセスに関するサブクエスチョンの回答から統合]

### [サブトピック]

**目標:** [一文]

[サブクエスチョンから引き継がれた引用付きのコンテンツ]

## 付録: [詳細なリファレンス]

[密集した詳細、表、設定オプション]

## 矛盾と解決

[ソース間で矛盾があった場合、どのように解決したかを文書化]
- [トピック]: ソースAはX、ソースBはY。解決: [理由]

(矛盾が見つからなかった場合は「なし」と書く)

## ソース

[すべてのサブクエスチョンから統合された番号付き引用]

作成ガイドライン

概要セクション:

• ビジュアル（ASCII図、フローチャート、または要約表）から始める
• ビジュアルの後の散文は最大2〜3文
• 読者は10秒でシステム全体を把握できるべき

表 vs 散文:

• 3つ以上の類似アイテムをリストする場合 → 表を使用する
• 散文は関係性を説明し、表は事実をリストする

引用:

• 事実と共にインラインで <sup>[1]</sup> を使用する
• すべての事実の主張に引用が必要
• 最後にソースを統合する
• 組み立て時に、引用番号を連番で振り直す

長いドキュメント（出力トークン制限）:

Claudeには出力制限があります（レスポンスあたり約4K〜8Kトークン）。約10ページを超えるドキュメントの場合:

• セクションごとに書き、FINAL.mdに追加していく
• または、最初に詳細なアウトラインを生成し、各セクションを個別に展開する
• ドキュメント全体を1回のレスポンスで生成しようとしない

フェーズ4: 検証

目標: 引用が主張を裏付けていることを確認する。裏付けのないステートメントをキャッチする。

ステップ1: 引用の列挙 (必須)

検証エージェントを起動する前に、計画/タスクリストにすべての引用を必ず列挙してください:

1. FINAL.md内の引用の数を数える（例: 12の引用）
2. 引用ごとに1つの計画項目を追加:
   • [1]を検証: 「主張テキストのプレビュー...」
   • [2]を検証: 「主張テキストのプレビュー...」
   • ... (全部で12)
3. 最後の項目を追加: 「12/12の検証エージェントが完了したことを確認」

計画にN+1項目（N個の引用 + 確認）が追加されるまで、起動に進まないでください。

これにより、「代表的な引用をいくつか検証する」だけでなく、すべてを検証するという失敗モードを防ぎます。

ステップ2: 検証エージェントの起動

マルチエージェントシステム向け:

事前にコンテキストがロードされた軽量な検証エージェントを起動します。各検証エージェントはツールを必要としません—推論だけです。

引用検証エージェント（引用ごとに1つ起動）:

プロンプト:
  あなたは懐疑的なレビュアーです。あなたの仕事は、正しさを確認するのではなく、問題を見つけることです。
  
  主張: 「ビルドプロセスはTwoliter.tomlをロードすることから始まる」
  引用元: twoliter/twoliter/src/project/mod.rs
  ソースコンテンツ:
  [ファイルから関連する行を貼り付ける]

  ソースコンテンツは、この特定の主張を**実際に**裏付けていますか？
  
  次のいずれかで返信:
  - SUPPORTED: [ソース内の何がこれを確認しているかの簡単な説明]
  - UNSUPPORTED: [何が欠けているか、間違っているか]
  - PARTIAL: [確認されていることと確認されていないこと]
  
  懐疑的になってください。ソースが関連しているが、主張を直接述べていない場合は、PARTIALまたはUNSUPPORTEDです。

引用なし主張検出器（ドキュメントセクションごとに1回起動）:

プロンプト:
  あなたは懐疑的なレビュアーです。あなたの仕事は、問題を見つけることです。
  
  セクション:
  [セクションテキストを貼り付ける]

  <sup>[N]</sup> 引用が欠けている事実の主張を見つけてください。
  事実の主張には以下が含まれます: ファイルパス、動作の説明、
  設定値、コンポーネント名、プロセスのステップ。
  
  意見、トランジション、要約には引用は必要ありません。
  
  見つけた引用なしの主張をそれぞれリストしてください。「問題なし」や「見つからなかった」とは言わないでください。
  すべての文をチェックしていない限り。何も見つからなかった場合は、引用なしの主張がないことを確認するために何をチェックしたかを説明してください。

これらをバッチ処理: spawn_batchを使用して、すべての引用検証エージェントを並行して実行します。バッチサイズは、引用数と等しくなければなりません。

シングルエージェントシステム向け:

セルフチェック（信頼性は低いですが、それでも行う価値があります）:

• FINAL.mdを読み直し、各 <sup>[N] を見つけて、対応するソースエントリを確認する
• 引用なしの主張を探す
• 各サブクエスチョンファイルを参照して、それらの回答が正しく統合されていることを確認する

### フェーズ4 完了ゲート (必須)

**⚠️ 停止: このゲートを通過するまでプロセスを完了と見なさないでください。**

検証を完了するには:

1. **すべての引用検証結果を確認:**
   - すべてSUPPORTED? → 完了
   - UNSUPPORTEDまたはPARTIALがある? → 修正する必要がある

2. **引用なし主張検出器の結果を確認:**
   - 見つからなかった? → 完了
   - 見つかった? → 引用を追加する必要がある、または削除する必要がある

3. **計画に最終項目を追加:**
   - [ ] すべての引用が検証され、サポートされている

4. **同じ理由で拒否された引用または修正不可能な引用がある場合、報告する:**
   - 引用`[3]`: ファイル`foo.rs`は行123〜125でXを説明していますが、主張はYです。ソースを更新する必要があります。

## playgroundディレクトリのクリーンアップ

完了したら、将来の実行のためにプレイグラウンドディレクトリをクリーンアップします:

```bash
rm -rf ./planning/<質問のスラッグ>

削除する前に、すべての関連するナレッジベースが更新されていることを確認してください。

ワークフロー図 (まとめ)

┌──────────┐   ┌────────────┐   ┌──────────────┐   ┌──────────────┐
│ フェーズ1 │   │  フェーズ2  │   │   フェーズ3   │   │   フェーズ4   │
│          │   │            │   │              │   │              │
│ スカウト  │──▶│ サブクエス │──▶│ ドラフトを    │──▶│ 引用を検証   │
│          │   │ チョンを   │   │ 組み立てる    │   │              │
│ 00-scout │   │ リサーチ   │   │              │   │ 各引用を     │
│ .md      │   │            │   │ FINAL.md     │   │ チェック     │
└──────────┘   │ NN-*.md    │   └──────────────┘   └──────────────┘
               └────────────┘                           │
                                                         ▼
                                                  ┌──────────────┐
                                                  │  最終出力     │
                                                  │              │
                                                  │ FINAL.md     │
                                                  │ (検証済み)   │
                                                  └──────────────┘

これは、単に「調査して書く」よりも優先されます。 このワークフローは:

1. 適切な範囲を強制する（スカウトが質問を適切なサイズに保つ）
2. 検索可能性を確保する（個別のサブクエスチョンファイル）
3. 検証を強制する（各引用がチェックされる）
4. 将来のリサーチのためにナレッジベースを作成する（成果物は永久に残る）