Claude Code Hooks: 自動化ポリシーの完全ガイド

Hooks は Claude Code の自動化レイヤーであり、Claude のアクションを自動的にインターセプト、検証、変更することができます。このガイドでは、すべての hook タイプ、設定パターン、実践的なユースケースを解説します。

Hooks とは？

公式ドキュメントによると、Hooks は以下の機能を持ちます：

Claude のアクションの前後で実行されるイベントインターセプター
動作を自動的に検証するポリシー適用機能
危険な操作を防ぐガードレール
カスタムロジックをトリガーする自動化機能

Hooks は Claude Code のミドルウェアと考えてください。Claude の意図と実際の実行の間に位置します。

Hook アーキテクチャ

┌────────────────────────────────────────────────────────────┐
│                     Claude Code CLI                         │
│                                                            │
│  User Prompt ──────────────────────────────────────►       │
│       │                                                    │
│       ▼                                                    │
│  ┌─────────────────┐                                       │
│  │ UserPromptSubmit│  Hook: Validate/modify prompt         │
│  │ Hook            │                                       │
│  └────────┬────────┘                                       │
│           │                                                │
│           ▼                                                │
│  ┌─────────────────┐                                       │
│  │ PreToolUse      │  Hook: Approve/deny/modify action     │
│  │ Hook            │                                       │
│  └────────┬────────┘                                       │
│           │                                                │
│           ▼                                                │
│  ┌─────────────────┐                                       │
│  │ Tool Execution  │  Actual action (Read, Write, Bash)    │
│  └────────┬────────┘                                       │
│           │                                                │
│           ▼                                                │
│  ┌─────────────────┐                                       │
│  │ PostToolUse     │  Hook: React to results               │
│  │ Hook            │                                       │
│  └────────┬────────┘                                       │
│           │                                                │
│           ▼                                                │
│  ┌─────────────────┐                                       │
│  │ Stop Hook       │  Hook: Verify completion              │
│  └────────┬────────┘                                       │
│           │                                                │
│           ▼                                                │
│      Response ◄────────────────────────────────────────    │
└────────────────────────────────────────────────────────────┘

Hook イベント

イベント	トリガータイミング	一般的なユースケース
`SessionStart`	セッション開始時	コンテキストの読み込み、セットアップの確認
`UserPromptSubmit`	ユーザーがプロンプトを送信時	コンテキストの追加、入力の検証
`PreToolUse`	ツール実行前	アクションの承認/拒否
`PostToolUse`	ツール実行後	監査、結果への反応
`Stop`	Claude が停止時	完了の確認
`SubagentStop`	サブエージェント完了時	タスク完了の確認

Hook の設定

Hooks は .claude/settings.json で設定します：

{
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "Stop": [...],
    "SessionStart": [...],
    "UserPromptSubmit": [...],
    "SubagentStop": [...]
  }
}

Hook の構造

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolName or *",
        "hooks": [
          {
            "type": "prompt | command",
            "prompt": "Instructions for Claude",
            "command": "shell command to run",
            "onFailure": "block | warn | ignore"
          }
        ]
      }
    ]
  }
}

PreToolUse Hooks

目的： アクションの実行前にインターセプトします。承認、拒否、または変更が可能です。

危険なコマンドをブロック

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "Check if command contains destructive operations (rm -rf, DROP TABLE, git push --force). If yes, return 'ask' for confirmation. Otherwise return 'approve'."
      }]
    }]
  }
}

ファイルアクセスの検証

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read",
      "hooks": [{
        "type": "prompt",
        "prompt": "If the file path contains .env, secrets, or credentials, return 'block' with explanation. Otherwise return 'approve'."
      }]
    }]
  }
}

書き込み前のセキュリティスキャン

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "prompt",
        "prompt": "Scan the content for potential secrets (API keys, passwords, tokens). If found, return 'block' with the line numbers. Otherwise return 'approve'."
      }]
    }]
  }
}

SQL インジェクション防止

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "prompt",
        "prompt": "If the code contains string concatenation with SQL keywords (SELECT, INSERT, UPDATE, DELETE), return 'block' with SQL injection warning. Otherwise return 'approve'."
      }]
    }]
  }
}

PostToolUse Hooks

目的： アクション完了後に反応します。ログ記録、監査、フォローアップのトリガーに適しています。

ファイル変更の監査

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "prompt",
        "prompt": "Log the file path and a summary of changes. If the file is in auth/, payment/, or admin/, note that security review is recommended."
      }]
    }]
  }
}

編集後のテスト自動実行

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "npm test --passWithNoTests",
        "onFailure": "warn"
      }]
    }]
  }
}

セキュリティスキャンのトリガー

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "prompt",
        "prompt": "If the written file is in auth/, payment/, or admin/ directories, trigger security-auditor agent for review."
      }]
    }]
  }
}

Stop Hooks

目的： Claude が停止する前に完了条件を確認します。品質ゲートに不可欠です。

テスト実行の確認

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "prompt",
        "prompt": "Check if code was modified (Write or Edit used). If yes, verify tests were run. If no tests ran, block and explain that tests are required before completion."
      }]
    }]
  }
}

セキュリティレビューの必須化

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "prompt",
        "prompt": "If code in auth/, payment/, or admin/ was modified, verify security-auditor was run. If not, block and explain security review requirement."
      }]
    }]
  }
}

ドキュメントの確認

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "prompt",
        "prompt": "If public API was modified, verify documentation was updated. If not, remind about documentation update before approving."
      }]
    }]
  }
}

カバレッジゲート

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "npm run test:coverage -- --coverageThreshold='{\"global\":{\"lines\":80}}'",
        "onFailure": "block"
      }]
    }]
  }
}

SessionStart Hooks

目的： セッション開始時にコンテキストを初期化します。

プロジェクトコンテキストの読み込み

{
  "hooks": {
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{
        "type": "prompt",
        "prompt": "Read CLAUDE.md and summarize key project policies. Load any saved memory entities related to recent work."
      }]
    }]
  }
}

環境チェック

{
  "hooks": {
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "node --version && npm --version",
        "onFailure": "warn"
      }]
    }]
  }
}

UserPromptSubmit Hooks

目的： Claude が行動する前にユーザー入力を処理します。

コンテキストの追加

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [{
        "type": "prompt",
        "prompt": "If the prompt mentions 'deploy' or 'release', add reminder about running full test suite first."
      }]
    }]
  }
}

キーワード検出

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [{
        "type": "prompt",
        "prompt": "If prompt contains 'urgent' or 'quickly', add reminder to maintain code quality despite time pressure."
      }]
    }]
  }
}

SubagentStop Hooks

目的： サブエージェントのタスク完了を確認します。

サブエージェント結果の検証

{
  "hooks": {
    "SubagentStop": [{
      "matcher": "*",
      "hooks": [{
        "type": "prompt",
        "prompt": "Review subagent results. If the task was security-related and no security-auditor was used, flag for review."
      }]
    }]
  }
}

Hook のタイプ

Prompt Hooks

Claude を使用して条件を評価します：

{
  "type": "prompt",
  "prompt": "Your evaluation instructions..."
}

Prompt Hook のレスポンス：

approve - アクションを許可
deny または block - アクションをブロック
ask - ユーザーに確認を求める
その他のテキスト - 変更/コンテキストとして扱われる

Command Hooks

シェルコマンドを実行します：

{
  "type": "command",
  "command": "npm test",
  "onFailure": "block | warn | ignore"
}

onFailure オプション：

block - コマンド失敗時に停止
warn - 警告を表示して続行
ignore - 失敗を無視

Matchers

特定のツール Matcher

{
  "matcher": "Bash"
}

ワイルドカード Matcher

{
  "matcher": "*"
}

複数のツール

各ツールに個別のエントリを作成します：

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Write", "hooks": [...] },
      { "matcher": "Edit", "hooks": [...] },
      { "matcher": "Bash", "hooks": [...] }
    ]
  }
}

実践的な例

例 1: セキュリティファースト設定

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "prompt",
          "prompt": "Block if command contains: rm -rf, DROP, TRUNCATE, --force, sudo rm. Return 'block' with explanation, or 'approve'."
        }]
      },
      {
        "matcher": "Read",
        "hooks": [{
          "type": "prompt",
          "prompt": "Block if path contains: .env, secret, credential, private, key. Return 'block' or 'approve'."
        }]
      },
      {
        "matcher": "Write",
        "hooks": [{
          "type": "prompt",
          "prompt": "Scan for secrets (API keys starting with sk_, tokens, passwords). Block if found."
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{
          "type": "prompt",
          "prompt": "If file in auth/payment/admin, recommend security-auditor review."
        }]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [{
          "type": "prompt",
          "prompt": "If auth/payment code modified, verify security-auditor ran. Block if not."
        }]
      }
    ]
  }
}

例 2: 品質ゲート設定

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{
          "type": "command",
          "command": "npm run lint -- --quiet",
          "onFailure": "warn"
        }]
      },
      {
        "matcher": "Edit",
        "hooks": [{
          "type": "command",
          "command": "npm run typecheck",
          "onFailure": "warn"
        }]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [{
          "type": "prompt",
          "prompt": "Verify: 1) Tests ran and passed, 2) Lint passed, 3) Types check. Block if any failed."
        }]
      },
      {
        "matcher": "*",
        "hooks": [{
          "type": "command",
          "command": "npm test -- --passWithNoTests",
          "onFailure": "block"
        }]
      }
    ]
  }
}

例 3: 監査証跡設定

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [{
          "type": "command",
          "command": "echo \"Session started: $(date)\" >> .claude/audit.log",
          "onFailure": "ignore"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{
          "type": "prompt",
          "prompt": "Log: file path, action type, timestamp. Append to .claude/audit.log"
        }]
      },
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "prompt",
          "prompt": "Log: command executed, exit status. Append to .claude/audit.log"
        }]
      }
    ]
  }
}

例 4: チームワークフロー設定

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "prompt",
          "prompt": "If command is 'git push', verify: 1) Tests pass, 2) Lint passes, 3) PR exists or being created. Block push without PR."
        }]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [{
          "type": "prompt",
          "prompt": "If feature work completed, remind to: 1) Update documentation, 2) Create/update PR, 3) Request review."
        }]
      }
    ]
  }
}

Hooks と他のツールの比較

機能	Hooks	Permissions	CLAUDE.md
自動化	はい	はい	いいえ（手動）
条件付き	はい	いいえ	いいえ
カスタムロジック	はい	いいえ	いいえ
シェルコマンド	はい	いいえ	いいえ
設定の容易さ	中	易	易

Hooks を使用すべき場面

Hooks を使用する場合：

条件付きロジックが必要な場合
自動適用が必要な場合
外部コマンドを実行する必要がある場合
監査証跡が必要な場合

Permissions を使用する場合：

シンプルな許可/拒否ルール
条件付きロジックが不要
静的なファイルアクセス制御

CLAUDE.md を使用する場合：

ガイドラインと設定
コンテキストとドキュメント
強制されない推奨事項

Hooks のデバッグ

Hook がトリガーされない

matcher がツール名と正確に一致しているか確認
JSON 構文が正しいか確認
hooks 配列の構造を確認

Command Hook が失敗する

ターミナルでコマンドを手動テスト
コマンドのパスと権限を確認
onFailure 設定を確認

Prompt Hook が動作しない

プロンプトの指示を明確にする
レスポンスオプションを明示的にする
より簡単なプロンプトでテスト

ベストプラクティス

1. シンプルに始める

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "Block rm -rf commands. Return 'block' or 'approve'."
      }]
    }]
  }
}

2. レスポンスを明示的にする

{
  "type": "prompt",
  "prompt": "Evaluate X. Return exactly one of: 'approve', 'block', or 'ask'."
}

3. onFailure を適切に使用する

// Critical: block on failure
{ "command": "npm test", "onFailure": "block" }

// Important: warn on failure
{ "command": "npm run lint", "onFailure": "warn" }

// Optional: ignore on failure
{ "command": "npm run optional-check", "onFailure": "ignore" }

4. Hooks を階層化する

PreToolUse → 悪いアクションを防止
PostToolUse → 監査と反応
Stop → 完了を確認

始め方

今日から：

危険なコマンド用に PreToolUse hook を 1 つ追加
テスト確認用に Stop hook を 1 つ追加
シンプルなシナリオでテスト

今週中に：

セキュリティ hooks を構築
品質ゲート hooks を追加
実際のワークフローでテスト

今月中に：

包括的な hook 設定を開発
チーム固有のポリシーを追加
監査証跡システムを作成

Hooks は Claude Code を受動的なアシスタントからポリシーを適用するパートナーへと変革します。一度設定すれば、常に信頼できます。

出典: Claude Code Documentation, Claude Code GitHub