32blogby StudioMitsu
claude-code14 min read

「context window exceeded」の正しい対処法

Claude Codeのcontext window exceededエラーに突然作業が止まった経験はないか。/compact・セッション分割・.claudeignore・Plan modeを組み合わせた正しい対処法を解説する。

claude-codecontext windowエラー対処トークン管理コスト最適化
目次

深夜に大きなリファクタをClaude Codeに任せていたら、終盤で「context window exceeded」が出て作業が止まった。どこまで進んだかもわからない。ファイルを確認しても中途半端な状態で、やり直すにも経緯が頭に入っていない。

この経験から学んだ予防策と復元手順を、僕が実際に使っているものをそのままここにまとめた。これを読めば、コンテキストウィンドウの問題で作業が止まる事態はほぼ回避できる。

Claude Codeの「context window exceeded」とは何か？

「context window exceeded」はClaude Codeが処理できるトークン数の上限に達したときに出るエラーだ。「もうこれ以上会話を続けられません」という意味で、それまでの会話履歴・読み込んだファイル・生成した出力、すべてを合算した数が限界を超えると発生する。

重要なのは、これは突然来るのではなく、徐々に近づいてくるという点だ。Claude Codeはセッション中にコンテキスト使用率をトラッキングしており、事前に把握する手段がある。つまり適切に監視して行動すれば、エラーが出る前に対処できる。

対策は大きく4つある。

  1. /compact で履歴を要約して圧縮する
  2. .claudeignore で不要なファイルをそもそも読み込まない
  3. セッションをドメイン別に分割して長期化させない
  4. Plan modeで先に設計を固め、実装時のトークン消費を最小化する

それぞれを後のセクションで詳しく解説する。まず、すでにエラーが出てしまった場合の復元手順から始めよう。

エラーが出た直後にどうやって作業を復元するか？

エラーが出た時点でセッションは終了している。パニックにならず、以下の順番で状況を把握する。

Step 1: git で差分を確認する

bash
git diff HEAD
git status

Claude Codeはファイルを変更するたびに実際にディスクに書き込む。会話が止まっても、それまでの変更はファイルシステムに残っている。git diff で何が変わったか確認すれば、作業がどこまで進んでいたか把握できる。

Step 2: 変更内容をコミットまたはスタッシュする

中途半端な状態でも、まず保存する。

bash
git add -A
git stash push -m "claude-code session 2026-02-26 interrupted"

あるいは作業が完結していそうな部分だけコミットしてもいい。

Step 3: 新しいセッションで続きを依頼する

新しいセッションを開始し、コンテキストを最小限にまとめて続きを依頼する。

前回のセッションでcontext window exceededが発生しました。
変更済みファイル: src/components/Header.tsx, src/lib/api.ts
残りのタスク: フッターコンポーネントの型エラー修正
関連ファイルのみ読み込んで続きをお願いします。

長い説明は不要だ。「何をするか」「どのファイルか」の2点だけ伝えれば十分。

コンテキスト使用率はどうやって確認するか？

Claude Codeはセッション中、会話の応答に使用率を表示することがある。ただし常に表示されるわけではないため、自分で把握する意識が必要だ。

セッションが長くなってきたと感じたら /status を確認する

/status

このコマンドでトークン使用量の概算が確認できる。70-80%に達していたら、そこが行動を起こすタイミングだ。

目安となるセッションの「重さ」

状況トークン消費の目安
小さなバグ修正（1-2ファイル）10-30k
機能追加（5-10ファイル）50-150k
大規模リファクタ（20ファイル以上）200k超え → 危険

ファイル数が増えるほど消費は急増する。「ついでにこっちも直して」を繰り返すと、あっという間に上限に近づく。

コンテキスト節約の基本姿勢

  • 1セッション = 1タスクを徹底する
  • 「ついでに」はしない
  • 新しいタスクは新しいセッションで始める

/compactコマンドはどう使えばいいか？

/compact はセッションの会話履歴を要約して圧縮するコマンドだ。詳細なやりとりを「ここまでの作業内容の要約」に置き換え、トークン数を大幅に削減する。

/compact

実行すると、Claudeがそれまでの会話から重要な情報を抽出して要約する。圧縮後も作業の文脈は引き継がれるため、続きの作業が可能になる。

正しい使いどき

  • コンテキスト使用率が60-70%に達したとき
  • 調査・設計フェーズが終わり、実装フェーズに移るとき
  • エラーのデバッグが一段落したとき

使ってはいけない場面

  • 複雑な設計の議論の途中（要約で重要な前提が失われる可能性がある）
  • コードの細かいニュアンスを維持したい場合

/compact は万能ではない。要約によって失われる情報もある。重要な決定事項はファイルに書き出すか、CLAUDE.mdに記録しておくと安全だ。

markdown
<!-- CLAUDE.md に残すべき内容の例 -->
## 現在の作業
- タスク: ユーザー認証モジュールのリファクタ
- 決定事項: JWT → セッションCookieに変更
- 変更済み: src/auth/index.ts, src/middleware/auth.ts
- 残り: テストの更新

.claudeignoreでトークン消費を減らすには？

コンテキスト管理で最も効果が高いのは、不要なファイルをそもそも読み込まない設計だ。.claudeignore ファイルを使うと、Claude Codeがファイルを探索する際に除外するパターンを指定できる。

bash
# プロジェクトルートに .claudeignore を作成
touch .claudeignore
plaintext
# .claudeignore

# 依存関係（絶対に読み込ませない）
node_modules/
vendor/
.venv/
__pycache__/

# ビルド成果物
dist/
build/
.next/
out/

# 大きなデータファイル
*.csv
*.json.bak
data/raw/

# ログ・キャッシュ
*.log
.cache/
coverage/

# 設計ドキュメント（作業に不要な場合）
docs/archive/
*.pdf

# テストのスナップショット（頻繁に変わるもの）
__snapshots__/

.gitignore と似た書式で書ける。.gitignore に書いてあるものと重複する場合も多いが、.claudeignore はClaude Code専用なので、開発には必要だがAIに読ませる必要がないファイルを細かく制御できる。

効果の見えやすい設定

node_modules/ だけで数万〜数十万トークンの節約になることがある。Next.jsプロジェクトなら .next/ も必ず除外する。設定ファイルを1つ置くだけで、セッションの寿命が2-3倍になることも珍しくない。

セッションをどう分割すれば長期作業を安全にできるか？

「1つの大きなタスク」を「複数の小さなセッション」に分割することが、コンテキスト管理の根本的な解決策だ。

分割の基準

悪い例（1セッションでやること）:
- ユーザー認証の設計
- DBスキーマの設計
- API実装
- フロントエンド実装
- テスト作成
- デプロイ設定

良い例（セッションを分ける）:
Session 1: 設計のみ（CLAUDE.mdに記録）
Session 2: DB + API
Session 3: フロントエンド
Session 4: テスト
Session 5: デプロイ

各セッションの開始時に必要な文脈だけを伝える。前のセッションの会話履歴をそのまま引き継がせようとするのが、コンテキスト爆発の最大の原因だ。

セッション間の引継ぎファイルを作る

markdown
<!-- session-handover.md -->
## 前回セッションの成果
- 認証はJWT（RSA256）で実装完了
- src/auth/ 以下のファイルが対象
- テストは書いていない

## 今回のセッションでやること
- src/auth/__tests__/ にテストを追加
- カバレッジ80%以上を目標

これをClaude Codeに渡すだけで、前の経緯を説明する長い会話が不要になる。

自動コンパクションはなぜ危険なのか？

Claude Codeには自動コンパクション機能がある。コンテキストが一定の閾値を超えると自動で要約を実行する設定だ。

便利に聞こえるが、重要な作業中の自動コンパクションは危険なこともある。

自動コンパクションが起きるタイミングは自分でコントロールできない。複雑なリファクタの最中や、エラーの原因を追いかけている途中で要約されると、重要な前提条件が失われて作業が迷走することがある。

json
{
  "autoCompact": false
}

自動コンパクションを無効にしておき、自分で判断したタイミングで /compact を実行するほうが安全だ。使用率70%を超えたら手動で実行し、要約の内容を確認してから続きに進む。

context window exceededを二度と出さないための設定チェックリスト

ここまでの内容をチェックリストにまとめた。プロジェクトを始めるときに一度設定しておけば、以降はほとんど意識しなくて済む。

プロジェクト初期設定

  • .claudeignore を作成し、node_modules/・dist/・.next/ を除外
  • CLAUDE.md に現在の作業状況と決定事項を書く習慣をつける
  • 自動コンパクションを無効化する

セッション開始時

  • 1セッション = 1タスクを守る
  • 前のセッションの引継ぎ情報をコンパクトにまとめて渡す
  • 関係ないファイルは絶対に読み込ませない

セッション中

  • コンテキスト使用率が60%を超えたら /compact を検討
  • 「ついでにこっちも」をやめる
  • 設計の決定事項は会話に留めず即座にファイルに書き出す

エラーが起きたとき

  • まず git diff で変更内容を確認
  • 変更をスタッシュまたはコミット
  • 新しいセッションで最小限の文脈を渡して続きを依頼

まとめ

「context window exceeded」は不運ではなく、設計で防げるエラーだ。

  • .claudeignore で読み込むファイルを絞る
  • 1セッション1タスクを徹底する
  • 70%超えで /compact を手動実行する
  • セッション間の引継ぎはファイルで管理する

この4つを実践するだけで、コンテキスト切れで作業が止まる経験はほぼなくなる。深夜の大規模リファクタも、セッションをうまく分割すれば安全にこなせるようになる。

まず今すぐ.claudeignoreを作ることから始めよう。