Claude Code の Hooks（フック）機能を使うと、AIがツールを実行するタイミングに合わせて任意のシェルコマンドを自動実行できます。コードの自動フォーマット、危険なコマンドのブロック、Slack通知など、エンジニアの業務フローに深く統合したカスタマイズが可能です。

この記事では、Hooksの仕組みから設定ファイルの書き方、すぐ使える実用例まで徹底解説します。

スポンサーリンク

目次

1. Hooksとは何か
2. フックの種類（5種類）
3. 設定ファイルの書き方
4. マッチャー（対象ツールの絞り込み）
5. すぐ使える実用例7選
6. 終了コードによる動作制御
7. 設定のコツと注意点
8. まとめ

1. Hooksとは何か

Hooks は Claude Code の設定ファイル（settings.json）に記述するイベントドリブンなシェルフック機能です。Claude がファイルを読む・書く・コマンドを実行するといった操作（ツール呼び出し）の「前後」に、指定したシェルコマンドを自動で走らせることができます。

フックは Claude が行う操作に「人間のコードレビュー」を差し込むようなイメージです。AIが何かしようとしたとき・した後に、あなたが書いたスクリプトが割り込んで確認・修正・通知を行えます。

2. フックの種類（5種類）

3. 設定ファイルの書き方

Hooksは settings.json に記述します。設定ファイルの場所は2種類あり、用途によって使い分けます。

基本構造

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

構造の説明

• 最上位キー: フックのタイプ（PreToolUse / PostToolUse / Notification / Stop / SubagentStop）
• matcher: 対象ツール名（正規表現使用可）
• type: 現時点では "command" のみ
• command: 実行するシェルコマンド

環境変数で情報を受け取る

フック実行時、Claude Code は以下の環境変数を自動でセットします。

4. マッチャー（対象ツールの絞り込み）

matcher フィールドには正規表現が使えます。これにより、特定のツールだけにフックを適用できます。

// Write または Edit ツールにのみ適用
"matcher": "Write|Edit"

// Bash ツールにのみ適用
"matcher": "Bash"

// すべてのツールに適用（matcher を省略）
// ※ matcher を省略すると全ツールにマッチ

// ファイル名でさらに絞り込む（コマンド側で条件分岐）
"matcher": "Write"

5. すぐ使える実用例7選

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT_FILE_PATH\" | grep -q '\\.py$'; then mypy \"$CLAUDE_TOOL_INPUT_FILE_PATH\" --ignore-missing-imports; fi"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -qE 'rm\\s+-rf|DROP\\s+TABLE|format\\s+[A-Z]:'; then echo 'BLOCKED: 危険なコマンドが検出されました' >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date '+%Y-%m-%d %H:%M:%S') [${CLAUDE_TOOL_NAME}] ${CLAUDE_TOOL_INPUT_FILE_PATH}\" >> ~/.claude/edit_history.log"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code の作業が完了しました\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT_FILE_PATH\" | grep -qE '\\.(test|spec)\\.(ts|js)$|^src/'; then npm test -- --passWithNoTests 2>&1 | tail -5; fi"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|Read",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT_FILE_PATH\" | grep -qE '\\.env\\.production|config/production'; then echo 'WARNING: 本番設定ファイルへのアクセスを検出しました。意図的ですか？' >&2; fi"
          }
        ]
      }
    ]
  }
}

6. 終了コードによる動作制御

フックのコマンドが返す終了コードによって、Claude Code の動作が変わります。

stderr への出力を活用する

フックのコマンドが stderr（標準エラー出力）に出力した内容は、Claude のコンテキストに渡されます。Claude がそのメッセージを読んで次の行動を判断できるため、単なるブロックより賢い制御が可能です。

# 例：詳細なエラーメッセージを stderr に出力
if [ 条件 ]; then
  echo "理由: 〇〇のため実行できません。代わりに〇〇してください。" >&2
  exit 2
fi

7. 設定のコツと注意点

複数フックは配列で並べる

同じイベントに複数のフックを登録したい場合は、hooks 配列に追加するだけです。上から順番に実行されます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true" },
          { "type": "command", "command": "eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true" }
        ]
      }
    ]
  }
}

フックが遅いと Claude の応答も遅くなる

フックは同期的に実行されるため、重い処理（ビルド全体など）を入れると Claude の応答が著しく遅くなります。フックには軽量なチェックのみを入れ、重い処理はバックグラウンドで走らせることを推奨します。

# NG: ビルド全体をフックに入れる（遅い）
"command": "npm run build"

# OK: バックグラウンドで実行する
"command": "npm run build &"

設定反映はセッション再起動が必要

settings.json を編集したあとは、Claude Code を再起動するか新しいセッションを開始しないと反映されません。

デバッグには echo で確認

フックが期待通り動いているか確認したいときは、一時的に echo でログを出力させて動作確認するのが手軽です。

{
  "type": "command",
  "command": "echo \"HOOK: $CLAUDE_TOOL_NAME が $CLAUDE_TOOL_INPUT_FILE_PATH に実行されました\" >> /tmp/hook_debug.log"
}

Hooksを活用することで、Claude Code は単なる「AIアシスタント」からチームの開発ルールに組み込まれた自動化エンジンへと進化します。まずは自動フォーマットや危険コマンドのブロックから試してみてください。