Claude Codeのコンテキスト管理 — 大規模コードベースは起動場所と3つの除外設定で決まる
Claude Codeのコンテキスト管理は、圧縮より前に読み込ませない設計で決まります。起動場所の選び方、読み込みを削る3つの設定と副作用、分割境界の決め方をまとめます。
Claude Codeのコンテキスト管理は、埋まってから圧縮するより、埋まる前に読み込ませない設計のほうが効きます。数百万行のリポジトリやパッケージの多いモノレポでは、最初のプロンプトを打つ前に、既定設定がタスクと無関係な命令とファイル読み取りでウィンドウを埋めてしまうためです。本稿が扱うのは4つです。起動場所の選び方、読み込みを削る3つの設定とそれぞれが効かない範囲、階層化したCLAUDE.mdがコンパクションで失われる挙動、そしてサブエージェントの分割境界です。
大規模コードベースでは、打ち込む前にコンテキストが埋まる
大規模コードベースとは、数百万行のコードを持つ1つのリポジトリ、または多くのパッケージを持つモノレポを指します。Claude Codeはどのサイズでも動きます。ただし小規模プロジェクト向けにチューニングされた既定設定は、コードベースが育つほど不利に働きます。無関係な命令とファイル読み取りがコンテキストウィンドウを占め、トークンを消費し、性能を落とします。
そもそもセッションは空の状態から始まりません。開始時点でCLAUDE.md、自動メモリ、MCPツールの名前、スキルの説明がすでに載っています。出力スタイルや--append-system-promptがあればそのぶん加算されます。作業が始まればファイル読み取り、パススコープルール、PostToolUseフックの出力が積み上がっていきます。あなたが1文字も打つ前に、消費はもう始まっています。
規模が響いてくる理由は、探し方にもあります。Claude Codeはコードベースの索引を作りません。ファイルシステムを歩き、ファイルを読み、grepで必要な箇所を見つけ、参照をたどる — つまり人間のエンジニアと同じ動き方です。埋め込みパイプラインを回さないので、2週間前に名前を変えた関数を古いまま返してくるような事故は起きません。代わりに、どこを見ればよいかが分かるだけの初期コンテキストを渡さないと成立しません。曖昧なパターンを巨大なコードベース全体から探せと頼めば、作業が始まる前にコンテキストウィンドウの上限に当たります。
対処は8つに整理されていますが、互いに置き換わるものではなく層状に重なります。その最上流に来るのは、設定ファイルではなく「どこでclaudeを起動するか」です。
なお本稿はClaude Code(CLI)の話に限定します。CLAUDE.mdそのものの書き方はCLAUDE.mdを実用に引き上げる10のパターン、記憶の三層構造はClaude Code memoryの三層構造で扱っているので、ここでは階層と読み込みタイミングに絞ります。
どこでclaudeを起動するかで、読み込まれるものが変わる
起動ディレクトリは、追加の許可なしに読み書きできるファイル、起動時に読み込まれるCLAUDE.md、そして適用されるプロジェクト設定の3つを同時に決めます。ドキュメントの表が扱うのは前の2つですが、運用で刺さるのは3つ目です。
| 起動場所 | 読み書きできるファイル | 起動時に読むCLAUDE.md | .claude/settings.json | スコープに入るスキル |
|---|---|---|---|---|
| リポジトリルート | 読み書きできるファイルすべてのファイル | 起動時に読むCLAUDE.mdルートのみ。サブディレクトリのものはClaudeがそこを読むときにオンデマンド | .claude/settings.jsonルートのものが適用される | スコープに入るスキルセッション中に触れる全サブディレクトリ分。数百に蓄積することがある |
| サブディレクトリ | 読み書きできるファイルそのサブツリーのみ(許可を足すまで) | 起動時に読むCLAUDE.mdそのディレクトリと、すべての祖先 | .claude/settings.jsonそのディレクトリのものだけ。親からは継承されない | スコープに入るスキルそのディレクトリ、ルートまでの親、ユーザーとエンタープライズ |
settings.jsonは親から継承されない
.claude/settings.jsonのプロジェクト設定は開始ディレクトリからのみ読み込まれ、CLAUDE.mdのように親ディレクトリから継承されません。リポジトリルートの.claude/settings.jsonは、ルートから開始する場合にのみ適用されます。
この1行が、モノレポ運用で最も踏みやすい段差です。CLAUDE.mdは上へ歩いて全部集めてくれるので、「サブディレクトリから起動してもルートの文脈は失われない」と理解しがちです。それはCLAUDE.mdに限った話です。packages/api/から起動した瞬間、リポジトリルートに置いたpermissionsもフックもプラグイン設定も、丸ごと外れます。読み込まれた気になっているのに実際は空、という状態が一番厄介です。
親ディレクトリを辿ってほしいという要望は、実際にIssueとして上がっています(anthropics/claude-code #12962、2026-07-30時点でOpen)。回避策は3つ挙がっています。全サブディレクトリに設定を複製する、常にリポジトリルートから起動する、~/.claude/settings.jsonに置いて全プロジェクトに適用してしまう。どれも副作用があり、現時点では仕様として受け入れて設計するほうが安全です。
逃げ道は、各サブディレクトリの.claude/settings.jsonをルートに層状に重ねず自己完結させることです。重複は出ますが、起動場所によって挙動が変わる不確実さは消えます。
スキルの数も起動場所で変わる
見落とされがちなのがスキルです。ルートから起動すると、セッション中にClaudeが触れるすべてのサブディレクトリのスキルがスコープに入ります。パッケージごとにスキルを整備しているモノレポでは、これが数百に蓄積することがあります。
Claudeは発見したすべてのスキルの名前と説明を読んで絞り込み、選ばれたものだけを全文で読み込みます。名前は常に読み込まれますが、説明は多くの場合短縮されます。短縮で削られた語がちょうど判定に必要なキーワードだった、という取りこぼしが起きます。説明は短く保ち、「packages/api/でテストを書く、または変更する」のようにリクエストに含まれそうな語を先頭へ置くのが対策になります。
使われていないスキルを洗い出したいときは、OpenTelemetryのログエクスポーターを有効にし、OTEL_LOG_TOOL_DETAILS=1を設定します。skill_activatedイベントがskill.name属性に呼び出しを記録し、invocation_triggerがコマンド・Claude・ネストされたスキルのどれが呼んだかを残します。統合や廃止の判断材料になります。
置き場所ではなくファイルパターンでスコープを絞る手もあります。スキルのpaths: frontmatterにグロブを書くと、リポジトリルートの.claude/skills/に置いたままでも、一致するファイルを扱うときだけ自動で読み込まれます。マイグレーション用のスキルを**/migrations/**に限定する、といった使い方です。
コンテキスト管理は読み込ませない設定3つで決まる
コンテキスト管理の解説は/compactに寄りがちですが、あれは埋まった後の対処です。事前に入れさせない側には独立した設定が3つあり、効く症状がそれぞれ違います。
| 症状 | 効く設定 | 置き場所 | 効かない範囲 |
|---|---|---|---|
| 起動直後から他チームの規約が載っている | 効く設定claudeMdExcludes | 置き場所ユーザー / プロジェクト / ローカル / 管理(配列はスコープ横断でマージ) | 効かない範囲管理ポリシーのCLAUDE.mdは除外できない。タスクごとの切り替えには向かない |
| コミット済みのベンダーコードや生成物を開いてしまう | 効く設定permissions.denyのReadルール | 置き場所起動ディレクトリのsettings.json。全セッション共通にするなら管理設定 | 効かない範囲再帰検索の出力からのフィルタリング、ファイルを自力で開く任意のサブプロセス |
| ワークツリーの作成が遅く、ディスクを食う | 効く設定worktree.sparsePaths | 置き場所起動ディレクトリの設定(スコープ横断でマージ。削除はできない) | 効かない範囲個別ファイルの指定は不可。セッション内の全ワークツリーが同じ値を共有する |
3つは競合しません。claudeMdExcludesが指示側を削り、Read拒否が読み取り側を塞ぎ、sparsePathsがそもそもディスクに置く量を減らします。順に入れていくと、どれがどこまで効いたかを切り分けやすくなります。
claudeMdExcludes — 指示側を削る
リポジトリルートから起動すると、各サブディレクトリのCLAUDE.mdは、Claudeがそのディレクトリ内のファイルを読んだ時点で読み込まれます。claudeMdExcludesはパスまたはグロブパターンで、特定のファイルをスキップします。
{
"claudeMdExcludes": [
"**/packages/admin-dashboard/**",
"**/packages/legacy-*/**"
]
}書式で1つだけ注意点があります。パターンは絶対ファイルパスに対してマッチするため、相対形のつもりで書くときは**/で始めないとツリーのどこにもマッチしません。"**/packages/*/CLAUDE.md"ならルートを残して各パッケージのものだけを外し、"/home/user/monorepo/legacy/CLAUDE.md"のような絶対パスで1ファイルだけを狙うこともできます。
自分だけに適用したいなら.claude/settings.local.jsonに置きます。Claude Codeが自動生成したものは.gitignoreに登録されますが、手で作ったときは自分で追記する必要があります。
除外リストは静的で、タスクごとのスイッチではありません。今日はAPIパッケージ、明日はWebパッケージ、という日替わりの使い分けには向きません。そちらは、目的のパッケージのディレクトリから起動するほうが噛み合います。
Read拒否ルール — 読み取り側を塞ぐ
コンテンツ検索は既定で.gitignoreに従うので、node_modules/やdist/のようにそこへ載っているパスは追加設定なしで検索結果から外れます。問題になるのはチェックインされているほうです。ベンダーSDK、コミットされた生成コード、巨大なスナップショット。これらは.gitignoreにないので、検索が拾えばClaudeは開きます。
{
"permissions": {
"deny": [
"Read(./**/dist/**)",
"Read(./**/build/**)",
"Read(./**/*.generated.*)",
"Read(./vendor/**)"
]
}
}ここで正確に押さえておきたいのが、拒否ルールがカバーする範囲です。対象は、Claudeの組み込みファイルツールと、認識されるBashのファイルコマンド(cat、head、grep、findなど)です。後者が対象になるのは、拒否されたパスが引数として渡される場合です。再帰的検索の出力から拒否パスをフィルタリングすることはありません。ファイルを自力で開く任意のサブプロセスもカバーしません。「読み取り禁止」と一言でまとめると取りこぼす部分です。
起動ディレクトリに関係なく全セッションへ同じ拒否ルールを効かせたい場合は、管理設定で指定します。ユーザー設定とプロジェクト設定はこれを上書きできません。
sparsePaths — 置く量そのものを減らす
--worktreeフラグは新しいgitワークツリーでセッションを開始し、変更をメインチェックアウトから切り離します。既定ではリポジトリ全体をチェックアウトするため、大規模リポジトリでは開始が重くなります。worktree.sparsePathsはgit sparse-checkoutを使い、列挙したディレクトリとルート直下のファイルだけをディスクへ書きます。
{
"worktree": {
"sparsePaths": [
".claude",
"packages/api",
"packages/shared"
],
"symlinkDirectories": [
"node_modules"
]
}
}sparsePathsのパスはリポジトリルート相対で、Claudeを起動するサブディレクトリには依存しません。同じ設定ファイルのadditionalDirectoriesが起動ディレクトリを基準に解決されるのと逆です。並べて書くときは、どちらを基準にした値かを意識しておくと事故が減ります。
sparsePathsで踏みやすい3つの段差
- ディレクトリのみを列挙します。個別ファイルは指定できません。
package.jsonやtsconfig.base.jsonのようなルート直下のファイルは常にチェックアウトされますが、ルート直下のディレクトリはそうではありません。ワークツリー内でリポジトリルートの.claude/settings.json・.claude/rules/・.claude/skills/を使いたいなら、リストに.claudeを含めます - セッション内の全ワークツリーが同じ値を共有します。サブエージェントAが
packages/api/を、サブエージェントBがpackages/web/を必要とするなら、両方を列挙しておく必要があります - ワークツリー作成後、作業ディレクトリはワークツリールートに移ります。起動したサブディレクトリではありません。そのため許可ルールやフックなど、ワークツリー内で効かせたい設定はリポジトリルートの
.claude/settings.jsonに置きます
symlinkDirectoriesはnode_modulesのような重いディレクトリをワークツリーごとに複製せず、メインリポジトリのコピーへシンボリックリンクを張ります。ワークツリーそのものの設計はClaude Code Worktree完全活用で扱っています。
時期によって挙動が変わる落とし穴も残っています。sparseなワークツリーが存在する間、gitは共有.git/configでextensions.worktreeConfigを有効にする必要があります。Claude Codeは最後のワークツリー削除後にそのエントリを消しますが、消すのはClaude Codeが追加した場合だけです。v2.1.207より前は、最後のワークツリーを消してもエントリが残りました。teaのようなgo-gitベースのツールは、git config --unset extensions.worktreeConfigを実行するまでリポジトリを開けません。
ファイル読み取りそのものを言語サーバーに置き換える
3つの除外設定と組み合わせが良いのがコードインテリジェンスです。大規模コードベースでありふれた関数名をgrepすると、何千件も返ってきます。Claudeはどれが本命かを判断するためにファイルを開き、コンテキストを燃やします。言語サーバーは同じシンボルを指す参照だけを返すので、Claudeが何かを読む前の段階で絞り込みが終わります。
/plugin install typescript-lsp@claude-plugins-official公式マーケットプレイスにはTypeScript、Python、Go、Rustなどのプラグインが揃っています。導入には、各開発者のマシンに対象言語の言語サーバーバイナリが必要です。マーケットプレイスからのインストールにはGitHubへのネットワークアクセスも要ります。制限されたネットワークなら、内部Gitホストやローカルパスからマーケットプレイスを追加する経路があります。リポジトリ全員に効かせるなら、個々のインストールではなくenabledPluginsプロジェクト設定に足します。
コスト側から見ても、定義へのジャンプ1回がgrepと複数候補ファイルの読み取りを置き換えるので、削減幅は大きい部類です。同じ発想でフックにも寄せられます。1万行のログをClaudeに読ませてエラーを探させる代わりに、フックがERRORをgrepして一致行だけを返せば、消費は数万トークンから数百まで落ちます。
兄弟パッケージへのアクセスは付与の仕方で中身が変わる
packages/api/から起動すると、そのディレクトリ内は読み書きできます。共有型を更新してapiとwebの両方の呼び出し側を直す、といったパッケージ横断の作業には、兄弟ディレクトリへのアクセスを足す必要があります。別チェックアウトのリポジトリも同じ仕組みです。
方法は2つあります。ファイルアクセスはどちらも同じで、付いてくるものが違います。
| 追加方法 | CLAUDE.mdとルール | スキル |
|---|---|---|
permissions.additionalDirectories設定 | CLAUDE.mdとルール読み込まない | スキル読み込まない |
--add-dirフラグ / /add-dirコマンド | CLAUDE.mdとルール環境変数を設定したときのみ | スキル読み込む |
claude --add-dir ../shared--add-dirや/add-dirで追加したディレクトリからCLAUDE.mdとルールファイルも読み込みたい場合は、CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD環境変数を設定します。この環境変数はadditionalDirectories設定に列挙したディレクトリには効きません。設定ファイル側で足したディレクトリには、規約が付いてきません。
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../sharedこの領域の全員に必要な兄弟ディレクトリは、additionalDirectoriesに書いて.claude/settings.jsonにコミットします。個人的な選択や1回限りのアクセスは、.claude/settings.local.jsonか起動時の--add-dirで済ませます。
階層化したCLAUDE.mdはコンパクションで一部が消える
ここが、ディレクトリごとの階層化を進めたチームがつまずきやすい箇所です。長いセッションがコンパクションされると、指示に何が起きるかはどう読み込まれたかで変わります。
| 読み込まれ方 | コンパクション後 |
|---|---|
| システムプロンプトと出力スタイル | コンパクション後変更なし。メッセージ履歴の一部ではない |
プロジェクトルートのCLAUDE.mdとスコープなしルール | コンパクション後ディスクから再度注入される |
| 自動メモリ | コンパクション後ディスクから再度注入される |
paths: frontmatterを持つルール | コンパクション後一致するファイルが再度読み込まれるまで失われる |
サブディレクトリのネストされたCLAUDE.md | コンパクション後そのサブディレクトリ内のファイルが再度読み込まれるまで失われる |
| 呼び出されたスキル本体 | コンパクション後再度注入される。スキルあたり5,000トークン、合計25,000トークンでキャップ。最も古いものから落ちる |
| フック | コンパクション後適用されない。コンテキストではなくコードとして実行されるため |
理屈は単純です。ルートのCLAUDE.mdとスコープなしルールはディスクから読み直されます。一方、パススコープルールとネストされたCLAUDE.mdは、トリガーとなるファイルが読まれたときにメッセージ履歴へ入ったものです。コンパクションは、これを他のメッセージと一緒にまとめてしまいます。一致するファイルがもう一度読まれるまで戻りません。
大規模コードベースのコンテキスト管理として設計した階層化が、長時間セッションでは自分の首を絞めます。パッケージ固有の規約ほど詳しく書き込んでいるのに、コンパクションを1回挟んだ後半戦ではそれが消えている。どうしてもコンパクションをまたいで残したいルールは、paths: frontmatterを外すか、プロジェクトルートのCLAUDE.mdへ移すのが確実です。階層化の思想とは逆を向く判断ですが、実質は「本当に効かせたいルールを絞り込む」作業になります。
スキル本体も同じ論点を抱えています。再度注入はされるものの、大きなスキルはキャップに収まるようトリミングされます。トリミングはファイルの先頭を保持するので、SKILL.mdの上部に最も重要な指示を置いておくと生き残る確率が上がります。
自分のセッションで何がどれだけ載っているかは/contextで分かります。カテゴリ別の内訳と最適化の提案が出ます。起動時にどのCLAUDE.mdと自動メモリファイルが読み込まれたかは/memoryです。設定を足す前にこの2つで現状を測っておくと、空振りが減ります。
パッケージ境界とサブエージェント境界を合わせる
サブエージェントは、サイドタスクがメイン会話を検索結果やログで溢れさせるときに使う仕組みです。それぞれが独自のコンテキストウィンドウ、システムプロンプト、ツールアクセス、独立した権限を持ちます。大規模コードベースでは「何を境界に切るか」で結果が変わります。
切り分けの材料ははっきりしています。メイン会話に置くのは、頻繁なやり取りや反復改善が要る作業、計画・実装・テストのように複数フェーズが重要コンテキストを共有する作業、素早くターゲットを絞った変更、そしてレイテンシが効く場面です。逆にサブエージェントへ出すのは、詳細な出力がメイン会話に要らない作業です。特定のツール制限や権限を強制したい作業、自己完結していて概要だけ返せばよい作業も同じ側に入ります。
これをモノレポの構造に重ねると、切り方が見えてきます。
- パッケージ単位で切る:
sparsePathsとワークツリー分離の粒度に一致させると、ディスク・権限・コンテキストの3つが同じ境界で揃います。ただしセッション内の全ワークツリーがsparsePathsを共有するので、必要なパッケージは全部列挙しておく必要があります - 変更タイプで切る: 調査を読み取り専用のサブエージェントに任せ、その結果をファイルに書かせてから、メインが全体像を持って編集に入る型です。探索と編集を同じセッションで走らせない、という切り分けになります
- 大量の出力が出る作業で切る: それがメインに要らないなら、境界はここです
一方で、サブエージェントは独立コンテキストという言葉の印象より重い荷物を持って起動します。起動時に読み込まれるのは、システムプロンプト、委譲プロンプト、そしてメイン会話が読み込むメモリ階層のすべてのレベル(~/.claude/CLAUDE.md、プロジェクトルール、CLAUDE.local.md、管理ポリシー)です。加えて、親セッション開始時点のgitステータスのスナップショットとプリロードスキルも載ります。組み込みのExploreとPlanだけが、このCLAUDE.mdとgitステータスを省略します。どのエージェントがスキップするかを変えるfrontmatterフィールドや、エージェント単位の設定は存在しません。外すこと自体はできます。この2つへの委譲をやめるならCLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1で、v2.1.198以降ではClaudeが委譲せずに自分でファイルを読んで探索します。
つまり、「vendor/ディレクトリを無視する」のようなルールをサブエージェントに確実に効かせたいなら、委譲時のプロンプトでもう一度書く必要があります。メイン会話はExploreとPlanの結果を完全なCLAUDE.mdコンテキストで読み込むため、ほとんどのルールはサブエージェント自体に到達しなくても済みます。
数の問題も残ります。詳細な結果を返すサブエージェントを多数走らせると、かなりのコンテキストを消費します。並列化はコンテキスト削減と同義ではありません。設計の型そのものはClaude Code Sub-agents完全ガイドにまとめてあります。
パッケージをまたぐ変更は、計画をファイルへ落としてから着手する
設定はClaudeが見るものを制御しますが、共有型を更新して呼び出し側を全部直すような変更では、タスクの切り方と順序も結果を左右します。使える手は2つです。
1つ目は、変更の全体を1回のセッションでClaudeに渡すことです。共有部分の編集とその呼び出し側を一緒に引き渡すと、各編集の背後にある判断が一貫します。パッケージごとにセッションを切ると、Claudeはそのつど判断を組み立て直し、微妙にずれた実装が並びます。
2つ目は、編集する前に計画をリポジトリのMarkdownファイルへ保存することです。パッケージをまたぐ長いセッションはコンパクションされます。前節で見たとおり、消えるものと残るものがあり、会話の中で組み上げた計画は消える側です。ファイルに書いてあれば、会話履歴が残っていなくても計画は生き残ります。
この2つは矛盾しません。1セッションで渡すのは変更のスコープ、ファイルへ落とすのは判断の記録です。調査と実装を分けて回す設計そのものは、サブエージェントの節で触れた分割境界の話とつながります。
失敗パターンの側から見ると、大規模コードベースで頻出するのは無限探索です。スコープを切らずに「調査して」と頼むと、Claudeは数百ファイルを読んでコンテキストを埋めます。調査の範囲を絞るか、サブエージェントに出すかの二択です。1つのタスクで始め、無関係な依頼を挟み、また元へ戻る型も同じ穴に落ちます。こちらはタスクの切れ目で/clearを入れるのが対処です。
CLAUDE.mdの階層が回らなくなったときに何を替えるか
ディレクトリごとのCLAUDE.mdは、コードベースが育つにつれて管理が難しくなります。規約が漂流し、ファイルが古くなり、誰もルートを所有していない状態。この兆候が出たら、個々の開発者ではなく、リポジトリのClaude Codeセットアップを保守するチームの仕事に移っています。
替え先は、常に読み込まれるCLAUDE.mdから、タスクに関連するときだけ読み込まれる仕組みです。スキルは、必要になったときだけ読み込む参照資料として使えます。プラグインは、スキル・フック・コマンドをバージョン管理されたバンドルにまとめます。MCPサーバーは、組織がすでにコード検索やRAGインデックスを回しているなら、それをツールとして公開する経路になります。
規約をプラグインへ移すと、別の穴が開きます。チームメイトが不慣れな領域でClaudeを起動したとき、その領域の所有者が保守しているプラグインの存在に気づく手段がありません。SessionStartフックがこの隙間を埋められます。フックがstdoutに出力したものは、最初のプロンプトの前にコンテキストへ追加されます。起動ディレクトリを読み取り、リポジトリにコミットしたパスとプラグインの対応表を引いて推奨を出力するスクリプトを、そこへ置いておく組み方になります。
モデルが変わると、いま最適な指示が次の世代では足を引っ張ることがあります。リファクタリングを単一ファイルの変更に分割させるルールは、以前のモデルには効いても、複数ファイルの協調編集をこなせるモデルには制約として働きます。Perforceコードベースでp4 editを強制していたフックが、Claude Codeのネイティブモード追加で不要になった例もあります。3〜6か月ごとに構成を点検しておく想定が示されています。主要なモデルリリース後に性能が頭打ちだと感じたときも、見直しどきです。
ここまでの設定を並べて、あえて優先順位を1つ選ぶなら、除外設定より先に起動場所です。claudeMdExcludesを10行書くより、packages/api/から起動するほうが、外れる範囲は広く、副作用も読みやすい。設定ファイルは増えるほど「どれが効いているか分からない」状態に近づきます。
ただし、これで全部が片付くわけではありません。トップレベルのフォルダが数百ある規模までなら、手当てはあります。各フォルダを1行で説明した軽量なMarkdownをリポジトリルートに置き、ルートには最上位の構造だけを書いて、詳細はサブディレクトリのCLAUDE.mdに持たせる二層構成です。破綻が残るのはその先です。数十万フォルダ・数百万ファイル規模や、git以外のバージョン管理に載ったレガシーシステムでは、階層的なCLAUDE.mdのアプローチ自体が通用しません。この2つはAnthropicのブログが同シリーズの続編で扱うとしており、いまのところ全体解は出ていません。ここに当たっているチームは、既存の手札で凌ぐ設計を自前で組む必要があります。
Claude Code全体の設計思想と各機能の関係はClaude Code完全ガイドにまとめてあります。
よくある質問
コンテキストが足りないとき、まず何を見ればよいですか
/contextを実行すると、現在のコンテキスト使用状況がカラーグリッドとして表示され、カテゴリ別の内訳と最適化の提案が出ます。フルスクリーンモードでは項目ごとの内訳が折りたたまれ、/context allで展開できます。起動時に読み込まれたCLAUDE.mdと自動メモリファイルの一覧は/memoryで確認できます。
/clearと/compactはどう使い分けますか
関係のないタスクへ切り替えるときは/clearです。エイリアスとして/resetと/newも使えます。同じ会話を続けながらコンテキストだけを解放したい場合は/compactを選びます。/compact focus on the auth bug fixのように指示を添えると、自動に任せたときの推測ではなく、自分で選んだものが要約に残ります。
CLAUDE.mdを@pathで分割すればコンテキストは減りますか
減りません。インポート先も起動時に読み込まれるためです。目安として、200行を超えるファイルはより多くのコンテキストを消費し、指示の遵守率が下がる可能性があるとされています。なお、ブロックレベルのHTMLコメント(<!-- maintainer notes -->)はコンテキストへ注入される前に削除されるので、保守用のメモはそこへ逃がせます。
1Mコンテキストのモデルを使えば設定は要らなくなりますか
ウィンドウが広がっても、無関係な内容を読み込む構造はそのままです。Fable 5、Sonnet 5、Opus 4.6以降、Sonnet 4.6は100万トークンのコンテキストウィンドウに対応し、Sonnet 5は[1m]バリアントを選ばなくても1Mで動きます。コンパクションの挙動は、上限が大きくても同じです。広いウィンドウは無関係な読み込みを許容する余地を増やすだけで、削る設計の必要性は変わりません。1Mを実務で使うときの勘所はClaude 1Mコンテキストの実務活用で扱っています。
MCPサーバーを増やすとコンテキストを圧迫しますか
MCPツールの定義は既定で遅延読み込みされ、使うまではツール名だけがコンテキストに入ります。とはいえgh・aws・gcloud・sentry-cliのようなCLIのほうがMCPよりコンテキスト効率が高い場面はあり、使っていないサーバーは/mcpで無効化できます。MCPの出力上限はMAX_MCP_OUTPUT_TOKENSが持ちます。既定は25,000トークンで、10,000トークンを超えると警告が出ます。
ディレクトリごとのCLAUDE.mdとパススコープルールはどちらを使いますか
ディレクトリの所有者が自分の規約を保守し、命令をコードと一緒にバージョン管理したいならディレクトリごとのCLAUDE.mdです。すべての規約を1か所に置きたい、または同じルールが散在する多くのパスに適用されるなら、リポジトリルートの.claude/rules/に置くパススコープルールが向きます。読み込まれるタイミングも違い、前者はそのディレクトリから起動したときか、オンデマンド、後者はpaths:グロブに一致するファイルでClaudeが動くときです。
まとめ
大規模コードベースでのコンテキスト管理は、/compactの使いこなしより手前の設計で決まります。起動場所がCLAUDE.mdとプロジェクト設定とスキルのスコープを一度に定め、そこにclaudeMdExcludes・Read拒否・sparsePathsの3つが症状ごとに重なる。この順で入れると、どこまで効いたかを切り分けられます。
同時に、階層化には代償があります。パススコープルールとネストされたCLAUDE.mdはコンパクションで失われ、サブエージェントにはメモリ階層が丸ごと載る。階層を細かくするほど、長時間セッションでの再現性は落ちていきます。残したいルールをルートへ引き上げる判断と、パッケージ境界をサブエージェントとワークツリーの境界に揃える設計が、そのぶんだけ効いてきます。
関連する記事
Claude Code をもっと見る →Claude Codeとは — Anthropicのエージェント型AIコーディングCLI完全ガイド
Claude Codeベストプラクティス — Anthropicが示す自走エージェントの設計原則と運用パターン
Claude Codeのエージェント設計パターン — 分割の判断基準と報告フォーマットの作り方
Claude Codeオーケストレーター設計 — メインを指揮に回し、サブエージェントに実務を任せる
ダイナミックワークフローとは — Claude Codeが数百のサブエージェントを並列で束ねる新機能の仕組みと使い方
Claude Codeプラグイン(Plugins)完全ガイド — /pluginの使い方・マーケットプレイス・自作と配布