Claude Code の Hooks を基礎から学んだのでまとめてみる

ここ数ヶ月、業務でClaude Codeを使う機会が増え、特に押さえておきたいと思ったのが「Hooks」です。CLAUDE.mdに「これはやらないで」と書いても、結局Claudeの判断で無視されてしまうことがあり、もっと確実に挙動をコントロールしたいと思ったのがきっかけでした。公式ドキュメントを読みながら学んだ基本を整理します。

Hooksとは何か

Hooksは、Claude Codeのライフサイクルの特定タイミングで、自分で指定したコマンドを実行できる仕組みです。編集後にファイルをフォーマットする、コマンド実行前にブロックする、Claudeが入力待ちのときに通知を送る、セッション開始時にコンテキストを注入する、といったことができます。

重要なのは、これが「お願い」ではなく「強制力のある仕組み」だという点です。CLAUDE.mdのルールはあくまで指示であり守られないこともありますが、Hooksは条件に合致すれば必ず実行されます。Gitのpre-commitフックをAIエージェントの動作にも使える、というイメージです。

設定の基本構造

Hooksは~/.claude/settings.json(グローバル)や、プロジェクト内の.claude/settings.jsonにhooksブロックを追加して設定します。

{
  "hooks": {
    "イベント名": [
      {
        "matcher": "対象を絞り込む条件",
        "hooks": [
          { "type": "command", "command": "実行したいコマンド" }
        ]
      }
    ]
  }
}

構成要素は3つです。

• イベント: いつ発火させるか(PreToolUse、PostToolUse、Notificationなど)
• マッチャー: どの対象に発火させるか(ツール名などの正規表現)
• アクション: 何をするか(基本はシェルコマンド)

代表的なイベント

• PreToolUse: ツール実行前に発火。危険な操作をブロックする用途に向く。
• PostToolUse: ツール実行後に発火。編集後にフォーマッターを自動実行するなどでよく使われる。
• Notification: Claudeが入力や許可待ちのときに発火。デスクトップ通知などに使える。
• Stop: Claudeが応答を終えたと判断したタイミングで発火。

このほかセッション開始・終了時のイベントなども用意されています。

具体例: 危険なコマンドをブロックする

PreToolUseの例として、ドキュメントに載っているdrop tableを検知してブロックするスクリプトは次の形です。

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2
  exit 2
fi
exit 0

ポイントは終了コードです。0なら通常通り処理が進み、2ならブロックされ、標準エラー出力の内容がClaudeへのフィードバックとして渡されます。複数のHookが同時に動いた場合は「拒否」が最優先される、という原則もあります。

Hooksとの通信の仕組み

Hooksはstdin・stdout・stderr・終了コードを通じてClaude Codeとやり取りします。イベント発火時にClaude Codeがイベント固有のJSONデータを標準入力に渡し、スクリプト側がそれを処理して終了コードで結果を返す、という流れです。session_idやcwdなど共通のフィールドに加え、イベントごとの固有データが渡されます。

どこから手をつけるか

最初から複雑に組もうとすると挫折しやすいので、まずは日常的に面倒な作業を一つ自動化するところから始めるのがよさそうです。編集後のフォーマット自動実行や、危険なコマンドのブロックといった単純なものから試すと、「確実に実行される」感覚をつかみやすいです。

まとめ

プロンプトベースの指示はあくまで「お願い」でしかなく、確実性が求められる場面ではHooksのような仕組みで担保する必要がある、というのが学びでした。基本は以下の点を押さえておけば十分そうです。

• イベント・マッチャー・アクションの3要素で構成される
• PreToolUseやPostToolUseなど、ライフサイクルの様々なタイミングで発火させられる
• 終了コードで処理を継続するかブロックするかをコントロールできる
• 設定はプロジェクト単位、もしくはグローバルにsettings.jsonへ記述する

詳細な仕様や全イベントの一覧は、公式のHooksリファレンスを参照するのが確実です。

参考

• Claude Code Hooks Guide(公式ドキュメント): https://code.claude.com/docs/en/hooks-guide