fast-jev-compaction はなぜ失敗する？2026年 Claude Code コンテキスト圧縮トラブルシューティング

公式設定資料では、Claude Codeの設定はユーザー、プロジェクト、ローカルという3つの範囲で管理されます。 Claude Codeの設定階層 と実行中の作業場所が一致しないだけでも、fast-jev-compaction の失敗に見える状態が起きます。

症状：圧縮されない、途中で止まる、重要なファイルや決定事項が消える。
最短の解決策：まずプラグイン未読込、Jevリクエスト失敗、圧縮方針による削除、Claude Code本体の制限を分け、要約ファイルとチェックポイントを保存してから自動圧縮を戻します。

対象となる読者

fast-jev-compaction が発動しない、または圧縮後のClaude Codeが作業状態を見失った人は、本文の問題ツリーに沿って確認してください。長時間のAI Codingを行う場合は、何を保存すべきか、どの時点で新しいセッションへ移るべきかを判断できます。

リモートMacでClaude Codeを運用するチームには、ログ、権限、通信経路、復旧手順を分けて管理するための基準になります。

最初の診断：未発動か、結果不完全か

最終的にタスクが失敗したという事実だけで、圧縮プラグインの不具合とは判断できません。コードのビルドエラー、認証切れ、対象ファイルの変更、モデル側の判断も同じ症状を起こすためです。

最初に次の4点を同じ作業単位で保存します。

• Claude Codeのセッション識別情報と開始時刻
• fast-jev-compaction の起動記録、警告、エラー
• 圧縮前後のモデル応答とツール呼び出し
• 圧縮直前の要約、未完了作業、変更ファイル、テスト結果

そのうえで、以下の順に判定します。

1. 起動時にプラグインの読込記録があるか。
2. 読み込まれているが、圧縮の判定条件に達していないのか。
3. 圧縮処理は始まったが、Jevへのリクエストが失敗したのか。
4. 圧縮は成功したものの、方針上、古いツール結果や詳細が省かれたのか。
5. プラグインを外してもClaude Code本体のコンテキスト制限で同じ状態になるのか。

圧縮が始まらない場合、最初に何を確認すべきですか？

まず設定を強めるのではなく、プラグインを外した短い再現を作ります。小さなリポジトリで同じ指示を実行し、読込ログ、Jev通信、圧縮前後の要約を比較してください。再現しない場合は、元の作業量、ツール結果、特定のファイル内容が原因候補です。

読込設定と起動経路

公開リポジトリのREADMEにあるインストール方法、設定項目、対応範囲を基準に確認します。 fast-jev-compactionの公開リポジトリ に記載のない環境変数やパスを推測して追加すると、原因を増やします。

確認する箇所は次の通りです。

• プラグインのディレクトリが、現在のClaude Codeから参照されているか
• インストール済みのバージョンと依存関係が一致しているか
• 実行ユーザーに読込、実行、ログ出力の権限があるか
• Claude Codeを起動したディレクトリと、対象ワークスペースが一致しているか
• ユーザー設定とプロジェクト設定のどちらに項目を書いたか
• コンテナ内の設定を、ホスト側の設定と取り違えていないか

Claude CodeのCLIオプションや起動時の確認方法は、 公式CLIリファレンス と照合します。設定変更後は既存セッションを使い回さず、新しいセッションで読込記録を確認してください。セッション開始後に設定ファイルを変更しても、すでに読み込まれた構成へ反映されない場合があります。

プラグインが読み込まれたことは、どのように確認できますか？

設定ファイルが存在するだけでは不十分です。起動ログにプラグイン名または初期化記録が出ていること、圧縮条件に到達したときに処理開始の記録が出ること、処理後に要約またはツール結果の変化を確認できること、この3段階を別々に見ます。ログがない場合は、まずパス、起動ユーザー、作業ディレクトリを疑います。

判断表

Jev通信と降格運用

Jevへの圧縮リクエストが失敗しても、必ずしもClaude Code全体が停止するとは限りません。影響は、プラグインがエラー時に処理を中断する設計か、標準の圧縮へ戻す設計かによって変わります。公開情報にない挙動は、使用中のバージョンのログで確認してください。

確認順序は、認証変数、名前解決、ネットワーク出口、プロキシまたは証明書、応答形式、タイムアウトです。企業ネットワークやリモートMacでは、端末から外へ出る経路とコンテナから出る経路が異なることがあります。 Claude Codeのプロキシ設定と証明書に関する説明 も参照し、プロキシを変更する前後で同じリクエストを比較してください。

通信障害時の降格手順を先に決めておくと、長い作業を失いにくくなります。

1. 現在の要約と変更ファイルを保存する。
2. Jevへの再試行を繰り返さず、エラー時のログを確保する。
3. fast-jev-compaction を一時停止する。
4. Claude Codeの標準機能、または手動要約で作業状態を再構成する。
5. 通信復旧後に、破棄してもよい検証用セッションで再度有効化する。

Jevの圧縮リクエストが失敗すると、Claude Codeに影響しますか？

影響の有無はプラグインの失敗時処理と、その時点のセッション状態で決まります。通信失敗だけでコードが壊れるわけではありませんが、圧縮結果が返らない、古い状態を再利用できない、セッションが中断する可能性はあります。作業を止めたくない場合は、Jev通信に依存しない降格経路を用意してください。

圧縮後の復旧と固定要約

コンテキスト圧縮はバックアップではありません。長い会話を扱いやすくするための情報選別であり、すべてのツール出力、ファイル断片、判断理由を無損失で保管する仕組みではありません。公開リポジトリがツール呼び出しや結果の選別、切り詰め、保持を行うと説明している点も、この前提で読んでください。 プラグインの圧縮機構 を確認し、残る情報をバックアップと混同しないことが重要です。

プロジェクト内に、たとえば docs/agent-state.md のような固定要約ファイルを用意します。ファイル名はプロジェクトの規約に合わせて構いませんが、内容は毎回同じ順序にします。

• 作業目的と完了条件
• 変更したファイルのパスと変更理由
• 実行したコマンドとテスト結果
• 未解決のエラーと再現条件
• API、依存関係、互換性などの制約
• ユーザーが決定した事項
• 次に実行する1つまたは2つの作業

Claude Codeのメモリファイルには、どの範囲の指示が読み込まれるかというルールがあります。 公式メモリファイル説明 とプロジェクトの配置を照合し、要約ファイルを置いただけで自動的に読まれるとは考えないでください。

復旧は次の順番にします。

1. 失敗前のセッション識別情報とログを保管する。
2. git diff、変更一覧、テスト結果を別に保存する。
3. 新しいClaude Codeセッションで対象ファイルを再読込する。
4. 固定要約から未完了作業と制約を再提示する。
5. 小さな確認作業を実行し、状態の一致を確認する。
6. それでも不一致なら、プラグインを停止して手動要約で続行する。

Claude Codeで圧縮後にファイルの文脈を失った場合の戻し方は？

会話履歴を無理に復元するより、コード、差分、テスト結果、固定要約から状態を再構成します。特に未コミットの変更は、会話だけを根拠に戻さず、差分とファイル本体を人間が確認してください。高リスクの削除、マイグレーション、デプロイを自動エージェントだけで再開するのは避けます。

長い指示を短く再利用する場合も、状態、入力、期待する出力を分離します。 長いコンテキストでの状態管理に関する公式資料 の考え方に沿って、毎回変わる作業状態を会話の奥に埋め込まない構成にしてください。

注意：圧縮後に見えている要約が自然な文章でも、重要なファイルパスやテスト結果が欠けていることがあります。次の書き込み操作の前に、必須情報をチェックしてください。

リモートMacの観測と停止基準

リモートMacでは、次のログを同じ時刻情報で保存します。

• Claude Codeのセッション開始と終了
• プラグインの初期化、圧縮開始、圧縮終了
• Jevのリクエスト、応答、失敗理由
• ツール呼び出しと対象ファイル
• 圧縮前後の要約とチェックポイント

Kvmjetの インフラストラクチャ情報 を確認する際も、マシンを借りられるかだけでなく、作業ログをどこへ保存するか、接続断後に同じワークスペースへ戻れるかを運用条件として見ます。チームで長時間のClaude Codeを扱うなら、個人の端末にしかない設定や認証情報を減らし、ワークスペース単位で復旧できる状態にしてください。

開発では手動要約を中心にし、圧縮結果を頻繁に確認します。検証では自動圧縮を使っても、変更前後の差分を保存します。本番に近い高リスク作業では、破棄方針を強くしたまま書き込み操作を自動化しないでください。

次のいずれかに該当したら、自動圧縮を止めます。

• 圧縮後に必須ファイル、制約、テスト結果が複数回欠落する
• Jevの認証または応答形式が安定しない
• ログと実際のセッション状態を照合できない
• 破壊的な変更を、圧縮直後の不完全な要約だけで続行しようとしている
• 同じ失敗を小さな再現でも確認できる

標準のトラブルシューティング手順も併用し、プラグインだけに原因を固定しないでください。 Claude Code公式トラブルシューティング には、認証や実行環境など本体側の確認項目もあります。

ローカル端末だけで長いセッションを続ける方法は、スリープ、ネットワーク変動、個人設定の混在が弱点になります。共有クラウド環境は接続経路や権限管理が複雑になり、障害時に原因を切り分けにくいことがあります。専用のMac環境をレンタルすれば、作業用ワークスペースを分離し、ログ保存と再接続の手順をチームで揃えやすくなります。

ただし、物理ポートへの常時アクセスや長期間の安定した高負荷処理が必要なら、自社保有のMacのほうが適する場合もあります。短期の検証、チーム共有のAI Coding環境、遠隔で再現可能なClaude Code作業を用意したい場合は、Kvmjetの サポート情報 を確認し、固定要約ファイルとチェックポイントを先に設計してから環境を選ぶのが安全です。