Claude Code フック チュートリアル：本番運用の5つのフックをゼロから作る

Claude Code は、大半の場面で正しい操作を選びます。問題は残りのわずかなケースです。main への force push、フォーマッタの実行漏れ、lint に通らないコードのコミット。フックは、Claude のワークフロー上にある31のライフサイクルポイント（2026年8月時点）に決定論的なゲートを置くことで、こうしたエッジケースを潰します。¹ 本チュートリアルは、本番品質のエージェントシステムを構築する AI エンジニアリングシリーズの一編です。フックはプロンプトの書き方やモデルの挙動にかかわらず、例外なく毎回発火します。

TL;DR： フックとは、Claude Code のライフサイクルイベントによって起動されるシェルコマンドです。¹ PreToolUse フックは操作を検査してブロックできます（終了コード2＝ブロック、0＝許可）。² PostToolUse フックは事後の検証とフォーマットを担います。設定は .claude/settings.json に書き、matcher（正確なツール名、| 区切りのリスト、または正規表現）とネストした hooks 配列を指定します。³ 以下のチュートリアルでは、本番で使えるフックを5つ組み立てます。自動フォーマッタ、セキュリティゲート、テストランナー、通知アラート、そしてコミット前の品質チェックです。

要点まとめ

• 個人開発者の方へ： まずは自動フォーマッタ（フック1）とセキュリティゲート（フック2）から始めてください。この2つで、Claude Code で最も起こりやすいミスを、以後の保守なしに防げます。
• チームリードの方へ： フックはリポジトリの .claude/settings.json にコミットしましょう。チーム全員が同じ安全ゲートと品質チェックを自動的に手にできます。
• セキュリティエンジニアの方へ： 操作をブロックするのは終了コード2です。² 終了コード1は警告をログに残すだけです。PreToolUse のセキュリティフックは必ず exit 2 を使ってください。そうでなければ、強制力はまったくありません。

フックとは何か

フックは、Claude Code のセッション中、特定のライフサイクルイベントで実行されるシェルコマンドです。LLM の外側で動く素のスクリプトであり、Claude の操作をきっかけに起動します。モデルが解釈するプロンプトではありません。

主要な4つのカテゴリで、よくあるユースケースはほぼカバーできます（Claude Code は2026年8月時点で31種類のイベントを文書化しています）。¹

• セッション系イベント： SessionStart はセッションの開始時に、SessionEnd は終了時に発火します。Stop は Claude が応答を終えるたびに発火します（セッション終了時だけではありません）。準備処理、後始末、通知に使えます。
• ツール系イベント： PreToolUse と PostToolUse は、Claude がツールを使う前後に発火します（ファイルの書き込み、bash コマンドの実行、コード検索など）。特定の操作を検査してブロックできるため、最も強力なフックです。
• 通知系イベント： Notification は Claude が通知を生成したときに発火します。Slack やデスクトップ通知、ログ基盤へアラートを流すのに便利です。
• サブエージェント系イベント： SubagentStop は、Agent ツールで起動したサブエージェントが完了したときに発火します。⁴ フックはサブエージェントの操作に対しても発火するため、安全ゲートは再帰的に効きます。

終了コードの意味は重要です。² 0は成功（続行）、2は操作のブロック、1はブロックを伴わないフックのエラーで、操作はそのまま進みます。セキュリティ上重要なフックは、ゲートを実際に効かせるために必ず exit 2 を使ってください。

考え方：3種類の保証

フックを書き始める前に、自問してください。必要なのはどの種類の保証なのか、と。

フォーマットの保証は、事後に一貫性を担保するものです。Write/Edit に対する PostToolUse フックは、ファイルが変わるたびにフォーマッタを走らせます。フォーマッタがすべてを正規化するので、モデルの出力がどうであったかは関係ありません。この種のフックは冪等で、編集のたびに実行しても安全です。

安全性の保証は、危険な操作を実行前に止めるものです。Bash への PreToolUse フックはコマンドを検査し、破壊的なパターンを終了コード2でブロックします。マッチしたツール呼び出しのすべてをゲートするため高速でなければならず（500ms 未満）、exit 1 では警告するだけでブロックできないので、必ず exit 2 を使います。

品質の保証は、意思決定の地点で状態を検証するものです。git commit コマンドに対する PreToolUse フックは linter やテストスイートを走らせ、品質チェックが落ちればコミットをブロックします。編集のたびに走るフォーマット系と違い、品質系は特定の瞬間にしか発火しないため、オーバーヘッドは小さく収まります。

概念上の先祖は Git フックです⁸: pre-commit、pre-push、post-commit が、まさに同じ3つの役割を担っています。Claude Code のフックは、このパターンを Git 操作からエージェントのあらゆるツール操作へと広げたものです。この進化についてはすべてのフックは傷跡であるで掘り下げました。どのフックも、それが無かったせいで何かが壊れたからこそ存在しているのです。

フック設定の基本

フックは設定ファイルに置きます。

• プロジェクト単位： リポジトリのルートに置く .claude/settings.json（チームで共有）³
• ユーザー単位： ~/.claude/settings.json（個人用のフック。すべてのプロジェクトに適用）³

JSON の構造は次のとおりです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/your/script.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/another-script.sh"
          }
        ]
      }
    ]
  }
}

各エントリは、Bash、Write、Edit、Read、Glob、Grep、Agent といったツール名を絞り込む matcher と、フック定義を並べた hooks 配列を持ちます。リファレンスに沿った matcher の意味は次のとおりです。"*"、""、あるいは matcher の省略は、すべてにマッチします。英数字と _、-、|、カンマ、スペースだけで構成された値は正確なツール名またはそのリストとして扱われ、Write|Edit は両方のツールにマッチします（mcp__github__search_code のような MCP ツール名ではアンダースコアが効いてきます）。それ以外は、アンカーなしの正規表現として扱われます。マッチングは大文字小文字を区別するため、bash が Bash にマッチすることはありません。各フックには type（シェルコマンドなら "command"）と、実行する command を指定します。

登録済みのフックは、セッション中に読み取り専用の /hooks ブラウザで確認できます。追加・変更・削除は、設定 JSON を直接編集してください。⁵

フックが発火すると、Claude Code はコンテキストを stdin 上の JSON オブジェクトとして渡します。ツール名、ツール入力（ファイル操作なら file_path を含む）、そしてセッションのメタデータです。⁶ スクリプト側は、たいてい jq を使って stdin を読み、判断を下します。コンテキスト用の環境変数もいくつか設定されます。パス解決のための $CLAUDE_PROJECT_DIR、現在の effort レベルを示す $CLAUDE_EFFORT などです。ただし、ファイルパスのようなツール固有のフィールドは stdin にしか届きません。ツールごとの $FILE_PATH という変数は存在しないのです。

実用的なフック5つ

以下のフックはいずれも、Claude Code を主力の開発ツールとして使うなかで実際にぶつかった問題を解決するものです。例はすべて、フックのリファレンスにある正しいネスト形式のスキーマに従っています⁷。

1. ファイル編集時の自動フォーマット

Claude が書くコードは機能的には正しいものの、プロジェクトのフォーマット規約を崩すことがときどきあります。最初は「Python ファイルを編集したら必ず black を実行する」と CLAUDE.md に書いてみましたが、この指示が効くのは8割ほどでした。複数ファイルにまたがる複雑な変更に集中していると、フォーマットの手順が飛ぶことがあるのです。PostToolUse フックを使えば、このばらつきは完全に消えます。モデルが何を選ぼうと、ファイルが書き込まれるたびにフォーマッタが走ります。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" == *.py ]]; then black --quiet \"$FILE\" 2>/dev/null; elif [[ \"$FILE\" == *.js || \"$FILE\" == *.ts ]]; then npx prettier --write \"$FILE\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

このフックは、ツールの JSON 入力を stdin から読み、jq で .tool_input.file_path を取り出します。Claude Code はツールごとの環境変数を設定しないため、ファイルパスが存在する場所はこの stdin のオブジェクトだけです。あとは拡張子を見て、適切なフォーマッタを実行します。Python ファイルには black、JavaScript と TypeScript には prettier です。2>/dev/null でうるさい出力を抑え、本当のエラーだけが見えるようにしています。

規模の大きいプロジェクトでは、インラインのコマンドを独立したスクリプトに切り出すと読みやすくなります。

2. 危険なコマンドを止めるセキュリティゲート

Bash ツールへの PreToolUse フックは、Claude がこれから実行しようとするコマンドを検査し、危険なパターンに一致すればブロックします。このフックの最初の版を書いたのは、リファクタリングのセッション中に Claude が main へ force push したあとでした。（エージェントの自律性がもたらす広い含意については、爪の解剖学とインフラとしての Claude Codeで論じています。）「変更を push して」と頼まれたモデルは、ブランチが分岐していたために、それを git push --force origin main と解釈したのです。復旧そのものは数秒で済みましたが、この一件が恒久的なゲートを作る動機になりました。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"rm\\s+-rf\\s+/|git\\s+push\\s+(-f|--force)\\s+(origin\\s+)?main|git\\s+reset\\s+--hard|DROP\\s+TABLE|:\\(\\)\\s*\\{\\s*:\"; then echo \"BLOCKED: Dangerous command detected: $CMD\" >&2; exit 2; fi'"
          }
        ]
      }
    ]
  }
}

このフックが終了コード2で終わると、Claude Code は保留中のコマンドをキャンセルします。エラーメッセージはターミナルと Claude のコンテキストの両方に出るため、モデルはなぜ操作が失敗したのかを理解し、より安全な代替案を提示します。

ブロックされるパターン： - rm -rf /（ルートからの再帰的な削除） - git push --force main と git push -f main（main ブランチへの force push） - git reset --hard（コミットしていない作業の破棄） - DROP TABLE（うっかりデータベースを壊す操作） - フォークボム（:(){ という書き出しにマッチするため、スペースの有無どちらの書き方も捕まえます）

このリストは自分の環境に合わせて調整してください。本番データベースを扱うなら破壊的な SQL のパターンが、CLI からデプロイするならデプロイコマンドのガードが要ります。

3. 変更後に走るテストランナー

Claude が Python ファイルを編集したら、関連するテストを自動で走らせます。すぐにテストを実行すれば、そのあと3つも4つもファイルを編集して問題が積み重なる前に、リグレッションを捕まえられます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" == *.py && \"$FILE\" != *test_* ]]; then TEST_FILE=\"tests/test_$(basename \"$FILE\")\"; if [[ -f \"$TEST_FILE\" ]]; then if ! OUT=$(python -m pytest \"$TEST_FILE\" -x --tb=short 2>&1); then echo \"TESTS FAILED after editing $FILE:\" >&2; echo \"$OUT\" | tail -20 >&2; exit 2; fi; fi; fi'"
          }
        ]
      }
    ]
  }
}

このフックは編集されたファイルのパスを stdin の JSON から取り出し、それが Python のソースファイルか（テストファイル自身ではないか）を確かめ、test_ プレフィックスの命名規約で対応するテストファイルを探し、見つかれば実行します。-x フラグは最初の失敗で止め、tail -20 は出力を簡潔に保ちます。このフックを実用に足るものにしているのは、失敗時に exit 2 する部分です。PostToolUse フックは、すでに起きてしまった編集を取り消せません。しかし exit 2 なら、失敗したテストの出力が stderr 経由で Claude に渡り、Claude は次へ進む前にその破損を直します。exit 0 のまま失敗を表示するだけの版では、出力はデバッグログ行きです。誰も見ていない場所へ流れていきます。

補足： 上のフックは、test_ プレフィックスの命名でフラットな tests/ ディレクトリを使う前提です。ソースツリーを写し取る構成（例：src/api/users.py に対応する tests/api/test_users.py）のプロジェクトでは、TEST_FILE の行を次のように置き換えてください。

TEST_FILE="tests/$(echo "$FILE" | sed 's|.*/src/||; s|\([^/]*\)\.py$|test_\1.py|')"

テストランナーのフックがとりわけ効いてくるのは、Claude が複数のファイルに触れるリファクタリングのセッションです。即座のフィードバックが無いと、エラーは積み重なります。Claude がファイル A を編集してファイル B のテストを壊し、その壊れた B の状態を前提にファイル C を編集する。気づいたときには、直すべきファイルは1つではなく3つになっています。編集のたびにテストを走らせれば、最初の破損をその場で捕まえられます。

4. Claude が応答を終えたら通知する

Claude Code の1ターンが数分に及ぶこともあります。ターミナルを眺めて待つのではなく、Claude が応答を終えたら通知を受け取りましょう。（Stop は応答が終わるたびに発火します。セッションが実際に閉じるときのフックが欲しい場合は、代わりに SessionEnd を登録してください。）

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished responding\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

上の macOS 版は osascript でネイティブ通知を出します。Linux なら、osascript の行を notify-send "Claude Code" "Finished responding" に置き換えてください。Slack へ通知する場合は Webhook を使います。

curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  -d '{"text": "Claude Code finished responding"}'

私は & <task>（Claude Code のバックグラウンドモード）で投げたタスクには Slack 版を使い、対話的なセッションはデスクトップ通知に任せています。

5. コミット前の品質チェック

Claude が git commit を実行する前に、コードが lint を通るかどうかを検証します。コミット前の lint ゲートは、フォーマットだけでは見逃す問題を捕まえます。未使用の import、未定義の変数、型エラーなどです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"^git\\s+commit\"; then if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then echo \"LINT FAILED -- fix before committing:\" >&2; echo \"$LINT_OUTPUT\" >&2; exit 2; fi; fi'"
          }
        ]
      }
    ]
  }
}

この品質ゲートが動くのは、Bash コマンドが git commit で始まるときだけです。高速な Python 用 linter である ruff を、error・pyflakes・warning のルールで実行します。問題があればフックはコミットをブロックし（exit 2）、Claude は lint の出力を目にします。たいていはそこで問題を修正し、やり直します。

品質チェックは重ねられます。型チェックの mypy、セキュリティスキャンの bandit、あるいはプロジェクト独自の検証スクリプトなどです。Bash コマンドへの PreToolUse フックは、あらゆるシェル操作の手前にプログラム可能なゲートを置いてくれます。

.claude/settings.json における PreToolUse と PostToolUse：リファレンス

PreToolUse／PostToolUse の設定の形を検索してここへたどり着いた方のために、要点だけをまとめます。どちらのイベントも、.claude/settings.json（プロジェクト）または ~/.claude/settings.json（ユーザー）の hooks キーの下にネストします。スコープは統合され、同一のハンドラは重複が除かれます。両方のイベントを1つのブロックで配線すると、次のようになります。³

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/guard.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": ".claude/hooks/format.sh" }]
      }
    ]
  }
}

契約は3行で言えます。どちらのイベントも、ツールの JSON を stdin で渡します（Bash なら .tool_input.command、Write/Edit なら .tool_input.file_path。ツールごとの環境変数はありません）。⁶ PreToolUse はツール呼び出しの前に発火し、exit 2 でそれをブロックできます。PostToolUse はツールの成功後に発火します。操作を取り消すことはできませんが、exit 2 なら stderr が Claude へ返り、Claude はフックが指摘した点を修正します。²

両イベントの完全なドキュメント（JSON 出力のフィールド、permissionDecision、updatedInput、タイムアウト）は、公式リファレンスの code.claude.com/docs/en/hooks にあります。私の Claude Code ガイドのフックのセクションでも、実地で検証したパターンとともに同じ範囲を扱っています。

イベント名を推測してしまったら：対応表

よく検索されるフックイベント名と、Claude Code が実際に発火させるイベントの対応です。¹

イベントは全部で31あります。ガイドのイベント一覧表にそのすべてが載っています。

PreToolUse・PostToolUse・Stop を1つの設定にまとめる

最もよく検索される3つのイベントを組み合わせた例です。コマンドのガード、フォーマッタ、そして完了通知の3つを配線します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/guard-bash.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); [[ \"$FILE\" == *.py ]] && black --quiet \"$FILE\" || true'" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude finished responding\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

guard-bash.sh は、フック2のセキュリティゲートを独立したスクリプトに移したものです。フック2の bash -c ワンライナーの中身（外側のシングルクォートに挟まれた部分すべて）を .claude/hooks/guard-bash.sh として保存し、#!/bin/bash のシバンを付けて chmod +x してください。あるいは、同名の出来合いのスクリプトを Claude Code フック徹底解説から持ってきても構いません。各イベントは、それぞれの意味をそのまま保ちます。PreToolUse のガードはコマンドを拒否でき（exit 2）、PostToolUse のフォーマッタはマッチした編集のたびに走り、Stop のフックは応答が終わるたびに発火します。Stop に matcher は要りません。ツールのイベントではないため、絞り込む対象がないからです。¹

フックのデバッグのコツ

フックは、思っている以上に静かに失敗します。デバッグに使っている手口を5つ挙げます。

1. まずスクリプト単体でテストする。 サンプルの JSON を手でスクリプトに流し込みます。echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh のように。Claude Code の外で失敗するものは、中でも失敗します。
2. stderr がどこへ行くのかを把握する。 stderr が Claude のコンテキストに届くのは、フックが exit 2 で終わったときだけです。exit 0 ならデバッグログへ落ち、それ以外の非ゼロ終了では、トランスクリプトにフックエラーの通知が出るだけです。開発中は claude --debug（セッション中なら /debug）を走らせ、exit 0 のフック出力が落ちるデバッグログを見てください。
3. jq の失敗に気をつける。 JSON のパスが間違っていると、jq⁹ は黙って null を返し、条件分岐はどこにもマッチしません。jq の式は、実際のツール入力に対して試してください。
4. 終了コードを検証する。 exit 2 は操作をブロックし、exit 1 は警告するだけです。うっかり exit 1 を使った PreToolUse フックは、動いているように見えて強制力はゼロです。基本は許容（デフォルトは exit 0）にしておき、exit 2 は明示的にブロックしたいパターンだけに使いましょう。
5. フックは速く保つ。 フックは同期的に実行されます。5秒かかるフックは、マッチしたツール利用のたびに5秒を上乗せします。私は全フックを2秒以内、理想的には500ミリ秒以内に収めています。

最も多いフックのミス： セキュリティゲートを exit 2 ではなく exit 1 で書いてしまうことです。警告メッセージがターミナルに出るため、テスト中は動いているように見えます。しかし exit 1 はブロックを伴わない警告にすぎません。危険なコマンドはそのまま実行されます。このミスは、3つの異なるチームのフック設定で見かけました。いずれも force push を止められていると信じていたのです。セキュリティフックは必ず、ブロック対象のパターンを実際に発生させ、警告が出ただけでなく操作が本当に止まったかどうかを確かめてください。

次のステップ

この5つのフックで、基本は押さえられます。フォーマット、セキュリティ、テスト、通知、そして品質ゲートです。これらのパターンに慣れてきたら、コンテキストの注入（セッション開始時にプロジェクト固有の指示を差し込む）、再帰ガード（サブエージェントの無限ループを防ぐ）、ワークフローのオーケストレーション（複数ステップの処理をつなぐ）といったフックも作れます。

フックのアーキテクチャ、31イベントすべてのライフサイクル、そして応用パターンについては、Claude Code ガイドのフックのセクション、またはイベントごとに解説した Claude Code フック徹底解説をご覧ください。

本番で使っている95個のフックの成り立ちについては、Claude Code のフック：95個のフックそれぞれが存在する理由に書きました。それぞれのきっかけとなった出来事を扱っています。

参考文献

FAQ

フックは Claude Code のコマンド実行をブロックできますか？

できます。PreToolUse フックは終了コード2で終わることで、あらゆるツール操作をブロックします。Claude Code は保留中の操作をキャンセルし、フックの stderr 出力をモデルに見せます。exit 1 はブロックを伴わないフックのエラーで、操作はそのまま進みます。この終了コードの違いは重要です。セキュリティフックは exit 1 ではなく、必ず exit 2 を使ってください。² Claude は却下の理由を読み取り、より安全な代替案を提示します。

フックの設定ファイルはどこに置きますか？

プロジェクト単位のフックはリポジトリにコミットしてチームで共有する .claude/settings.json に、ユーザー単位のフックは全プロジェクトに適用される個人用の ~/.claude/settings.json に置きます。両方が存在する場合、フックは上書きではなく統合されます。すべてのスコープからマッチするフックが実行され、同一のハンドラは重複が除かれます。スクリプトのファイルは、作業ディレクトリにまつわる問題を避けるため、絶対パスで指定することをおすすめします。

フックはサブエージェントでも動きますか？

動きます。フックはサブエージェントの操作に対しても発火します。⁴ Claude が Agent ツールでサブエージェントを起動した場合、そのサブエージェントが使うすべてのツールで PreToolUse と PostToolUse のフックが実行されます。再帰的に強制されなければ、サブエージェントは安全ゲートをすり抜けられてしまいます。SubagentStop イベントを使えば、サブエージェントがタスクを終えたときにクリーンアップや検証を走らせられます。⁴

フックは何個からが多すぎるのでしょうか？

制約になるのは数ではなく性能です。フックはそれぞれ同期的に実行されるので、フックの合計実行時間が、マッチしたツール呼び出しごとに上乗せされます。私はユーザー単位とプロジェクト単位を合わせて95個のフックを動かしていますが、体感できる遅延はありません。各フックが200ms 未満で終わるからです。目安にしているのは、PostToolUse フックがファイル編集ごとに500ms を超えて足すようなら、セッションがもたつき始めるという線です。デプロイの前に time でフックをプロファイルしてください。速いフック10個は、遅いフック2個に勝ります。