Hooks の 7 つの基本レシピ

コース構成

このコースで学ぶこと

1. 01

   Hook が必要な瞬間

   Skill との違い。「Claude の判断に任せたくない」「毎回必ず動かしたい」が Hook のサイン。

   Skill は「Claude が読んで判断して実行する手順書」、Hook は「決まった瞬間に決まったコードを叩く」もの。lint・テスト・通知・ブロックのような決定論的な処理は Hook の領分です。

   29 個ある Hook イベントの中で、最初に覚えるべきは 7 つ。これを押さえれば 80% カバーできます。

   • **PreToolUse** — ツール実行前。ブロックや引数書き換え
   • **PostToolUse** — ツール実行後。フォーマッタ・テスト走らせ
   • **SessionStart** — セッション開始時。env 注入や挨拶
   • **Stop** — Claude が応答を終えたとき。通知に
   • **UserPromptSubmit** — ユーザー入力直後。検閲・展開
   • **PreCompact** — コンパクション前。要約観点を渡す
   • **Notification** — Claude が入力待ちになったとき

   Hooks 完全版（29 イベント）

   理解度チェック

   1. Q1.Skill ではなく Hook を選ぶべき瞬間は？

      AClaude に判断を任せたい処理（要約・推論）Bユーザーが頻繁に使うコマンドをショートカット化したいC決まったタイミングで必ず実行したい決定論的な処理（lint・通知・ブロック）DAI モデルを切り替えたい
   Recipe 1：編集後に自動フォーマット
2. 02

   Recipe 1：編集後に自動フォーマット

   PostToolUse で Edit/Write の直後に Biome / Prettier を走らせる。最も使われるパターン。

   コードベースが常に綺麗な状態に保たれます。チームで共有すれば全員のコミットが整います。

   json

   {
     "hooks": {
       "PostToolUse": [
         {
           "matcher": "Edit|Write",
           "command": "biome format --write ${FILE} 2>/dev/null || prettier --write ${FILE}"
         }
       ]
     }
   }

   理解度チェック

   1. Q1.PostToolUse の matcher に `Edit|Write` を指定する意味は？

      Aすべてのツール実行後に発火させるBEdit / Write ツールが使われた直後だけ発火させる（Read 等は無視）CEdit と Write を同時実行するDEdit を Write に置き換える
   Hook が必要な瞬間Recipe 2：本番ファイルへの書込をブロック
3. 03

   Recipe 2：本番ファイルへの書込をブロック

   PreToolUse で `infra/prod/**` や `.env` への書込を確実に止める。事故防止の必須レシピ。

   deny ルールでも防げますが、Hook ならパスを正規表現で柔軟に判定でき、なぜ止めたかの理由を Claude にフィードバックできます。matcher で tool を絞り、path 判定はスクリプト側で行います。

   json

   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Edit|Write",
           "command": "scripts/guard-prod.sh"
         }
       ]
     }
   }

   理解度チェック

   1. Q1.PreToolUse Hook で exit code `2` を返すと？

      AClaude が無視して続行するBツール実行をブロックし、stderr の内容を Claude にフィードバックするCセッションが強制終了するDログに警告だけ残る
   Recipe 1：編集後に自動フォーマットRecipe 3：Stop で完了通知
4. 04

   Recipe 3：Stop で完了通知

   長時間タスクを任せて席を立つときの友。macOS なら osascript、Linux なら notify-send、Windows なら Slack 通知。

   json

   {
     "hooks": {
       "Stop": [
         {
           "command": "osascript -e 'display notification \"Claude が応答を終えました\" with title \"Claude Code\" sound name \"Glass\"'"
         }
       ]
     }
   }

   理解度チェック

   1. Q1.Stop hook が発火するタイミングは？

      Aユーザーがプロンプトを入力した直後BClaude が応答を終えた（次のユーザー入力待ちになった）ときCツール実行の前Dコンパクション直前
   Recipe 2：本番ファイルへの書込をブロックRecipe 4：SessionStart で開発情報を注入
5. 05

   Recipe 4：SessionStart で開発情報を注入

   セッション開始時に「現在のブランチ」「直近のテスト結果」「環境メモ」などを Claude に渡す。シークレットは渡さない。

   SessionStart Hook は stdout に JSON を返し、`hookSpecificOutput.additionalContext` が会話冒頭に注入される。CLAUDE.md だけでは伝わらない動的情報（今日のブランチ・前回のテスト結果）を毎セッションで補える。

   json

   {
     "hooks": {
       "SessionStart": [
         {
           "command": "scripts/session-context.sh"
         }
       ]
     }
   }

   理解度チェック

   1. Q1.SessionStart で会話冒頭に動的情報を注入する方法は？

      Asettings.json の `prompt` フィールドに書くBCLAUDE.md を毎回書き換えるCHook スクリプトが stdout に `hookSpecificOutput.additionalContext` を含む JSON を出力するD環境変数に書く
   Recipe 3：Stop で完了通知Recipe 5：UserPromptSubmit で PII 検閲
6. 06

   Recipe 5：UserPromptSubmit で PII 検閲

   ユーザーが Claude に送信する直前に、電話番号・メール・クレジット番号らしき文字列を検出して警告。

   json

   {
     "hooks": {
       "UserPromptSubmit": [
         {
           "command": "scripts/pii-check.sh"
         }
       ]
     }
   }

   理解度チェック

   1. Q1.UserPromptSubmit Hook で PII を検出したときの正しいブロック方法は？

      Astdout に警告を表示するだけBexit 0 で正常終了するCstderr に理由を書いて exit 2 で返す（送信ブロック）Dファイルに記録するだけで処理は続行する
   Recipe 4：SessionStart で開発情報を注入Recipe 6：PreCompact で観点を渡す
7. 07

   Recipe 6：PreCompact で観点を渡す

   コンパクション直前に「これだけは必ず残して」という観点を Claude に注入。長期セッションでの記憶喪失を防ぐ。

   PreCompact Hook も SessionStart 同様、stdout に JSON を返して `hookSpecificOutput.additionalContext` で要約観点を渡す。スクリプト側でプロジェクト状態を読んで動的に組み立てると効果が大きい。

   json

   {
     "hooks": {
       "PreCompact": [
         {
           "command": "scripts/precompact-guide.sh"
         }
       ]
     }
   }

   理解度チェック

   1. Q1.PreCompact hook が解決する“長期セッションの困りごと”は？

      Aセッションが終了しなくなるBコンパクションで重要事項（バグ修正の核心・触らないファイル等）が要約の中で薄まり喪失する問題CSkill が呼べなくなるDMCP が切断される
   Recipe 5：UserPromptSubmit で PII 検閲Recipe 7：バックグラウンドでテスト並走
8. 08

   Recipe 7：バックグラウンドでテスト並走

   編集後にテストを走らせたいが、毎回 30 秒以上待ちたくないとき。Hook をバックグラウンド detach し、結果は次のセッション開始時に拾う設計が現実的。

   json

   {
     "hooks": {
       "PostToolUse": [
         {
           "matcher": "Edit",
           "command": "nohup pnpm test --silent > .claude/last-test.log 2>&1 & disown"
         }
       ]
     }
   }

   Hooks 完全版（公式 docs）

   理解度チェック

   1. Q1.Hook をバックグラウンドで走らせるトレードオフは？

      A結果が同期で取り込めず、次セッションで明示的に読み込ませる工夫が要るBAnthropic に追加料金が発生するCClaude が応答しなくなるDファイルが壊れる
   Recipe 6：PreCompact で観点を渡す