Claude Code が 1 つのセッションの間に記憶するすべてが収まる空間、コンテキストウィンドウ (context window) と、それを効率的に管理する方法を整理します。

背景リファレンス

このページは、MoAI-ADK が動作する基盤である Claude Code そのもの を解説する背景資料です。MoAI-ADK の使い方は トークン予算管理と安全な中止 で扱います。

情報

ひとことで言うと: コンテキストウィンドウは Claude の 作業デスク であり、トークンコストが発生する台帳です。デスクが満杯になる前に自動圧縮 (compaction) と /clear で空間を空けることで、長い作業が品質とコストの両面で最後まで滑らかに流れます。

たとえで理解する

コンテキストウィンドウを デスクの大きさとして想像してみてください。作業する書類 (ファイル・対話) をデスクの上に広げて仕事をしますが、デスクは無限ではありません。デスクが満杯になったら古い書類を 要約して引き出しにしまうことが圧縮 (compaction) で、デスクをまるごと片づけて新しく始めることが /clear です。デスクが広くてもガラクタで埋めると、いま見るべき書類が押し出されてしまうので、大きさを増やすより 載せておく量を減らすことが肝心です。

コンテキストウィンドウは、Claude が 1 セッションで同時に「見られる」情報の総量です。ここにはユーザーが入力したプロンプトだけでなく、ターミナルに表示されない内容まですべて含まれます。

トークン (token) はこの情報を数える単位です。おおよそ英単語 1 つが 1~2 トークンで、韓国語や日本語は 1 文字あたりより多くのトークンを占めます。直感に反する事実が 1 つあります。セッションを始める前からすでにかなりの量が埋まっている という点です。CLAUDE.md、メモリ、スキル一覧、MCP のツール名が最初のプロンプトより先にロードされるからです。

Claude が作業しながら読むファイルが、コンテキスト使用量を支配します。だからプロンプトを具体的に書き (「auth.ts のバグを直して」)、Claude が読むファイル数を減らすことがトークン節約の核心です。リサーチのようにファイルを大量に漁る作業はサブエージェント (subagent) に委任すると、大きなファイルの読み取りが別のコンテキストウィンドウで処理され、結果の要約だけがメインセッションに戻ります。

コンテキストウィンドウのサイズはモデルによって異なります。正確な数値は使用するモデル次第なので、以下は一般論として理解してください。

サイズが大きいほど一度により多くのファイルと会話を収められますが、ウィンドウは無限ではありません。どのモデルを使っても限界に近づけば管理が必要です。重要な原則は、ウィンドウのサイズを増やすことより、入れる内容を少なく保つこと のほうが安定するという点です。

セッションが長くなるとコンテキストが限界に近づきます。Claude Code はこれを 2 つの方法で扱います。

圧縮は蓄積された会話履歴を 1 つの構造化された要約に置き換えて 空間を確保します。/compact を直接実行することも、コンテキストが限界に近づくと自動で起きることもあります。要約は次を保存します。

• ユーザーのリクエストと意図
• 主要な技術概念
• 参照または修正したファイルと重要なコード片
• 発生したエラーと解決方法
• 残りの作業と現在の進行状況

その代わり、全ツール出力と中間の推論過程は消えます。Claude は作業内容を参照できますが、以前に読んだコードの原文をそのまま保持してはいません。

圧縮後に各情報がどうなるかは、ロード方式によって異なります。

圧縮を生き延びてほしいルールなら、paths: フロントマターを外すか、プロジェクトルートの CLAUDE.md へ移しましょう。スキルは切り詰め時に冒頭が残るため、重要な指示は SKILL.md の上部に置くのが安全です。

自動圧縮のタイミングを調整したい場合は、環境変数 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE でしきい値 (デフォルト: 全コンテキスト比で約 75~80%) を変更できます。たとえば余裕を持って圧縮したいなら、より低い値を指定します。

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70  # 70%で圧縮開始

/clear は圧縮とは異なります。要約すら残さず会話コンテキストを丸ごと空にし、新しいセッションのように 始めます。直前の作業と無関係な新しい作業へ移るときに最もクリーンです。要約 (圧縮) は「続けてさらに作業するとき」、初期化 (/clear) は「トピックを変えるとき」に使うと覚えておけばよいでしょう。

flowchart TD
    A[セッション開始
CLAUDE.md・メモリを自動ロード] --> B[作業進行
ファイル読み取り・応答の蓄積]
    B --> C{コンテキストが
限界に接近?}
    C -->|いいえ| B
    C -->|続けて作業| D[圧縮
会話を要約に置き換え]
    C -->|トピック転換| E[/clear
コンテキストを全消去/]
    D --> F[作業継続
要約 + 自動再注入の上で]
    E --> F

いまコンテキストがどれだけ埋まっているかを知らなければ管理できません。Claude Code は実測ツールを提供します。

長い作業に入る前や途中で /context を一度実行し、どの項目がコンテキストを占めているかを確認する習慣が大きな差を生みます。

大規模な作業ほどコンテキストが第一の制約です。次の戦略を組み合わせれば、1 つの作業を複数の圧縮境界を越えて安定して続けられます。

• 要約してから続ける: 1 つの段階を終えたら圧縮で整理し、続く段階は要約の上で進めます。
• サブエージェントで分離: ファイルを大量に読む必要のある探索・リサーチはサブエージェントに任せ、メインセッションのコンテキストを守ります。
• メモリにチェックポイントを残す: 重要な決定と進行状況はメモリに記録し、圧縮や /clear を越えて生き残らせます。これはチェックポインティング (checkpointing) とともに長いセッションの連続性を支えます。
• CLAUDE.md のダイエット: プロジェクトの CLAUDE.md は 200 行以下に保ち、参照用の内容はスキルやパススコープのルールへ移して、必要なときだけロードされるようにします。
• プロンプトを具体的に: 読むファイルを絞り、不要なファイル読み取りを減らします。

このうちメモリとチェックポイントは、MoAI-ADK の SPEC ワークフローおよびセッションハンドオフと直接かみ合います。MoAI-ADK はこのページの原理を コンテキストダイエット (context diet) という名の運用規律へ拡張します — 常時ロードされる指針を最小化し、モデル別のしきい値 (1M コンテキストモデルは使用量 50%、200K モデルは 90%) で進行状態をディスクへ保存し、貼り付け 1 回で次のセッションを続けられるセッションハンドオフを提供し、statusline にコンテキスト使用率 (CW%) を常時表示してしきい値への接近を事前に知らせます。ここでは「コンテキストが埋まる前に先に空け、重要な状態はディスクに残す」というベストプラクティス (best practices) だけ覚えておけば十分です。

• メモリと自動メモリ
• チェックポインティング

• Claude Code Docs — Context window

ヒント

新しい作業を始める直前に /clear を一度実行しましょう。前の作業のファイル読み取りと会話が積み上がったまま新しい作業に入ると、無関係なトークンがデスクを占め、応答品質とコストの両方が悪化します。