Claude Code コンテキストバッファ

167Kトークンに達する。Claude がコンパクションする。コンテキストが失われる。毎回。必ず。

厄介な点はこうだ: コンテキストウィンドウの一部は使用できない状態に保たれており、Claude Code 自体が予約している。そのスペースはかつて45,000トークン（200Kの22.5%）だった。2026年初頭、バッファは約33,000トークン（16.5%）に削減され、実際の作業に使える約12Kのトークンが解放された。

この変更は公式の Claude Code チェンジログには記載されていない。最も近い手がかりはv2.1.21の「大出力トークン制限を持つモデルで自動コンパクションが早く発動しすぎる問題を修正」という記述で、これがバッファ計算を再調整したと思われる。オンラインの投稿やドキュメントでは今でも45Kという数値が使われているが、現在のバージョンでは /context が33Kと表示される。

バッファには正当な理由がある。その仕組みを正確に理解することが、システムと戦う人とシステムとともに働く人を分ける。

バッファ自体が問題になっているとき（コンパクションが発動するタイミング、予約スペースが存在する理由、実際に変化する環境変数）はこのページを読んでほしい。より大きなウィンドウのワークフローへの影響を知りたければ、Claude Code の1Mコンテキストウィンドウを読んでほしい。セッションを継続すべきかリセットすべきかの実用的なルールについては、コンテキスト管理を読んでほしい。

自動コンパクションの実際の仕組み

コンテキストの使用量は Claude Code によって継続的に監視されている。合計ウィンドウの約83.5%（以前の約77〜78%から上昇）に達すると、自動コンパクションが作動する。

その流れは以下の通り:

1. Claude が会話履歴を要約する
2. 古いメッセージが凝縮された要約に置き換えられる
3. セッション初期の細かい詳細が失われる
4. コンテキストを縮小した状態でセッションが継続される

200Kウィンドウでは、コンパクションは実使用約167Kトークン付近で発生する。33Kのバッファは何もしていない状態で待機しているわけではない。Claude はそれを要約処理自体に使う。

/context コマンド

/context を実行すると、トークンがどこに使われているかが正確にわかる:

claude-opus-4-5-20251101 · 76k/200k tokens (38%)

System prompt: 2.7k tokens (1.3%)
System tools: 16.8k tokens (8.4%)
Custom agents: 1.3k tokens (0.7%)
Memory files: 7.4k tokens (3.7%)
Skills: 1.0k tokens (0.5%)
Messages: 9.6k tokens (4.8%)
Free space: 118k (58.9%)
Autocompact buffer: 33.0k tokens (16.5%)

Messages の行が会話履歴だ。これが増えていくのを見守ること。空きスペースがゼロ（バッファを含む）になると、コンパクションが発動する。

バッファが存在する理由

この約33Kには3つの役割がある:

1. コンパクション処理のためのワーキングスペース。要約処理自体がトークンを必要とする
2. 完了バッファ。コンパクションが発動する前に現在のタスクを終了させる
3. レスポンス生成スペース。Claude が推論してレスポンスを構築するためのワーキングメモリが必要

バッファは Claude Code のアーキテクチャに組み込まれている。設定可能にするよう求めるリクエストは重複として却下されている。GitHub Issue #15435 がこれを求めた。答えはノーだった。

アウトプットトークンの誤解

多くの開発者は CLAUDE_CODE_MAX_OUTPUT_TOKENS がコンパクションバッファを制御していると思っている。

違う。

2つは別々のメカニズムで、重複はゼロ:

• アウトプットトークン。単一の Claude レスポンスの最大長を制限する
• コンパクションバッファ。自動コンパクションをトリガーする予約済みコンテキストスペース

CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000 と設定すれば、Claude の最大レスポンス長は縮小する。コンパクション前のコンテキストは変わらない。33Kバッファは固定だ。

# This limits response length, NOT context buffer
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000

アウトプットトークンを下げる理由:

• より速いレスポンス（生成量が少ない）
• レスポンスあたりのコスト削減
• 簡潔さの強制

コンパクション前の使用可能なコンテキストは? 依然として約167K。

1つ注記すべき点: CLAUDE_CODE_MAX_OUTPUT_TOKENS はコンパクションバッファには影響しないが、これを非常に高く設定すると、_実効_コンテキストウィンドウが縮小する可能性がある。アウトプットトークンは同じコンテキストプールから取られるため、アウトプット予約が大きくなるほど履歴とシステムコンテキストの領域が減る。32Kのデフォルトはほとんどのワークフローで適切なバランスを保っている。

実際の影響

典型的なヘビーセッションの状況:

33Kバッファでは、コンパクションは167Kで発生する。これが作業の上限で、以前の155Kより12K高い。

情報はどこへ行くか? 要約の中へ。セッション初期の正確な変数名、精確なエラーメッセージ、微妙な選択がすべて、要旨は捉えるが詳細を失う要約に押し込められる。

実際にコントロールできること

1. コンパクション発動パーセンテージのオーバーライド

自動コンパクションの発動タイミングを実際に変える環境変数が1つある: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE。

# Trigger compaction at 90% instead of the default ~83.5%
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=90
 
# Trigger earlier at 70% for more aggressive compaction
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70

1から100までの値が受け付けられる。この数値は自動コンパクションが発動するパーセンテージを直接設定する。高い設定ではコンパクション前の使用可能なコンテキストが増え、要約処理のためのスペースが減る。低い設定ではコンパクションが早く発動し、ワーキングスペースが多く残るが、最初のヒット前の余裕が減る。

設定可能なバッファとして一番近いもの。バッファサイズは変わらない。フルウィンドウに対してコンパクションが発動する瞬間をずらすだけだ。

2. 拡張コンテキストモデルの使用

200Kの上限と格闘するより、1Mトークンコンテキストウィンドウを活用する方がいい。

2026年3月時点で、1Mコンテキストウィンドウは Opus 4.6 と Sonnet 4.6 で一般提供されており、価格プレミアムなし。900Kトークンのリクエストは9Kのものとトークンあたり同じコストになる。変更点と意味合いの詳細については、1Mコンテキストウィンドウガイドを参照してほしい。

/model sonnet[1m]

1Mトークンでは、コンパクション閾値が大幅に遠くなる。比例的なバッファ後でも、コンパクションが発動する前の余裕は大幅に広がる。完全なモデルエイリアスリファレンスはモデル選択ガイドを参照してほしい。

3. 自動コンパクションを無効にする（リスクあり）

// ~/.claude/settings.json
{
  "autoCompact": false
}

警告。GitHub Issue #18264 では、この設定が一部のケースで無視される可能性があると報告されている。機能した場合でも、ハードなコンテキスト制限にぶつかってセッションがクラッシュするリスクがある。

以下の準備ができている場合のみ切り替えること:

• /context でコンテキストを手動監視する
• 100%に達する前に /compact を実行する
• 時々セッションがクラッシュすることを受け入れる

4. 戦略的なタイミングでの手動コンパクション

自動コンパクトをオフにして、自分のスケジュールでコンパクションする:

/compact   # Compact when you decide
/clear     # Full reset when starting new major task

意図的にコンパクションするのに良いタイミング:

• 主要な機能を完成させた後
• 新しいコンポーネントを始める前
• デバッグコンテキストが古くなったと感じたとき

利点: 何がいつ要約されるかを自分で選べるため、作業中の細かい詳細を維持できる。

5. 167Kの制限内で作業する

ヘビーセッションはコンパクションされると受け入れること。そのために準備する:

• CLAUDE.md とスキルをスリムに保つ
• 状態を保持するためにセッションファイルを使う
• 複雑なタスクを複数のセッションに分割する

6. プロアクティブなバックアップ戦略

最も効果的な方法: コンパクションが来る前にバックアップを取る。

Claude Code コミュニティで広まりつつあるアイデア: 50%での積極的なクリア＋構造化された復元は、損失のある自動コンパクションに勝る。

自動コンパクションは会話を凝縮して細かい詳細を落とす。しかし代わりにこうする:

1. セッションを構造化されたバックアップに継続的に記録する
2. 閾値（50%など）で手動でコンテキストをクリアする
3. 損失のある要約ではなく構造化されたバックアップからリロードする

コンテキストの忠実度が上がる。バックアップには要約が捨てる正確な詳細が保持される。

操作モードの選び方

ほとんどの人は魔法の設定を1つ必要としているわけではない。やっている作業の種類に合ったモードが必要なのだ。

正しい問いは「バッファにどう勝つか?」ではない。「このセッションで損失のあるコンパクションのコストはどれくらい高いか?」だ。

3つの実例

例1: 通常の機能ビルド

1つの機能をビルドしており、少数のファイルを触るだけで、セッションが100Kトークンを超えることはほぼない。

最善の方法:

• デフォルトを使う
• /context を1〜2回確認する
• 過剰に考えない

バッファはここでは問題ではない。

例2: 多くの行き詰まりがあるデバッグセッション

ログ、トレース、失敗した仮説を40分かけて調査した。次のフェーズが実装になることはすでにわかっている。

最善の方法:

• 自動コンパクションを待たない
• /compact focus on the confirmed root cause, affected files, and fix plan を実行する
• 実装に進む

これにより、有用な診断を残しつつ不要な情報を削除できる。

例3: 高詳細コンテンツやオーディットセッション

セキュリティフローを監査したり、ソース重視の記事を書いたりしているとする。正確な引用、ファイルパス、観察された動作が重要だ。

最善の方法:

• 構造化されたバックアップまたはメモファイルを維持する
• 通常より早めにクリアする
• コンパクションされた要約を信頼するのではなく、正確なバックアップから復元する

これはバックアップワークフローが勝る場面だ。問題は生の容量ではなく、情報の忠実度だ。

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE を変更するタイミング

この変数は有用だが、特定のケースに限られる。

上げるべき場合:

• 現在のタスクが一貫していて、コンパクション前により多くの余裕が欲しいとき
• 使用量を積極的に監視しているとき
• 早すぎるコンパクションのコストが待つリスクより高いとき

下げるべき場合:

• セッションが乱雑で、より早く要約したいとき
• より頻繁なコンパクションで問題ないとき
• Claude にワーキングセットをより引き締めてほしいとき

そのままにすべき場合:

• コンテキストを積極的に監視していないとき
• トリガーを変える明確な理由がないとき
• 実際の問題がコンパクションではなくタスク切り替えのとき

トリガーを変えることは、適切なセッション境界の代替にはならない。同じ基本メカニズムが発動するタイミングをずらすだけだ。

StatusLine: 唯一のライブモニター

StatusLine はリアルタイムのコンテキストメトリクスを取得できる唯一のメカニズムだ。他のフックはトークン数を受け取れない。

// .claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "node .claude/hooks/context-monitor.mjs"
  }
}

statusline は context_window.remaining_percentage を含むJSONを受け取る。これがライブデータで、すぐに活用できる。

重要な計算。remaining_percentage フィールドはすでに16.5%の自動コンパクトバッファを考慮している。実際の「自動コンパクションまでの空き」を求めるには:

const AUTOCOMPACT_BUFFER_PCT = 16.5;
const freeUntilCompact = Math.max(
  0,
  remaining_percentage - AUTOCOMPACT_BUFFER_PCT,
);

25%残りということは、実際にはコンパクション前に8.5%しか残っていないことを意味する。

フックが /clear を注入できない理由

多くの人がぶつかる技術的な壁: フックはスラッシュコマンドを注入できない。

合理的な推測: フックが高いコンテキスト使用量を検出して /clear を注入する。しかしそれはできない:

• UserPromptSubmit には updatedPrompt フィールドがない。コンテキストの追加やブロックはできるが、置き換えはできない
• スラッシュコマンドはフック評価を完全にスキップする
• ユーザー入力の「代わりに」発動するフックはない

プログラム的にクリアして復元する実際の方法:

1. Claude Agent SDK。SDK経由で /clear を送る
2. ヘッドレスCLIラッパー。ヘッドレス Claude Code にコマンドをパイプする
3. 手動ワークフロー。フックが警告し、あなたが /clear を実行し、SessionStart が復元する

コンテキストが100%に達したときに起こること

コンテキストを端まで使い切ると、以下のことが起こる:

1. ベストケース。Claude のレスポンスが途中で切れる
2. 悪化したケース。APIがエラーを返し、ターンが失敗する
3. 最悪のケース。セッションが応答しなくなる

33Kバッファはこれらが起きないようにするためのものだ。無駄ではなく、保護だ。

重要なポイント

1. バッファが45Kから33Kに削減された。未公式の変更で、約12K多くのトークンが使えるようになった
2. コンパクションは使用率約83.5%で発動するようになった。使用可能なコンテキストは約167K（以前の約155Kから増加）
3. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE でトリガーをずらせる。1から100の値でコンパクションの発動タイミングを設定
4. sonnet[1m] で1Mトークンコンテキストが利用可能。200Kの制限と格闘する代わりの真の選択肢
5. アウトプットトークンとコンパクションバッファは別物。混同しないこと
6. autoCompact: false は機能する可能性がある。バグの報告もある
7. StatusLine が唯一のライブコンテキストモニター。他のフックはトークン数を見られない
8. フックは /clear を注入できない。SDK、ラッパー、または手動ワークフロー経由で行うこと
9. 積極的なクリア＋構造化された復元は損失のある自動コンパクションに勝る

バッファには正当な理由がある。戦うのではなく、うまく付き合う: 状態をセッションファイルに保持し、コンパクション前に閾値ベースのバックアップを実行し、ヘビーセッションでは積極的なクリアを検討する。

解決策: 閾値ベースのバックアップ

バッファは固定だ。それに近づいたときの対処法は固定ではない。

閾値ベースのバックアップシステムを確認してほしい。これは StatusLine でコンテキストを監視し、残り30%、15%、5%でバックアップを作成する積極的なセットアップで、コンパクションがセッション履歴を消去する前にバックアップが作成される。

関連リソース

• コンテキスト復元フック - 閾値ベースのバックアップシステム
• コンテキストエンジニアリングガイド - 戦略的なコンテキスト使用
• メモリ最適化 - 静的コンテキストのオーバーヘッドを削減
• Claude Code フックガイド - 12種類のフック全て解説