Claude Code Hooks入門：編集後の自動フォーマット・危険コマンドのブロック・テスト自動実行まで

Claudeスキル・MCP
Claudeスキル・MCP のアイキャッチ

Claude Codeには「hooks（フック）」という仕組みがあります。セッション開始・ツール実行前後・停止など、Claude Codeのライフサイクル上の特定タイミングでシェルコマンドを自動実行できるしくみです。MCPがClaudeに新しい能力を与えるのに対し、hooksは「AIが何をしようとも必ず実行される保証」を与えます。本記事ではhooksの概念から、すぐ使えるパターン5選までを実際の設定例とともに解説します。

AIエージェント・ツールのイラスト

hooksとは何か：「AIの判断」ではなく「確実な実行」

Claude Codeでコードを書かせるとき、AIが「Prettierを実行しよう」と判断しなければフォーマットされません。しかしhooksを使えば、ファイルを編集するたびに必ずPrettierが走るという保証をシェルスクリプトで担保できます。

公式ドキュメントおよびコミュニティの説明によれば、hooksの位置づけはこうです：

  • MCP：Claudeに新しい能力（GitHub連携・DBアクセス等）を追加する
  • hooks：Claudeが何をするかに関わらず、特定のタイミングで必ず実行される処理を保証する

この「決定論的な実行保証」こそがhooksの価値です。AIが「やり忘れた」では済まない処理——lint・フォーマット・セキュリティチェック・監査ログ——を仕込む場所として設計されています。

使用できる主なフックイベント

Claude Codeでは2026年6月時点で30近くのフックイベントが用意されています。カテゴリ別に整理すると以下のとおりです。

カテゴリ イベント名 発火タイミング ブロック可否
セッション SessionStart セッション開始時 不可
セッション SessionEnd セッション終了時 不可
プロンプト UserPromptSubmit ユーザーがプロンプトを送信するたび 可
プロンプト Stop Claudeが応答を完了しようとしたとき 可
ツール呼び出し PreToolUse ツール実行の直前 可
ツール呼び出し PostToolUse ツール実行の直後 不可（観察・注入）
ツール呼び出し PostToolUseFailure ツール実行失敗時 不可
通知 Notification Claude Codeが通知を送るとき 不可
コンテキスト PreCompact コンテキスト圧縮の直前 可
サブエージェント SubagentStop サブエージェントが完了したとき 可
ターミナルで作業する開発者
Photo: Peer.Gynt / CC BY-SA（Openverse経由）

settings.jsonの基本構造

hooksの設定はsettings.jsonに記述します。読み込み順は以下の3段階で、後ろが上書きします。

  1. ~/.claude/settings.json：個人設定（全プロジェクト共通）
  2. .claude/settings.json：プロジェクト設定（チーム共有・リポジトリに含める）
  3. .claude/settings.local.json：プロジェクト内個人設定（gitignore推奨）

基本構造はこうです：

{
  "hooks": {
    "イベント名": [
      {
        "matcher": "ツール名（正規表現）",
        "hooks": [
          {
            "type": "command",
            "command": "実行するシェルコマンド"
          }
        ]
      }
    ]
  }
}

matcherはPreToolUse/PostToolUseではツール名に対する正規表現です。"Write|Edit"のようにパイプで複数指定できます。matcherを空文字列にすると全ツールにマッチします。

実用フック5選：コピーして使えるサンプル

1. PostToolUse：ファイル編集後に自動フォーマット

Claude Codeがファイルを作成・編集するたびにPrettierとESLintを自動実行します。AIが「フォーマットし忘れる」問題をゼロにします。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" && eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>&1 | head -5 || true"
          }
        ]
      }
    ]
  }
}

環境変数 $CLAUDE_TOOL_INPUT_FILE_PATH には編集されたファイルのパスが自動的にセットされます。

2. PreToolUse：危険なコマンドをブロック

PreToolUseフックでスクリプトが exit code 2 を返すと、Claudeはそのツール呼び出しを実行せず、stderrの内容を理由として受け取ります。これを使って rm -rf、DROP TABLE、git push --force などの危険な操作を防御できます。

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

safety-check.sh の中では $CLAUDE_TOOL_INPUT にBashコマンド文字列が入っているので、危険なパターンをgrepしてexit 2を返す実装が典型です。

3. SessionStart：作業開始時にgitの状況を確認

セッション開始時にgit statusとログを自動表示することで、Claudeが毎回プロジェクトの現状を把握した状態でスタートできます。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && git status --short && git log --oneline -5"
          }
        ]
      }
    ]
  }
}

4. Stop：セッション終了前にテストを自動実行

StopフックはClaudeが「完了しました」と終了しようとするタイミングで発火します。ここでテストを実行し、失敗したら "decision": "block" を返すことで、テストが通るまでClaudeに作業を継続させられます。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && npm test 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}

テストが失敗するとClaudeはエラー内容を受け取って修正を試みます。「テストが赤いのにセッションを閉じる」問題を自動的に防げます。

5. Notification：権限プロンプトをDiscordに通知

Claudeが権限を求めるタイミングでDiscordのWebhookに通知を送れます。Claudeをバックグラウンドで動かしているときに、スマホで確認・承認の判断ができます。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/discord-notify.js"
          }
        ]
      }
    ]
  }
}

Discord Webhook URLなど秘密情報を含む場合は、チームのリポジトリには入れず ~/.claude/settings.json（個人設定）に置くのが推奨です。

hooks vs MCP：何が違うか

比較軸 hooks MCP
役割 ライフサイクルの特定タイミングで確実に実行 Claudeに新しいツール能力を追加
実行トリガー イベント駆動（自動） Claude が判断して呼び出す
ブロック可否 PreToolUse / Stop は実行を止められる 止められない
実装形態 シェルコマンド（またはHTTPコール） MCPサーバー（プロセス or SSE）
適用例 lint・フォーマット・監査ログ・セキュリティガード GitHub・DB・Slack・ブラウザ操作

両者は補完的です。MCPツール呼び出しの直前にPreToolUseフックでバリデーションする、MCPツールの実行結果をPostToolUseフックで監査ログに記録する、といった組み合わせも有効です。

セキュリティ上の注意点

hooksは強力な自動化機能である反面、設定ファイルの改ざんによる悪用リスクもあります。2026年5月には、npm パッケージを通じて ~/.claude/settings.json に悪意ある SessionStart フックが注入される攻撃事例が報告されています（StepSecurity レポート）。

安全に使うためのポイント：

  • 設定ファイルを定期的に確認する：~/.claude/settings.json と .claude/settings.json を目視でレビューする習慣を持つ
  • hookスクリプトをバージョン管理する：.claude/hooks/ ディレクトリをgitで管理し、変更履歴を追跡する
  • hookは薄く保つ：1つのhookファイルに複数の役割を持たせず、ロジックは共通ライブラリ/スクリプトに切り出す
  • Webhookなどの秘密情報は個人設定に：~/.claude/settings.json に置き、プロジェクトのリポジトリにはコミットしない

まとめ

Claude Code hooksは、AIコーディングセッションの「確実性」を高める機能です。MCPが「何ができるか」を拡張するのに対し、hooksは「何が必ず起きるか」を保証します。まずPostToolUseで自動フォーマットから始めて、徐々にPreToolUseのセキュリティガード、Stopのテストゲートへと育てていくのが、実際に使い続けているエンジニアたちの推奨ルートです。

主な情報源

各ツールは提供元の規約に従ってご利用ください。情報は各情報源の公開時点のものです。収集・要約はAI、公開判断は人。