Tools
Claude Code の context 注入層
CLAUDE.md / memory / hook / skill の loading タイミング・token コスト・cache 挙動と使い分け
要点: 「絶対忘れさせない」なら hook (毎ターン fresh、cache 効かない) が最強。長期セッションでは 2 倍くらい高い。通常忘れさせない程度なら CLAUDE.md (起動時 1 回、cache 効く) で十分。3 重は過剰。
4 層の比較
| 層 | Loading | Cache | 毎ターンコスト | 使い所 |
|---|---|---|---|---|
~/.claude/CLAUDE.md | 起動時 1 回、全プロジェクト共通 | ✅ prompt cache | ~cache 読み | 常時ロード、user 全体のルール |
{project}/CLAUDE.md | 起動時 1 回、cwd がその project の時 | ✅ prompt cache | ~cache 読み | プロジェクト固有ルール |
| memory (MEMORY.md + on-demand) | 起動時に索引 (MEMORY.md、~200行) のみ、本体は Claude が Read | 索引は ✅ / 本文は Read 時のみ | ほぼ 0 | 事実・reasoning、on-demand で十分な情報 |
| UserPromptSubmit hook | 毎ターン、shell command 実行 → stdout 注入 | ❌ 毎回 new | full size × turn 数 | 絶対忘れさせない、salience 最強 |
| Skill | 明示 invoke (Skill tool) 時のみ full load | 呼んだ時だけ | 呼んだ時だけ | 手順・チェックリスト |
Token コスト実測 (概算)
20 ターン session で、2KB (~500 tokens) のルール文を注入するコスト:
CLAUDE.md: 500 (初回 full) + 500 × 19 × 0.1 (cache 読み) ≈ 1,450 tokens 相当
Hook: 150 × 20 (毎回 full) = 3,000 tokenshook の方が 2 倍高い (cache 効かないため)。ただし hook の方が短い文言で済むなら差は縮む。
Prompt caching の理屈
Anthropic の prompt cache は連続した prefix をキャッシュする:
- system prompt → CLAUDE.md → 過去の会話 → 現在のユーザー入力
- 過去の会話の中身は毎ターン追加されるだけで、既存部分は再送不要 (cache hit)
- hook は user turn の一部として毎回 new content で入る → 過去 hook はキャッシュされるが、今回の hook は新規
つまり:
- CLAUDE.md: 初回 full price → 以降ずっと cache hit price (~10%)
- hook: 毎回 current turn 分は full price
3 重の切り分け方
| 目的 | 手段 |
|---|---|
| 絶対忘れさせない (事故防止) | hook で毎ターン fresh 注入 |
| 常に念頭に置いてほしい (ルール・facts) | CLAUDE.md (user or project level) |
| 関連時に思い出せば良い (reasoning・詳細) | memory (MEMORY.md 索引 + on-demand read) |
| 定型作業のチェックリスト | skill (明示 invoke) |
実務的な選択
- 既定は CLAUDE.md + memory。これで大半足りる
- 絶対事故防止したい 1-2 個の behavioral rule だけ hook に切り出す
- hook のメッセージは超短く (100 tokens 以内)、詳細は CLAUDE.md に置いて "詳細は ~/.claude/CLAUDE.md" と link
- skill 化は「手順が長い + 明示的に呼びたい」時のみ
注意
- hook が長すぎるとセッション累計で数万 tokens 食う。短く保つ
- hook が失敗する (exit != 0) と prompt 送信が止まる。shell 出力を必ず 0 exit で返す
- hook を追加した場合、settings.json が壊れると Claude Code が起動しない (valid JSON 必須)
関連
- 個人メモサイトの運用 — このサイトの構成
- Claude Code の system prompt を書き換える方法 — CLI フラグでの追記・置換
最終更新: