Hooksとは？Claude Codeの操作に必ず反応する自動ガードレール

Hookは、Claude Codeのライフサイクルイベントでシェルコマンド、HTTP、MCP、prompt、agentなどを起動する設定です。モデルが「たぶん実行する」ことを期待するSkillと異なり、条件に合うイベントでは決めた処理を走らせます。

仕組み

設定JSONのどこを確かめるかを対応させます。

1. 1イベント：いつツールの前後、終了時など、発生する時点。
2. 2matcher：どれに対象のツール名や条件を絞る。
3. 3handler：何をする検査コマンドなどを実行し、結果を扱う。

Hookが動かないときは、この三つと設定スコープを順に確認します。まず同じ処理を手動で確かめます。

設定はユーザーまたはプロジェクトのsettings.jsonに、イベント、matcher、handlerの3層で書きます。代表的なイベントはPreToolUse（ツール実行前）、PostToolUse（実行後）、Notification、Stop、SessionStartです。たとえばBash実行前に危険なコマンドを拒否し、ファイル編集後にformatterを起動する、といった構成です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "npm run format -- --check"
        }]
      }
    ]
  }
}

matcherは対象ツールや条件に合わせて狭くします。Hookの標準入力にはイベントのJSONが渡るため、スクリプト側で入力を検証し、終了コードと出力の意味を決めておきます。非同期Hook、prompt・agent Hook、HTTP・MCP handlerは便利ですが、失敗時の扱いと権限を先に設計してください。

Windowsでの注意

PowerShellやcmd.exeの構文、実行ポリシー、パスの引用符が関係します。まず手動で同じコマンドを実行し、プロジェクトのルートから動くことを確認してからHookへ移します。Hookは無限ループや大量ログを生み得るため、PostToolUseで同じファイルを再編集する処理は避けます。

Hooks入門とHooksリファレンスを照合しました。具体的なlint設定はHooksで自動チェック、全体の比較は自動化機能まとめを参照してください。実機検証はしていません。