対象Hooksで開発を自動化したい開発者

達成目標全22イベント・4ハンドラータイプを使いこなせる

前提知識Plugins & Skills理解

所要時間25分

Hooks完全ガイド

Claude CodeのHooksは、特定のイベントに応じて自動的にコマンドやスクリプトを実行する仕組みです。安全性の確保、品質の自動チェック、ワークフローの自動化を実現します。

Hooksの全体像

Hooksは「いつ」「何を」「どう実行するか」を定義する仕組みです。22のイベントタイミングと4つのハンドラータイプの組み合わせで、あらゆる自動化が可能になります。

主要イベント一覧

Hooksがトリガーされるタイミングを示す主要なイベントです。

カテゴリ	イベント名	発火タイミング
ツール	`PreToolUse`	ツール実行前（ブロック可能）
	`PostToolUse`	ツール実行後
ファイル	`PreWrite`	ファイル書き込み前
	`PostWrite`	ファイル書き込み後
コマンド	`PreBash`	Bashコマンド実行前
	`PostBash`	Bashコマンド実行後
セッション	`SessionStart`	セッション開始時
	`SessionEnd`	セッション終了時
通知	`Notification`	通知発生時
停止	`Stop`	エージェント停止時

4つのハンドラータイプ

command（コマンド実行）

シェルコマンドを実行する最も基本的なハンドラー。bash -c "..."形式でスクリプトを実行。終了コード0以外でブロック。

http（HTTPリクエスト）

外部APIにHTTPリクエストを送信するハンドラー。Slack通知、Webhook連携、外部サービスとの統合に使用。

prompt（LLM判断）

LLMにyes/no判断をさせるハンドラー。「この変更はセキュリティリスクがあるか？」などの判断を自動化。

agent（サブエージェント）

サブエージェントを起動するハンドラー。複雑な検証タスクをサブエージェントに委譲し、結果を受け取る。

安全系Hooks実践

破壊的な操作をブロックし、シークレットの漏洩を防止するHooksの設定方法を解説します。最初に設定すべき最重要のHooksです。

破壊操作ブロック

危険なコマンドの実行を事前に検知し、ブロックします。

.claude/settings.json - 破壊操作ブロック

{
  "hooks": {
    "PreBash": [
      {
        "matcher": "rm -rf|rmdir /s|del /f",
        "command": "echo 'BLOCKED: 破壊的なファイル削除コマンドが検出されました' && exit 1"
      },
      {
        "matcher": "DROP TABLE|DROP DATABASE|TRUNCATE",
        "command": "echo 'BLOCKED: データベース破壊コマンドが検出されました' && exit 1"
      }
    ]
  }
}

シークレットチェック

ファイル書き込み時に、APIキーやパスワードなどのシークレットが含まれていないかチェックします。

.claude/settings.json - シークレットチェック

{
  "hooks": {
    "PreWrite": [
      {
        "matcher": "**/*.ts,**/*.js,**/*.py",
        "command": "grep -nE '(sk-ant-api|AKIA[0-9A-Z]|password\\s*=\\s*[\"'\''].[\"'\'']|BEGIN RSA PRIVATE KEY)' $FILE && echo 'BLOCKED: シークレットが検出されました' && exit 1 || true"
      }
    ]
  }
}

force pushブロック

git push --forceやその省略形をブロックし、チームの作業を守ります。

.claude/settings.json - force pushブロック

{
  "hooks": {
    "PreBash": [
      {
        "matcher": "git push.*--force|git push.*-f",
        "command": "echo 'BLOCKED: force pushは禁止されています。--force-with-leaseを使用してください。' && exit 1"
      }
    ]
  }
}

⚠️ Warning

安全系Hooksは最初から設定してください。「後で設定しよう」と思っていると、その前に事故が起きます。特にforce pushブロックとシークレットチェックは必須です。

品質系Hooks実践

コードの品質を自動的に維持するためのHooksを設定します。ファイル保存後の自動lint、テスト実行、型チェックなどを自動化します。

自動lint/format（PostWrite）

ファイルが書き込まれた直後にlinterとformatterを自動実行し、コードスタイルを統一します。

.claude/settings.json - 自動lint/format

{
  "hooks": {
    "PostWrite": [
      {
        "matcher": "**/*.ts,**/*.tsx",
        "command": "npx eslint --fix $FILE && npx prettier --write $FILE"
      },
      {
        "matcher": "**/*.py",
        "command": "ruff check --fix $FILE && ruff format $FILE"
      }
    ]
  }
}

テスト自動実行

ソースコードが変更された時に、関連するテストファイルを自動実行します。

.claude/settings.json - テスト自動実行

{
  "hooks": {
    "PostWrite": [
      {
        "matcher": "src/**/*.ts",
        "command": "TEST_FILE=$(echo $FILE | sed 's/src/tests/' | sed 's/.ts/.test.ts/') && [ -f $TEST_FILE ] && npx vitest run $TEST_FILE || true"
      }
    ]
  }
}

型チェック

TypeScriptファイルの変更後に型チェックを実行し、型エラーを即座に検出します。

.claude/settings.json - 型チェック

{
  "hooks": {
    "PostWrite": [
      {
        "matcher": "**/*.ts,**/*.tsx",
        "command": "npx tsc --noEmit --pretty 2>&1 | head -20"
      }
    ]
  }
}

✅ Tip

品質系Hooksは|| trueで終わらせることで、チェック失敗時にClaude Codeの処理をブロックせず警告だけを表示できます。逆に、厳格にブロックしたい場合は&& exit 1を使います。

Prompt Hooks

Prompt HooksはLLMにyes/no判断をさせるハンドラータイプです。ルールベースでは判断が難しい複雑なケースに対して、AIの判断力を活用します。

LLMにyes/no判断させるHook

変更内容をLLMが分析し、問題がある場合にブロックまたは警告します。

Prompt Hookの設定例

{
  "hooks": {
    "PreWrite": [
      {
        "matcher": "src/api/**/*.ts",
        "type": "prompt",
        "prompt": "以下のファイル変更を分析し、セキュリティリスクがあるかどうかをyes/noで判断してください。認証バイパス、SQLインジェクション、XSSの可能性を確認してください。リスクがある場合はyesと回答し、理由を説明してください。"
      }
    ]
  }
}

セキュリティリスク分析

Prompt Hooksの典型的なユースケースは、コード変更のセキュリティリスク分析です。

認証・認可チェック — 新しいAPIエンドポイントに適切な認証ミドルウェアが設定されているか
入力バリデーション — ユーザー入力が適切にサニタイズされているか
データ漏洩リスク — レスポンスに不必要な個人情報が含まれていないか
依存関係の安全性 — 新しく追加されたパッケージに既知の脆弱性がないか

📝 Note

Prompt Hooksは追加のLLM呼び出しを行うため、実行コストが増加します。全ファイルに適用するのではなく、セキュリティ上重要なファイル（API、認証、決済処理など）に限定して使用してください。

Agent Hooks

Agent Hooksはサブエージェントを起動するハンドラータイプです。単純なコマンド実行では対応できない複雑な検証タスクをサブエージェントに委譲します。

サブエージェントをHookで起動

特定のイベント発生時に、定義済みのサブエージェントを自動的に起動し、検証タスクを実行させます。

Agent Hookの設定例

{
  "hooks": {
    "PostWrite": [
      {
        "matcher": "src/components/**/*.tsx",
        "type": "agent",
        "agent": "accessibility-checker",
        "prompt": "このReactコンポーネントのアクセシビリティを検証してください。WCAG 2.1 AA準拠を確認し、問題があれば修正を提案してください。"
      }
    ]
  }
}

ファイル検証自動化

Agent Hooksを使って、ファイル変更時に自動的にコードレビューを実行する例です。

.claude/agents/code-reviewer.md

あなたはコードレビューの専門エージェントです。

## チェック項目
1. 命名規則の遵守
2. エラーハンドリングの適切性
3. パフォーマンスの問題
4. テスタビリティ
5. DRY原則の遵守

## 出力形式
- 問題の重要度: Critical / Warning / Info
- 該当箇所: ファイル名と行番号
- 修正提案: 具体的なコード例

✅ Tip

Agent Hooksは最もコストが高いハンドラータイプです。頻繁に発火するイベント（PostWrite等）に設定する場合は、matcherを厳密に設定して発火頻度を制限してください。

Hooks設計パターン集

実戦で使える5つのHooks設計パターンを紹介します。コピーして自プロジェクトに適用できる形で提供します。

Pattern 1: CI的Hook

セッション開始時にCI/CDパイプラインと同等のチェックを実行し、開発開始前の品質を保証します。

CI的Hookの設定

{
  "hooks": {
    "SessionStart": [
      {
        "command": "npm run lint && npm run type-check && npm run test -- --bail 2>&1 | tail -5"
      }
    ]
  }
}

Pattern 2: 通知Hook

重要なイベント（セッション終了、エラー発生など）をSlackやメールで通知します。

Slack通知Hookの設定

{
  "hooks": {
    "SessionEnd": [
      {
        "type": "http",
        "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
        "method": "POST",
        "body": {
          "text": "Claude Codeセッションが終了しました: $SESSION_SUMMARY"
        }
      }
    ]
  }
}

Pattern 3: 長セッション警告

セッションが一定時間を超えた場合に警告を表示し、/compactの実行を促します。

長セッション警告の設定

{
  "hooks": {
    "PostToolUse": [
      {
        "command": "SESSION_MINS=$((($EPOCHSECONDS - $SESSION_START) / 60)) && [ $SESSION_MINS -gt 30 ] && echo 'WARNING: セッションが30分を超えました。/compactを検討してください。' || true"
      }
    ]
  }
}

Pattern 4: コミット前チェック

Gitコミットの実行前に、テスト通過とlintクリアを確認します。

コミット前チェックの設定

{
  "hooks": {
    "PreBash": [
      {
        "matcher": "git commit",
        "command": "npm run lint -- --quiet && npm run test -- --bail --silent || (echo 'BLOCKED: lint/testが失敗しています。修正してからコミットしてください。' && exit 1)"
      }
    ]
  }
}

Pattern 5: MCP監視

MCPサーバーの呼び出しを監視し、異常なリクエストパターンを検出します。

MCP監視の設定

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__*",
        "command": "echo \"[MCP-LOG] $(date +%H:%M:%S) Tool: $TOOL_NAME\" >> .claude/mcp-access.log"
      }
    ]
  }
}

📝 Note

Hooksの設計は「最小限から始めて必要に応じて追加」が原則です。最初から全パターンを導入すると、パフォーマンスが低下し、デバッグが困難になります。まずは安全系Hooks（Pattern 4のコミット前チェック等）から始めてください。

← 前のページ

上級テクニック集

その他業務