Claude Code Hooks 実践：自動フォーマット、検証、セキュリティブロック

CLAUDE.md はモデル向けのガイダンスで、作業習慣やアーキテクチャの制約に適する。Hook は特定のライフサイクルイベントで発火するプログラムで、フォーマット、通知、監査、ブロックに適する。

ある要件が例外なく必ず発生しなければならないなら、「必ず」の注意書きだけに頼るべきではない。逆に、意味的判断が必要なアーキテクチャの選択を、壊れやすい shell Hook に押し込むべきでもない。

Hook 設定ではまずイベントを選ぶ。例えばツール呼び出し前後の PreToolUse、PostToolUse、またはセッションや停止関連のイベント。次に matcher で対象ツールに絞り込み、hooks 配列で実際のハンドラーを定義する。

リスクが低く観察しやすい PostToolUse から始める。発火回数、実行ディレクトリ、所要時間を確認してからブロックロジックを追加する。

コマンド Hook は標準入力から JSON を受け取り、セッション、イベント、ツール入力などのコンテキストが含まれる。スクリプトは JSON パーサーでフィールドを読み取るべきで、文字列分割に依存してはならない。

複雑なロジックはリポジトリ内のテスト可能なスクリプトに置き、settings.json はスクリプトのパスを参照するだけにする。スクリプトは欠落フィールド、タイムアウト、非ゼロ終了を処理し、診断は stderr に書き出すべきだ。

PreToolUse はアクション発生前に入力を検査でき、機密パスや高リスクコマンドの保護に適する。ブロック結果には具体的な理由と修正方法を示し、エージェントが原因を知らないまま再試行を繰り返さないようにする。

Hook 自体はローカルマシンの権限で実行されるため、悪意や改ざんのあるスクリプトは通常のプロンプトよりも危険になり得る。プロジェクトの Hook を有効にする前に出所を審査し、チームの変更は PR でレビューする。

まず固定の JSON fixture でスクリプトの単体テストを行い、許可、ブロック、異常入力の各パスを確認する。次に /hooks を実行して設定の読み込みを確認し、無害な操作を1つ実行して結果を観察する。

設定が反映されない場合は settings のスコープ、JSON の構文、スクリプトのパス、matcher を確認する。claude --debug-file /tmp/claude-hooks-debug.log を使って読み込みと実行の診断を取得する。

毎回の編集後に完全なテストを実行すると、セッションが遅くなり大量のコンテキストが発生する。軽量なフォーマットは PostToolUse に任せ、モジュールテストはフェーズ終了時に実行し、完全な CI はコミットやパイプラインに残す。

Hook の数が増えたら、所有者、イベント、平均所要時間、失敗処理を記録する。価値がなくなった Hook は削除すべきであり、開発者がエラーを習慣的に無視する放置しないようにする。