コンテンツにスキップ
Reports
Deep Analysis Zenn Cnative Tkb Hook Change Tracking

Deep Analysis: Claude Code hooksで変更の足跡を自動記録する設計パターン

date: 2026-06-01 analyst: deep-analysis skill（壁打ち） sources: 1件（Zenn記事: https://zenn.dev/cnative_tkb/articles/164e976539f194） total_claims: 5件 total_counterargs: 採用2件 / 却下1件

概要

Claude Code の PostToolUse / SessionStart hookを使い、重要な設定ファイル（SSOT）への変更を自動記録・起動時表示することで「AIが前回セッションの作業を覚えていない」問題を解消する設計パターンの記事。中心的なアイデアは「全ファイルでなくSSOT（正本）だけを記録する」という絞り込みで、実装コード付きで解説している。

当プロジェクト（waribashi_konbu）への適用は高い有用性がある。ただし既存の2つのhookとの同居設計、およびwikiページ更新をIMPORTANTリストから除外する判断が必要。

抽出クレーム（5件）

ID主張Tierstatus
2026-06-01-W001AIはセッションをまたいで前回の作業を記憶できない（コンテキストウィンドウがリセットされるアーキテクチャ上の制約）Tier 1verified
2026-06-01-W002PostToolUse hookで「正本（SSOT）ファイルのみ」に変更を自動記録することで変更漏れゼロを達成できるTier 2unverified
2026-06-01-W003SessionStart hookが出力するテキストは次のAIのコンテキスト（Context Window）にも自動で渡される（公式仕様）Tier 1verified
2026-06-01-W004「全ファイル記録」はノイズになり失敗する。ホワイトリスト方式で5〜10の重要ファイルに絞ることが設計の肝（著者の実体験）Tier 2unverified
2026-06-01-W005hooksはCLAUDE.md指示と異なり決定論的に動作する（AIが無視できない仕組み上の保証）Tier 1verified（公式仕様）

詳細

W001・W005（Tier 1 / verified）

AIがセッション間で記憶を持てない事実はClaudeを含む大規模言語モデルのアーキテクチャ上の特性。hookが「必ず動く」という決定論的保証はClaude Code公式ドキュメントに明記されている（“Hooks are deterministic — Claude can ignore CLAUDE.md instructions, but hooks always run."）。両者はTier 1として自動昇格対象。

W003（Tier 1 / verified）

SessionStart hookの出力がAIのコンテキストに渡されることも公式仕様。記事内で「人に見せる」と「AIに思い出させる」が同時実現できると説明されており、これは公式の動作として確認されている。

W002・W004（Tier 2 / unverified）

「ホワイトリスト方式で変更漏れゼロを達成できる」は実装次第。著者の実体験として「全ファイル記録で失敗した」経験は述べられているが、「5〜10ファイルが最適」の根拠は実体験ベースであり定量検証なし。当プロジェクトへの適用時も最適なIMPORTANTリストは試行錯誤が必要。

当プロジェクト（waribashi_konbu）の既存hook構成

  • PostToolUse: check_verified_promotion.py（Edit/Write後に検証済み昇格チェック）
  • SessionStart: activate-env.sh（venv起動）

記事の手法を追加する場合、PostToolUseにlog-changes.pyを追記する形で同居可能。settings.jsonのhooks配列に追加するだけで既存処理は干渉しない。

反論と判定

反論 C001: 変更ログは「何を変えたか」のみ記録し「なぜ変えたか」が欠落する

  • 判定: 採用
  • 理由: ファイル名・ツール名・タイムスタンプの記録では、意図的な設計変更とAIによる誤変更を区別できない。障害調査・レビュー時にwhyが不明では診断効率が上がらない
  • 採用時の処置: hookログをコミットメッセージ・session-readmeスキルによる意図記録で補完する設計が必要。hookは「what/when」の自動化、「why」は人間または別スキルが担う役割分担を明示する

反論 C002: waribashi_konbuはwiki構造+CLAUDE.mdで既にセッション間コンテキスト管理を行っており、hook追加の差分効果が限定的かもしれない

  • 判定: 採用（部分）
  • 理由: wiki/themes/*.mdへの変更は観察ログとして既に構造化されており、hookによる変更ログで二重管理になる。ただし .claude/settings.json・CLAUDE.md・スキル定義ファイルはwikiに記録されないため、設定ファイル群の変更追跡には依然として高い価値がある
  • 採用時の処置: IMPORTANTリストは設定・スキル・hook定義ファイルのみとし、wiki/・reports/・processed/は明示的に除外する

反論 C003: sessionStartで毎回hookが走るとwikiファイルが大量記録されパフォーマンス低下するリスクがある

  • 判定: 却下
  • 理由: 記事の実装はis_important()ホワイトリストで明示的に除外するアーキテクチャ。IMPORTANTリストにwiki/を含めなければ記録対象にならない。C002の採用処置でwikiを除外すると決めることでこのリスクも同時に排除される

統合結論

記事の設計パターンは当プロジェクトに高い有用性がある。適用範囲は「設定ファイル群の変更追跡」に限定するのが最善。

採用反論を踏まえた適用方針：

  1. IMPORTANTリストの対象（wiki/・reports/は除外）:

    • CLAUDE.md
    • .claude/skills/*/SKILL.md または skill.md
    • .claude/hooks/*.py / .claude/hooks/*.sh
    • .claude/settings.json
    • sources.yaml

  2. 役割分担の明確化: hookログは「what/when」の自動記録、「why/意図」はsession-readmeスキルまたはコミットメッセージで補完

  3. 既存hook同居: settings.jsonのPostToolUse配列への追記で干渉なし

不確実性：「ホワイトリスト5〜10ファイルが最適」は著者の実体験ベース。当プロジェクトの適切なリストサイズは実運用で検証が必要。

評価観点判定
アーキテクチャの妥当性◎ Tier1 verified事実に基づく
実装の移植容易性◎ 既存hookと同居可能
当PJとの重複リスク△ wiki除外を明示すれば解消
記録の完全性△ whyは別手段で補完が必要

当プロジェクトへの取り込み推奨度

技術/知見推奨度（★1-3）具体的アクション
PostToolUseによる設定ファイル変更ログ★★★.claude/hooks/log-changes.py を追加し settings.json PostToolUseに追記
SessionStartでの直近変更表示★★★activate-env.sh に変更サマリー表示を追加 or 別hookを追加
SSOT（正本）概念の明示的な列挙★★★CLAUDE.mdまたは設計ドキュメントに「SSOT対象ファイルリスト」を明記
全ファイル記録（wiki含む）★☆☆対象外：既存wiki構造と二重管理になる

参考ソース

ReportsDeep Analysis Zenn Dev Cnative Tkb 9701bb43ffc74f