Claude Code Hooks 設定ガイド｜自動化フックで開発を効率化

Claude Code Hooks とは

Claude Code Hooksは、Claude Codeの各操作の前後に独自のスクリプトやコマンドを自動実行できる仕組みです。たとえば、ファイル編集後に自動でリンターを走らせたり、コマンド実行前にセキュリティチェックを挟んだりできます。

Hooksを活用することで、手動で行っていた作業を自動化し、一貫性のある開発ワークフローを構築できます。Claude Codeの基本的な使い方をすでに理解している方は、Hooksで次のステップに進みましょう。

フックタイプの一覧

Claude Code Hooksには、いくつかのタイプがあります。それぞれのトリガータイミングを理解することが重要です。

PreToolUse

ツール（ファイル編集、コマンド実行など）が実行される前に発火します。バリデーションやセキュリティチェックに最適です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "command": "bash /path/to/pre-edit-check.sh $CLAUDE_FILE_PATH"
      }
    ]
  }
}

PostToolUse

ツールが実行された後に発火します。フォーマッターの実行や通知送信に使えます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Notification

Claude Codeが通知を送るタイミングで発火します。長時間タスクの完了通知をSlackやDiscordに送る用途に便利です。

{
  "hooks": {
    "Notification": [
      {
        "command": "curl -X POST -H 'Content-Type: application/json' -d '{\"text\": \"Claude Code: タスク完了\"}' $SLACK_WEBHOOK_URL"
      }
    ]
  }
}

Stop

Claude Codeがタスクを完了して停止するときに発火します。クリーンアップ処理や最終チェックに使えます。

settings.json での設定方法

Hooksは .claude/settings.json に記述します。プロジェクトルートに配置することで、プロジェクト固有のフックを定義できます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo \"コマンド実行前チェック: $CLAUDE_COMMAND\""
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      },
      {
        "matcher": "Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

matcher の指定方法

matcher にはツール名を指定します。主なツール名は以下のとおりです。

matcher	対象操作
`Edit`	ファイルの編集
`Write`	ファイルの新規作成
`Bash`	シェルコマンドの実行
`Read`	ファイルの読み取り

matcherを省略すると、すべてのツール操作に対してフックが発火します。

実践的なHooks設定例

例1: ファイル編集後に自動フォーマット

最も一般的な使い方です。Claude Codeがファイルを編集するたびに、Prettierで自動フォーマットをかけます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ]
  }
}

2>/dev/null || true を付けることで、Prettierが対応していないファイルでもエラーにならないようにしています。

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

本番環境に影響するコマンドを事前にブロックする例です。

#!/bin/bash
# pre-command-check.sh
BLOCKED_COMMANDS=("rm -rf /" "DROP TABLE" "git push --force")

for blocked in "${BLOCKED_COMMANDS[@]}"; do
  if echo "$CLAUDE_COMMAND" | grep -q "$blocked"; then
    echo "BLOCKED: 危険なコマンドが検出されました: $blocked"
    exit 1
  fi
done

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "bash .claude/scripts/pre-command-check.sh"
      }
    ]
  }
}

例3: テストの自動実行

ソースコードが変更されるたびに、関連するテストを自動実行する設定です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "bash -c 'if [[ $CLAUDE_FILE_PATH == *.ts ]]; then npx vitest run --reporter=verbose 2>&1 | tail -20; fi'"
      }
    ]
  }
}

Hooksのデバッグ方法

フックが期待通りに動かない場合は、以下の手順でデバッグしましょう。

コマンド単体でテスト - フックに設定するコマンドを、まずターミナルで直接実行して動作確認します
環境変数の確認 - echo コマンドで環境変数の中身を出力して確認します
ログ出力を追加 - コマンドの出力をファイルにリダイレクトして記録します

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "echo \"$(date): $CLAUDE_FILE_PATH が編集されました\" >> /tmp/claude-hooks.log"
      }
    ]
  }
}

CLAUDE.md との連携

CLAUDE.mdファイルにHooksの存在を記述しておくと、Claude Codeがフックを考慮した操作を行いやすくなります。

## Hooks
- ファイル編集後にPrettierが自動実行されます
- テストファイル変更時にvitestが自動実行されます

まとめ

Claude Code Hooksは、開発ワークフローを自動化する強力な仕組みです。最初は単純なフォーマッター連携から始めて、徐々にセキュリティチェックやテスト自動実行など高度な設定を追加していくのがおすすめです。

Claude Code APIとの連携と組み合わせれば、CI/CDパイプラインに組み込んだ高度な自動化も実現できます。