Hooksとは？Claude Codeの「自動ガードレール」を初心者向けに整理

Claude Codeを使っていると、設定ファイルに「Hooks」という項目が出てくる。名前は見かけるのに、何をしてくれるのかがいまいち掴めない――という人は少なくない。結論を先に言うと、HooksはClaude Codeがツールを実行する直前・直後に「自動でシェルコマンドを走らせる仕組み」だ。自分でルールを書いておけば、危険な操作を止めたり、実行記録を残したりできる。

Hooksとは — 一言でいうと

Hooksとは、Claude Codeがツールを実行する直前または直後に、自動的にシェルコマンドを走らせる仕組みだ。

具体的には、ファイルを読み込む前、コマンドを実行した後――そういうタイミングで、自分が指定したコマンドが勝手に動く。どこに書くかというと、settings.jsonのhooksセクションだ。

たとえばClaude CodeがRemove-Item（ファイル削除）を実行しようとした瞬間に「待った」をかけられる。権限設定や確認プロンプトでも止められる場合はありますが、Hooksを使うと、特定の条件に合う操作を実行前に自動チェックしやすくなります。Hooksがあれば、実行前に自動でチェックが入る――この違いが、Hooksを知る最大の理由になる。

Hooksには多数のイベント種別があるが、代表的なものは次の3つだ。

イベント	タイミング	何ができるか
PreToolUse	ツール実行の直前	実行をブロックできる
PostToolUse	ツール実行の直後	結果のログ記録や後処理
Notification	通知の送信時	通知の外部連携

まずはPreToolUseを押さえると、「実行前に止める」というHooksの代表的な使い方を理解しやすくなる。

なぜHooksが必要なのか

Claude Codeは自律的にツールを実行する。ファイルの読み書き、コマンドの実行、コードの編集――すべてをAIが判断して進める。

ここで気になるのが「意図しない操作が起きる可能性」だ。たとえば、プロジェクトの重要なファイルを上書きしてしまったり、想定外のコマンドが走ってしまったりする。人が毎回「これ実行していい？」と確認するのは現実的ではない。Claude Codeは高速にツールを連続実行するので、手動での監視は追いつかない。

Hooksはこの問題に「自動で安全弁を効かせる」方向で答えを出す。ルールをあらかじめ書いておけば、Claude Codeが危険な操作を試みた瞬間にブロックされる。人がその場にいなくても、ガードレールが効いている状態だ。

実務的な例で言うと、Remove-ItemやRemove-Item -Recurseのような削除系コマンドに対してPreToolUseフックを仕掛けておく。Claude Codeが削除を試みた瞬間にフックが発火し、exit code 2を返せば実行は止まる。PostToolUseの実用例として、ファイル編集後にlint・format・testを自動実行する設定もある。

Hooksの仕組み — 代表的な3つのイベント種別

3つのイベント種別の違いを整理する。ここがHooksの核心部分だ。

PreToolUse は、ツールが実行される直前に発火する。ここでexit code 2を返すと、ツールの実行がブロックされる。exit code 0ならそのまま実行が進む。Claude Codeが何をしようとしているかは、stdin（標準入力）経由でJSON形式のツール情報が渡されるので、それを読み取って判断する。

PostToolUse は、ツールが実行された直後に発火する。実行結果のログを残したり、後処理の自動化に使ったりする。PreToolUseのようにブロックはできず、「実行後に何かする」のが役割だ。

Notification は、Claude Codeが通知を送るタイミングで発火する。外部のチャットツールに通知を転送したり、ログシステムに記録したりする用途で使う。

3つのイベントの発火タイミングを時系列で並べると、次のようになる。

Claude Codeがツールを実行しようとする
PreToolUse が発火 → ブロック判定（exit code 2ならここで停止）
ツールが実行される
PostToolUse が発火 → 実行後の処理
（必要に応じて）Notification が発火

stdinで渡されるJSONには、ツール名（tool_name）と入力パラメータ（tool_input）が含まれている。これを受け取って処理を書くのがフックの基本形だ。

settings.jsonへの書き方 — 最小限の例

Hooksはsettings.json系の設定ファイルに書く。初心者がまず押さえたい場所は3つある。

ユーザー設定: ~/.claude/settings.json（自分の環境全体に適用）
プロジェクト設定: プロジェクトルートの.claude/settings.json（そのプロジェクトに適用。チームと共有される場合がある）
ローカル設定: プロジェクトルートの.claude/settings.local.json（自分だけに適用。通常は共有しない）

設定スコープの詳細は、設定ファイルのスコープ整理記事で詳しく解説している。

基本構造は、hooksオブジェクトの中にPreToolUseやPostToolUseなどのイベント名をキーとして書き、その配下にmatcherと内側のhooks配列を置く形だ。実行する処理は、内側のhooks配列にtypeとcommandを書く。

まずは一番シンプルな例。Bashツールが実行される前にメッセージを出すだけのフックだ。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host 'Bashツールが実行されます'"
          }
        ]
      }
    ]
  }
}

これだけだとブロックはしない。ただメッセージが出るだけだ。ブロックするには、exit code 2を返す必要がある。

削除コマンドをブロックする例:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "$json = [Console]::In.ReadToEnd(); if ($json -match 'Remove-Item') { [Console]::Error.WriteLine('削除コマンドはブロックされました'); exit 2 } else { exit 0 }"
          }
        ]
      }
    ]
  }
}

matcherにはツール名を指定する。Bash、Write、Readなど、Claude Codeが使うツール名に合わせる。commandにはPowerShellのコマンドを書く。

JSONの書き方で一番つまずきやすいのはカンマ忘れと括弧のミス。要素の末尾にカンマが抜けているとHooks全体が動かず、しかもエラーメッセージが出ないことがある。書き終わったらJSONの構造チェックをしておくと安心だ。

Windows環境でPowerShellのコマンドを書く場合は、command hook側に"shell": "powershell"を明示しておくと分かりやすい。パス区切りにはバックスラッシュ（\）を使う。

Hooksと他の機能はどう違うのか

Claude Codeにはカスタマイズ機能がいくつかある。初心者にとって「これとこれは何が違うの？」が一番のつまずきポイントだ。ざっくり整理してみよう。

CLAUDE.md ＝ Claude Codeへの「指示書」。常に読み込まれてAIの行動指針になる。「こういう文体で書いて」「このルールを守って」といった内容を書く場所だ
Skills ＝「作業手順書」。/skill-nameのように明示的に呼び出せるほか、内容によってはClaudeが文脈から自動で使うこともある（Skillの自作手順も参考に）
MCP ＝「外部ツールへの接続窓口」。Claude Codeが使えるツールを増やす仕組み
Hooks ＝「イベントに自動反応するガードレール」。ツールの前後に自動実行される

「同じことをしたい場合、どれを使うべきか」の目安:

やりたいこと	使う機能
AIに常に守ってほしいルールを書く	CLAUDE.md
一連の作業を手順化する	Skills
外部ツール（ブラウザ等）を連携する	MCP
ツール実行の前後に自動で何かする	Hooks

Hooksの特徴は「自動で動く」ことだ。CLAUDE.mdはAIが参照するが、実行そのものはAIの判断に委ねられる。Skillsは明示的に呼び出せるうえ、設定によってはClaudeが必要だと判断したタイミングで使うこともある。Hooksだけが、特定のイベントに反応して強制的に動く。

Windows環境でHooksを使うときの注意点

Windows環境でHooksを設定する場合、いくつか押さえておきたい点がある。

コマンドはPowerShellで実行される。Unix系のシェルコマンド（echo、cat、grep等）ではなく、PowerShellのコマンドレット（Write-Host、Get-Content等）を使う。

パス区切り文字にも注意が必要。Windowsではバックスラッシュ（\）が使われる。JSON内ではバックスラッシュをエスケープする必要があるので、C:\\Users\\ユーザー名\\...のように書く。

動作確認は、意図的にフックを発火させて試すのが手っ取り早い。確認用の最小限の設定例:（権限プロンプトの頻度を減らしたい場合は、/permissionsとsettings.local.jsonの設定方法も参考に）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host '=== Hook fired ==='"
          }
        ]
      }
    ]
  }
}

この設定をしてからClaude Codeで何かコマンドを実行してみる。ターミナルに「=== Hook fired ===」と表示されれば、Hooksは動いている。

設定ミスでClaude Codeが動かなくなることは基本的にはないとされている。Hooksの記述にエラーがある場合、そのフックはスキップされてツールの実行自体は進むのが通常の挙動だ。ただし、ブロック系のフック（exit code 2を返すもの）の条件が厳しすぎると、本来動くべき操作まで止まってしまう。まずはブロックなしの確認用フックで動作を確かめてから、条件を絞っていくと良い。

まとめ

Hooksは、Claude Codeがツールを実行する前後に自動でコマンドを走らせる仕組みだ。PreToolUseでブロック、PostToolUseでログ記録、Notificationで外部連携――この3つを押さえておけば実務上は十分。設定はsettings.jsonのhooksセクションに書く。まずはブロックなしの確認用フックで動作を試してから、用途に合わせて条件を絞っていく。Claude Codeのカスタマイズ機能の中では「自動で動くガードレール」という立ち位置で、CLAUDE.mdやSkillsとは役割が明確に違う。

Claude Codeでどこまでできる？