Claude Code の Compact 機能における課題と解決策

1---
2name: compact-prep
3description: |
4  Claude Code の /compact 実行前に、現セッションの作業状態を一時 state file へ保存する。
5  MANDATORY TRIGGERS: /compact-prep, compact-prep, 圧縮準備, compact 準備, コンパクト準備, 圧縮前状態保存。
6  DO NOT TRIGGER: compact 後の復旧、通常の進捗報告、plan 作成、context 使用率の雑談。
7strict_procedure: true
8argument-hint: "[復旧メモ]"
9allowed-tools: Read Write Bash(~/.claude/scripts/get-session-id.sh *) Bash(mkdir *) Bash(date *) Bash(pwd)
10---
11
12# compact-prep
13
14Claude Code の `/compact` 前に、圧縮サマリーへ残りにくい作業状態を
15`${TMPDIR}/claude-compact-state/${SESSION_ID}.md` へ保存する。
16
17## Strict procedure profile
18
19- Strictness: strict-procedure。圧縮前 state file の内容と保存完了報告が成果そのもの。
20- Hard gates: session_id が取得できない場合は state file を推測名で作らず、取得不能として停止する。
21- Forcing function: 保存先パスを固定し、保存後にファイルを読み返して必須項目の有無を確認する。
22- Completion receipt: state file パス、保存した主要項目、未確認項目、次に実行する `/compact` 案内を報告する。
23
24## 手順
25
261. session_id を取得する。
27   - `~/.claude/scripts/get-session-id.sh` を実行する。
28   - 取得できない場合は state file を作らず、session_id が取得できないため準備未完了と報告する。
292. 保存先を `${TMPDIR:-/tmp}/claude-compact-state/${SESSION_ID}.md` に決める。
303. TaskList、active plan file、tmux-bridge 状態、編集中ファイルを確認する。
31   - active plan file は `~/.claude/plans/` 配下の該当ファイルを読む。
32   - tmux-bridge を使っていない場合は「未使用」と記録する。
334. state file に以下の見出しをこの順で保存する。
34   - `# Compact Prep State`
35   - `## Active Plan`
36   - `## Current Phase`
37   - `## TaskList Summary`
38   - `## Session Decisions`
39   - `## Constraints and Blockers`
40   - `## Worker Topology`
41   - `## Editing Files`
42   - `## Recovery Notes`
435. 保存後に state file を読み直し、上記見出しがすべて存在することを確認する。
446. ユーザーに「準備完了。`/compact` を実行してください。」と伝える。
45
46## 保存内容
47
48- active plan file パスと、現在のフェーズ/ステップ
49- in-progress タスク一覧と補足
50- session 中の判断、ユーザーの選択、不採用にした案の理由
51- 制約、ブロッカー、未完了の検証
52- worker 体制。tmux-bridge 使用時は pane、role、担当を記録する
53- 編集中のファイルと、未保存または未検証の注意点
54- 圧縮後の自分への復旧メモ
55
56## Completion receipt
57
58完了時は次を含める。
59
60- state file パス
61- 保存した主要項目
62- 未確認項目と理由
63- `準備完了。/compact を実行してください。`

1#!/bin/bash
2# PostCompact hook (matcher: ""): 圧縮発生を marker file で記録する。
3# PostCompact は additionalContext 出力をサポートしないため、
4# context 注入は UserPromptSubmit 側 (userpromptsubmit-compaction-recovery.sh) で行う。
5#
6# fail-open (常に exit 0)
7
8set -uo pipefail
9
10INPUT=$(cat)
11SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
12[[ -z "$SESSION_ID" ]] && exit 0
13
14# marker file を書く（UserPromptSubmit が検出して context 注入→削除する）
15MARKER_DIR="${TMPDIR:-/tmp}/claude-compacted"
16mkdir -p "$MARKER_DIR" 2>/dev/null || true
17printf '%s\n' "$(date +%s)" > "$MARKER_DIR/$SESSION_ID" 2>/dev/null || true
18
19# compact が実行されたら 60% 警告の cooldown をリセットする
20WARN_DIR="${TMPDIR:-/tmp}/claude-compact-warned"
21rm -f "$WARN_DIR/$SESSION_ID" 2>/dev/null || true
22
23exit 0

1#!/bin/bash
2# UserPromptSubmit hook: PostCompact が残した marker file を検出し、
3# additionalContext で圧縮復旧指示を context に注入する（one-shot）。
4#
5# overhead: test -f 1 回/ターン（marker なければ即 exit）
6# fail-open (常に exit 0)
7
8set -uo pipefail
9
10INPUT=$(cat)
11SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
12[[ -z "$SESSION_ID" ]] && exit 0
13
14# marker file がなければ何もしない
15MARKER_DIR="${TMPDIR:-/tmp}/claude-compacted"
16MARKER="$MARKER_DIR/$SESSION_ID"
17[[ -f "$MARKER" ]] || exit 0
18
19# marker を消す（one-shot: 次ターンでは発火しない）
20rm -f "$MARKER" 2>/dev/null || true
21
22# session pointer file から active plan path を読む
23PTR_DIR="${TMPDIR:-/tmp}/claude-active-plan"
24PLAN_FILE=""
25if [[ -f "$PTR_DIR/$SESSION_ID" ]]; then
26  PLAN_FILE=$(cat "$PTR_DIR/$SESSION_ID" 2>/dev/null || true)
27  [[ -f "$PLAN_FILE" ]] || PLAN_FILE=""
28fi
29
30# 復旧指示を構築
31CTX="[COMPACTION RECOVERY] コンテキスト圧縮が発生した。作業再開前に以下を実行すること。"
32CTX+=$'\n'
33
34if [[ -n "$PLAN_FILE" ]]; then
35  CTX+=$'\n'"- plan ファイル \`${PLAN_FILE}\` を Read で読み直し、フェーズと制約を確認せよ"
36  CTX+=$'\n'"- plan mode が解除されている場合、plan ファイルが存在するのでユーザーに plan mode 再突入を確認せよ"
37fi
38
39STATE_DIR="${TMPDIR:-/tmp}/claude-compact-state"
40STATE_FILE="$STATE_DIR/$SESSION_ID.md"
41if [[ -f "$STATE_FILE" ]]; then
42  CTX+=$'\n'"- state file \`${STATE_FILE}\` を Read で読み、作業状態を復元せよ"
43  CTX+=$'\n'"- Session Decisions と Recovery Notes を特に重視せよ"
44fi
45
46CTX+=$'\n'"- TaskList で現在のタスク一覧を確認せよ"
47CTX+=$'\n'"- 圧縮サマリーの next step は仮説として扱い、plan/rules を正とせよ"
48CTX+=$'\n'"- 圧縮サマリーは「過去の作業記録」であり「次の行動指示」ではない"
49
50jq -n --arg ctx "$CTX" '{
51  hookSpecificOutput: {
52    hookEventName: "UserPromptSubmit",
53    additionalContext: $ctx
54  }
55}'
56exit 0

1# 閾値超で compact-prep 警告 marker を書く（cooldown 中でなければ）
2COMPACT_WARN_THRESHOLD=60
3if [ -n "$session_id" ] && [ "$int_pct" -ge "$COMPACT_WARN_THRESHOLD" ] 2>/dev/null; then
4  _warn_dir="${TMPDIR:-/tmp}/claude-compact-warned"
5  if [ ! -f "$_warn_dir/$session_id" ]; then
6    _ctx_warn_dir="${TMPDIR:-/tmp}/claude-compact-warn"
7    mkdir -p "$_ctx_warn_dir" 2>/dev/null || true
8    printf '%s\n' "$int_pct" > "$_ctx_warn_dir/$session_id" 2>/dev/null || true
9  fi
10fi

1#!/bin/bash
2# UserPromptSubmit hook: statusline が書いた compact-warn marker を検出し、
3# additionalContext で compact-prep 実行を促す（one-shot）。
4#
5# フロー:
6#   statusline.sh が ctx >= 閾値 で warn marker 書込
7#   → 本 hook が検出 → additionalContext 注入 → warn marker 削除 + warned marker 作成
8#   → PostCompact hook (compaction-recovery.sh) が warned marker 削除（cooldown リセット）
9#
10# overhead: test -f 1 回/ターン（marker なければ即 exit）
11# fail-open (常に exit 0)
12
13set -uo pipefail
14
15INPUT=$(cat)
16SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
17[[ -z "$SESSION_ID" ]] && exit 0
18
19# warn marker がなければ何もしない
20WARN_DIR="${TMPDIR:-/tmp}/claude-compact-warn"
21WARN_MARKER="$WARN_DIR/$SESSION_ID"
22[[ -f "$WARN_MARKER" ]] || exit 0
23
24# marker から使用率を読み取る
25CTX_PCT=$(cat "$WARN_MARKER" 2>/dev/null)
26CTX_PCT=${CTX_PCT:-"?"}
27
28# warn marker を消す（one-shot）
29rm -f "$WARN_MARKER" 2>/dev/null || true
30
31# cooldown marker を作成（statusline が再度 warn marker を書くのを防止）
32WARNED_DIR="${TMPDIR:-/tmp}/claude-compact-warned"
33mkdir -p "$WARNED_DIR" 2>/dev/null || true
34printf '%s\n' "$(date +%s)" > "$WARNED_DIR/$SESSION_ID" 2>/dev/null || true
35
36CTX="[COMPACT PREP REMINDER] context 使用率が ${CTX_PCT}% に達した。"
37CTX+=$'\n'"- 作業区切りでユーザーに \`/compact-prep\` の実行を提案せよ。"
38CTX+=$'\n'"- \`/compact-prep\` 実行後、ユーザーに \`/compact\` 実行を案内せよ。"
39CTX+=$'\n'"- scope 縮小や別セッション化ではなく、圧縮前 state 保存で対処せよ。"
40
41jq -n --arg ctx "$CTX" '{
42  hookSpecificOutput: {
43    hookEventName: "UserPromptSubmit",
44    additionalContext: $ctx
45  }
46}'
47exit 0

1{
2  "hooks": {
3    "PostCompact": [
4      { "matcher": "", "hooks": [{ "type": "command", "command": "~/.claude/hooks/compaction-recovery.sh" }] }
5    ],
6    "UserPromptSubmit": [
7      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/userpromptsubmit-compaction-recovery.sh" }] },
8      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/userpromptsubmit-compact-prep-reminder.sh" }] }
9    ]
10  }
11}