Claude Code Hooks完全ガイド——pre/postフックでAI開発ワークフローを自在にカスタマイズ

はじめに

Claude Codeで開発を進めていると、こんな場面に遭遇します。

AIエージェントは確率的に動作するため、「毎回必ずPrettierを走らせる」「絶対に.envを触らせない」といった決定論的な制御はプロンプトだけでは保証できません。

そこで活用したいのがClaude Code Hooksです。ツール実行の前後やセッションのライフサイクルにシェルコマンドやHTTPリクエスト、さらにはLLM評価を差し込むことで、AIの動作に確実性をプラスできます。

この記事を読み終わると、以下ができるようになります：

• Hooksの4タイプ・17イベントの全体像を理解できる
• ファイル保存後の自動フォーマットを設定できる
• 危険なファイルや危険なコマンドの実行をブロックできる
• 通知・Slack連携・テスト自動実行の仕組みを構築できる

Hooksの全体像

アーキテクチャ

Hooksは、Claude Codeのライフサイクル上の特定イベントに応じて自動実行されるユーザー定義のアクションです。

4つのHookタイプ

全17イベント一覧

type HookEvent =
  | "SessionStart"       // セッション開始・再開・コンパクション後
  | "UserPromptSubmit"   // プロンプト処理前
  | "PreToolUse"         // ツール実行前（ブロック可能）
  | "PostToolUse"        // ツール実行成功後
  | "PostToolUseFailure" // ツール実行失敗後
  | "PermissionRequest"  // 権限ダイアログ表示時
  | "Notification"       // Claude側から注意喚起
  | "SubagentStart"      // サブエージェント開始
  | "SubagentStop"       // サブエージェント終了
  | "Stop"               // Claudeの応答完了
  | "PreCompact"         // コンテキスト圧縮前
  | "ConfigChange"       // 設定ファイル変更
  | "WorktreeCreate"     // ワークツリー作成
  | "WorktreeRemove"     // ワークツリー削除
  | "SessionEnd"         // セッション終了
  | "TeammateIdle"       // チームメイトがアイドル状態
  | "TaskCompleted";     // タスク完了

特に頻繁に使うのは PreToolUse（ブロック用）、PostToolUse（後処理用）、Stop（品質チェック用）、Notification（通知用）の4つです。

事前準備

必要なもの

設定ファイルの配置場所

設定ファイルの基本構造

{
  "hooks": {
    "イベント名": [
      {
        "matcher": "マッチ条件（省略可）",
        "type": "command",
        "command": "実行するコマンド",
        "description": "フックの説明"
      }
    ]
  }
}

/hooksコマンドで対話的にセットアップすることもできます。

ハンズオン 1: ファイル保存後の自動フォーマット

架空の業務システム「KanriPro」の開発を例に、最も基本的なHookを設定します。

Step 1: プロジェクトの設定ファイルを作成

mkdir -p .claude
touch .claude/settings.json

Step 2: PostToolUseフックを追加

.claude/settings.json に以下を記述します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "type": "command",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null; exit 0",
        "description": "ファイル保存後にPrettierで自動フォーマット"
      }
    ]
  }
}

ポイント:

Step 3: 動作確認

Claude Codeを起動し、ファイル編集を行います。

KanriProのsrc/lib/utils.tsにformatCurrency関数を追加してください

ファイル保存後、自動でPrettierが走りフォーマットが統一されることを確認してください。

ESLint自動修正も追加する

Prettierに加えて、ESLintの自動修正も同時に行いたい場合は配列に追加します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "type": "command",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null; npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null; exit 0",
        "description": "保存後にフォーマット＋Lint修正"
      }
    ]
  }
}

ハンズオン 2: 危険な操作をブロックする

Step 1: 機密ファイルの編集をブロック

.envやpackage-lock.jsonへの意図しない変更を防止します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "type": "command",
        "command": "echo \"$CLAUDE_FILE_PATH\" | grep -qE '\\.(env|env\\..*)$' && echo 'BLOCKED: .envファイルの編集は禁止されています' && exit 2 || exit 0",
        "description": ".envファイルへの編集をブロック"
      }
    ]
  }
}

PreToolUseフックで終了コード2を返すと、そのツール実行がブロックされます。これがHooksの最も強力な機能です。

Step 2: 危険なBashコマンドをブロック

rm -rfやgit push --forceなど、破壊的なコマンドもブロックできます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "type": "command",
        "command": "echo \"$CLAUDE_COMMAND\" | grep -qE '(rm -rf|drop table|git push --force|git reset --hard)' && echo 'BLOCKED: 危険なコマンドの実行は禁止されています' && exit 2 || exit 0",
        "description": "破壊的なコマンドをブロック"
      }
    ]
  }
}

ブロック結果の確認

Claude Codeで以下のように指示してみましょう。

KanriProの.envファイルにAPI_KEY=testを追加して

フックが発火し、「.envファイルの編集は禁止されています」というメッセージとともに編集がブロックされるはずです。Claude Codeはブロックされた旨を理解し、代替手段を提案してくれます。

ハンズオン 3: 通知・Webhook連携

macOSデスクトップ通知

長時間タスクの実行中に席を外しても、Claudeからの呼びかけを見逃しません。

{
  "hooks": {
    "Notification": [
      {
        "type": "command",
        "command": "osascript -e 'display notification \"$CLAUDE_NOTIFICATION\" with title \"Claude Code\"'",
        "description": "macOSデスクトップ通知"
      }
    ]
  }
}

Slack Webhook通知

タスク完了時にSlackチャンネルに通知を送ります。

{
  "hooks": {
    "TaskCompleted": [
      {
        "type": "http",
        "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
        "headers": {
          "Content-Type": "application/json"
        },
        "description": "タスク完了時にSlackへ通知"
      }
    ]
  }
}

httpタイプはイベントデータをJSON形式でPOSTします。Slack Incoming Webhookとの連携が特に簡単です。

セッション開始時のカスタム初期化

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "echo '## 今日のリマインダー' && echo '- KanriProはyarnを使用' && echo '- テストはVitest' && echo '- コミットはConventional Commits形式'",
        "description": "セッション開始時にプロジェクトリマインダーを表示"
      }
    ]
  }
}

ハンズオン 4: LLMフック・エージェントフックで品質を自動検証

commandタイプは確定的な処理に向いていますが、「コードの品質を判断する」にはLLMの力が必要です。

promptフック: セキュリティチェック

{
  "hooks": {
    "Stop": [
      {
        "type": "prompt",
        "prompt": "直前の変更に以下のセキュリティ問題がないか確認してください：\n- ハードコードされたAPIキーや秘密情報\n- SQLインジェクションの可能性\n- XSS脆弱性\n- 認証バイパスの可能性\n問題がなければ「OK」、問題があれば具体的に指摘してください。",
        "description": "応答完了時にセキュリティチェック"
      }
    ]
  }
}

promptタイプはHaiku（高速・低コスト）で1ターンの評価を実行します。

agentフック: テスト自動実行＋修正

{
  "hooks": {
    "Stop": [
      {
        "type": "agent",
        "prompt": "変更されたファイルに対応するテストを実行してください。テストが失敗した場合は、原因を特定して修正を試みてください。修正後、再度テストを実行して成功することを確認してください。",
        "description": "応答完了後にテストを自動実行・修正"
      }
    ]
  }
}

agentタイプはマルチターンのサブエージェントを起動し、テスト実行→失敗の分析→修正→再テストまで自律的に行います。

実務での組み合わせパターン

「防御 → 整形 → 検証」の三段構え

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "type": "command",
        "command": "echo \"$CLAUDE_FILE_PATH\" | grep -qE '\\.(env|env\\..*)$' && exit 2 || exit 0",
        "description": "Layer 1: 機密ファイルをブロック"
      },
      {
        "matcher": "Bash",
        "type": "command",
        "command": "echo \"$CLAUDE_COMMAND\" | grep -qE '(rm -rf|drop table|git push --force)' && exit 2 || exit 0",
        "description": "Layer 1: 危険コマンドをブロック"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "type": "command",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null; exit 0",
        "description": "Layer 2: 自動フォーマット"
      }
    ],
    "Stop": [
      {
        "type": "prompt",
        "prompt": "直前の変更にセキュリティ上の問題がないか確認してください。",
        "description": "Layer 3: セキュリティチェック"
      }
    ],
    "Notification": [
      {
        "type": "command",
        "command": "osascript -e 'display notification \"$CLAUDE_NOTIFICATION\" with title \"Claude Code\"'",
        "description": "デスクトップ通知"
      }
    ]
  }
}

コンパクション対策

メモリシステムの記事でも触れますが、コンテキスト圧縮後に重要な文脈を再注入するHookも有効です。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "type": "command",
        "command": "cat .claude/context-reminder.md",
        "description": "コンパクション後にコンテキストを再注入"
      }
    ]
  }
}

SessionStartイベントは通常のセッション開始だけでなく、コンパクション後にも発火します。compactマッチャーで圧縮後のみに絞り込み、context-reminder.mdに書いた重要な文脈を再注入できます。

Tips・注意点

デバッグ方法

利用可能な環境変数

パフォーマンスの注意点

• commandフックは同期実行されるため、重い処理を入れるとClaude Codeの応答が遅くなります
• Prettierのように高速なツールは問題ありませんが、テスト実行などはStopイベント（応答完了後）に配置するのが適切です
• prompt/agentフックはLLMを呼び出すため、APIコスト（Haiku）が追加で発生します

まとめ

次のアクションとしておすすめ：

1. まずPostToolUseでPrettierを設定する — 最も効果が実感しやすい
2. PreToolUseで.envをブロックする — セキュリティの基本
3. Notificationでデスクトップ通知を設定する — 長時間タスクで威力を発揮
4. 慣れてきたらprompt/agentフックを追加する — 品質の自動検証

Hooksは小さく始めて大きく育てるのがコツです。まずは「保存したらPrettierを走らせる」という1行から始めてみてください。

---

参考リンク：

• Claude Code公式ドキュメント — Hooks
• Claude Code Hooks: Complete Guide with 20+ Examples（DEV Community）
• Claude Code Hooks Mastery（GitHub）

---

関連記事：

• Claude Code Skills完全ガイド——カスタムスキルの書き方とベストプラクティス
• Claude Code エージェントチーム実践ガイド——複数エージェントを束ねるオーケストレーション
• Claude Code Remote Control実践ガイド——リモートマシンでエージェント開発を24時間回す