プロンプトキャッシュとは

Claude Codeは毎ターン、システムプロンプト（CLAUDE.md、skills、設定情報）をAPIに送信する。キャッシュが効いていれば、前回と同じ部分は再計算されない。効いていなければ、全文が新規トークンとして課金される。

キャッシュが効いている状態では1ターンの消費が軽い。壊れると同じ操作でも消費が2〜5倍になる。

原因1: git statusがシステムプロンプトに含まれる

#47107で指摘された問題。Claude Codeはシステムプロンプトに現在のgit statusを含める。つまり:

ファイルを1つ変更するとgit statusが変わる
git statusが変わるとシステムプロンプトが変わる
システムプロンプトが変わるとキャッシュが壊れる

コードを書くたびにキャッシュが壊れる。

回避策

環境変数で無効化できる:

export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1
claude

ただしgit関連の指示がなくなるため、gitを多用するワークフローでは注意が必要。

原因2: skills + CLAUDE.mdが毎回キャッシュを再生成する

#47098の発見。新しいセッションを開始すると、skills・CLAUDE.md・設定情報（約6,500トークン）がキャッシュなしで送信される。

これは仕様上避けられない——新セッションには前回のキャッシュがない。問題は、この6,500トークンのキャッシュ作成がセッションを開始するたびに発生すること。

セッションを頻繁に切り替える使い方だと、毎回6,500トークンのオーバーヘッドが積み重なる。

回避策

セッションを安易に切り替えない。1セッション=1テーマで、テーマが完了するまで続ける
CLAUDE.mdを短くする。長いCLAUDE.mdはキャッシュ再生成コストを増やす。100行→35行に凝縮するとキャッシュ効率が改善する
skillsを整理する。使わないskillsは無効化する

原因3: Cache TTLが1時間→5分にサイレント変更された

#46829で報告された問題。2026年3月初旬、Anthropicはプロンプトキャッシュの有効期間（TTL）を1時間から5分に短縮した。事前の告知なし。

何が起きるか:

以前は1時間以内の操作ならキャッシュが効いていた
5分に短縮されたため、少し考えたり休憩したりするとキャッシュが切れる
キャッシュミス → 全文再送信 → トークン消費が20-32%増加

5分間操作しないだけでキャッシュが消える。 コードを読んで考える時間、ドキュメントを確認する時間——人間にとって普通のペースがキャッシュを壊す。

回避策

作業を中断しない。5分以内に次の操作を行う
長考が必要なら新セッションを前提にする。--resumeは使わない（#42338でキャッシュ完全無効化が報告されている）
hookでキャッシュ効率を監視する（下記参照）

hookでキャッシュ破壊を検知する

settings.jsonのhookで、キャッシュ効率の低下を自動検知できる:

#!/bin/bash
# cache-efficiency-monitor.sh (PostToolUse hook)
# セッション中のトークン消費を記録し、急増を警告
SESSION_LOG="/tmp/cc-token-session-$(date +%Y%m%d).log"
INPUT=$(cat)
TOKENS=$(echo "$INPUT" | jq -r '.session_tokens // empty' 2>/dev/null)
[ -z "$TOKENS" ] && exit 0

echo "$(date +%H:%M:%S) $TOKENS" >> "$SESSION_LOG"
exit 0

まとめ

キャッシュ破壊の3大原因:

git statusの変更（ファイル編集のたびに発生）→ CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1で回避
セッション切り替え時の再生成（6,500トークン/回）→ セッション頻度を減らす + CLAUDE.mdを短く
Cache TTLサイレント短縮（1h→5min、2026年3月）→ 5分以上の中断でキャッシュ消失。コスト20-32%増

自分のキャッシュ効率を確認したい方へ
Token Checkupで5つの質問に答えるだけでトークン消費パターンを診断できる（無料）。

📖 トークン消費に困っているなら → Claude Codeのトークン消費を半分にする——800時間の運用データから見つけた実践テクニック（¥2,500・はじめに+第1章無料）

関連記事: Claude Codeのトークン消費を減らす5つの方法——Opus 4.7対応
:::note info
📖 AIで事業を回す実体験を全記録 → Claude Code×個人事業 800時間の全記録（¥800・第2章まで無料）
:::

⚠️ Opus 4.7緊急情報（2026年4月17日）
Opus 4.7のauto mode安全分類器がOpus 4.6にハードコードされている問題が発覚。3日間で23件以上のデータ損失。さらにv2.1.100以降、APIコールごとに約20,000トークンが見えない場所で追加課金されている問題も判明（#46917、GitHub上196件のリアクション）（50GB永久消失含む）。4倍のトークン消費も報告されている。対策: npx cc-safe-setup --opus47（Survival Guide / Safety Scanner）

📚 主張と実態の乖離の事例の整理と防衛の手順 (2026 年 5 月 22 日発売)

本記事の「キャッシュが毎回壊れる3つの原因」 (git status の混入、 skills の段の波打ち、 TTL の沈黙の変更) は、利用者の意図 (キャッシュの効いた経路で軽い消費) と実態 (毎ターン全文の再課金) の乖離の系統。 TTL の1時間から5分への沈黙の変更 (起票 #46829) は、出荷の主張と実態の動作の乖離の最強の事例の一つ。本書は同型の沈黙の挙動の変更の事例を継続して追跡。

5/22 発売の Claude Code Claim-Verify Handbook で、同型の主張と実態の乖離の事例を 130 件 (本文 15 件 + 付録 D 115 件) に整理した試し読み (無料、約 9,900 字、日本語) を公開済。 14 件の防衛の手順と 5 件の自動の点検の道具 (4 件は cc-safe-setup の枝で取り込み待機、 1 件は本書の付録の標準の道具、合計 165 件以上の試験が全件通過) も収録。

購入の検討の判断の助け (Should I buy the Claim-Verify Handbook?) の対話型の道具で、無料の hook の解説で十分の場合の判定の経路も整理しています。