meta-methodology-research-methodology

調査方法

クイックガイド： 調査では、検索を繰り返さなくても次の行動に移れる調査結果を別のエージェントに渡します。ファイル名で場所を特定し、内容で絞り込んでから、答えが含まれるファイルを読みます。各主張には、その根拠となったファイル、行範囲、シンボルを明記します。何も見つからなかった検索も、その検索条件と併せて報告します。検索結果の意味を変えるツール上の事実が2つあります。検索結果が空でも、不在の証明にはなりません。Grep ツールは gitignore 対象のファイルをスキップし、Glob のリストには上限があり、長いファイルの Read は一部しか返さないことがあります。また、macOS、Linux、WSL では、Claude Code のデフォルトのツールセットに Glob と Grep のツールが含まれないため、同じ手順をシェルの find と grep で実行します。

詳細なリソース：

• examples/core.md — 検索の手順、証拠の形式、調査結果のテンプレート、パスと不在の確認、範囲の設定、進捗メモ、実例
• reference.md — 各検索ツールがスキップするものと、結果が途中で切り詰められる箇所、セッションで利用できるツール、報告前のチェックリスト

---

該当するパス

• 作業中の指示で報告形式が定められている場合 — その形式に従って記入します。このスキルでは、各項目に含める証拠と、証拠が満たすべき確認事項を示します。
• 報告形式が指定されていない場合 — examples/core.md の調査結果テンプレートを使用します。

---

<critical_requirements>

調査結果を報告する前に

パスや内容を調査結果に含める前に、ファイルを開いてください。 慣例から推測したパスは単なる推測です。それをもとに動くエージェントが、存在しないファイルを開くことになります。

各主張に、その根拠となったファイル、行範囲、シンボルを記載してください。 行範囲があれば一度読むだけで主張を確認でき、シンボルがあれば編集によって行が移動した後でも再び見つけられます。

何も見つからなかった検索は、その検索条件と併せて報告してください。 不在という結論の確かさは、検索パターン、パス、フィルターに左右されます。読者はそれらを再実行できますが、あなたの結論を再実行することはできません。

調査中は、コードを見つけたときの状態のままにしてください。 調査の途中で変更を加えると証拠が変わり、読者は主張がどの状態をもとに読み取られたのか分からなくなります。

</critical_requirements>

---

自動検出： X はどこで定義されているか、X はこのコードベースでどのように動作するか、類似する実装を探す、コンポーネント／エンドポイント／コマンドの一覧作成、パターンの発見、コードベースの調査、アーキテクチャの調査、API の一覧、ファイルと行の参照、使用回数、参照するファイル、調査結果、Glob、Grep

対象：

• パターンの所在と、どの程度一貫して適用されているかを見つける
• 存在するもの（コンポーネント、API とエンドポイント、コマンド、設定、アーキテクチャ上の決定事項）を一覧にする
• 新しいものを構築する前に、既存の最も近い実装を見つける
• 検索を繰り返さなくても別のエージェントが行動に移せる調査結果を作成する

ここでは扱わないもの：

• 調査結果が示す変更を実施すること — 調査は場所の特定までで、実装とそのテストは別のステップです
• コードの良し悪しを判断すること — 調査では、何が存在し、どの程度使われているかを報告します。品質やセキュリティの評価はレビューで行います
• 調査結果を仕様にまとめること — 範囲と受け入れ条件は計画で定めます

---

調査結果を読む人は、調査の過程を見ていません。主張が実際に読み取ったものか、推測したものかを判断できないため、引き継ぐ価値があるのは確認可能な主張だけです。つまり、場所、その箇所に記載されているコード、そしてそのコードを見つけた検索です。読者が自分で導き出さなければならない調査結果は、何の役にも立ちません。誤った調査結果は、読者がそれをもとに作業を進めてしまうため、何もないよりも大きな損失を招きます。

---

<decision_framework>

どの検索から始めるか

What do you already know?
├─ The symbol's name → its definition first (a language server's go-to-definition
│                      where one is running, else a search for the declaration),
│                      then its references
├─ Text the code contains → content search, scoped to the directory if known
├─ What the file would be called → name search, then read the likeliest match
└─ Nothing yet → list the top-level layout, then search by name

どこまで調べるか

問いが成果物を決め、成果物が調査の深さを決めます。

"How does X work?"          → X's flow: 2–3 exemplary files read end to end
"What exists for X?"        → a catalogue with counts; 1–2 files sampled
"Find similar to Y"         → the closest match, read completely
"How should I implement Z?" → the existing code to follow, in reading order
"Patterns for X?"           → several instances, and where they vary

いつ終了するか

Is the question that was asked answered?
├─ NO  → keep going, inside the question
└─ YES → Does every claim carry a location you read?
         ├─ YES → report
         └─ NO  → read the file now, or drop the claim

</decision_framework>

---

基本パターン

パターン 1：検索し、絞り込み、読み込む

名前で候補を探し、内容で絞り込んでから、回答につながるファイルを読み込みます。各ステップは次のステップよりコストが低いため、コストの高い読み込みは、重要だとすでに分かったファイルに対してのみ行います。

Glob  "src/**/*error*"                    → 6 candidate files
Grep  "extends AppError" in src/ (count)  → 4 matches in 4 files
Read  src/errors/app-error.ts             → class AppError, lines 8–31

セッションで Glob または Grep ツールを使えない場合は、シェルの find と grep で同じ 2 つのステップを実行できます。

詳細な手順：examples/core.md

パターン 2：根拠に基づく主張

1 つの主張につき、1 つの場所を示します。ファイル、行の範囲、シンボル、その箇所に記載されているコード、そして該当する箇所の数です。

AppError base class — src/errors/app-error.ts:8-31, class AppError
Usage: 4 subclasses (Grep "extends AppError" in src/, count mode → 4)

失敗するバージョンと並べた全体像：examples/core.md

パターン 3：構造化された調査結果

レポートの形式が指定されていない場合は、概要、見つかったパターン、順に読むファイル、参考にする既存ファイル、未解決の点、そして結果が空だった検索も含む検証表を記載します。

## Research Summary        ## Recommended Approach
## Patterns Found           ## Gaps
## Files to Reference       ## Verification Checklist

完全なテンプレート：examples/core.md

パターン 4：パスと不在を検証する

パスを調査結果に含めるのは、ファイルを開いた後に限ります。検索結果で見ただけのパスは、未読として「未解決の点」に記載します。不在を記載する際は、検索とともに示します。ただし、その前に、同じパスに同じフィルターを使って既知の内容を検索する対照検索を行い、検索でテキストを見つけられることを確認します。

Grep "jwt" -i in src/      → 0 matches
Grep "session" -i in src/  → 12 matches   (control: the search works here)
Finding: no JWT handling in src/ — gitignored files not searched

コード全体：examples/core.md

パターン 5：質問の範囲に絞る

質問で求められたことを報告します。範囲外の情報は、回答に関係する場合は「未解決の点」に 1 行で記載し、関係しない場合は省きます。

Asked:  How does the API authenticate requests?
Report: the session flow, the route guard, the files to read first
Leave:  database schema, deployment, the client's login form

コード全体：examples/core.md

パターン 6：長期調査の進捗メモ

複数のパッケージにまたがる調査では、調べたファイル、件数とともに見つかったパターン、未解決の点を進捗メモに記録しておきます。これにより、コンテキストの圧縮や引き継ぎの後も、記憶に頼らずメモをもとに調査を再開できます。

完全なテンプレート：examples/core.md

---

<red_flags>

注意すべき点

調査結果に基づいて行動するエージェントを誤解させます：

• 検索結果ではなく慣例から推測したパス（utils/formatDate.ts）を記載すると、読者は存在しないファイルを開いてしまいます。検索で返されたパスを記載してください。
• ファイル名や、そのフレームワークのコードベースで一般的に行われていることからパターンを推測すると、別のコードベースについて説明することになります。ファイルを読み、引用してください。
• 呼び出し箇所から API を説明すると、契約ではなく、ある呼び出し元の引数について説明することになります。宣言までたどってください。
• 「50行目あたり」「認証モジュール内」「既存の慣例に従う」では、読者はあなたの検索を繰り返すことになります。ファイル、範囲、シンボルを示してください。
• 一致した行の一覧から使用数を読み取ると、一覧はツールの結果上限で打ち切られるため、数が少なくなります。すべての一致を網羅する合計が得られる、カウントモードで数えてください。
• 裏付けとなるカウントがないまま「すべてのルートがこれを使っている」と断言すると、あなたを信頼した読者が、たった一つの例外のせいで変更に失敗します。カウントと検索方法を示してください。
• 場所を尋ねられた調査結果に実装コードや品質に関する判断を含めると、実装者が持っていない文脈のまま、誰も尋ねていない質問への回答を提示することになります。参考にすべき既存ファイルを示してください。
• 調査結果に読む順序がないと、読者はファイルを無作為に開きます。最初に開くべき2、3個を優先順位を付けて示してください。

意外な挙動：

• Grep ツールは gitignore 対象のファイルをスキップするため、「一致なし」は生成コード、ビルド出力、インストール済みの依存関係について何も示しません。Glob はデフォルトでは gitignore によるフィルタリングを行わないため、Grep が検索しないファイルも一覧に表示されます。
• Glob の結果は関連性ではなく更新日時で並べ替えられ、件数にも上限があります。打ち切りフラグがある場合、一覧は不完全です。
• 長いファイルの Read では、最初のページだけが返され、PARTIAL view と表示されることがあります。その読み取り後に「ファイルに X は含まれていない」と断言しても、未確認のままです。
• Grep のパターンは ripgrep の正規表現なので、interface{} は interface\{\} と記述する必要があります。古い Claude Code ビルドでは、ripgrep が拒否したパターンや、ツールが読み取れなかったパスが、エラーではなく一致なしとして返されることがありました。
• 行番号は、読み取った時点のファイルを示します。その後に編集が行われると（別のエージェントによる編集も含みます）、行番号がずれるため、範囲とともにシンボルも記載してください。
• テストには本番コードではすでに使われなくなったパターンが示されている場合があり、設定によってソースコードから推測される内容が上書きされることもあります。また、モノレポ内の各パッケージがそれぞれ独自の慣例に従っている場合もあります。調査結果がどれに基づくものかを明記してください。
• 広く使われているパターンでも、@deprecated とマークされている場合があります。コピーすべき慣例としてではなく、非推奨として報告してください。