Claude Code Hooksの使い方｜設定・matcher・テスト自動化

Claude Code Hooksは、Claudeに毎回「テストして」「lintして」と頼む代わりに、決まったタイミングで処理を自動実行する仕組みです。まずは通知や整形など影響の小さい処理から始め、テスト、最後に危険操作のブロックへ広げると設計しやすくなります。

まず結論：目的からHook eventを選ぶ

やりたいこと	主なevent	タイミング
危険なコマンドを止める	PreToolUse	Tool実行の前
編集後にlint・テストを回す	PostToolUse	Toolが成功した後
セッション開始時に環境情報を準備する	SessionStart	セッション開始・再開時
完了時に確認処理を入れる	Stop	Claudeが応答を終えるとき

Claude Codeの公式Hooks仕様では、eventが発火し、matcherが一致するとhandlerへJSONコンテキストが渡されます。PreToolUseはTool実行前に動き、結果によってTool callを止められます。PostToolUseはToolが成功した後に動きます。

Hooksの設定はevent・matcher・handlerの3段階で考える

用語解説：Hook
Claude Codeのライフサイクル上の特定タイミングで自動実行される処理です。shell command、HTTP endpoint、LLM promptなどをhandlerとして設定できます。

設定は「いつ実行するか」をeventで決め、「どのToolに反応するか」をmatcherで絞り、「何を実行するか」をhandlerで定義します。たとえばPostToolUseでmatcherをEdit|Writeにすると、ファイル編集系Toolの成功後だけ処理を走らせられます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/lint-check.sh"
          }
        ]
      }
    ]
  }
}

Hookは自動でコードを実行できるため、設定例をそのまま貼る前に実行内容を確認します。共有Repositoryでは、信頼できるScriptだけをproject設定から呼び出し、個人環境だけの処理はlocal設定へ分ける方が管理しやすくなります。

設定場所は共有範囲で選ぶ

設定場所	範囲	向く用途
~/.claude/settings.json	自分の全Project	個人共通の通知・補助処理
.claude/settings.json	1 Project・共有可能	チーム共通のlint・test・安全チェック
.claude/settings.local.json	1 Project・ローカル	端末固有のコマンドや個人設定

公式ドキュメントでは、設定場所によってHookの適用範囲と共有可否が変わります。チーム全員に必要な品質チェックと、個人端末に依存する処理を分けると、設定の意図が伝わりやすくなります。

編集後のlintやテストはPostToolUseで絞る

ファイル変更後に毎回同じ検査をしたい場合は、PostToolUseの対象Toolをmatcherで絞ります。AnthropicもHooksの利用例として、コード変更後のテスト実行やcommit前のlintを挙げています。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --runInBand"
          }
        ]
      }
    ]
  }
}

重いテストをすべての編集後に回すと待ち時間が増えます。軽いlintや対象テストをPostToolUseに置き、全テストはStopやCIなど別の境界で実行する、といった分担も検討します。

危険操作を止めたいならPreToolUseで実行前に判定する

削除や本番操作など、実行後では遅い処理はPreToolUse側で確認します。公式Hooks仕様ではPreToolUseからTool callをdenyできるため、Bashのような実行Toolをmatcherで絞り、入力内容を検査する構成が取れます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.sh"
          }
        ]
      }
    ]
  }
}

判定Scriptは「すべて許可する」前提にせず、どの操作を止めるかを小さく定義します。またHookが黙って終了したことと、Claude Codeの通常のpermission判定で許可されたことは別です。