deep-read

Deep Read — コードベース読解エンジン

ソースコードを体系的に読み解く分析プロトコルです。インターフェースだけでなく、実装を読みます。すべての調査結果には file:line を記載します。

基本原則： ソースコードが真実の源です。ドキュメントには誤りがあり、コメントは古くなり、関数名は誤解を招くことがあります。実際のコードを読みましょう。コードグラフやインデックス（LSP、コードグラフツール）はコードの 特定 を速めますが、それ自体は古くなっている可能性のあるスナップショットです。決して真実の根拠にはなりません。コードグラフや LSP から得た該当箇所は、引用する前に必ず現行のソースコードで確認してください。

プロトコル

すべての /deep-read の実行を、以下の 6 つのフェーズに厳密な順序で通してください。フェーズを飛ばしてはいけません。各フェーズにゲートを設け、ゲート条件を満たすまで次に進まないでください。

---

フェーズ 1：SCOPE — 読解対象の定義

何かを読む前に、対象を扱いやすい範囲に絞り込みます。

1. $ARGUMENTS を読解対象（モジュール、フロー、質問、またはパス）として解析します
2. プロジェクトのコンテキストを把握するために CLAUDE.md と MEMORY.md を読みます。ただし、これらは ヒントであり、真実ではない と見なしてください
3. 初期調査を行い、対象範囲を見積もります：
   • 関連するファイルパターン（**/*.ts、**/*.py など）に対して Glob を実行します
   • 対象の説明に含まれるキーワードを Grep で検索します
   • 一致するファイルの数を数えます
4. 対象範囲がソースファイル 50 個を超える場合は、決定論的に 範囲を絞り込みます。このスキルはフォークして実行され、ユーザーに確認できないためです（Fork の注記を参照）：
   • 候補集合内のインポート被参照数で候補を順位付けし、同順位の場合は更新日時（git log -1 --format=%ct -- <file>）で順位を決めます
   • 上位 49 件を残し、残りを除外します（以下のフェーズ 1 のゲートは厳格で、50 未満でなければなりません）。恣意的にサンプリングしてはいけません。また、対象に合わせてゲートを緩和してはいけません
   • 上限（候補の総数、残した数、順位付けのキー）を対象範囲の定義に記録し、報告書でも明示的な網羅性の制限として改めて述べます
   • 残したファイル群に無関係なサブシステムが含まれる場合、対象は一貫性を保って読解するには広すぎます。恣意的な一部の範囲を全体であるかのように示すのではなく、その旨を報告書に記し、後続の /deep-read で扱うべき、より狭いサブ対象を挙げます
5. 対象が 質問（例：「手数料はどのように計算されますか？」）の場合：
   • 具体的な検索語に置き換えます
   • ドメイン用語を Grep で検索して、関連モジュールを特定します
6. 対象が パス（例：src/services/billing/）の場合：
   • パス内のすべてのファイルを一覧表示します
   • エントリーポイント（エクスポートされた関数、ルートハンドラー、メインファイル）を特定します

出力： 以下を含む対象範囲の定義：

• 対象の説明（1～2 文）
• ファイル一覧（ソースファイル 50 個未満）
• 範囲を絞り込んだ場合は、その上限（候補の総数 → 残した数、順位付けのキー）
• 特定したエントリーポイント
• 対象外の領域（明記）

ゲート： 対象範囲が定義され、ソースファイルが 50 個未満であること。エントリーポイントが特定されていること。次に進みます。

---

フェーズ 2：MAP — 構造の概要を把握する

コードを深く読み込む前に、コードの全体像を把握します。

1. ディレクトリ構成 — 関連するディレクトリを整理します：
   • Glob を使って、種類やディレクトリごとにファイルを一覧表示します
   • 機能別、レイヤー別、ドメイン別など、整理パターンを確認します
2. 技術スタック — ドキュメントではなく設定ファイルから特定します：
   • package.json、Cargo.toml、go.mod、requirements.txt などを読みます
   • フレームワーク、主要な依存関係、ビルドツールを記録します
3. エントリーポイント — ファイル名だけでなく、実際のファイルを読んで確認します：
   • ルート定義、メインファイル、エクスポートされたモジュールを読みます
   • エントリーポイント候補ごとに、最初の 50 行を読みます
   • 実際のエントリーポイントとヘルパーを見分けます
4. 依存関係グラフ — 対象範囲内の内部インポートを整理します：
   • 対象範囲内のファイルで、インポート／require 文を grep します
   • 何が何を呼び出し、何が何に依存するかを把握します
   • 他のファイルから最も多くインポートされているコアファイルを特定します
   • コードグラフのヒューリスティック（「ツールの使用方法」を参照）を満たす場合、インデックス化されたコードグラフへのクエリ（または LSP ワークスペースシンボル）を使うと、モジュール構造と中心性を一度に取得できます。言語ごとのツールにまたがってインポートを grep するよりも高速です。ただし、順位を信頼する前にソースコードと照合してください
5. 設定と定数 — 動作を定義するファイルを読みます：
   • 設定ファイル、環境スキーマ、定数、列挙型、型
   • これらもコードと同様に動作を左右します

対象ファイルが 20 個以上ある場合は、手順 2～4 をフォーク内で順番に実行します。各手順で、独立した Glob／Grep／Read 呼び出しを 1 つのメッセージにまとめて並列実行します（フォークに関する注記を参照）。

出力： 以下を含む構造マップ：

• 注釈付きのディレクトリ構成
• 技術スタック（ドキュメントではなく設定ファイルから）
• エントリーポイント（読み取って確認済み）
• 依存関係の流れ図（テキスト形式）
• 中心性の高い順に並べたコアファイル

ゲート： 実際のファイルを読んでエントリーポイントを確認します。依存関係の流れを整理します。次に進みます。

---

フェーズ 3：TRACE — 実行経路をたどる

エントリーポイントから開始し、コードをたどります。経路上のファイルはすべて読みます。

1. 読み取り対象に基づいて、主要な実行経路を選びます：
   • フロー（例：「決済処理」）の場合：ユーザー向けのエントリーポイントから開始します
   • モジュールの場合：公開 API／エクスポートから開始します
   • 質問の場合：答えが含まれている可能性が最も高いコードから開始します
2. エントリーポイントから先へたどります：
   • Read ツールを使って、エントリーポイントのファイルをすべて読みます
   • 見つかった関数呼び出し、クラスのインスタンス化、モジュールインポートごとに：
     • 実装箇所を特定します。正確に 1 ホップだけ移動するには LSP の goToDefinition／outgoingCalls を使い、見つからない場合は Grep を使います。1 ホップの言語ごとの LSP では追跡できない、リポジトリ全体にまたがる推移的な経路や言語横断の経路には、コードグラフを照会します。ただし、ツールの使用方法にある 2 つのゲートのヒューリスティックを満たす場合に限ります（言語をまたぐ場合でも、対象シンボルを 1 つに絞ったトレースには LSP／Grep を使います）
     • Grep を使って、実装箇所を探します（型シグネチャだけでは不十分です）
     • 実装ファイルをすべて読みます。グラフ／LSP のエッジで分かるのはファイルまでです。ゲートを通過するには、そのファイルを読む必要があります
   • DB クエリ、API 呼び出し、ファイル I/O、戻り値などの終端処理に到達するまで続けます
3. 経路を file:line 形式の引用付きで連鎖として記録します：

   Request enters at routes/payments.ts:42 (POST /api/payments)
     -> calls PaymentService.processPayment() at services/payment.ts:87
       -> validates input via PaymentSchema at schemas/payment.ts:15
       -> calls StripeClient.charge() at clients/stripe.ts:34
         -> constructs request at clients/stripe.ts:45-62
       -> stores result via PaymentRepository.save() at repos/payment.ts:28
     -> returns PaymentResponse at routes/payments.ts:58
   

4. 読み取り対象が複数のフローに関わる場合は、追加の経路もたどります：
   • エラー経路、エッジケース、フォールバックロジック
   • 主要な経路によって起動されるイベントハンドラー、Webhook、バックグラウンドジョブ
5. 分岐点をすべて記録します。条件、switch、機能フラグなどが対象です：
   • どのような条件で経路が分かれますか？
   • 「条件分岐がある」と記録するだけでなく、条件のロジックを読みます

出力： 各手順に file:line 形式の引用を付けた、完全な実行トレース（複数可）。

ゲート： エントリーから終端まで、少なくとも 1 つの完全な経路を追跡します。経路上のファイルはすべて Read で読み取ります。次に進みます。

---

フェーズ 4：徹底的に読む — 重要ファイルを行ごとに分析する

ここが中心となるフェーズです。重要ファイルを徹底的に読み、ビジネスロジックのすべての行を理解します。

1. フェーズ 3 から重要ファイルを特定する — 次の内容を含むファイルです。
   • ビジネスロジック（計算、ルール、変換）
   • 状態管理（変更、トランザクション、副作用）
   • セキュリティロジック（認証、検証、アクセス制御）
   • データ変換（マッピング、フィルタリング、集計）
   • エラー処理（catch ブロック、エラーバウンダリ、復旧ロジック）
2. Read ツールを使って、重要ファイルをそれぞれ最後まで読む：
   • ざっと目を通すだけにしないでください。ファイル全体を読んでください
   • 500 行を超えるファイルはセクションごとに読んでください。ただし、すべてのセクションを読んでください
   • 独立したファイルについては、Read の呼び出しを並行して開始してください
3. 重要ファイルごとに、次の内容を記録する：
   • 目的： コメントではなく、コードに基づいて、このファイルが実際に何をするのか
   • 主要な関数： 各関数のロジックと、その根拠となる箇所：

     calculateCommission(sale: Sale): number  [billing/commission.ts:45-78]
       - 基本料率：sale.amount の 5%（52 行目）
       - ボーナスの段階：sale.amount > 10000 の場合、料率に 2% を加算（56 行目）
       - 上限：コミッションは 5000 を上限とする（62 行目）
       - 日割り計算：daysInPeriod/30 を乗算（67 行目）
       - 戻り値：小数点以下 2 桁に丸める（74 行目）
     

   • 数式と条件： 要約ではなく、実際の計算式とロジックを書く
   • 状態の変更： 何が変更され、どのような副作用が発生するか
   • 処理されるエッジケース： null チェック、境界値、エラー復旧
   • 処理されないエッジケース： 検証の不足、未検証の前提
4. ファイル間を相互参照する：
   • ファイル A がファイル B を呼び出す場合、A の想定が B の実装と一致することを確認する
   • インターフェース契約と実装の間に不一致があれば記録する
   • 呼び出し元のエラー処理が、呼び出し先がスローするエラーに対応しているか確認する

出力： 各重要ファイルの詳細な分析。次の内容を含めます。

• file:line の引用を含む、関数単位のロジックの文書化
• 明示的に記述した数式
• 文書化した条件と分岐ロジック
• 状態の変更と副作用の一覧

ゲート： 特定したすべての重要ファイル（ステップ 1）が最後まで Read されています。ロジックが数式、条件、引用とともに文書化されています。次に進んでください。

---

フェーズ 5：CONNECT — 理解を統合する

システム全体を俯瞰して推論します。構造化された分析には、sequential-thinking MCP を使用します。

1. フェーズ 1～4 のすべての証拠を使って、sequential-thinking の思考チェーンを開始します：

   mcp__sequential-thinking__sequentialthinking({
     thought: "Synthesizing understanding of <target>. Evidence from phases: ...",
     thoughtNumber: 1,
     totalThoughts: 8,
     nextThoughtNeeded: true
   })
   

2. コードベース全体のパターンを特定します（最低 3 つ）：
   • アーキテクチャパターン（レイヤー化、依存性注入、イベント駆動など）
   • コーディング規約（エラー処理のスタイル、命名パターン、データフローパターン）
   • 暗黙のルール（コードでは強制されず、慣習によって維持されている不変条件）
   • アンチパターンまたは技術的負債
   • 集約的な構造上の手掛かり — デッドコード、インターフェースのすべての実装、依存関係の循環、ファンイン／ファンアウトのホットスポット — インデックス化されたコードグラフがあればそこから抽出し、統合の材料にします。ただし、ライブソースで確認し、file:line の引用を示すまでは、調査結果として扱わないでください。
3. エンドツーエンドでデータフローをマッピングします：
   • データはどのようにシステムに入りますか？
   • どのような変換を受けますか？（file:line の引用を付けてください）
   • 最終的にどこに到達しますか？（DB、API レスポンス、ファイル、イベント）
4. リスクと前提条件を特定します：
   • コードが前提としているものの、検証されていないことは何ですか？
   • それらの前提条件が満たされなかった場合、何が壊れますか？
   • 競合状態、一貫性の欠如、セキュリティ上の懸念はありますか？
5. 読み取り対象が質問である場合は、元の質問に回答します：
   • 根拠の完全な連鎖を示して回答します
   • すべての出典を引用します

曖昧なコードについて別の解釈を検討するには、sequential-thinking の分岐を使用します。

出力： 以下を含む統合結果：

• 証拠（file:line）を示した 3 つ以上のパターン
• エンドツーエンドのデータフローマップ
• リスク評価
• 元の質問への回答（該当する場合）

ゲート： 推論ステップを少なくとも 5 つ完了していること。file:line の証拠を伴うパターンを少なくとも 3 つ特定していること。次に進みます。

---

フェーズ 6：REPORT — 構造化された成果物

最終レポートを作成します。すべての主張に file:line の引用を付けてください。

## Deep Read Report: <target>

### Scope
- **Target:** <what was analyzed>
- **Files analyzed:** <count> files, <count> read in full
- **Coverage limit:** <none, or: top <N> of <total> candidates by <ranking key>; remainder out of scope>
- **Entry points:** <list with file:line>

### Architecture Overview
<structural summary from Phase 2 — directory layout, tech stack, dependency flow>

### Execution Flow
<traced paths from Phase 3 — entry to terminal with file:line citations>

### Critical Logic
<detailed function-level analysis from Phase 4>

For each critical area:
- **What it does:** <plain language description>
- **How it works:** <formulas, conditions, logic with file:line>
- **State changes:** <what gets mutated>
- **Edge cases:** <handled and unhandled>

### Patterns & Conventions
<synthesized patterns from Phase 5>
1. <pattern> — evidence: <file:line>
2. <pattern> — evidence: <file:line>
3. <pattern> — evidence: <file:line>

### Data Flow
<end-to-end data flow map from Phase 5>

### Risks & Assumptions
<risk assessment from Phase 5>

### Key Findings
<concise bullet list of the most important discoveries>
- <finding> — <file:line>

### Answer
<if the reading target was a question, answer it here with full evidence>

ゲート： すべてのセクションに内容が記載されていること。すべての調査結果に file:line の引用があること。レポートが完成していること。

---

フェーズごとのツール使用

フェーズ	主なツール	並列処理とエスカレーション（フォーク内）
1. SCOPE	Read、Glob、Grep、Bash（新しさの順位付けに使用する git log）	--
2. MAP	Glob、Grep、Read（設定、エントリーポイント）、LSP／コードグラフ（構造、中心性）	ステップ 2～4 の検索を 1 つのメッセージにまとめて実行（20 ファイル以上）
3. TRACE	Read（ファイル全体）、Grep（相互参照）、LSP の呼び出し階層、コードグラフ（リポジトリ全体の推移的関係／集約 — ヒューリスティックを参照）	独立した Grep／LSP 検索をまとめて実行
4. DEEP READ	Read（ファイル全体、並列）	--
5. CONNECT	sequential-thinking MCP、コードグラフ（集約／デッドコードのクエリ）	複雑な推論には deep-analysis スキル
6. REPORT	構造化された出力	--

フォークに関する注意： /deep-read はコンテキストを分離するため、フォーク（context: fork）で実行されます。ファイル全体の読み取りとトレースはメインの会話に持ち込まれず、レポートだけが返されます。フォークされたサブエージェントは Agent ランチャーや AskUserQuestion を使用できないため、このプロトコルはどちらも不要なように設計されています。各フェーズでは Primary Tools（Read／Glob／Grep／Bash／LSP／sequential-thinking）を使用し、フェーズ 1 では質問する代わりに決定論的に範囲を絞り込みます。また、全体を通じて「並列」とは、独立したツール呼び出しを 1 つのメッセージにまとめることを意味し、エージェントを起動することはありません。ユーザーの選択が本当に必要な場合は、実行中に質問するのではなく、未解決の質問としてレポートに記載します。

コードグラフによる高速化（任意、ツール非依存）。 リポジトリごとにインデックス化されたコードグラフの初期設定に価値があるのは、次の両方の条件を満たす場合に限られます。（1）リポジトリの規模が大きい（数百ファイル以上）か、複数の言語にまたがっている。（2）質問がリポジトリ全体にわたる推移的な関係や集約に関するもの（影響範囲全体、広範なリファクタリング、デッドコード、「X のすべての実装者」、アーキテクチャの概要）である。どちらか一方の条件だけでは不十分です。対象を絞ったトレースは、言語をまたいでいても、単一言語の小規模なリポジトリに関する集約的な質問であっても、LSP／Grep／Read を使用します。それ以外の場合は、LSP（常に利用可能で、1 ホップの関係を調べられ、古くなることがない）＋Grep＋Read のほうが高速です。既存のインデックスがあれば直接クエリします。インデックスがなく、両方の条件を満たす場合は、密かに初期設定するのではなく、レポートで構築を推奨します。どのコードグラフツールでも使用できます。たとえば CodeGraphContext／cgc はオプトイン方式で、リポジトリごとに使用するものであり、このフレームワークには同梱も登録もされていません（インストール方法はツール自身のドキュメントを参照してください）。

アンチパターン — このスキルで防ぐこと

悪い習慣	/deep-read での代替方法
README／CLAUDE.md を読んで終わりにする	フェーズ 1 ではドキュメントを手掛かりとして扱い、フェーズ 3～4 でソースを読みます
ファイルのヘッダーとインポートだけをざっと見る	フェーズ 4 では引用を添えながら行単位で読むことが必須です
根拠なしに要約する	すべての主張に file:line の引用を付けます
最初の抽象化レイヤーで止める	フェーズ 3 では呼び出しチェーンをリーフ関数まで完全にトレースします
関数名から動作を推測する	フェーズ 4 では実装を読み、実際のロジックを記述します
曖昧な「これは X を行うようです」という記述をする	フェーズ 4 では具体的な数式と条件を示すことが必須です
実装ではなく型やインターフェースを読む	フェーズ 3 ではシグネチャだけでなく、実装を Grep で検索します
グラフ／インデックスのクエリを真実として信頼する	グラフや LSP は古くなることのあるスナップショットです。引用（file:line）する前に、すべてのヒットを実際のソースで確認します
エラー経路やエッジケースを読み飛ばす	フェーズ 3 では二次的な経路をトレースし、フェーズ 4 ではエッジケースを記述します

範囲の例

/deep-read payment processing flow from checkout to settlement
/deep-read src/services/billing/
/deep-read how are sales commissions calculated and distributed?
/deep-read the authentication and authorization system
/deep-read data pipeline from ingestion to reporting dashboard
/deep-read how does the caching layer work and when does it invalidate?

/deep-read とほかのツールを使い分ける場面

状況	使用するもの
既存のコードの動作を理解する	/deep-read
「この関数は何をするのか」を手早く確認する	Read ツールを直接使用
バグ、クラッシュ、エラー、予期しない動作	/investigate
アーキテクチャの決定やトレードオフ	/deep-analysis
決定する前に選択肢を検討する（「どのような選択肢があるか」）	/diverge
新しい機能を構築する	/execute
コードを理解してから、その内容について考察する	/deep-read の後に /deep-analysis
コードを理解してから、再設計する	/deep-read の後に /deep-analysis、さらに /execute
不慣れなコードベースに慣れる	/deep-read
十分なコンテキストを踏まえたコードレビュー	/deep-read の後に code-quality エージェント

参考資料

コードベースの種類に応じた読み進め方とコンテキスト管理の方法については、references/reading-strategies.md を参照してください。