リファクタリング45分。ファイルを12個触って、コードベース全体を読み込ませて、あとは最後のピースを書くだけ——というところで「context window exceeded」。
全部止まる。文脈が消える。最初からやり直し。
Claude Codeを使い込んでいる人ほど、この瞬間を経験しているはず。
結論から言うと、これはAIの性能限界じゃない。自分の「渡し方」の問題だった。コンテキストウィンドウの扱いを変えるだけで、途中で止まることはほぼなくなる。
・Claude Codeで長めの作業をすると途中で止まる
・なぜ止まるのか原因がよく分からない
・対策があるなら知りたいけど、設定をいじるのは怖い
ここで止まっている人ほど、この先を読んでほしい。
コンテキストウィンドウは「AIの作業机」だと思えばいい
まず前提の話。コンテキストウィンドウという言葉がピンとこない人も多いと思う。
簡単に言えば、AIが一度に覚えていられる情報量の上限のこと。人間で言えば「作業机の広さ」に近い。机が広ければ資料をたくさん広げながら作業できるし、狭ければすぐに溢れる。
Claude Codeの場合、この机の上に載るのは自分が打ったプロンプトだけじゃない。AIが読んだファイルの中身、grepの検索結果、エラーメッセージ、AIが書いたコードの変更内容——全部がこの机に積まれていく。
つまり、自分では大した量を打ち込んでいないつもりでも、裏側ではどんどん机が埋まっている。気づいたときには「もう載りません」と言われる。遅すぎたけど。
「理解して」の一言が、一瞬でコンテキストを食い尽くす
なぜこんなに速く埋まるのか。原因は明確で、AIに渡す情報量を自分でコントロールしていないからだ。
典型的なのが「プロジェクト全体を理解して」という指示。これをやると、Claude Codeは律儀にファイルを片っ端から開いて読む。200行のファイルを10個読めば2,000行。grepの結果が500行返ってくれば、それだけで500行分の机が埋まる。
自分もClaude CodeをVPSに入れて日常的に使っているが、最初の頃は何も考えずに「このプロジェクトの構成を把握して」と投げていた。便利そうに見えるこの一言が、実は一番コンテキストを無駄遣いしていたと気づいたのは、何度も途中で止まった後だった。
対策1：1つのタスクに1つのセッション
最もシンプルで、最も効果が大きい。
昨日のデバッグセッションの続きで今日の機能追加をやる——これが一番危ない。前のセッションのゴミが全部残っているから、新しい作業に使える机のスペースがほとんどない。
タスクが変わったら、新しいセッションを始める。/compactや/resetはコストゼロで使える。遠慮する理由がない。
ポイントは、新しいセッションを始めるときに「何をやるか」「どのファイルを読むか」を最初に明示すること。「認証モジュールのauth.jsとミドルウェアだけ読んで、ログインAPIにレート制限を追加して」と言えば、読むファイルは2つ。「コードベースを理解して」と言えば40ファイル読まれるかもしれない。この差はでかい。
対策2：/compactは「限界が来る前」に使う
Claude Codeには/compactというコマンドがある。会話の履歴を要約して、ツールの実行ログなどの冗長な部分を圧縮してくれる機能だ。
多くの人が「コンテキストが限界です」という警告が出てから慌てて使うが、それでは遅い。すでにギリギリの状態で圧縮しても、焼け石に水になることがある。
自分がやっているのは、作業のフェーズが変わるタイミングで先回りして/compactを叩くこと。たとえばデータベースのスキーマ設計が終わったら、API実装に移る前に一度圧縮する。そのあとで「ここまでスキーマは完了。次はAPIレイヤーを作る」と一言添えてやると、AIが文脈を見失わない。
これ、地味な作業に見えるけど効くんですよ。体感で作業の中断率が激減した。
対策3：.claudeignoreとCLAUDE.mdで「読まなくていいもの」を先に決める
Claude Codeには.claudeignoreというファイルがある。ここに書いたディレクトリやファイルは、AIが自動的に読み込む対象から除外される。
node_modules、dist、coverage、ロックファイルあたりは真っ先に入れるべきだ。これらは開発に必要だがAIに読ませる意味がほぼない。.claudeignoreに入れたファイルは、うっかりコンテキストを食うこともなくなる。
もう一つ重要なのがCLAUDE.md。これはプロジェクトの基本情報を書いておくファイルで、Claude Codeがセッション開始時に自動で読んでくれる。
技術スタック、テストの実行コマンド、重要なファイルの場所、開発ルール——毎回AIに口頭で説明していた情報をここに書いておけば、セッションごとに数百トークン節約できる。しかもAIの理解精度も上がる。
自分の場合、CLAUDE.mdを整備してからは「このプロジェクトはNode.jsで、テストはJestで……」という前置きが完全に不要になった。これ、半年前に知ってたら何時間節約できたか。
対策4：大きなタスクは「セッションのリレー」で回す
複数のモジュールにまたがる大規模リファクタリング。これを1セッションでやろうとするのは、A4の机の上に百科事典を広げるようなものだ。
代わりに、タスクをセッション単位に分割する。
セッション1は調査と計画。現状を読んで、何をどの順番で変更するかチェックリストを作る。ファイルには触らない。
セッション2は実装。セッション1で作った計画ファイルだけを読み込んで、最初のステップだけ実行する。
セッション3はテストと修正。変更したファイルとテストファイルだけ読んで、壊れたテストを直す。
各セッションはクリーンな状態で始まる。前のセッションの成果物（計画ファイルや変更済みのコード）が、次のセッションへの最小限のコンテキストになる。
対策5：大きな出力はファイル経由で渡す
テストの実行結果やログファイルをそのままClaude Codeに貼り付けると、800行のログがそのままコンテキストを圧迫する。
代わりに、出力をファイルに保存してからAIに読ませる。同じ情報量でも、コンテキストの扱いが少しクリーンになる。さらに大きな出力の場合は、末尾の50行だけに絞って渡すといい。エラーの原因はたいてい最後のほうに集中しているから、全部読ませる必要はない。
もし作業中に限界が来てしまったら
対策をしていても、たまに限界警告が出ることはある。そのときの対処も覚えておくと慌てない。
まず深呼吸。AIが途中まで書いたコードはファイルシステムに保存されている。消えてはいない。
すぐに/compactを実行して圧縮を試みる。それでも厳しければ、新しいセッションを開始して「認証モジュールのリファクタリング中。auth.jsへの変更は保存済み。続きとしてserver.jsにミドルウェア登録を追加して」と伝える。
「何が完了していて」「どのファイルに保存されていて」「次に何をするか」——この3点を伝えれば、Claude Codeは途中から拾ってくれる。全部やり直す必要はない。
自分も最初は途中で止まるたびに最初からやり直していたが、この「引き継ぎ方」を覚えてからは、止まっても30秒で復帰できるようになった。試した。動いた。もう戻れない。
まとめ
- コンテキストウィンドウは「AIの作業机」。渡す情報量を自分でコントロールするのが最重要
/compactの先回り使用、.claudeignoreの設定、CLAUDE.mdの整備で無駄な消費を大幅に減らせる- 大きなタスクはセッション分割で回し、途中で止まっても「引き継ぎ3点セット」で即復帰できる
コンテキスト管理は地味な作業だ。でも、これができるかどうかで「Claude Codeは途中で止まるから使えない」と感じるか「同じツールなのに別物になった」と感じるかが分かれる。自分はそう思ってる。すごく。
【PR】フリーランスエンジニアにおすすめのツール
VALUE-DOMAIN（バリュードメイン）
ドメイン取得とレンタルサーバーをまとめて管理できる。コスパ重視のフリーランスに。
コメント