Claude Code コンテキスト圧縮 完全ガイド｜/compact・/autocompact・auto-compact の発動点・CLAUDE.md【2026年10月版】

Claude Code を本気で日常の開発に組み込み始めると、誰もがぶつかる壁が「コンテキストの管理」です。長時間セッションを回すと応答が鈍り、Autocompact is thrashing の赤いエラーで作業が止まり、/compact を打ったのに直前の議論を Claude が思い出せない ── こうした症状の根は、コンテキストウィンドウを「圧縮」「メモリ」「分離」の3層でどう設計するかにあります。

この記事では、Anthropic 公式 Effective context engineering for AI agents（Anthropic Engineering）と Claude Code 公式 docs を一次ソースに、/compact / auto-compact / /clear / /rewind / サブエージェントの5手段の使い分けマトリクス、Anthropic 公式の3戦略（compaction / structured note-taking / multi-agent）と設計指針を Claude Code 実装に落とす対応表、コピペできるCLAUDE.md 階層テンプレ、トークン削減ベンチ3シナリオ、組織導入で使えるレビュー観点10項目 ── 個人開発から組織運用までフルカバーする実務リファレンスに仕上げました。基本概念はClaude Code完全ガイド、CLAUDE.md の書き方はclaude.md 書き方ガイド、エラー全般はClaude Code トラブルシューティングも合わせて参照ください。

TL;DR ── 結論サマリー

• コンテキスト管理は「圧縮」「メモリ」「分離」の3層設計: /compact / auto-compact / /clear / /rewind の4コマンド + サブエージェント・Skills・CLAUDE.md・MEMORY.md・claude-mem を組み合わせて回す
• auto-compact の発動点は「何%」ではなくモデルごとのトークン数で決まる: 公式 docs では、1M ウィンドウで動くモデル（Anthropic API 上の Sonnet 5 / Fable / Opus 4.7 以降）は既定で約 967K トークン、200K で動く構成は 200K の境界で圧縮。/autocompact 500k のように発動点を前倒しできる
• v2.1.299（2026年10月14日公開）から、サブスクで使うターミナルの長い会話は放置中にも自動で圧縮される: 200K トークン以上の会話を約54分放置すると、1時間のプロンプトキャッシュが切れる前に要約される（API キー・クラウド経由は既定では対象外）。止めるには settings.json に "idleCompaction": false
• /compact は focus 引数付きで先回り実行が安定: 自動圧縮は満杯近くまで待つため、区切りのよいタイミングで手動圧縮して「何を残すか」を自分で決める
• Autocompact is thrashing は「圧縮 → 大ファイル再読込 → 圧縮」の無限ループ: 公式トラブルシュート手順（行範囲読み込み / /compact keep only the plan and the diff / サブエージェント分離 / /clear）で対処する
• CLAUDE.md は 200行以内・階層分割: User / Project / Subdirectory の3層に .claude/rules/ と @include を組み合わせる
• auto memory は v2.1.59 以降で自動運用: 保存先は ~/.claude/projects/<project>/memory/、MEMORY.md の最初の200行 / 25KB のみ毎セッションロードされる

結論 ── コンテキスト管理は「圧縮」「メモリ」「分離」の3層で設計する

Claude Code のコンテキスト管理は、単一のコマンドで完結する問題ではありません。「圧縮」「メモリ」「分離」の3層を組み合わせて初めて、長時間セッション・長期プロジェクト・並列 worktree のすべてに耐える運用基盤になります。

Anthropic は公式記事 Effective context engineering for AI agents で「コンテキストは最も希少な資源」と位置付け、エージェントが長期タスクをこなすために compaction（要約圧縮）/ structured note-taking（構造化ノート）/ multi-agent architectures（マルチエージェント） の3つを推奨しています（出典: Anthropic Engineering）。Claude Code の上記3層は、この公式ガイドラインを CLI で実装したものとほぼ一対一に対応します。

この3層の背景にある設計思想（Write / Select / Compress / Isolate の4戦略、5要素モデル、context pollution などの失敗パターン）を体系的に押さえたい場合は、理論編のコンテキストエンジニアリング完全ガイドを先に読むと、本記事の各手段が「なぜそう設計されているか」まで一気に腑に落ちます。本記事はその実践編にあたります。

この記事はこの3層を5手段 × 4層メモリ × 分離アーキテクチャとして具体的に分解し、現場で詰まるautocompact thrashing、CLAUDE.md 設計、トークン削減ベンチ、組織標準化まで一気通貫で扱います。

コンテキスト圧縮5手段 完全使い分けマトリクス

5手段の機能比較表

「コンテキストが重い」と感じたときに最初に開くべきが、この比較表です。

状況別 早見マトリクス

「何を残したいか」「何を捨てたいか」で軸を切ると判断が速くなります。

判断フローチャート

実際の判断はテキストフローで覚えるのが速いです。

1. タスクが完全に切り替わる → /clear
2. 直近の数ターンが筋悪 → /rewind
3. 重い独立タスクを始める → サブエージェントに委任
4. 会話を継続したいが圧迫されてきた → /compact（focus 引数を必ず指定）
5. 介入せず上限を回避 → auto-compact に任せる（情報損失リスクは許容する）

コマンドの一覧はClaude Code スラッシュコマンド集で網羅していますが、コンテキスト圧縮系の判断軸はこの表とフローで足ります。

/compact コマンド完全リファレンス

基本実行

/compact は会話履歴をサマリーに圧縮するコマンドです。引数なしで実行すると、Claude が会話全体を分析し、重要な情報を残しつつ不要な部分を自動的に圧縮します。

/compact

「とりあえず圧縮したい」局面で有効ですが、焦点を指定しない圧縮は情報損失が大きくなりやすいため、実務では次の focus 引数つき実行を推奨します。

focus 引数で残す情報を制御する

/compact の最も重要な使い方が focus 引数 です。「何を残すべきか」を引数として渡すと、その領域を優先的に保持した状態で圧縮されます。公式トラブルシューティングでも /compact keep only the plan and the diff の例が明示されています（出典: Claude Code Docs - トラブルシューティング）。

/compact APIの仕様について重点的に残してください

/compact keep only the plan and the diff

/compact 直近のデバッグ過程は破棄、確定した設計判断のみ保持

focus 引数の実用テンプレート8パターン

実務で頻出する局面ごとに、コピペできる focus 引数のテンプレートを示します。

「引数なし /compact = Claude にすべて任せる」モードに対し、focus を渡すと「人間が判断軸を渡してから圧縮させる」モードになります。情報損失の最小化に最も効くのが focus 引数の運用です。

/compact 後の状態リカバリ

公式ドキュメントは「プロジェクトルートの CLAUDE.md は /compact 後にディスクから再読込・再注入される」と明記しています（出典: Claude Code Docs - memory）。一方でサブディレクトリの CLAUDE.md はそのディレクトリのファイルを読むタイミングで再ロードされるため、/compact 直後には反映されない場合があります。

そこで実務では、圧縮前に失いたくない情報をファイルへ退避する運用を推奨します。

# /compact 直前に重要な決定をファイルに書き出す
cat > .steering/notes/decision-2026-05-19.md <<'EOF'
- 検討中のAPI設計案A/B/Cの比較結果
- 採用案: B（理由: 既存スキーマとの後方互換 + パフォーマンス）
- 未解決: 認証方式の最終決定（次セッション持ち越し）
EOF

退避先を CLAUDE.md から @.steering/notes/decision-2026-05-19.md のように import しておけば、/compact 後のセッションでも自動的に再注入されます。Hooks 機能で PreCompact イベントに退避処理を仕込む高度な自動化はClaude Code Hooksで自動化する5つの実例で扱っています。

トラブル時の最終手段（/compact でも回復しない Prompt is too long）は「Prompt is too long」の対処法を参照してください。

auto-compact の発動メカニズムと制御

発動点はモデルと構成ごとに決まる

Claude Code はコンテキストが上限に近づくと自動的に圧縮します。以前は「200k トークンのモデルでおよそ 76〜83% 付近」という観測値が広く共有されていましたが、2026年9月時点の公式 docs では、発動点は割合ではなく「auto-compact ウィンドウ」というトークン数で説明されています。auto-compact ウィンドウとは「コンテキストがどこまで埋まったら自動圧縮するか」の値です（出典: Claude Code Docs - model configuration）。

auto-compact ウィンドウを自分で設定していない場合の既定の発動点は次のとおりです。

つまり、Anthropic API で 1M モデルを使う一般的な構成では、自動圧縮はウィンドウのほぼ満杯（約 967K / 1M）まで待ってから走ります。現在のコンテキスト使用量は /context で内訳つきで確認できます（出典: Claude Code Docs - context window）。

自動発動は便利ですが、満杯近くまで膨らんでから圧縮するため何を残すかを自動判断に任せることになります。公式 docs も、長い新タスクに入る前に focus 付きの /compact を実行したり、/autocompact で発動点を前倒ししたりして、自動圧縮の前に手を打つ方法を案内しています。

なお v2.1.273 の changelog には「advisor ツールのターンを実際の約2倍のコンテキストとして数えていたため、auto-compact が実際のウィンドウの約半分で発動していた」不具合の修正が記載されています（出典: Claude Code changelog）。想定よりかなり早く自動圧縮が走る場合は、まず Claude Code を最新版に更新してください。

/autocompact ── 発動点をトークン数で指定する

発動点を変えたいときの公式の手段が /autocompact コマンドです（出典: Claude Code Docs - commands、model configuration、CLI reference）。

/autocompact 500k    # 50万トークンで自動圧縮
/autocompact auto    # モデルに合わせた既定値に戻す
/autocompact         # 引数なしで現在のウィンドウを表示するダイアログを開く

• 値は 100K〜1M トークン。200000 のような数値、500k / 1M のような接尾辞つき、100〜1000 の数値（千単位、200 なら 20万）のいずれでも指定できる
• 値はユーザー設定の autoCompactWindow に保存され、現在のセッションにもすぐ反映される
• モデルのコンテキストウィンドウを超える値は、そのウィンドウで頭打ちになる

設定する場所は3つあり、用途で使い分けます。

# スクリプトや CI では環境変数で指定（"500k" ではなく整数で書く）
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=500000

環境変数に 500k と書くと 500 と読まれて最小値の 100K に丸められる点に注意してください。また、ステータスラインの used_percentage は常にモデルの全ウィンドウに対する割合なので、この環境変数を設定すると「何%で圧縮されるか」の目安にはならなくなります（出典: Claude Code Docs - environment variables）。

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE ── 割合で「早める」方向にだけ調整

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE は、auto-compact ウィンドウに対する割合（1〜100）で発動点を指定する環境変数です。

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

公式 docs の説明では、この変数は閾値を上げることはできず、既定の割合より大きい値は無視されます。また、モデルの上限より前に圧縮するセッションにだけ適用され、メインの会話とサブエージェントの両方に効きます（出典: Claude Code Docs - environment variables）。発動点を具体的なトークン数で決めたい場合は、前述の /autocompact や CLAUDE_CODE_AUTO_COMPACT_WINDOW の方がわかりやすい手段です。

DISABLE_AUTO_COMPACT=1 ── auto-compact をオフにする

auto-compact 自体を止めたい場合は、DISABLE_AUTO_COMPACT=1 を設定するか、/config の Auto-compact をオフ（settings.json の autoCompactEnabled: false）にします。どちらの方法でも手動の /compact は引き続き使えます。/compact も含めてすべての圧縮を止める DISABLE_COMPACT=1 という別の変数もあります（出典: Claude Code Docs - environment variables、settings reference）。

export DISABLE_AUTO_COMPACT=1

autoCompactEnabled と DISABLE_AUTO_COMPACT は、どちらか一方がオフにすると、もう一方でオンに戻すことはできません。

注意: auto-compact をオフにしたままコンテキストが上限に達すると、圧縮される代わりに「Prompt is too long」系の上限エラーで止まります（CLAUDE_CODE_DISABLE_1M_CONTEXT=1 で 200K に制限している場合は 200K の境界で止まる、と公式 docs に記載があります）。以前は「DISABLE_AUTO_COMPACT=1 を設定しても発動した」という報告（Issue #42394、2026年5月に Not planned としてクローズ）もあったため、オフにする場合も /compact の手動運用や PreCompact Hook を併用しておくと安心です。

使いどころ:

• カスタム Hook（PreCompact 等）や手動 /compact で圧縮タイミングを完全に自分で管理したい
• 短セッション運用が中心で auto-compact が逆に邪魔になりがち

1M ウィンドウのモデルでは既定の発動点がすでに約 967K とウィンドウの端に近いため、「遅らせたいからオフにする」必要性は以前より小さくなっています。

idleCompaction ── 放置した長い会話を自動圧縮する（v2.1.299〜）

2026年10月15日追記：2026年10月14日公開の Claude Code v2.1.299 から、ターミナルで長い会話を放置すると、戻る前に自動で圧縮されるようになりました。 Claude のサブスクリプションで使う 200K トークン以上の会話を約54分放置すると、1時間のプロンプトキャッシュが切れる直前に要約し、次のメッセージで会話全体を送り直さずに済むようにする仕組みです。不要なら settings.json に "idleCompaction": false を書けば止まります（出典: Claude Code changelog、settings reference - idleCompaction）。

公式 docs では、次の条件をすべて満たす会話で既定で有効になります。

1時間のキャッシュ TTL が既定で使われるのは、Claude のサブスクリプションでプランの利用枠内のメイン会話です。API キー・クラウドプロバイダ経由、または利用上限を超えて使用量クレジットで使っている間は、既定では5分 TTL になるため、この条件に当たりません（出典: Claude Code Docs - prompt caching）。

圧縮されたかどうかは、戻ったときの会話に表示される Compacted while idle, before the prompt cache expired で分かります。圧縮後の会話は要約に置き換わるため、細かい議論の経緯は残らないことがあります。休憩前に残したい内容がはっきりしているなら、離れる前に focus 付きの /compact を自分で打っておくほうが確実です。

"idleCompaction": false 以外の止め方と、閾値の変え方は次のとおりです。

• DISABLE_AUTO_COMPACT=1 を設定している場合は、auto-compact と一緒にアイドル時の圧縮も止まります
• 閾値は環境変数 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS で変えられます。下限は 100,000 で、それより小さい値は 100,000 に引き上げられます

200K ウィンドウで動く構成は、既定のままだと 200,000 トークンに達する前に通常の auto-compact が走るため、アイドル時の圧縮の対象になりません。公式 docs は、このような構成で使いたい場合に閾値を 150,000 へ下げる例を載せています。

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 ── auto memory の無効化

auto memory（後述）も環境変数で無効化できます（出典: Claude Code Docs - memory）。

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

機密性の高いプロジェクトや、auto memory が好ましくないチームでの一時的な無効化に有効です。/memory コマンド内のトグル、または settings.json の autoMemoryEnabled: false でも同等です。

PreCompact Hook で圧縮前にカスタム処理を挟む

Claude Code v2.x 以降は Hook 機能が拡張され、PreCompact イベントで auto-compact 発動直前にカスタム処理を実行できます。実務では「圧縮前に重要状態をファイルへ退避する」スクリプトを仕込むのが最も効きます。

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/snapshot-state.sh" }
        ]
      }
    ]
  }
}

Hooks の詳しい設計はClaude Code Hooksで自動化する5つの実例で扱っていますが、PreCompact は「情報損失の主因（圧縮）を人間ルールでフックして回避する」最強の予防策です。

autocompact thrashing エラーが出たとき

Autocompact is thrashing は、自動圧縮には成功したのに、大きなファイルやツール出力がすぐにコンテキストを満杯に戻すことが続いたため、Claude Code が再試行を止めた状態です。対処の基本は、ファイルを行範囲で読む・focus 付きの /compact・大きな処理のサブエージェント分離・/clear の4つです。原因の切り分けと手順はAutocompact is thrashing の原因と直し方で詳しく解説しています。

/clear と /rewind を効果的に使う

/clear ── 会話を完全リセット

/clear

会話履歴をすべて破棄し、CLAUDE.md だけが残った白紙状態に戻します。タスクが完全に切り替わるとき、または「もう過去の会話を引きずりたくない」ときに使います。

/clear と新セッションの違い: /clear は同じ Claude Code プロセス内で context だけをリセットしますが、CLAUDE.md・Skills・MCP 設定はリロード不要で即座に再利用できます。claude を再起動するより起動コスト分速いのが実務上の利点です。

ログは消えない: /clear してもターミナル上の会話ログや transcript ファイルは残ります。claude --resume で過去セッションに戻れる仕組みは公式トラブルシュートでも触れられています（出典: troubleshooting）。

/rewind ── 特定のチェックポイントに巻き戻し

/rewind は直近の数ターンを取り消し、過去のチェックポイントに戻ります。「直近5ターンの試行錯誤が筋悪だったので、最初の方針からやり直したい」というケースで威力を発揮します。

主な利用シーン:

• 試行錯誤が一気に詰まり「もう少し前に戻りたい」とき
• Claude が大きく道を逸れた回答をした直後（その回答を採用したくない）
• 別アプローチを試したいが、現在の状態を保存しておきたい時

/compact は要約してから継続、/clear は完全リセット、/rewind は特定の過去地点から再始動 ── この違いを意識すると無駄なコンテキスト消費を抑えられます。

圧縮 vs リセット vs 巻き戻しの判定軸

サブエージェント・Skills・Memory Tool の使い分け

/compact や /clear に頼らない、最も効果的な予防策が「コンテキストを最初から分離する」設計です。Claude Code には3つの分離手段があります。

3つの分離手段 比較表

判断フロー

「新しい仕事」をどう設計するか:

新しい仕事 → 大規模な独立処理？
  Yes → サブエージェント（独立コンテキスト窓で処理 → 結果サマリーだけ親に返す）
  No  → 知識・手順を再利用するか？
    Yes → Skills（手順をライブラリ化）
    No  → 単発のメインセッション
       └─ 過去の議論を呼び出したい？
            Yes → Memory Tool / claude-mem
            No  → CLAUDE.md / MEMORY.md に書き留めるだけ

サブエージェントの実装例

# 親セッション側
このリポジトリの全テストファイルを読んで、
失敗しがちなテスト戦略の傾向を要約してください
（サブエージェント `test-analyzer` で実行）

サブエージェント側で消費されたトークンは結果サマリーだけが親セッションに返るため、/compact で事後対処するより最初から重い処理を分離する設計のほうがコンテキスト効率が高くなります。詳しくはClaude Code サブエージェント完全ガイドで扱っています。

Skills でのコンテキスト分離

Skills は「呼び出し時にだけロードされる手順書」です。常時 CLAUDE.md に書くべきではないニッチで再利用可能な手順（例: 特殊な PR テンプレート、特定 API への接続フロー）は Skills に切り出すと、メインのコンテキスト消費が劇的に減ります。Skills の設計はClaude Code Skills 完全ガイドで詳述しています。

Memory Tool / MCP との関係

Anthropic API レベルでは Memory Tool / Context Editing が用意されています（公式: Context Editing API / Claude Cookbook - context engineering）。Claude Code 内では MEMORY.md（auto memory）と claude-mem プラグインがこの層に相当します。Managed Agents で組織レベルに展開するパターンはClaude Managed Agentsで扱っています。

4層メモリモデルの全体像

ここまでがセッション内の「圧縮」と「分離」。次はセッションを跨いで情報を持続させるための「メモリ」に視点を移します。

設計原則: 同じ情報を複数層に重複させない。CLAUDE.md は「常に守るべき指示」、MEMORY.md は「Claude が学んだ事実」、claude-mem は「過去議論の検索インデックス」と役割を切ります。Managed Agents や Skills を併用する組織は、加えて Skills を「呼び出し時ロードの手順」として5層目に置く設計も可能です。

CLAUDE.md 階層設計テンプレート（コピペ可）

User / Project / Subdirectory の3層

公式 docs は User instructions → Project instructions → Local instructions → Subdirectory CLAUDE.md の階層を明文化しています（出典: Claude Code Docs - memory）。

ロード順は「上位ディレクトリ → 下位」「CLAUDE.md → CLAUDE.local.md」の順で、後から読まれるものほど優先度が高くなります。

コピペ用テンプレ ── User レベル（~/.claude/CLAUDE.md）

# 個人共通の好み

## 言語
- 会話は日本語で
- 変数名・関数名・コミットメッセージは英語

## エディタ・ツール
- パッケージマネージャは pnpm を優先
- フォーマッタは prettier、リンタは eslint-config-next を想定

## コード品質
- TypeScript 厳格モード前提。`any` 禁止
- 関数は 50 行以内、ファイルは 400 行を目安に分割

## レビュー姿勢
- 「動くだけ」のコードでなく、命名・構造・テスタビリティを重視
- PR では必ず変更理由（why）を書く

コピペ用テンプレ ── Project レベル（./CLAUDE.md）

# {プロジェクト名} の指示

## プロジェクト概要
- {1〜2行で何のプロジェクトか}
- 主要技術: Next.js 16, TypeScript, Tailwind CSS v4, ...

## ディレクトリ構成
- `apps/web` ── ユーザー向け Next.js アプリ
- `apps/api` ── バックエンド API
- `packages/ui` ── 共通 UI コンポーネント

## ビルド・テストコマンド
- 開発: `pnpm dev`
- 型チェック: `pnpm typecheck`
- テスト: `pnpm test`
- リント: `pnpm lint`

## コーディング規約
@.claude/rules/code-quality.md
@.claude/rules/typescript-style.md
@.claude/rules/git-workflow.md

## 優先順位
1. セキュリティ（秘密情報を出力しない、権限を超えない）
2. 既存のコーディング規約
3. ユーザーの直近の指示
4. Claude の好み

## 禁止事項
- `git push origin main` の直接実行（必ず PR 経由）
- 秘密情報・APIキーの CLAUDE.md / MEMORY.md への記載

コピペ用テンプレ ── Subdirectory レベル（apps/web/CLAUDE.md）

# apps/web 固有の指示

## このディレクトリの責務
- ユーザー向け Web フロントエンド（Next.js 16 App Router）
- マーケティングサイトとアプリケーション UI を兼ねる

## 重要なルール
- コンポーネントは `components/` 配下、ロジックは `lib/` 配下
- API 呼び出しは `lib/api/` 経由、直接 fetch は禁止
- 国際化は next-intl v4 を使用、ハードコードされた文字列は禁止

## このディレクトリで作業するときの注意
- スタイルは Tailwind CSS v4（@plugin 構文）のみ。CSS Modules は使わない
- shadcn/ui v4 のコンポーネントは Base UI 系。Radix を新規導入しない

.claude/rules/ で path-scoped ルールを切り出す

./.claude/rules/ 配下の Markdown ファイルは、paths フロントマターで対象ファイルを絞れます。これにより「特定ファイルを読むときだけロード」する条件付きルールが実現でき、ベースのコンテキスト消費を抑えられます（出典: Claude Code Docs - memory）。

---
paths:
  - "src/api/**/*.ts"
---

# API 開発ルール

- 全 API エンドポイントは Zod で入力バリデーションを実装
- エラーレスポンスは標準フォーマット `{ error: { code, message } }`
- OpenAPI 用 JSDoc コメントを必須

200行ルールと例外条件

公式 docs は「CLAUDE.md は1ファイルあたり 200行以内を目安に」と推奨しています。長くなるとコンテキスト消費が増え、Claude の指示遵守率も下がります。

詳細な書き方はclaude.md 書き方ガイドで深掘りしています。

大規模モノレポでの注意 ── claudeMdExcludes

モノレポで自チームに無関係な CLAUDE.md が読まれてしまう場合、.claude/settings.local.json の claudeMdExcludes で除外できます。

{
  "claudeMdExcludes": [
    "**/other-team/CLAUDE.md",
    "/abs/path/legacy/.claude/rules/**"
  ]
}

managed policy 配置の CLAUDE.md は除外できない仕様で、組織標準は必ず適用されます。

MEMORY.md（auto memory）の運用

公式仕様 ── 200行 / 25KB / ~/.claude/projects/<project>/memory/

Claude Code v2.1.59 以降 で利用可能（要件は claude --version で確認）。重要な公式仕様（出典: Claude Code Docs - memory）:

• 保存先: ~/.claude/projects/<project>/memory/ ── <project> は Git リポジトリ単位で導出され、同一リポジトリの worktree や subdirectory は1つのメモリディレクトリを共有
• MEMORY.md のロード閾値: 最初の 200行 または 25KB（先に到達した方）。これを超える部分はセッション開始時にはロードされない
• トピックファイル: debugging.md, api-conventions.md 等は起動時ロードされず、Claude が必要なときにファイルツールで読み込む
• マシンローカル: クラウド・他マシンと共有されない
• 設定: autoMemoryEnabled: false, autoMemoryDirectory: ~/my-custom-memory-dir（project / local settings からは設定不可 ── セキュリティ上の理由）

/memory コマンドでの閲覧・編集

/memory で auto memory フォルダを開き、Claude が自動保存した内容を確認・編集・削除できます。エディタで開いて自由に編集してください。

自動保存される情報の種類

Claude が「次回以降も役立つ」と判断したものが自動追記されます。典型例:

• ビルドコマンド: pnpm test が型チェックまで走る、pnpm dev:local で .env.local がロードされる、等
• デバッグ時の気づき: DB 接続には direnv の .envrc が必要、ローカル Redis 起動の手順、等
• アーキテクチャの要約: モノレポ構成、主要パッケージの責務、等
• コードスタイルの好み: 関数命名規則、import の並べ方、等
• ワークフロー習慣: PR 作成前に必ず実行するコマンド、等

「ユーザーが同じ指示を2回入れた」「Claude が同じ失敗を2回した」あたりが自動追記の発火点です。

棚卸しと秘密情報チェック

公式 docs も明示しているとおり、auto memory はplain markdown でユーザーが自由に編集・削除できます。実務では月次レベルで棚卸しを推奨:

サブエージェントの auto memory

公式 docs に明記されているとおり、サブエージェントも独自の auto memory を持てます。subagents セクションで enable-persistent-memory を有効化すると、サブエージェント単位で学習ログが蓄積されます。テスト戦略を担うサブエージェント、リファクタリング担当のサブエージェント等、責務ごとに分けると有効です。

claude-mem プラグインの判断基準

thedotmack 氏が開発する claude-mem は、Claude Code の会話を AI で圧縮し、ベクトルデータベースに保存し、新セッションで関連部分を自動注入するプラグインです。

仕組み: 3層ワークフロー

1. Capture: セッション中の会話・ツール呼び出しを収集
2. Compress: Claude Agent SDK で圧縮・要約
3. Retrieve: 新セッションの入力に対し、ベクトル検索（コサイン類似度）で関連過去文脈をトップ N 件返し、context に注入

導入判断: 向く / 向かない

Worker クラッシュとの関連

claude-mem を有効化した状態で「Worker started ログが連発する」「応答が極端に遅い」などの症状が出る場合、claude-mem の SQLite データベース肥大が原因のことがあります。詳しくはClaude Code トラブルシューティング - Worker クラッシュを参照してください。

Context Engineering の3戦略と設計指針 × Claude Code 実装マッピング

Anthropic は公式記事 Effective context engineering for AI agents で、長期エージェントの安定運用に必要な3つの主要戦略（compaction / structured note-taking / multi-agent architectures）と、それを支える設計指針（smallest set of high-signal tokens、just-in-time retrieval、context rot への配慮）を整理しています（出典: Anthropic Engineering）。Claude Code はこれらを CLI レイヤーで具体的に実装したものとして理解できます。

3つの主要戦略

設計指針（3戦略を支える土台）

加えて、Anthropic は context rot を「ハード上限の前から既に劣化が始まっている」と警告しています。つまり「上限の 100% まで使い切ってから圧縮」は理論上ベストプラクティスではなく、60-80% で圧縮するコミュニティの経験則は理論的にも正しい挙動です。

3戦略 + 設計指針 → Claude Code 実装の対応表

context rot ── 「上限に達する前」の精度劣化

実務での示唆:

• 「コンテキスト残量があるから大丈夫」と油断しない
• 長いコンテキストでは重要事項を末尾に再注入するパターン（CLAUDE.md @include や .steering/notes/ ファイル）が効く
• 1M ウィンドウのモデル（Sonnet 5 / Opus 4.7 以降など）でも context rot は発生する ── 物理的上限と実用性能は別

詳しい理論背景はContext Engineering 完全ガイドで扱っています。

トークン削減ベンチ実測（3シナリオ）

「圧縮を真面目にやると、どれくらいトークンが減るのか」── 実務で問われる定量問いに答える参考データを示します。

計測条件

3シナリオの結果（観測される傾向）

観測される傾向と意思決定への示唆

• A → B: 50% 前後の削減。「読み込み戦略」と「proactive 圧縮」だけで効果が出る ── 最も低コストな改善
• B → C: さらに 20% 程度の追加削減。サブエージェント運用コスト（定義作成・テスト）と引き換えにメインコンテキスト窓の保護が得られる
• 絶対値ベンチがないので$換算は概算: Sonnet 4.6 / Opus 4.7 の公式 pricing から逆算した推定値であり、実プロジェクトでは MCP やキャッシュヒット率で大きく変わる

意思決定の指針:

「圧縮しないほうが速い」逆説パターン

「圧縮 = 常に正解」という単純化を避けるため、圧縮が逆効果になる4ケースを列挙します。

ケース1: 短セッション（30分以内）

圧縮自体のオーバーヘッド（要約生成のための API 呼び出し）が、削減で得られるトークン分のメリットを上回ります。30分以内に閉じるセッションは /compact を入れない方が速いことが多いです。

ケース2: 1M ウィンドウのモデル使用時（Sonnet 5 / Opus 4.7 以降など）

200K ウィンドウでは 60-80% は 120K-160K トークン圏ですが、1M ウィンドウでは 600K-800K トークン圏に相当します。そもそも物理的に余裕があるため、圧縮タイミングは大幅に後ろ倒しできます。公式 docs によると、こうしたモデルの自動圧縮は既定で約 967K トークンまで走らないため、auto-compact をオフにしなくても圧縮が入ることはまれです。逆に context rot が気になる場合は、/autocompact 500k のように発動点を前倒しする使い方もできます。

ケース3: 直近ターン依存の精密タスク

リファクタリングのように「数ターン前の中間思考の細部」が次のターンに必要な場面では、要約が逆に精度を落とすことがあります。中間思考を残したい場合は /compact の focus 引数で「最近の N ターンは詳細を残す」と指示するか、そもそも圧縮しないのが安全です。

ケース4: 同一ファイル連続編集（キャッシュヒット最適化）

Claude API はプロンプトキャッシュを持ち、同じ大きな読み込みは2回目以降キャッシュヒットで安価になります。/compact で要約に置換するとこのキャッシュが効かなくなるため、短時間で同じファイルを何度も触る局面では圧縮しない方が結果として安いことがあります。

→ 圧縮は常に正解ではない。「圧縮を入れない判断」も技術判断として持つことが、長期運用の質を上げます。

チーム標準化 ── context pollution 防止レビュー観点10項目

組織で Claude Code を運用すると、context pollution（コンテキスト汚染）が個人レベルから組織レベルの問題に変わります。CLAUDE.md が秘密情報を含む、Skills が重複する、MEMORY.md がチームで bias する ── こうした事故を防ぐため、PR / 設計レビューで使える10項目チェックリストを示します。

このチェックリストを .claude/rules/team-review.md に置き、PR テンプレートからリンクさせる運用がおすすめです。組織導入時の context pollution 対策はClaude Code エンタープライズ導入でもさらに深掘りしています。

実践運用シナリオ

シナリオ1: 1週間の長期タスク

• 日次で /compact を proactive 実行（60-80% あたり）
• 大規模ファイル読込みは subagent に委任
• CLAUDE.md に前提をまとめ直し、決定ログを .steering/notes/ に外出し
• claude-mem を有効化して過去 1 週間の文脈を呼び出し可能に
• PreCompact Hook で「圧縮前に重要状態を退避」を自動化

シナリオ2: 複数 worktree 並行開発

• CLAUDE.md はプロジェクトルート（全 worktree 共通）
• worktree 固有の前提は .steering/worktree/<branch>.md に書き、CLAUDE.md から @include
• auto memory は同一リポジトリの全 worktree で共有される（公式仕様）ため、矛盾しないルールを徹底
• 並列開発の詳細はClaude Code worktree並列化を参照

シナリオ3: チーム横断プロジェクト

• CLAUDE.md は Git で共有、.claude/rules/ で paths フロントマターを使いチーム別ルールを path-scope
• auto memory は個人ごと（共有しない、秘密情報混入リスク）
• ベクトル DB / Managed Agents を持つならチーム共有 DB で役割別インデックスに分ける
• Managed policy 配置の CLAUDE.md で組織標準を強制

シナリオ4: フェーズが完全に切り替わるとき

• 「設計フェーズ→実装フェーズ」「機能A→機能B」のようにタスクが完全に切り替わる場合は /clear でリセットが最も効率的
• /compact で残しても、無関係な過去会話が圧縮された形で残り続け、新フェーズの作業を阻害する

シナリオ5: 並列デスクトップアプリ運用

Claude Code Desktop で複数セッションを並列で動かす場合、各セッションが独立した context window を持ちます。デスクトップ並列運用の設計はClaude Code デスクトップアプリ並列セッション完全ガイドを参照ください。

Gotcha ── メモリ運用の落とし穴

CLAUDE.md に秘密情報を書かない

CLAUDE.md は Git 共有されるのが通常です。API キー・DB 接続文字列・個人情報を書くと即座に漏洩します。秘密情報は環境変数・シークレットマネージャで管理し、CLAUDE.md には「環境変数 XXX 経由」と抽象表現で書きます。個人プロジェクトの秘密情報は CLAUDE.local.md（.gitignore 推奨）に分離します。

auto memory にも秘密情報が記録されうる

Claude が会話中に触れた DB パスワード・API キー・個人情報が auto memory に自動記録されることがあります。/memory で定期的に内容確認し、秘密情報があれば削除してください。CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 で完全停止する選択肢もあります。

claude-mem 等の外部プラグインの保存先

プラグインによってはベクトル DB がローカルではなくクラウドに保存されることがあります。社外秘プロジェクトでは保存先と暗号化方式を事前に確認してください。

auto memory の陳腐化

半年前の auto memory が今でも正しいとは限りません。「これは古い」と Claude が判断できないケースは、人間の定期棚卸しが必要です（前述）。

/compact 後の状態リカバリ

/compact 直後、Claude が直前の作業を正確に思い出せないことがあります。「いま何を作業中だったか」を明示的に再注入する習慣（CLAUDE.md への作業中タスク記載、明示的なリマインダー）が有効です。プロジェクトルート CLAUDE.md は自動再注入されるため、ここに作業中フラグを書く運用も実用的です。

サブディレクトリの CLAUDE.md は自動再注入されない

公式 docs によれば、ネストされた CLAUDE.md は /compact 後に自動再注入されません。サブディレクトリ固有のルールを永続させたい場合は、プロジェクトルート CLAUDE.md から @include する形にしておくと圧縮後も生き残ります。

--add-dir で追加した外部ディレクトリの CLAUDE.md

claude --add-dir ../shared-config で別ディレクトリを参照させる場合、デフォルトではそのディレクトリの CLAUDE.md はロードされません。CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 を設定すると --add-dir 配下の CLAUDE.md もロードされます（出典: Claude Code Docs - memory）。マルチリポ運用で活躍する設定です。

コンテキストウィンドウの可視化

「いま何% 消費しているか」が分からないと圧縮判断ができません。Claude Code には可視化手段が2つあります。

/context コマンド

セッション内で /context を実行すると、現在のコンテキスト使用率と内訳（会話履歴 / ツール定義 / 添付ファイルなど）を確認できます。/compact 実行前にこのコマンドで現状を把握しておくと、「あと何% 余裕があるか」を踏まえて focus 引数を設計できます。

statusline での常時表示

~/.claude/settings.json の statusLine 設定でカスタムシェルスクリプトを指定すると、ターミナル下部にコンテキスト使用率を常時表示できます。

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

statusline.sh 内で Claude Code が提供する情報をパースして整形表示します。設定後、Claude Code を再起動すると反映されます。

/doctor ── 一発自動診断

公式トラブルシュート docs で推奨されているのが /doctor コマンドです。インストール、設定、MCP サーバー、コンテキスト使用量を一度に自動チェックできます。claude が起動しない場合は代わりにシェルから claude doctor を実行します（出典: Claude Code Docs - troubleshooting）。

60-80% を超えたら proactive に /compact を実行するルールを習慣化すると、auto-compact による情報損失を避けられます。

コンテキスト診断・運用系コマンド集

コンテキスト圧縮を運用する上で押さえておきたい公式コマンドをまとめます（出典: Claude Code Docs - troubleshooting）。

claude --resume ── セッション再開

ターミナルを閉じてしまった、/clear した直後に「やっぱり戻りたい」、Claude Code がハングして再起動した ── こうした場面で過去セッションを再開できます。同じディレクトリで実行するだけです。

claude --resume

公式トラブルシュート docs も「再起動してもカンバセーションは失われません。同じディレクトリで claude --resume を実行してセッションを再開してください」と明記しており、/clear の安全装置として覚えておくと便利です。

/heapdump ── メモリ状態のスナップショット

応答が遅い、メモリ使用量が異常に高い ── そんな時は /heapdump で JavaScript ヒープスナップショットを取得できます。~/Desktop に .heapsnapshot ファイルが出力され、Chrome DevTools のメモリタブで開くことができます。Linux でデスクトップフォルダがない場合はホームディレクトリに出力されます。

Claude Code のメモリ問題を GitHub Issue に報告する際は、このファイルを添付するのが推奨されています。コンテキスト肥大が JavaScript オブジェクト由来なのか、ネイティブメモリ由来なのかを切り分けられます。

/feedback ── Anthropic への直接報告

Autocompact is thrashing を再現性ある形で起こせる、ドキュメントに載っていない挙動がある ── そうした場合は /feedback で Anthropic に直接報告できます。コミュニティ Issue に出す前後で活用すると、修正の優先度が上がりやすくなります。

USE_BUILTIN_RIPGREP=0 ── 検索パフォーマンス改善

副次的ですが、Search ツールが遅い／結果が不完全な場合はバンドル版 ripgrep ではなくシステム ripgrep を使う設定が公式トラブルシュートで推奨されています。WSL 環境などでは特に効果的です。

検索が高速化するとコンテキスト消費（無駄な読み込み）も減るため、結果的に圧縮頻度が下がります。

よくある質問

まとめと次のステップ

Claude Code のコンテキスト管理は、「すべてを記憶させる」ではなく「適切な層に適切な情報を配置する」という発想で設計するのが本質です。

• 5手段の使い分け: /compact（継続） / auto-compact（自動） / /clear（リセット） / /rewind（巻き戻し） / サブエージェント（分離・予防）
• /compact の focus 引数で情報損失を最小化、autocompact thrashing は 行範囲 / focus / Subagent / clear の4手順で対処
• auto-compact の発動点はモデル別（公式 docs: 1M ウィンドウのモデルは既定約 967K トークン、200K 構成は 200K 境界）。/autocompact で前倒しでき、context rot 観点では区切りのよいタイミングで先回りの /compact が有効
• CLAUDE.md は User / Project / Subdirectory の3層 + .claude/rules/ の path-scoped、200行以内を維持
• auto memory（MEMORY.md）は v2.1.59+ で自動運用、保存先は ~/.claude/projects/<project>/memory/、200行 / 25KB ロード
• Anthropic Context Engineering の3戦略（compaction / structured note-taking / multi-agent）と設計指針は Claude Code 実装に1対1で対応する ── 公式の長期エージェント設計の柱
• トークン削減は読み込み戦略+proactive圧縮で約50%、サブエージェント分離でさらに20%（観測値）の削減が期待できる
• 組織導入時はレビュー観点10項目を .claude/rules/team-review.md に整備し、PR テンプレートからリンク

次のステップ:

• CLAUDE.md の書き方を深める → claude.md 書き方ガイド
• Hooks で自動化 → Claude Code Hooksで自動化する5つの実例
• スラッシュコマンドの全容 → Claude Codeスラッシュコマンド集
• Context Engineering を理論で深掘り → Context Engineering 完全ガイド
• エラー全般のリファレンス → Claude Code エラー一覧と解決手順
• サブエージェント設計 → Claude Code サブエージェント完全ガイド
• 並列 worktree 運用 → Claude Code worktree並列化
• 組織導入 → Claude Code エンタープライズ導入 / Claude Managed Agents

関連記事

• Claude Code完全ガイド
• Claude Code エラー一覧と解決手順
• Claude Code Skills 完全ガイド
• Claude Code サブエージェント完全ガイド
• Claude Code プラグイン & マーケットプレイス完全ガイド
• Claude Code デスクトップアプリ並列セッション完全ガイド