Claude Codeの動作遅延とコスト増大を防ぐ方法

Claude Code セッションの低速化とコスト増大を防ぐ方法

Claude Code のセッションが長くなると、動作が遅くなりコストも増大します。これは、ターンごとに全コンテキストが再送され、コンテキストが肥大化し続けるためです。解決策は、以下の手順で整理を行うことです。まず /context を実行して、何がウィンドウを占有しているかを確認してください。次に、リクエストのたびに課金対象となる項目を削除します。無関係なタスクの間には /clear を、一つの長いタスク内での指示には /compact を使用してください。プロンプトキャッシュが機能しないと、安価な読み取りが全発言の再書き込みに変わるため、作業は連続した短い単位で行ってください。

トークン消費の仕組みについては、エージェントセッションのトークンメーター で説明しています。

変更を加える前に /context を確認してください

ウィンドウの内容を推測しないでください。Claude Code が情報を表示します。

/context [all] は現在の context 使用状況をカラーグリッドで表示します。これには、context が多いツールやメモリ消費の増大に対する最適化の提案が含まれます。all を使用すると、フルスクリーンモードで項目ごとの内訳が展開されます。結果は5つのグループとして解釈してください。

• The system prompt. Claude Code 自体の動作指示。セッション中は固定です。
• Tool definitions. エージェントが呼び出せるすべてのツールのスキーマ。接続されているすべての MCP (Model Context Protocol) サーバーを含みます。
• Memory files. セッション開始時に読み込まれる CLAUDE.md および auto memory。
• Files and tool results. 読み込まれたすべてのファイルと、コマンドの出力結果。
• Message history. ユーザーの入力とそれに対する回答。

最初の3つは固定のコストであり、セッション中はすべてのリクエストで発生します。後半の2つは増加します。固定コストは開始時に一度だけ確認し、増加する部分は継続的に管理してください。

ウィンドウが一杯であることを示す2つの文字列があります。

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

1つ目はハードリミットであり、リクエストは拒否されます。対応する API (application programming interface) エラーは Prompt is too long です。2つ目はコンパクションウィンドウであり、1 million token モデルの場合、モデルの実際の context window より低く設定されることがあります。これを超えてもリクエストは成功するため、こちらは拒否ではなく警告となります。

有料プランでは、/usage がもう一方の情報を追加します。これには、長い context や cache miss などの挙動のフラグ立て、および最近の使用量を個別の skill、subagent、MCP server ごとに割り当てた情報が含まれます。

CLAUDE.md は永続的なコストとなるため、最小限に保ってください

CLAUDE.md はセッション開始時にコンテキストに読み込まれ、保持されます。詳細なデプロイ手順が含まれている場合、テストファイルのタイポを修正している間も、それらのトークンが消費されます。Anthropic のガイドラインでは、必須事項のみを含め、ファイルサイズを 200 行未満に抑えることが推奨されています。

手順は skills に移動してください。skill は呼び出された時のみ読み込まれるため、週に2回実行するワークフローであれば、それ以外の日のコストは発生しません。skill は compaction 後に独自の予算を持ちます。内容は再注入されますが、1つの skill あたり 5,000 トークン、合計で 25,000 トークンに制限され、古いものから削除されます。Truncation はファイルの冒頭部分を保持するため、最も重要な指示は SKILL.md の上部に記述してください。

Compaction 後に保持される内容によって、指示をどこに配置すべきかが決まります。

• System prompt と出力スタイルは、メッセージ履歴の一部ではないため、変更されません。
• プロジェクトルートの CLAUDE.md、unscoped rules、および auto memory は、ディスクから再注入されます。
• paths: frontmatter を持つ rule は、一致するファイルが再度読み込まれるまで失われます。
• サブディレクトリ内のネストされた CLAUDE.md は、そのディレクトリ内のファイルが再度読み込まれるまで失われます。
• Hooks は、コードとして実行されコンテキストに入らないため、影響を受けません。

したがって、依存している rule はプロジェクトルートの CLAUDE.md に配置してください。Claude Code は古い tool outputs を優先的にクリアしてから要約を行うため、会話の初期段階の指示は失われる可能性があります。Memory の編集には /memory を使用してください。Claude Code はセッション開始時に読み込んだコピーを保持します。セッション中の trim は prompt cache を維持するため、次の /clear、/compact、または再起動が適用されるまで反映されません。

タスク間では /clear、単一タスク内では /compact を使用

これら2つは似ていますが、コストが大きく異なります。

/clear [name] はコンテキストを空にして新しい会話を開始します。リクエストを送信しないため、コストはかかりません。/resume ピッカーで以前の会話を識別するために名前を指定してください。/reset と /new はエイリアスです。無関係なタスクに切り替える際は、直ちにこれを使用してください。そうしないと、新しいタスクのメッセージごとに古いタスクが再送信され、再度課金されます。

/compact [instructions] は、同じ会話を継続しながらコンテキストを解放します。これまでの履歴を要約して置き換えます。継続性が必要な、一つの長いタスク内で使用してください。

必ず /compact に指示を与えてください。 指示のない /compact は、作業のどの部分がまだ必要なのかを判断できないデフォルトのプロンプトで要約を行います。指示がある場合は、必要な部分を保持します。

/compact focus on the auth bug fix
/compact keep only the plan and the diff

常に同じ理由でコンパクションを行う場合は、プロジェクトの CLAUDE.md 内の # Compact instructions 見出しに定型指示を記述してください。新しいセッションでは /compact が Not enough messages to compact. と出力されます。これは、まだ履歴がないことを意味します。

ここで2つのコストが混同されがちです。要約リクエストはプレフィックスを共有します。そのため、履歴を再処理するのではなく既存のキャッシュを読み取ります。処理時間の大部分は要約の生成に費やされます。大きなコンテキストをコンパクションする場合でも、要約対象の会話が入力となるため、リクエスト自体は大きくなります。コンパクション直後のターンは低速ではありません。短いプロンプトに対してキャッシュを再構築するだけだからです。

より安価なコマンドが2つあります。/rewind [description] は、コードと会話をチェックポイントまでロールバックします。完全に破棄したいパスがある場合は、コンパクションよりも /rewind [description] が適しています。なぜなら、既にキャッシュされているプレフィックスまで切り詰められるからです。/recap は、履歴を置き換える代わりに要約をコマンド出力として追加します。これにより、キャッシュされたプレフィックスが維持されます。

自動コンパクションが繰り返し発生すると、次のように出力されます。

Autocompact is thrashing: the context refilled to the limit...

コンパクションは成功しましたが、ファイルまたはツールの出力によってウィンドウが何度も埋まったため、Claude Code は再試行を停止しました。リカバリするには、行範囲を指定して巨大なファイルを読み取るか、大きな出力を除外するように /compact を実行するか、その作業を subagent に移すか、あるいは以前の会話が終了している場合は /clear を実行してください。

MCP server は固定オーバーヘッドです

接続されている MCP server は、セッション中のすべてのリクエストに対して負荷を加えます。ツールを使用するかどうかに関わらず、コストが発生します。

Claude Code はこの問題を軽減します。デフォルトでは MCP tool definition は遅延読み込みされるため、Claude が特定のツールを使用するまで、ツール名のみが context に含まれます。サーバーの実際のコストを確認するには /context を、今日使用しないサーバーを削除するには /mcp disable <name> を実行してください。VPS 上で独自の MCP servers を運用している場合も、同様の計算によって、1つのサーバーが公開すべきツールの数が制限されます。

これはセッションの開始時に行ってください。definition が遅延読み込みされている間は、サーバーの接続や切断は会話の末尾に追加されるだけで、cache は保持されます。一方、tool search がオフであるか、server が遅延読み込みの対象外であるために definition が prefix にロードされる場合、同様の変更を行うと、次のリクエストですべての内容が再読み込みされます。

コンテキストに入る前に verbose なツール出力をフィルタリングする

ツールの実行結果は入力となり、その入力は以降のすべてのターンで再送されます。20,000 tokens の出力を生成するテスト実行は、一度限りのコストではありません。出力がコンテキストウィンドウから消えるまで、ターンごとにコストが発生します。

ソース段階でフィルタリングしてください。Claude が出力を確認する前に、テスト結果を失敗した箇所だけに絞り込む hook を使用します。これにより、膨大な出力が、現在のターンおよびその後の再送時において、数百 tokens に削減されます。

npm test 2>&1 | grep -E "FAIL|Error:" | head -40

Hook 自体はコードとして実行されるため、コンテキストには含まれません。出力が画面を越えるようなツールには、この手法を適用してください。3,000行のファイルに対しても同様のロジックが有効です。ファイル全体がコンテキストに残り続けるため、必要な行の範囲のみを要求するようにしてください。

エージェントの読み取り範囲を制限し、冗長な作業を委譲する

ファイル名と症状を指定したプロンプトは、そのファイルを読み取ります。プロジェクトの整理を依頼する場合、エージェントは関連があると判断したものをすべて読み取ります。その読み取り結果はすべてコンテキストウィンドウ内に保持されます。

冗長な作業は subagent に委譲してください。テストの実行やログの処理は、どちらも大量のコンテキストを消費します。subagent は出力を自身のウィンドウ内に保持し、要約のみを返します。トレードオフとして、subagent は初回呼び出し時にキャッシュが空の状態から開始し、subscription を使用していても 5 分間のキャッシュ有効期間が適用されます。委譲を行うことで、メインのコンテキストを確実に保護できます。ただし、総トークン数が必ずしも減少するとは限りません。

キャッシュの有効期限：継続的な作業が重要です

Prompt caching により、再送コストを抑えられます。Prefix の読み取りはベース入力レートの 0.1x、書き込みは 1.25x です。1時間有効なキャッシュの書き込みは 2x となります。使用するたびにエントリが更新されるため、有効期限は最終使用時からカウントされます。

有効期限は認証方法によって異なります。「キャッシュは5分で失効する」という一律の認識は誤りです。

• Claude subscription を使用している場合、Claude Code は自動的に1時間の有効期限を要求します。
• プランの制限を超え、usage credits を使用している場合、その使用量に対して課金されるため、有効期限は5分に短縮されます。
• API key または cloud provider を使用している場合、有効期限は5分に維持されます。ENABLE_PROMPT_CACHING_1H=1 は1時間の有効期限を適用し、FORCE_PROMPT_CACHING_5M=1 は5分に強制的に戻します。

どちらの場合も、作業の進め方は同じです。継続的に作業を行ってください。有効期限が切れるほど、次のリクエストで蓄積された Prefix 全体を書き直すことになります。tmux での detached な Claude Code session は、アイドル状態でもコストはかかりません。アイドル時間を設けることは、ウォームキャッシュを失うことを意味します。

作業中にキャッシュが破棄される操作があります。モデルの切り替え、effort level の変更、fast mode の有効化、MCP server の接続・切断、plugin の有効化・無効化、ツール全体の拒否、compacting、および Claude Code のアップグレードです。/model はよくある落とし穴です。モデルごとに個別のキャッシュを持つため、内容が同一であっても、次のリクエストではキャッシュヒットなしで履歴全体を読み取ることになります。

ファイルの編集、CLAUDE.md の編集、スキルやコマンドの呼び出し、/recap の実行、rewind、および subagent の生成は、キャッシュを維持します。キャッシュの範囲は、1つのマシンと1つのディレクトリに限定されます。そのため、異なるディレクトリでの2つのセッションは、互いのキャッシュを利用できません。

キャッシュが機能しているか確認するには、current_usage を参照してください。cache_creation_input_tokens はキャッシュの書き込みレートで作成されました。cache_read_input_tokens は標準入力レートの約10分の1で提供されました。読み取り対作成の比率が高い状態が理想的です。作成コストが継続的に高い場合は、Prefix 内の何かが変化し続けています。

コンテキストウィンドウの拡大で解決しますか？

部分的に解決します。現在のモデルの多くは 1 million token のコンテキストウィンドウをサポートしており、コンパクションは大きな制限値でも同様に機能します。プロンプト全体が毎回再送され、毎回課金されるため、コスト構造は変わりません。ウィンドウの拡大は、いつ制限に達するかを決定します。コストを抑えるには、ハイジーン（hygiene）が必要です。制限値ではなく料金が問題である場合は、作業スタイルに合った Claude のプラン を選ぶことで、支払額かプランの割り当て量かを決定できます。

APIにおけるContext editingとCompactionは異なる機能です

Messages APIで独自のagentを構築する場合、slash commandsは存在しないため、これらは自身で実装する必要があります。サーバー側にはこれらを実現する2つの機能がありますが、これらは別物です。

Context editingは、会話履歴の増加に合わせて特定のコンテンツを選択的に削除します。削除された箇所にはプレースホルダーが挿入され、Claudeは何かが削除されたことを認識できます。これはbeta機能です。anthropic-beta: context-management-2025-06-27を送信し、context_management.editsでstrategyを設定してください。clear_tool_uses_20250919はtool resultsを削除し、clear_thinking_20251015はthinking blocksを管理します。triggerのデフォルトは100,000 input tokens、keepは直近3回のtool uses、clear_tool_inputsはfalseです。これにより、inputは保持され、resultのみが削除されます。

Compactionは、要約を生成して会話履歴全体をその要約で置き換えます。これもbeta機能です。anthropic-beta: compact-2026-01-12を送信し、edit typeにcompact_20260112を使用してください。triggerのデフォルトは{"type": "input_tokens", "value": 150000}で、値は50,000以上である必要があります。

Compactionには、agentの動作を損なう可能性のあるhandoffルールが1つあります。レスポンスは、要約を含むcompaction content blockから始まり、その後に通常のtext blockが続きます。後続のリクエストでは、このblockを必ず返送してください。そうすると、APIはそれより前にあるすべてのcontent blockを破棄します。実務上の注意点として、textだけでなくresponse.contentのすべてを付加してください。

Anthropicのドキュメントでは、サーバー側でのcompactionは長期の会話におけるコンテキスト管理の主要な戦略であり、context editingは削除する内容を細かく制御するためのオプションであると説明されています。まずモデルのサポート状況を確認してください。現在のOpus、Sonnet、Fableモデルはcompactionをサポートしています。claude-haiku-4-5はサポートしていません。最新のリストはcompactionのページで確認できます。なお、どちらのbeta機能もClaude Code独自の/compactを制御するものではありません。ドキュメントによれば、/compactはクライアントが送信する単発のsummarization requestです。

FAQ

なぜ Claude Code のセッションは、実行時間が長くなるほど遅くなり、コストも高くなるのですか？

ターンごとに会話全体が再送されるためです。一日中開いているセッションでの一行の質問には、その日の全履歴が含まれます。Prompt caching が有効な間は、読み取りコストはベース入力レートの 0.1x に抑えられます。キャッシュが切れると、同じプレフィックスが 1.25x のコストで再送されます。何がウィンドウを占有しているかを確認するには /context を実行してください。仕組みについては Claude Code の課金メカニズム を参照してください。

Claude Code における /clear と /compact の違いは何ですか？

/clear は、コンテキストを空にして新しい会話を開始します。リクエストを送信しないためコストはかからず、無関係なタスクに移る際に適しています。/compact は、現在の会話を維持したまま履歴を要約に置き換えます。一つの長いタスクを継続する場合に適しています。/compact keep only the plan and the diff のように指示を与えることで、何を残すかを制御できます。

Claude Code のコンテキストウィンドウは何が消費しているかを確認する方法は？

/context を実行するか、項目ごとの詳細が必要な場合は /context all を実行してください。システムプロンプト、tool definitions、MCP servers、memory files、および履歴がカラーグリッドで表示されます。コンテキストを大量に消費する tool や memory の肥大化に関する提案も表示されます。有料プランでは、/usage によって最近の使用量が個別の skills、subagents、MCP servers ごとに集計されます。

compact を使う代わりに 1 million token のコンテキストウィンドウを使用すべきですか？

ウィンドウを大きくしても、問題の解決ではなく先送りにするだけです。Opus 4.8 や Sonnet 5 を含む現在の複数のモデルは 1 million token のコンテキストウィンドウに対応していますが、compaction の挙動は同じです。ターンごとにフルプロンプトが再送され、その分コストが発生するため、400,000-token の会話は、ウィンドウに収まるかどうかにかかわらず高額になります。

Claude API における context editing と compaction の違いは何ですか？

Context editing は、古いコンテンツ（主に tool results）を選択的に削除します。削除された箇所にはプレースホルダーが残るため、Claude は内容が削除されたことを認識できます。Compaction は要約を生成し、フル履歴をその要約で置き換えます。Anthropic のドキュメントでは、compaction を長期的な会話の主要な戦略とし、context editing を詳細な制御のためのオプションとして位置づけています。どちらもベータ版であり、Claude Code の /compact とは別物です。