こんにちは。よっしーです(^^)
背景
この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。
1. 一言でいうと何か
このページは、Claude Code のコンテキストウィンドウが1セッションのあいだにどう埋まっていくかを、起動からコンパクションまで通して見せるものです。
定義から入ります。Claude Code のコンテキストウィンドウには、セッションについて Claude が知っているすべてのものが含まれます。つまり、あなたの指示、読み込まれたファイル、Claude 自身の応答、およびターミナルに表示されないコンテンツです。
最後の一節がこのページの主題です。**ターミナルに表示されないコンテンツ。**あなたが画面で見ているものと、Claude が見ているものは、量も中身も一致していません。
そしてこのページは他のページと形が違います。本文の中心がインタラクティブなタイムライン——起動からコンパクションまでを再生するシミュレーションで、各イベントにトークン数と解説が紐づいています。原文はこう案内しています。以下のタイムラインは、スタートアップからコンパクションまでの完全なセッションを再生します。何が読み込まれ、各ファイル読み込み、ルール、フックが Claude の作業中に追加するもの、そしてサブエージェントが大きな読み込みをコンテキストから外す方法を確認できます。
数値の扱いについて、原文自身が注記しています。ビジュアライゼーションは代表的な数値を使用しています。実際の値は CLAUDE.md の大きさ、MCP サーバー、ファイルの長さで変わります。本記事で挙げる数字もあくまで例示です。
2. どういう場面で役立つか
シーン1：「何も入力していないのに、もう重い」の理由を知る
タイムラインの最初のセクションのタイトルが答えです——Before you type anything（何も入力する前に）。
**CLAUDE.md、自動メモリ、MCP ツール名、スキルの説明がすべてコンテキストに読み込まれます。**例示された数値の合計は約7,850トークン。プロンプトを1文字も打つ前の状態です。
シーン2：コンテキストを食っている犯人を特定する
タイムラインを追うと、最大の消費源はファイル読み込みだと分かります。原文のヒントも直球です。File reads dominate context usage（ファイル読み込みがコンテキスト使用を支配する）。
シーン3：サブエージェントの節約効果を数字で理解する
第9回のサブエージェントが「なぜコンテキストを節約するのか」は、ここで初めて数量的に示されます。サブエージェントは6,100トークンのファイルを読み、あなたが受け取ったのは420トークンの結果。それが節約分です。
シーン4：コンパクション後に何が消えるかを事前に知る
「コンパクション後に残るもの」の表が、このページで最も実用価値の高い部分です。設計判断——ルールを paths: にするか CLAUDE.md に書くか、スキルの指示をどこに置くか——が、この表で変わります。
不要・向かないケース
- 自分の実際の使用量を知りたい。このページの数字は例示です。
/contextを実行して、カテゴリ別の詳細な内訳と最適化の提案を取得してください。 - スマートフォンで読みたい。原文のシミュレーションは700px 未満では非表示になり、「大きい画面で見るか、下の書かれた説明を読め」というフォールバックが出ます。
- **コンパクションを止めたい。**止められません。Claude Code はコンテキストウィンドウの制限に近づくと自動的にコンパクションを実行するため、コンテキストウィンドウがいっぱいになってもセッションが終了することはありません。変えられるのはいつ走るか（
/autocompact）だけです。 - **より大きいウィンドウが欲しいが、モデルを変えたくない。**1Mトークンは対応モデル限定です（後述）。
3. タイムラインが示す中身の解説
このページには読者向けのコードブロックが1つもありません。本文の大半はシミュレーションの実装コードで、これは読者が書き写すものではないため引用しません。代わりに、その中に埋め込まれたイベントごとのトークン数と説明を表と散文に再編します。原文の説明は英語のまま埋め込まれているため、事実を変えずに日本語で示します。
前提：数値はすべて例示。コンパクション時の拡張思考の継承は v2.1.198 以降の挙動です。
可視性という軸
タイムラインは各イベントに3段階の可視性を付けています。ここがこのページ独自の視点です。
| 記号 | 意味 | 内容 |
|---|---|---|
| ○ | ターミナルに出ない | 内容はまったく表示されない |
| ◐ | 1行だけ出る | 短い言及のみ。中身は見えない |
| ● | ターミナルに出る | 実際の内容が表示される |
**Claude のコンテキストの大半は「○」と「◐」です。**あなたが読んでいるのは氷山の一角、という構図がこの軸で可視化されます。
起動時に自動で載るもの
プロンプトを打つ前に載る7項目（例示のトークン数付き）。
| 項目 | 例示トークン | 可視性 | 中身 |
|---|---|---|---|
| システムプロンプト | 4,200 | ○ | 振る舞い・ツール利用・応答整形の中核指示。常に最初に読み込まれ、あなたは決して見ない |
| 自動メモリ（MEMORY.md） | 680 | ○ | 前のセッションから Claude が自分宛てに残したメモ |
| 環境情報 | 280 | ○ | 作業ディレクトリ、プラットフォーム、シェル、OS、git リポジトリか否か |
| MCP ツール（遅延） | 120 | ○ | ツール名だけ。スキーマは既定で遅延読み込み |
| スキルの説明 | 450 | ○ | 各スキルの1行説明。本体は実際に使うときだけ載る |
~/.claude/CLAUDE.md | 320 | ○ | 全プロジェクト共通の個人設定 |
| プロジェクト CLAUDE.md | 1,800 | ○ | プロジェクトの規約・ビルドコマンド・アーキテクチャ |
合計で約7,850トークン。全部「○」——ターミナルには1行も出ません。
細部に重要な仕様が埋まっているので、4つ拾います。
**自動メモリには上限がある。**最初の200行または25KB のいずれか早いほうがコンテキストに読み込まれます。
MCP のスキーマは既定で遅延。既定ではフルスキーマは遅延のままで、タスクが必要とするときに Claude がツール検索で個別に読み込みます。変更したい場合はENABLE_TOOL_SEARCH=auto を設定すると、コンテキストウィンドウの10%以内に収まる場合に事前読み込み、ENABLE_TOOL_SEARCH=false ですべて読み込み。第55回・第62回で触れたツール検索の、コンテキスト側から見た姿です。
**スキル説明のリストには例外がある。****disable-model-invocation: true のスキルはこのリストに入りません。/name で呼び出すまで完全にコンテキストの外に留まります。**さらに——起動時コンテンツの中でこれだけは /compact 後に再注入されません。実際に呼び出したスキルだけが保持されます。
**プロジェクト CLAUDE.md には推奨サイズがある。**200行以内に保つこと。参照系の内容はスキルやパススコープ付きルールに移して、必要なときだけ読み込まれるようにする。
作業中に積み上がるもの
最初のプロンプト（例示45トークン）を送ると、Claude が働き始めます。原文の要約はこうです。あなたのプロンプトは、すでに読み込まれているものに比べて極めて小さい。Claude のコンテキストの大半は、あなたの言葉ではなくプロジェクトの知識です。
以降の流れ（例示）。
| イベント | 例示トークン | 可視性 |
|---|---|---|
src/api/auth.ts を読む | 2,400 | ◐ |
src/lib/tokens.ts を読む | 1,100 | ◐ |
ルール api-conventions.md 自動読込 | 380 | ◐ |
middleware.ts を読む | 1,800 | ◐ |
auth.test.ts を読む | 1,600 | ◐ |
ルール testing.md 自動読込 | 290 | ◐ |
grep "refreshToken" | 600 | ◐ |
| Claude の分析 | 800 | ● |
auth.ts を編集 | 400 | ● |
| フック: prettier | 120 | ○ |
auth.test.ts を編集 | 600 | ● |
| フック: prettier | 100 | ○ |
npm test の出力 | 1,200 | ◐ |
| まとめ | 400 | ● |
ファイル読み込みだけで6,900トークン——起動時の全自動読込に匹敵します。原文のヒントは実務的です。プロンプトで具体的に書けば（「auth.ts のバグを直して」など）、Claude が読むファイルは減ります。調査が重いタスクにはサブエージェントを使ってください。
パススコープ付きルールの挙動も、ここで初めて動きとして示されます。api-conventions.md は**.claude/rules/ にあり、paths: パターンが src/api/** に一致するため、Claude がそのディレクトリのファイルを読んだ時点で自動的に読み込まれたものです。ターミナルには「Loaded .claude/rules/api-conventions.md」という1行だけが出て、ルールの中身は見えません。**
フックの挙動は、ここが連載で最も具体的な記述です。PostToolUse フックが prettier を走らせ、結果を返すとき——hookSpecificOutput.additionalContext 経由で報告します。このフィールドが Claude のコンテキストに入ります。終了コード0での素の stdout は入りません。デバッグログにのみ書き込まれます。
さらにヒントとして3点。Claude に情報を送るには additionalContext を含む JSON を出力する。PostToolUse フックでは終了コード2は stderr をエラーとして表面化させるが、ツールは既に実行済みなのでブロックはできない。10,000文字を超える出力はファイルに保存され、Claude にはプレビューとファイルパスが渡される。
**「フックの出力が Claude に届かない」**というトラブルの原因が、ここに全部書かれています。
サブエージェントは別のウィンドウを持つ
2つ目のプロンプト——「サブエージェントを使ってセッションタイムアウト処理を調査してから直して」——で、節約の仕組みが可視化されます。
生成されたサブエージェントが自分のコンテキストに積むもの（例示）。
| サブエージェント側の項目 | 例示トークン |
|---|---|
| システムプロンプト（メインより短い） | 900 |
| プロジェクト CLAUDE.md（自前のコピー） | 1,800 |
| MCP ツール ＋ スキル | 970 |
| メインからのタスクプロンプト | 120 |
session.ts を読む | 2,200 |
timeouts.ts を読む | 800 |
config/*.ts を読む | 3,100 |
**合計9,890トークン。そのうちファイル読み込みが6,100トークン。**そしてメイン側に戻ってくるのは——サブエージェントの最終テキスト応答と、トークン数と所要時間を含む小さなメタデータトレーラーだけ。例示で420トークン。
**6,100トークン読んで、420トークンだけ返す。**これが節約の実体です。
継承関係にも細かい規定があります。**サブエージェントは CLAUDE.md、同じ MCP とスキルの構成を読み込みますが、あなたの会話履歴やメインセッションの自動メモリなしで始まります。**例外もあります。組み込みの Explore と Plan エージェントは、コンテキストを小さく保つため CLAUDE.md を読み込みません。カスタムエージェントが frontmatter に memory: を持つ場合は自前の MEMORY.md をここで読み込みます。
ツールも完全に同じではありません。親のツールのほとんどを得ますが、ネストされた文脈で適用されないものは除かれます。プランモード制御、バックグラウンドタスクツール、そして再帰を防ぐため既定では Agent ツール自体。
! と / — 2つの特殊な入力
タイムラインは、ユーザー入力の2つの形も扱っています。
!git status（例示180トークン、●）——! 接頭辞でシェルコマンドを実行しました。コマンドとその出力は、両方ともあなたのメッセージの一部としてコンテキストに入ります。Claude に実行させずにコマンド出力で Claude を地に足つかせるのに有用です。
/commit-push（例示620トークン、◐）——**disable-model-invocation: true を持つスキルを呼び出しました。その説明は起動時のスキルインデックスに入っていなかったので、この瞬間までコンテキストコストはゼロでした。**そして呼び出した今、本体が読み込まれます。
原文のヒントが具体的です。**コミット、デプロイ、メッセージ送信のような副作用のあるスキルには disable-model-invocation: true を設定してください。必要になるまで完全にコンテキストの外に留まります。**第55回・第59回で見たスキル設計の指針が、コンテキスト観点から裏付けられた形です。
コンパクション後に残るもの
ここが本ページの核心です。各種コンテンツに何が起こるかは、それらがどのように読み込まれたかによって異なります。
| メカニズム | コンパクション後 |
|---|---|
| システムプロンプトと出力スタイル | 両方とも引き続き適用されます |
| プロジェクトルート CLAUDE.md とスコープなしルール | ディスクから再度注入されます |
| 自動メモリ | ディスクから再度注入されます |
| plan mode で Claude が作成したプラン | ディスクから再度注入されます |
paths: frontmatter を持つルール | Claude がそれらが一致するファイルを読み込むときに Claude Code が再度読み込みます |
| サブディレクトリ内のネストされた CLAUDE.md | Claude Code がそのサブディレクトリ内のファイルを読み込むときに再度読み込みます |
| Claude が読み込んだまたは編集したファイル | Claude Code は最大5つを再度読み込みます。最近変更されたものが最初です |
| 呼び出されたスキル本体 | 再度注入されます。スキルあたり5,000トークン、合計25,000トークンでキャップされます。最も古いものが最初にドロップされます |
| フックが以前に追加したコンテキスト | 会話の残りの部分と一緒にまとめられます |
compact ソースと一致する SessionStart フック | Claude Code がそれらを実行し、その出力をコンパクションされたコンテキストに追加します |
理由が明快に説明されています。パススコープ付きルールとネストされた CLAUDE.md ファイルは、トリガーファイルが読み込まれるときにメッセージ履歴に読み込まれるため、コンパクションはそれらを他のすべてのものと一緒にまとめます。
つまり**「起動時にディスクから載るもの」は復活し、「作業中に会話へ差し込まれたもの」は要約に潰れる。**この一線がすべてを決めています。
そして設計上の助言が続きます。ルールがコンパクション全体で永続化する必要がある場合は、paths: frontmatter をドロップするか、プロジェクトルート CLAUDE.md に移動してください。
ファイル再読込にも条件があります。コンパクション直後に、Claude Code はセッション内で Claude が読み込んだまたは編集したファイルのうち最大5つを再度読み込みます。ただし5,000トークンを超えるファイルは、パス参照として戻ります。その内容なしで、Referenced file として表示されます。そのルールは依然として再度読み込みます。
スキル本体にも、もう一段の助言があります。大きなスキルはスキルあたりのキャップに収まるようにトリミングされ、合計予算を超えると最も古い呼び出されたスキルがドロップされます。トリミングはファイルの開始を保持するため、SKILL.md の上部に最も重要な指示を配置してください。
SKILL.md は上から大事な順に書け——コンパクション時のトリミング仕様から導かれる、具体的な執筆指針です。
最後に、要約処理そのものの挙動。v2.1.198 以降、要約リクエストはセッションの拡張思考設定を継承するため、セッションで有効になっている場合は思考を有効にして推論し、そうでない場合はオフのままになります。思考は要約の生成方法にのみ影響します。セッション設定はその後変更されません。
満杯になる前に手を打つ
自動コンパクションは避けられませんが、先回りはできます。原文が挙げる5手を整理します。
| 手 | やり方 | 効果 |
|---|---|---|
| フォーカスを絞ってコンパクション | /compact focus on the auth bug fix のように指示付きで実行 | 自動パスが重要だと推測するものではなく、あなたが選択したものを保持します |
| 会話の一部をコンパクション | /rewind でメッセージを選び「ここから要約」「ここまで要約」 | 片側だけを圧縮（第69回） |
| より早くコンパクション | /autocompact 500k のようにトークン数付きで実行 | 自動パスが実行される前にコンテキストウィンドウがどの程度いっぱいになるかを設定 |
| タスク間でクリア | 無関係な作業に移るとき /clear | 古い会話は次に必要なファイルを圧迫し、すべてのメッセージでトークンを消費します |
| 大きな読み込みを委譲 | 調査をサブエージェントへ | ファイル内容が自分のウィンドウに入らない |
ウィンドウそのものを大きくする
より小さな会話ではなく、より大きなウィンドウが必要な場合、Fable モデル、Sonnet 5、Opus 4.6 以降、および Sonnet 4.6 は100万トークンのコンテキストウィンドウをサポートしています。
1つ扱いが違うモデルがあります。**Sonnet 5 は 1M コンテキストウィンドウで実行され、選択する [1m] バリアントはありません。**他は [1m] バリアントを選ぶ形です。
なお**コンパクションはより大きな制限でも同じ方法で機能します。**1Mにしてもコンパクションは無くなりません。
自動コンパクションが走る地点は固定ではありません。あなたのモデルと設定によって異なります。そしてClaude Code があなたのモデル ID（LLM ゲートウェイエイリアスなど）に対して間違ったウィンドウを想定している場合の修正手順も用意されています——ゲートウェイ利用者は、ここを確認する必要があります。
自分のセッションを測る
任意の時点でのあなたの実際のコンテキスト使用状況を確認するには、/context を実行して、カテゴリ別の詳細な内訳と最適化の提案を取得してください。これには、どの CLAUDE.md と自動メモリファイルが読み込まれたかが含まれます。編集するなら/memory を実行して、これらのファイルを開いて編集してください。
**このページを読んだら /context を叩く。**それがこのページの正しい使い方です。
4. まとめ ＋ 次回予告
- コンテキストウィンドウにはあなたの指示、読み込まれたファイル、Claude の応答、そしてターミナルに表示されないコンテンツが入る。見えているものは一部。
- 可視性は3段階——ターミナルに出ない／1行だけ出る／内容が出る。起動時コンテンツは全部「出ない」。
- プロンプトを打つ前に約7,850トークン（例示）が載っている。内訳はシステムプロンプト・自動メモリ・環境情報・MCP ツール名・スキル説明・個人 CLAUDE.md・プロジェクト CLAUDE.md。
- 自動メモリは最初の200行または25KB まで。
- MCP スキーマは既定で遅延。
ENABLE_TOOL_SEARCH=autoで「コンテキストの10%以内なら事前読込」、=falseで全読込。 - **
disable-model-invocation: trueのスキルは起動時リストに載らず、呼ぶまでコストゼロ。**副作用のあるスキル（コミット・デプロイ・送信）はこれにする。 - プロジェクト CLAUDE.md は200行以内が推奨。参照系はスキルかパススコープ付きルールへ。
- **最大の消費源はファイル読み込み。**プロンプトを具体的に書くほど読むファイルが減る。
- **パススコープ付きルールは、一致するファイルを読んだ瞬間に自動で載る。**ターミナルには「Loaded」の1行だけ。
- **フックの出力が Claude に届くのは
hookSpecificOutput.additionalContext経由だけ。**終了コード0の素の stdout はデバッグログ行き。10,000文字超はファイル化され、プレビューとパスだけが渡る。 - **サブエージェントは別のウィンドウ。**例示では6,100トークン読んで420トークンだけ返す。**メインの自動メモリと会話履歴は継承しない。**Explore と Plan は CLAUDE.md も読まない。
- コンパクションの分かれ目は**「ディスクから載るもの」か「会話に差し込まれたもの」か。**前者は復活し、後者は要約に潰れる。
paths:ルールを恒久化したいなら、paths:を外すかプロジェクトルート CLAUDE.md に移す。- コンパクション後の再読込は最大5ファイル（最近変更順）。5,000トークン超は
Referenced fileとして中身なしで戻る。 - 呼び出したスキル本体は再注入されるが1スキル5,000／合計25,000トークンでキャップ、古い順にドロップ。トリミングは先頭を残すので、SKILL.md は上から重要な順に書く。
- 先回りの手は5つ——指示付き
/compact／/rewindの部分要約 ／/autocompact <tokens>／/clear／ サブエージェントへの委譲。 - 1Mウィンドウは Fable・Sonnet 5・Opus 4.6以降・Sonnet 4.6。**Sonnet 5 だけは
[1m]バリアントが無く、常に1M。**大きくしてもコンパクションは働く。 - 数字はすべて例示。自分の実測は
/context、編集は/memory。
次回予告（暫定）：今回コンパクションの挙動が繰り返し参照していた**Claude Code の仕組み（how-claude-code-works）**を取り上げ、コンテキストウィンドウが満杯になったときに内部で何が起きるかを扱う予定です。
何か質問や相談があれば、コメントをお願いします。また、エンジニア案件の相談にも随時対応していますので、お気軽にお問い合わせください。
それでは、また明日お会いしましょう(^^)
コメント