コンテキストが埋まったときの対処法

症状

「コンテキストが上限に近づいています」という警告が表示される
Claudeの応答が急に遅くなる・短くなる
以前の会話内容をClaudeが忘れているように見える
「コンテキストが満杯です。新しいセッションを開始してください」というエラーが出る

※コンテキスト: Claudeが一度に記憶・参照できる会話・コードの範囲。上限を超えると古い情報が失われる。

原因

原因1: 長時間の連続作業

一つのセッションで長時間作業すると、会話履歴が積み重なってコンテキストを圧迫します。特に試行錯誤を繰り返したとき（「こう直してほしい→やっぱり違う→こっちの方がいい」）は急速にコンテキストが消費されます。

原因2: 大きなファイルを何度も読み込んでいる

大きなファイルを繰り返し参照したり、長い出力（ビルドログ全体など）をそのまま貼り付けると、一気にコンテキストを使い切ります。

原因3: 会話の中で大量のコードが生成されている

Claudeがコードを生成するたびに、そのコードもコンテキストに積み重なります。大規模な実装をすると、コード自体がコンテキストを圧迫します。

原因4: `--verbose` モードや詳細ログの出力

詳細なログを含む長い出力をセッション内でClaudeに見せると、コンテキストが急速に消費されます。

解決手順

対処法1: `/compact` コマンドを使う（推奨）

Claude Codeには会話を圧縮するコマンドがあります。

/compact

これを実行すると、会話履歴を要約した形で圧縮します。重要な情報は保持されますが、詳細なやりとりは省略されます。作業の途中で定期的に使うのが最善です。

対処法2: 新しいセッションで作業状態を引き継ぐ

コンテキストが限界に達したら、新しいセッションを開始し、現在の作業状態を整理して伝えます。

新しいセッションで伝える内容の例:

「プロジェクト: [名前]
現在の作業: ユーザー認証機能のバグ修正
やったこと: src/auth/login.ts の validateToken() を修正
残り作業: テストを書く（spec/auth/login.spec.ts）
重要なメモ: JWTの有効期限は env.JWT_EXPIRY を参照している」

対処法3: 作業ログをファイルに書き出してもらう

長い作業の前に、Claudeに作業ログをファイルに書き出させます。

「今から長い作業に入ります。作業の進捗をファイルに書き出してください。
ファイル: .claude/work-log.md
内容: 何をやったか、何が残っているか、重要なメモ」

次のセッションでこのファイルを参照させれば、コンテキストを引き継げます。

対処法4: 大きなファイルの読み込みを最小限にする

# ❌ 悪い例: ファイル全体を貼り付ける
「このファイルを見てほしい」
（5000行のコードを貼り付ける）

# ✅ 良い例: 関連部分だけ指定する
「src/auth/login.ts の validateToken() 関数（150行目付近）を見てほしい」

※JWT: JSON Web Token の略。ユーザー認証情報をJSON形式でエンコードしたトークン。ヘッダーに付けてAPIを呼び出す際に使う。

予防策

CLAUDE.mdで作業スコープを明確にする

## Claudeへのお願い

- 一度に複数の大きな変更をしない
- 長い作業の前に作業計画を提示して確認を取る
- 完了したタスクは `.claude/progress.md` に記録する

定期的な `/compact` の習慣化

長時間作業するときは、1〜2時間ごと、または大きなタスクが完了するたびに /compact を実行する習慣をつけましょう。

出力サイズのコントロール

# ❌ 大量の出力を求める
「プロジェクト全体をリファクタリングして、全ファイルを表示して」

# ✅ 少量ずつ処理する
「まず src/auth/ ディレクトリだけリファクタリングして」
（完了後）「次に src/api/ を進めましょう」

※CLAUDE.md: プロジェクトのルートに置くClaude Code専用の設定ファイル。プロジェクト固有のルールやコンテキストを記述する。※リファクタリング: 外部から見た動作を変えずに、コードの内部構造を整理・改善すること。