大規模コードベースのコンテキスト管理

大規模コードベース探索におけるコンテキスト管理は、Claude Certified Architect — Foundations（CCA-F）試験のドメイン 5.4 を構成する中核トピックである。タスクステートメント 5.4「大規模コードベース探索においてコンテキストを効果的に管理する」は、15 ％の配点を持つ「コンテキスト管理と信頼性」ドメインの 6 タスクの一つだが、その設計上の影響範囲は「Claude Code を使ったコード生成」「Claude による開発者生産性」「継続的インテグレーションのための Claude Code」という 3 つの採点シナリオにまたがる。数万ファイル・数百万行・数百モジュールからなる実世界のリポジトリに触れるあらゆる Claude Code のデプロイは、最初の自律タスクの中で、エージェントがリポジトリのどの断片を読むか・どの順番で・どの粒度で・どれをディスクに残すかを意図的に選択しない限り、context window を二〜三桁分超過する。タスク 5.4 はまさにその規律を問う。

本学習ノートは、CCA-F 受験者がアーキテクチャレベルで設計できるようになるべき大規模コードベース探索のコンテキスト管理の全面を網羅する：リポジトリ全体が context window に収まらない理由、遅延ローディング原則がツール選択を支配する仕組み、正規の Glob → Read パイプライン、シンボル駆動探索のための Grep-first アプローチ、状態を外部化するスクラッチパッドファイルパターン、依存グラフの段階的マッピング規律、エントリポイントと設定ファイルを優先する優先順位ヒューリスティック、抽出済みファイル内容を破棄するコンテキスト衛生、セッションをまたいで生き続けるハイレベルなリポジトリマップ、リスクある大規模読み込み前のコンテキスト予算追跡、後から参照するためのファイルごとの要約メモ、そして Grep と Glob の混同や全ファイル読み込みに関する試験の典型的な罠。

大規模コードベースの課題 — リポジトリ全体は context window を桁違いに超える

本番リポジトリは、Claude が一括取り込みできるドキュメントではない。ファイル数 2,000・平均 200 行の控えめなマイクロサービスコードベースでさえ、行番号・import・コメントを含めると 400 万トークンを超え、どの Claude context window よりも桁違いに大きい。300 ファイル程度の比較的小規模なサービスでも、数十万トークンに達することが多い。大規模コードベース探索のコンテキスト管理は「すべてを読むことはできない」という公理から出発する。よって設計上の問いは「リポジトリをコンテキストに収める方法」ではなく、「Claude が次の正しいアクションをとれる最小限の断片をどう読むか」である。

試験はこの公理を絶対的なものとして扱う。「コードベース全体をロードする」「すべてのファイルを再帰的に読む」「リポジトリ全体を単一のコンテキストプロンプトに連結する」を提案するどの選択肢も、どれだけ補足説明が添えられていても、誤りである。特に「Claude Code を使ったコード生成」シナリオは、このトラップを中心に設計されている。大量読み込みに反射的に手を伸ばす受験者は、選択的・シンボル駆動の探索が正解である問題を落とす。

CCA-F における重要性

「Claude Code を使ったコード生成」シナリオと「Claude による開発者生産性」シナリオは、いずれも長時間タスク（バグ調査・複数ファイルリファクタリング・テスト作成・コードツアー）を提示する。エージェントは最初のツール呼び出し前に完全な読み込み順序を事前計画できない。代わりに、反復的に発見・絞り込み・読み込みを行い、タスク末尾の実際のコード変更のためにコンテキストの余裕を確保しなければならない。コミュニティの合格報告では、ファイル読み込みをコストゼロと見なす受験者がドメイン 5.4 の問題を落とし、読み込みをエージェントが行う最も高コストなアクションと見なす受験者が正しい遅延ローディングアーキテクチャを選択する傾向が一貫して報告されている。

遅延ローディング戦略 — コードベース全体ではなく関連ファイルのみを読む

大規模コードベース探索のコンテキスト管理の根本原則は遅延ローディングである：ファイルを読むコストは、そのファイルが現在のタスクに関連するという証拠が得られるまで先送りにする。遅延ローディングは「すべて読んで後から絞り込む」というデフォルトを「先に絞り込み、絞り込みを生き残ったものだけを読む」に反転させる。Claude Code の組み込みツールサーフェス（Read・Write・Edit・Bash・Grep・Glob）は、まさにこの反転を前提に設計されている。

遅延ローディングの三原則

1. 発見は読み込みより安い。 Glob（パス発見）と Grep（内容検索）は軽量な構造的シグナル（ファイルパス・行一致）を返す。完全な Read が消費するトークンのほんの一部にすぎない。まず発見に費やすこと。
2. 読み込みは編集より安い。 Read はファイルを変更せずに内容を確認できる。Edit の前に常に対象領域を Read して前提条件を確認すること。
3. 読み込まれたすべてのファイルは他の何かを押し出す。 context window は共有予算である。タスクの序盤に読み込まれた 3,000 行のファイルは、次の判断を実際に左右するテストファイルを押し出す。

遅延ローディングのデフォルトを破るとき

遅延ローディングはデフォルトであり禁止ではない。いくつかの小さくて中心的に重要なファイル、たとえばトップレベルの CLAUDE.md、サービスのメインエントリポイント、テスト設定などは、それ以降のすべての判断に影響を与えるため、正当なイーガー読み込みの対象である。試験は正当なイーガー読み込み（小さく・情報密度が高く・事前に判明している）と不正な「リポジトリ全体を読む」パターン（大量・トークンあたりシグナルが低い・投機的）を区別する。ヒューリスティックは上級エンジニアと同じだ：README とメインエントリポイントは積極的に読む；テストファイルすべてはテストが重要だとわかるまで読まない。

Glob → Read パイプライン — 選択的読み込み前の候補ファイル発見

Claude Code における正規の遅延ローディングパイプラインは、Glob に続いて狭い部分集合の選択的 Read を行うものだ。Glob はパスパターン（src/**/*.ts・**/auth/*.py・apps/*/config/*.yaml）に一致するファイルのパスリストのみを返す。ファイルの内容は一切読まない。そのパスリストは同じファイルの内容よりも桁違いに安く、Claude が読み込み予算を使う前に情報に基づいた選択を行えるようにする。

パイプラインのステップバイステップ動作

1. パス仮説を立てる。 タスクを考えると、どのディレクトリや命名パターンに関連ファイルがあるはずか？「認証は **/auth/** か **/login/** にありそうだ。」
2. 仮説に対して Glob を実行する。 ツールはパスリスト（数百件の可能性もある）を、どれも読まずに返す。
3. リストを絞り込む。 ファイル名の手がかり（*.test.ts・index.*・*.config.*）を使って、関連コードを含む可能性が最も高い少数のファイルを選ぶ。
4. 絞り込んだセットのみを読む。 残った各パスに対して Read を呼び出す。理想的には行範囲パラメータを使い、関連領域のみをコンテキストに入れる。
5. 仮説が外れたら反復する。 最初の Glob が有用な結果を返さなかった場合、パターンを精緻化する。**/* による再帰的スイープへ拡大しない。

Glob はパスツールであり、内容ツールではない

CCA-F で最も頻繁に問われる Glob と Grep の違いは、Glob がパスパターンのみに一致し、どのファイルも開かないという点だ。「このパスパターンにどのファイルが一致するか？」に答えるものであり、「このシンボルを含むファイルはどれか？」には決して答えられない。内容指向の質問（「AuthService を import するファイルはどれか？」）には Glob では答えられない。Grep が必要だ。

Grep-first アプローチ — 全ファイル読み込み前の関連シンボル検索

Grep は Glob のシンボル駆動の対になる存在だ。Glob がファイル名でファイルを見つけるのに対して、Grep はファイルの内容（クラス宣言・関数名・設定キー・文字列定数）でファイルを見つける。ほとんどの実際のコードベース探索タスクにおいて、Grep-first が試験正解のパターンだ：ファイル全体を読む前に、タスクが言及するシンボルや文字列に対して Grep を実行し、返されたマッチした行番号を使ってその行のみを対象とした狭い Read を行う。

Grep-first ワークフロー

1. タスクから検索語を抽出する。 タスクが processRefund に言及しているなら、最初のアクションは processRefund に対する Grep であり、それらしいファイルのディレクトリに対する Read ではない。
2. 一致リストを解釈する。 Grep はマッチした行番号付きのファイルパスを返す。数件のヒットから、定義サイト（シンボルが宣言されている場所）と呼び出しサイト（使われている場所）がわかることが多い。
3. ターゲットを絞った Read。 調査する価値のある各ヒットに対して、マッチした行と小さな周囲のウィンドウ（例えば各方向 20 行）を含む行範囲で Read する。数百行を超えるファイルでは行範囲なしの Read は避けること。
4. 必要な場合のみ依存関係を追う。 ターゲットを絞った Read で、その関数が別のシンボルに委譲していることがわかった場合、委譲先ファイル全体を読むのではなく、そのシンボルに対して Grep-first パターンを繰り返す。

Grep-first が予算を守る理由

関数の定義サイトは通常 20〜60 行を占める。同じ関数のファイル全体を読むと 800 行の周辺コードが読み込まれる可能性がある。これはトークンコストが 20 倍になることを意味する。マルチステップのタスクではこの差が積み重なる：Grep-first エージェントは、全ファイル読み込みエージェントが 2 つのシンボルを調査する予算で 10 個の異なるシンボルを調査できる。

Grep vs Glob — 試験の区別

• Glob はファイルパスを検索する。 入力：パスパターン。出力：ファイルリスト。ファイルの内容は一切読まない。
• Grep はファイルの内容を検索する。 入力：正規表現またはリテラル。出力：path:line:content のヒット。

これらのツールを混同する受験者は、Glob で十分な場面で Grep を実行する（内容スキャンにより高コスト）か、Grep が必要な場面で Glob を実行する（Glob はファイル内のシンボルを見つけられないため無意味）かのどちらかになる。両方のエラーが CCA-F「コード生成」シナリオ問題の誤答選択肢として登場する。

スクラッチパッドファイル — 永続的な状態のための探索メモの外部ファイルへの書き出し

スクラッチパッドファイルとは、探索中にエージェントが中間の発見（発見したファイルパス・抽出した関数シグネチャ・未検証の仮説・ToDo リスト）を保持するためにディスク上に書くファイルである（慣習的に NOTES.md・SCRATCH.md・.claude/scratchpad/task-<id>.md など）。スクラッチパッドは、タスク 5.1 の事例ファクトブロックのコードベース探索版だ：永続的な状態を context window の外に出してディスクに置き、マルチターンの会話履歴を再生する代わりに、後で短い Read で正確に参照できるようにする。

スクラッチパッドファイルが会話内メモに勝る理由

会話内メモ、つまりエージェントが「processRefund は billing/refunds.ts の 42 行目にあり、refundGateway.submit に委譲していることを確認した」と書くこと、は大規模コードベース探索のコンテキスト管理のすべての病理にさらされる。そのメモは後続のすべてのターンで再生されなければならない。実際のコード内容と注目を競い合う。会話が長くなるにつれて lost-in-the-middle 効果の影響を受ける。スクラッチパッドファイルはこれら三つのコストをすべて回避する：継続的なトークンコストゼロでディスク上に存在し、必要なときに予測可能なコストで再読み込みでき、エージェントは履歴を書き直すことなく新しい発見を追記できる。

スクラッチパッドの内容パターン

よく構造化されたスクラッチパッドが記録するもの：

• 確認済みの事実。 "processRefund は billing/refunds.ts:42 に定義されている。"
• 未検証の仮説。 "払い戻し金額は billing/policy.ts でクランプされている可能性がある — 未確認。"
• 却下したリード。 "legacy/old-refund.ts は未使用 — インポートグラフに呼び出し元なし。"
• 決定ログ。 "refundGateway.submit を置き換えるのではなくリファクタリングすることを選択した。理由：3 つの下流呼び出しサイトが現在のシグネチャに依存しているため。"
• ToDo リスト。 "1. refundGateway.submit のテストカバレッジを確認する。2. マイグレーションスクリプトを実行する。"

セッション境界を越えた生存

スクラッチパッドファイルは Claude Code セッション終了後も生き残る。つまり、翌日ユーザーが作業を再開するとき、またはスクラッチパッドを主要な入力として subagent がスポーンされるときのハンドオフドキュメントを兼ねる。この特性は大規模コードベース探索のコンテキスト管理を session-state-resumption-and-forking（タスク 1.7）に接続する：スクラッチパッドは探索状態の永続的なキャリアである。

段階的探索 — 深いファイル読み込み前の依存グラフのマッピング

上級エンジニアは未知のコードベースをトップダウンで探索する：まずモジュール境界を学び、次に公開インターフェースを、そして実際にタスクが触れるモジュールの内部実装を学ぶ。段階的探索は Claude Code のアナログだ。単一ファイルを深く読む代わりに、エージェントはまず依存グラフをシャローレベルでマッピングし（どのモジュールが存在し、どれがどれに依存するか）、次にタスクの入力と出力の間のパス上にあるモジュールだけを掘り下げる。

段階的探索プロトコル

1. レイヤー 0：リポジトリ形状。 トップレベルディレクトリに対して Glob、ルートの README.md・package.json / pyproject.toml・トップレベルの CLAUDE.md を Read する。総コスト：数百トークン。成果：プロジェクトの技術スタックとモジュール境界のマップ。
2. レイヤー 1：公開インターフェース。 タスクに関連する各モジュールについて、index.* または同等の公開サーフェスファイルを Glob し、それだけを Read する。これらのファイルには通常、モジュールがエクスポートするものがリストされている。
3. レイヤー 2：定義サイト。 タスクが言及する特定のシンボルに対して Grep-first を実行し、マッチした行範囲でターゲットを絞った Read を行う。
4. レイヤー 3：実装の詳細。 前の 3 つのレイヤーによって正当化された場合にのみ、大きな実装ファイルの全ファイル読み込みを行う。

レイヤーをスキップすること、たとえば「ユーザーが払い戻しフローを変更したい」から billing/ ディレクトリのすべてのファイルの全ファイル読み込みに直接飛ぶことは、試験が問う失敗モードである。レイヤー化された探索は安価で情報密度の高い読み込みを前倒しし、証拠が蓄積されるまで高価で限界シグナルが低い読み込みを先送りにする。

依存グラフ vs コールグラフ

依存グラフは粗い構造マップ（モジュール A がモジュール B に依存する）である。コールグラフはより細かいシンボルマップ（関数 foo() が関数 bar() を呼ぶ）である。段階的探索は通常、レイヤー 0 と 1 に依存グラフを使い、レイヤー 2 と 3 に Grep-first のコールグラフルックアップを使う。

優先順位ヒューリスティック — エントリポイント・設定ファイル・テストファイルを起点として

タスクが曖昧またはコードベースが未知の場合、エージェントはランダムウォークではなく決定論的な起点ヒューリスティックを必要とする。CCA-F は、シグナル密度の高い順に 4 つの正規的な起点の認識を要求する。

エントリポイント

メインバイナリのエントリファイル（main.ts・index.ts・app.py・cmd/*/main.go）は、サービスのトップレベル構成を明らかにする：どのモジュールが接続され、どのバックグラウンドワーカーが存在し、どの HTTP ルートが登録されているか。エントリファイルはその後のすべての判断を形作るため、積極的に読む価値がほぼ常にある。

設定ファイル

package.json・tsconfig.json・pyproject.toml・docker-compose.yml・.env.example・Cargo.toml などは、プロジェクトの依存関係・ビルドツール・ランタイム環境を記述する。これらのファイルは小さく・情報密度が高く・ほぼ必ず関連性がある。早期に読むことで、どのテストランナー・リンター・パッケージマネージャーが適用されるかについての後の混乱を防ぐ。

テストファイル

テストファイルはしばしばテスト対象コードの最高品質の実行可能仕様を符号化している。タスクが「この関数が何をすべきかを理解する」である場合、最も近いテストファイルが正しいメンタルモデルへの最速経路であることが多い。エントリポイントや設定ファイルと並んで、*.test.*・*_test.*・spec/**・tests/** を第一級の起点として扱うこと。

CLAUDE.md ファイル

CLAUDE.md ファイルの階層（グローバル・プロジェクト・ディレクトリ）は Claude のために特別にキュレーションされた起点だ。パス固有の CLAUDE.md 指示は、エージェントが触れるファイルに基づいて条件付きで読み込まれる。プロジェクトの慣習・編集禁止リスト・アーキテクチャの不変条件を符号化している。各探索ステップで最も近い CLAUDE.md を読むことは、CCA-F で期待される反射である。

コンテキスト衛生 — 必要な情報を抽出した後の不要なファイル内容の破棄

ファイルを読むことはライフサイクルの始まりであり終わりではない。エージェントが 600 行のファイルから必要な 2〜3 の事実を抽出したら、残りの 600 行が後続のすべてのターンで context window を占有し続けるべきではない。コンテキスト衛生は、すでに採掘済みのファイル内容を凝縮または破棄し、後のステップが予算を保持できるようにする規律である。

三つの衛生アクション

1. 抽出してパラフレーズする。 ファイルを読んだ後、スクラッチパッドに 1〜2 文を書く（「refundGateway.submit(amount, orderId) は /v1/refunds に POST し、{status, traceId} を返す」）そしてその要約を以降の正規の参照として扱う。生のファイル内容は破棄可能になる。
2. 古いツール結果を圧縮またはクリアする。 Claude 4 は廃止されたツール結果を削除するコンテキスト編集機能をサポートしている。完全に採掘されたファイル読み込みに対して意図的に使用すること。
3. 変更されていない同じファイルを再読みしない。 最後の Read 以降にファイルが編集されていない場合、以前の Read で抽出された事実はまだ有効である。再読みはコストを倍にするだけで情報は増えない。

衛生 vs 要約

衛生は一般的な要約より強い動作だ。衛生は「このファイルが寄与するものを抽出した；もう生の内容は必要ない」と言う。要約は「これが生の内容の圧縮版だ」と言う。衛生が試験で報われる動作であり、要約はしばしば、より困難な判断（内容を完全に削除する）が正しい回答であるときに建築的解決策として提示される誤答選択肢である。

リポジトリマップパターン — ナビゲーションのための高レベルインデックスファイルの維持

リポジトリマップとは、コードベースのモジュール境界・公開 API・クロスモジュール依存関係を密度の高いナビゲート可能な形式で要約した、手作業でキュレーションされたまたはエージェントが維持するファイルである（多くの場合 REPO_MAP.md・.claude/REPO_MAP.md・または CLAUDE.md に埋め込まれる）。良いリポジトリマップがあれば、Claude は Glob や Grep を一度も実行せずに「認証はどこにあるか？」「課金モジュールの公開インターフェースは何か？」に答えられる。

リポジトリマップに含めるべきもの

• モジュールインベントリ。 各トップレベルモジュールの一文説明のリスト。
• 公開インターフェースインデックス。 各モジュールについて、公開エクスポートの名前とそれが宣言されている場所へのポインタ。
• 依存関係の矢印。 粗粒度の「モジュール X はモジュール Y に依存する」リンク。
• 既知の不変条件。 「すべての金額はセント単位の整数；浮動小数点の金額はバグ。」
• 編集禁止リスト。 生成された・サードパーティの・その他変更が許可されていないファイルやディレクトリ。

維持の規律

古いリポジトリマップはないよりも悪い。なぜなら誤解を招くからだ。正規の規律は、モジュール境界に触れるどの PR の一部としてもリポジトリマップを更新し、マップをレビューアーティファクトとして扱い、バージョンまたは「最終確認」タイムスタンプを含めることだ。Claude Code 自身が再構築タスク後にリポジトリマップを更新するよう指示できる。

リポジトリマップ vs スクラッチパッド vs CLAUDE.md

これら三つのアーティファクトには異なる役割がある：

• CLAUDE.md — プロジェクトルール・慣習・編集禁止リスト・プロンプトヒント。タスクをまたいで安定。
• リポジトリマップ — モジュール・インターフェース・依存関係の構造インデックス。タスクをまたいで安定；構造変更時に更新。
• スクラッチパッド — 一時的な発見・未検証の仮説・タスク固有の決定ログ。タスクごとにリセット。

これらのアーティファクトを混同すること（たとえば CLAUDE.md に一時的なタスク状態を置く、またはスクラッチパッドに構造的アーキテクチャを置く）は実際の試験の罠である。

コンテキスト予算追跡 — 大きなファイル読み込み前の残りコンテキストの推定

すべての自律 Claude Code エージェントは、context window を観測可能な残高のある予算として扱うべきだ。コンテキスト予算追跡は、残りのヘッドルームを推定し、その推定に対して大規模読み込みを制限する規律である。これは、マルチファイルリファクタリングの途中で予算切れになることを防ぐアーキテクチャ上の習慣だ。

予算を知らせるシグナル

• 反復回数。 各ターンは少なくとも 2 つのメッセージ（アシスタント + tool_result）を追加する。深いループは急速に蓄積する。
• 累積ツール結果サイズ。 大きな Read や Bash の出力が長いセッションのトークン使用を支配する。
• CLAUDE.md + ツール定義のオーバーヘッド。 これらは毎ターン再生され、恒久的な下限を設定する。
• モデルの公表 context window。 それに対してすべてが測定される上限。

リスクある Read 前の予算認識ゲート

大きなファイルに対して Read を発行する前に、エージェント（またはフック）は確認すべきだ：

1. 推定ファイルサイズ。 Glob で返されたパスや簡単な Bash wc -l でサイズ推定ができる。
2. 現在の残り予算。 以前のツール結果サイズの合計からの大まかな推定。
3. 代替手段。 ファイルが大きく特定の領域が既知の場合（以前の Grep ヒットから）、行範囲のみを読む。領域が不明の場合、まず Grep を行う。

ファイルサイズを確認せずに常に全ファイルを読むエージェントは、単一の巨大なファイルで予算を吹き飛ばす。何らかの閾値（たとえば 500 行）を超えるファイルに対して常に Grep または行範囲読み込みを行うエージェントは、はるかに長いセッションをスムーズに実行する。

探索済みファイルの要約 — 後から参照するためのファイルごとの簡潔なメモの作成

エージェントが探索しながら、ファイルごとのメモインデックス（スクラッチパッドに記録された探索済み各ファイルについての 1〜2 文）を構築することで、後のステップが「billing/refunds.ts についてわかったことは何だったか？」とファイルを再読みしたり 600 行の Read ツール結果を再生したりせずに問い合わせられるようにする。

ファイルごとのメモに含めるべき内容

• 一行の目的説明。 "processRefund ハンドラを含む；払い戻し計算を調整し refundGateway.submit を呼ぶ。"
• 主要なシンボルや行番号。 "processRefund は 42 行目；clampRefundAmount は 118 行目。"
• 既知の特殊な点。 "金額はドルではなくセント；processRefund は正の整数を期待する。"
• 状態。 "ターン 5 でレビュー済み；編集保留なし。"

ファイルごとのメモ vs リポジトリマップ vs スクラッチパッド決定ログ

スクラッチパッドはすべてを収容するが、それぞれが異なる機能を果たす。ファイルごとのメモは個別読み込みの蒸留された出力だ。決定ログはファイルをまたいで行われた選択を記録する。リポジトリマップ（プロジェクトレベルで維持される場合）は構造的でセッションをまたいで生き残る。混在させることは問題ない；混同すること、たとえばタスク固有のファイルごとのメモをグローバルリポジトリマップに昇格させること、は問題だ。

CCA-F においてこのパターンが重要な理由

「開発者生産性」シナリオの試験問題は、長いタスクのターン 15 において、エージェントがターン 4 に既に探索したファイルを再読みしないことを認識するかどうかを定期的にテストする。正しいアーキテクチャはそのファイルを一度参照し、スクラッチパッドに簡潔なメモを書き、元の 600 行の読み込みではなくメモを真実の源として参照する。後続のターンごとにすべての探索済みファイルを再読みするようエージェントに指示する誤答選択肢は、解決策ではなく失敗モードを記述している。

Explore Agent パターン — コードベース調査のための読み取り専用 subagent

大規模コードベース探索の繰り返しパターンは、リポジトリを調査し・発見のスクラッチパッドを生成し・ファイルを一切編集せずに戻ってくることを担当する読み取り専用の Explore subagent を専用に設けることだ。コーディネーターエージェントはそのスクラッチパッドを消費し、メインエージェントが編集を進めるかどうかを判断する。このパターンは発見と変更をきれいに分離し、subagent は独立したコンテキストで動作するため、コーディネーターのコンテキストが一時的な生のファイル内容で汚染されることを防ぐ。

Explore subagent をスポーンするとき

• タスクが最初の編集を安全に計画できる前に大量のファイルを読む必要がある。
• 探索がコーディネーターに直接見せる必要のない数万トークンの生のファイル内容を生成する。
• コーディネーターの残りコンテキスト予算が制約されており、探索だけで使い果たされる。
• 探索の出力をコーディネーターが有界のコストで読めるスクラッチパッドファイルにシリアライズできる。

subagent ツール許可リストの規律

Explore subagent はツール許可リストに Read・Grep・Glob・Write（スクラッチパッド用）を持つべきで、Edit や破壊的な Bash ツールを持つべきではない。許可リストの制限は安全策（subagent がリポジトリを誤って変更できない）でもありコンテキスト策（subagent が探索の役割から逸脱する誘惑を受けない）でもある。

白話文解釋（平易な言葉での解説）

抽象的なコンテキスト予算の規律は、物理的なシステムに根ざしているとよく定着する。三つの異なる領域から意図的に選ばれた比喩が、大規模コードベース探索のコンテキスト管理の全体像を網羅する。

比喩 1：図書館の参考書架 — 書棚そのものではなくカード目録

研究者が大きな参考図書館に入ったところを想像してほしい。図書館には数十万冊の本がある、一人の人間が生涯で読める量よりはるかに多い。初心者の研究者は最初の 10 冊の本を手に取り、全部ざっと読み始めるかもしれない。経験豊富な研究者は全く違うことをする：まずカード目録（図書カード）に行き、正確なトピックを調べ、目録が挙げる特定の巻だけを取り出し、各巻の中では索引を使って関連ページに直接ジャンプする。

カード目録が Glob だ。巻の索引が Grep だ。特定のページが行範囲を指定した Read だ。参照した各本から重要な 2 文をメモする研究者のノートがスクラッチパッドだ。そして図書館の主要なコレクション分野を列挙する司書の恒久的な「主題ガイド」小冊子がリポジトリマップだ。

目録と索引をスキップして建築のコーナーのすべての本を座って読んだ研究者は、実際の研究課題を終える前に時間切れになる。これは Glob と Grep をスキップして大規模なリポジトリ全体への全ファイル読み込みをデフォルトにした Claude Code エージェントに起こることとまったく同じだ。

比喩 2：持ち込み可試験 — ライブラリではなく予算

大きな教科書の 8 時間の持ち込み可試験を受けている受験者を想像してほしい。教科書・白紙のノート・無制限のペンが許可されているが、机の上には一度に物理的に少数のページしか開けておけない。机が context window だ。教科書がリポジトリだ。ノートがスクラッチパッドだ。

すべての章を同時に机に広げた受験者は何も見つけられない；机は散らかり、3 問目には物理的なスペースが足りなくなる。代わりに教科書に索引を付け・どこにでも出てくる 3 つの公式をノートに写し・特定の問題には特定のページにジャンプし・必要なものを抽出したら各ページを閉じた受験者は、余裕をもって試験を終える。

「重要な 2 文をコピーして本を閉じて次へ進む」という受験者の規律がコンテキスト衛生だ。「1 ページ目からではなく索引から教科書を開ける」という受験者の反射がGrep-first パターンだ。「すべては読めない」という受験者の受け入れと「どのページを読まないかを計画しようとする」姿勢が、個人化された遅延ローディングだ。

比喩 3：工事現場 — 作業台と倉庫

大きな倉庫が付属している工房で、棚の製作をしている大工を想像してほしい。作業台には今作業中のもの（数枚の板・いくつかの工具・現在の部品の設計図）が載っている。倉庫にはその他すべてが入っている：何千枚の板・数百の工具セット・数十年分のアーカイブプロジェクト。

倉庫全体を作業台に引きずり込んだ大工は作業できない；台は埋まってしまう。倉庫を一切見ない大工は 1 時間以内に資材が切れる。実際の作業規律はこうだ：倉庫のマニフェスト（リポジトリマップ）を参照して何があるかを知り、現在のステップに必要な特定の板と工具を取り出し（ターゲットを絞った Read）、台のクリップボードに切断リストを作り（スクラッチパッド）、使い終わったものを倉庫に戻し（コンテキスト衛生）、実際の作業ができるよう台を十分に空けておく。

試験正解の Claude Code エージェントはこの大工だ。試験不正解のエージェントは「念のため」倉庫のすべての板を台に積み上げて、なぜあり継ぎがきれいに切れないのかと不思議がるエージェントだ。

どの比喩がどの試験キューに合うか

• Glob/Grep/Read パイプライン、Grep-first パターン、遅延ローディング → 参考図書館のカード目録の比喩。
• コンテキスト予算追跡、コンテキスト衛生、衛生 vs 要約 → 持ち込み可試験の予算の比喩。
• スクラッチパッドファイル、リポジトリマップ、Explore subagent の隔離 → 大工の作業台と倉庫の比喩。

会話コンテキスト管理（タスク 5.1）との整合

タスク 5.4 とタスク 5.1 は context window という基盤を共有するが、異なる内容タイプを扱う。タスク 5.1 は会話内容（ユーザーターン・アシスタントの返答・事例ファクト・約束）に焦点を当て、失敗モードはトランザクションファクトの要約ドリフトだ。タスク 5.4 はファイル内容（ソースコード・設定・ログ）に焦点を当て、失敗モードは無差別な読み込みによる予算消耗だ。

アーキテクチャ上の並行関係は意図的だ。タスク 5.1 の事例ファクトブロックはタスク 5.4 のスクラッチパッドファイルに対応する：どちらも永続的な状態を有界のコストで再生されるマシン管理のアーティファクトに外部化する。タスク 5.1 のツール出力トリミングはタスク 5.4 の Grep-first ターゲットを絞った Read に対応する：どちらも最初から冗長な内容が window に入ることを防ぐ。タスク 5.1 のセクションヘッダーはタスク 5.4 のリポジトリマップに対応する：どちらも大きな非構造的なペイロードにナビゲーションの足場を提供する。タスク 5.1 を内面化した受験者は、タスク 5.4 が同じ原則を異なるコンテンツドメインに再適用したものだと気づくだろう。

試験の典型的な罠

CCA-F ドメイン 5.4 は、大規模コードベース探索のコンテキスト管理に関連する 6 つの繰り返しパターンを利用する。各罠は、遅延ローディングの公理を適用するまでは合理的に聞こえる誤答選択肢としてコミュニティの合格報告で記録されている。

罠 1：「事前に関連ファイル全体を読む」

誤答の表現：「Claude が編集前に完全なコンテキストを持つように、まずファイル全体を読む。」これは数百行を超えるすべてのファイルに対して誤りだ。ターゲットを絞った Grep に加えて行範囲の Read は、トークンコストのほんの一部で同じ判断品質を提供する。試験は大きなファイルへの全ファイル読み込みをデフォルトの安全な行動ではなくデフォルトの悪い行動として扱う。

罠 2：「Grep はファイルパスを検索する」

誤答の表現：「src/auth/ 配下に存在するファイルを発見するために Grep を使う。」これは Grep と Glob を混同している。Grep はファイル内容を検索し、Glob はファイルパスを検索する。二つを入れ替えるどの回答も誤りであり、コミュニティはこれをドメイン 5.4 で最も誤答率が高い区別として一貫して報告している。

罠 3：「すべての発見を会話に保持する」

誤答の表現：「Claude がターンをまたいで参照できるように探索の発見を会話履歴に維持する。」短いタスクでは機能するが、スケールでは失敗する。試験正解の動作は、永続的な発見をスクラッチパッドファイルに外部化することだ。スクラッチパッドはターンをまたいで有界のコストで生き残り、lost-in-the-middle 効果に対して免疫がある。

罠 4：「より大きな context window が解決策だ」

誤答の表現：「リポジトリ全体を収めるために、より大きな context window を持つモデルに切り替える。」より大きな window は構造的なミスマッチを解消しない。リポジトリはいまだに利用可能な window よりも桁違いに大きく、膨らんだ window は位置的顕著性効果を悪化させる。修正はアーキテクチャ的（遅延ローディング・Grep-first・スクラッチパッド）であり、容量拡張ではない。

罠 5：「Claude がプロンプト内でリポジトリマップを維持する」

誤答の表現：「Claude が探索しながらリポジトリマップを構築・維持するようにシステムプロンプトで指示する。」プロンプト内のモデル管理の状態はドリフトと要約損失の影響を受ける。試験正解のアーキテクチャでは、Claude がリポジトリマップ（またはスクラッチパッド）をファイルに書き、永続プロンプトセクションには書かない。

罠 6：「探索には常に subagent をスポーンする」

誤答の表現：「すべてのコードベース調査に常に Explore subagent を使う。」subagent は探索がコーディネーターのコンテキストを置き換えるほど深い場合に価値があるが、短いターゲットを絞ったタスク（単一ファイル編集・クイック Grep ルックアップ）では、subagent をスポーンすることはメリットなしにオーバーヘッドを追加する。問題を解決する最も軽量なパターンを選ぶことが試験で報われる。

実践アンカー — タスク 5.4 シナリオ問題テンプレート

大規模コードベース探索のコンテキスト管理に結びついた CCA-F 実践問題は、「Claude Code を使ったコード生成」「Claude による開発者生産性」「継続的インテグレーションのための Claude Code」シナリオにまたがる 5 つの繰り返しパターンに分類される。詳細な問題は ExamLab CCA-F 問題バンクにある；以下のテンプレートはパターン認識のトレーニングだ。

テンプレート A：シンボルルックアップ

エージェントは 2,000 ファイルのリポジトリで processRefund の動作を変更するよう求められる。提案されたアーキテクチャには（a）パスに refund を含むすべてのファイルを Glob、（b）src/billing/ のすべての *.ts ファイルを Read、（c）processRefund を Grep して各ヒットの行範囲を Read、（d）すべての課金ファイルを読む Explore subagent をスポーンする、が含まれる。正しい最初の動作は何か？

• 正しい動作：（c）Grep-first。シンボルが明示的でタスクがターゲットを絞っている；Grep に加えて行範囲の Read は有界のコストで定義サイトと呼び出しサイトを提供する。オプション（a）（b）（d）は過剰読み込みだ。

テンプレート B：未知のリポジトリ

ユーザーが Claude にこれまで見たことのないリポジトリを渡した。タスクはユーザーが一文で説明する機能を追加することだ。正しい探索順序は何か？

• 正しい順序：（1）トップレベルの CLAUDE.md、（2）主要設定ファイル（package.json / pyproject.toml / 同等）、（3）メインエントリポイント、（4）想定ターゲットディレクトリに沿った最も近い CLAUDE.md。これら 4 回の読み込みの後にのみ Grep-first 探索を始めること。リポジトリ形状を確立せずに Grep に直接飛び込む受験者は後続の予算を誤誘導する。

テンプレート C：長いリファクタリング

エージェントはマルチファイルリファクタリングの 20 ターン目だ。以前のターンが不要になった全ファイルを読んだ。残り予算が厳しく、エージェントはまだ重要な編集を行いテストを実行しなければならない。正しい衛生動作は何か？

• **正しい動作：**コンテキスト衛生 — 採掘済みのファイルを短いスクラッチパッドメモに凝縮し、元の全ファイル読み込みを削除または圧縮する。すべてを再読みしようとしないこと；より大きな window のモデルに切り替えないこと；残り予算で十分だという仮定のもとで衛生なしで続けないこと。

テンプレート D：Glob vs Grep の誤答選択肢

AuthService シンボルを import するすべてのファイルを見つける正しい方法はどれか？

• **正しい：**リポジトリ全体で AuthService（または import.*AuthService）を Grep し、マッチするヒットを読む。
• 誤り：**/*AuthService* を Glob する — これはシンボルを含むファイルではなく、文字列を含むファイルパスのみに一致する。

テンプレート E：探索 subagent の判断

タスクは計画された大規模リファクタリング前の深いマルチファイル調査だ。コーディネーターのコンテキスト予算が厳しく、調査だけで数万トークンの生のファイル内容を生成する。コーディネーター自身が探索するべきか、Explore subagent をスポーンするべきか？

• 正しい動作：Read・Grep・Glob・Write（スクラッチパッド）は持つが Edit は持たない Explore subagent をスポーンする。subagent の独立したコンテキストが生のファイル内容を吸収し、スクラッチパッドの要約だけがコーディネーターに返る。これによりコーディネーターの予算を計画と編集のために確保できる。

大規模コードベース探索のコンテキスト管理 — よくある質問

タスクの開始時に Claude のコンテキストにコードベース全体を読み込むのはなぜ誤りなのか？

本番リポジトリは通常、数千ファイルにわたる数百万トークンを有している。これはどの Claude context window よりも二〜三桁大きい。わずかなサービスでさえ、数百回のファイル読み込みで利用可能な予算を超えることが多い。さらに重要なことに、投機的なコンテキストの読み込みに費やされたすべてのトークンは、タスクが実際に必要とする後の推論と編集には使えない。正しいパターンは遅延ローディングだ：いくつかのターゲットを絞った読み込み（CLAUDE.md・設定・エントリポイント）でリポジトリ形状を確立し、次にタスクが言及するシンボルに対して Grep-first し、次に生き残った候補に対して行範囲 Read のみを行い、次に発見をスクラッチパッドに抽出して生のファイル内容を破棄する。

Claude Code における Glob と Grep の違いは何か、なぜその区別が重要なのか？

Glob はファイルパスパターン（src/**/*.ts・**/auth/*.py）に一致し、内容を読まずにマッチしたファイルパスのリストを返す。Grep はスキャンするファイル全体で正規表現またはリテラルのファイルの内容を検索し、マッチした path:line:content のヒットを返す。「このパス形状に存在するファイルは何か？」という質問には Glob を使い、「このシンボルまたは文字列を含むファイルはどれか？」という質問には Grep を使う。混同することは CCA-F で最も誤答率が高いドメイン 5.4 の区別だ：Glob で十分な場面で Grep を使うと不要な内容スキャンで予算を消費し、Grep が必要な場面で Glob を使うとファイル内のシンボルを全く見つけられない。

スクラッチパッドファイルとは何か、なぜ発見を会話に保持するよりも好ましいのか？

スクラッチパッドファイルとは、エージェントが探索中に蓄積する発見（確認済みの事実・未検証の仮説・却下したリード・決定ログ・ファイルごとのメモ）を書くディスク上のファイルである（慣習的に NOTES.md・SCRATCH.md・または .claude/scratchpad/task-<id>.md）。会話ベースのメモよりも好ましいのは、会話内の永続的な状態は毎ターン再生され・活発な推論と顕著性を競い合い・lost-in-the-middle 効果に対して脆弱だからだ。ディスク上の永続的な状態は参照しないターンではトークンコストがかからず・必要なときに有界のコストで再読みでき・セッション境界を越えて生き残る。タスク 5.1 の事例ファクトブロックのコードベース探索版だ。

メインエージェントで調査を行う代わりに Explore subagent をスポーンするのはいつか？

調査がコーディネーターの重要なコンテキストを置き換えるほど深い場合に Explore subagent をスポーンする。明確なトリガー：調査が数十ファイルに触れる・数万トークンの生の内容を生成する・計画された大規模リファクタリングに先行する・またはコーディネーターの残り予算がすでに制約されている。subagent には Read・Grep・Glob・Write（スクラッチパッド）を与えるが Edit は与えない。subagent の仕事は発見であり変更ではない。短いターゲットを絞った調査の場合、subagent はメリットなしにオーバーヘッドを追加する；問題を解決する最も軽量なパターンが試験正解のパターンだ。

未知のリポジトリでタスクを開始するとき、何をイーガーに読み、何を遅延して読むかをどう決めるか？

小さく・情報密度が高く・それ以降のすべての判断に影響を与えるファイルをイーガーに読む：トップレベルの CLAUDE.md・主要設定ファイル（package.json・pyproject.toml・Cargo.toml など）・メインエントリポイント・想定ターゲットディレクトリに沿った最も具体的な CLAUDE.md。これら 4 回の読み込みは通常数千トークンかかり、プロジェクトの技術スタック・モジュール境界・慣習のマップをエージェントに提供する。それ以外はすべて遅延して読む：まず Glob と Grep で絞り込み・全ファイルではなく行範囲を読み・次のステップに進む前に発見をスクラッチパッドに抽出する。

長いタスクがセッションの早い段階で検査したファイルを再度読む必要がある場合、コンテキストをどう管理するか？

変更されていないファイルを再読みしない。早い段階での読み込みで関連する事実を抽出してスクラッチパッドに記録してあれば、ターゲットを絞ったスクラッチパッドの Read で元のファイルのコストのほんの一部で抽出された要約を取得できる。すでにスクラッチパッドの 1 行に要約されている 2 つの事実を取得するために変更されていない 600 行のファイルを再読みすることは、情報を追加せずにトークンコストを倍にする。規律はこうだ：最初の読み込みで抽出し・スクラッチパッドに要約し・スクラッチパッドを以降の正規の参照として扱い・ファイルが変更された場合またはより深い領域が関連するようになった場合にのみ生のファイルを再読みする。

コンテキスト衛生とは何か、要約とどう違うのか？

コンテキスト衛生とは、すでに関連する事実のために採掘されたファイル内容を積極的に破棄または圧縮する規律で、後のステップが予算を保持できるよう生の内容を window から落とす。要約は、window 内に削減されたコストで残る生の内容の圧縮版を生成する。衛生はもう一歩踏み込む：抽出された事実はスクラッチパッドに残り、生のファイル内容は完全に破棄可能として扱われる。CCA-F では、衛生が正しい動作であるときに要約を提案する回答選択肢は一般的な誤答選択肢だ。要約は継続的なトークンコストを支払うのに対して、衛生はディスク上のスクラッチパッドと組み合わせると支払わないからだ。

さらなる学習リソース

• Claude Certified Architect — Foundations（CCA-F）試験ガイド: https://everpath-course-content.s3-accelerate.amazonaws.com/instructor/8lsy243ftffjjy1cx9lm3o2bw/public/1773274827/Claude+Certified+Architect+%E2%80%93+Foundations+Certification+Exam+Guide.pdf
• Context windows — Claude API Docs: https://docs.anthropic.com/en/docs/build-with-claude/context-windows
• Long context prompting tips — Claude API Docs: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/long-context-tips
• Tool reference — Anthropic-provided built-in tools: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/tool-reference
• CLAUDE.md configuration — Claude Code Docs: https://docs.anthropic.com/en/docs/claude-code/claude-md
• コミュニティ合格報告（893/1000、Kishor Kukreja、2026-04-09）: https://medium.com/@kishorkukreja/i-passed-anthropics-claude-certified-architect-foundations-exam-with-a-score-of-893-1000-2206c27efd6c

関連 ExamLab トピック: 長いインタラクションにわたる会話コンテキストの管理、組み込みツールの選択と適用、パス固有のルールと条件付き規約の読み込み、セッション状態・再開・フォーキング。