Claude Code Hooks実例カタログ — 9つのユースケース別レシピと避けたい落とし穴

要点

Claude CodeのHooksは、ツール呼び出しやセッションのライフサイクルに合わせて任意のシェルコマンドを差し込める機構です。手動で「保存後にprettierを回す」「危険コマンドを止める」といった作業を、Claude Codeの挙動と一体化させて自動化できます。

入門は別記事Claude Code Hooks入門 — 最初のHookを5ステップで動かすで扱ったので、本記事は「実運用で使われている9つのレシピ」を一気に紹介します。各レシピには settings.json の最小例と「使いどころ / 注意点」を添えます。

Hooksの全体像(おさらい)

Hooksは ~/.claude/settings.json または <project>/.claude/settings.json の hooks キーに登録します。event名 → 配列 → 各要素にマッチャとcommandという構造です。

各hookの command には標準入力経由でイベントのJSONが流し込まれるので、jq で必要な値を抜き出して使う形が定型です。

9つの実例レシピ

レシピ1: Markdown保存後に日本語スペースを自動正規化(本サイトで運用中)

執筆ワークフローで、Claude Codeが media/content/*.mdx を編集したら、保存直後に正規化スクリプトを走らせる例です。本サイトでは実際にこれを media/.claude/settings.json に登録して運用しています。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path // empty' | (read p; case \"$p\" in *media/content/*.mdx) cd \"$(git rev-parse --show-toplevel)/media\" && npx --no-install tsx scripts/normalize-ja-spaces.ts \"${p#*/media/}\" --apply 1>&2 ;; esac)"
          }
        ]
      }
    ]
  }
}

使いどころ: 編集対象が決まったパスにあるとき、編集の度にチェックを入れたい場合。

注意点: matcher で対象ツールを絞らないと、BashやReadの度に発火して遅くなる。

レシピ2: コードファイル保存後にPrettierを走らせる

定番のフォーマット自動化です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path // empty' | (read p; case \"$p\" in *.ts|*.tsx|*.js|*.jsx|*.json) npx --no-install prettier --write \"$p\" 1>&2 ;; esac)"
          }
        ]
      }
    ]
  }
}

使いどころ: チームのprettier設定を保存毎に当てたい場合。eslint --fix でも同じ要領。

注意点: npx --no-install を付けないと、毎回キャッシュ確認の通信が走り、遅延の原因になる。

レシピ3: 危険なBashコマンドを実行前にブロック(PreToolUse)

rm -rf / や chmod 777 のような破壊的コマンドを、実行前に止めるパターン。PreToolUse でexit codeを2にするとClaude Codeはそのtool呼び出しを失敗扱いにします。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command // empty' | grep -qE 'rm[[:space:]]+-rf[[:space:]]+/|chmod[[:space:]]+777|:\\(\\)' && { echo 'Blocked: dangerous command' >&2; exit 2; } || true"
          }
        ]
      }
    ]
  }
}

使いどころ: 共有環境 / 本番接続環境でClaude Codeを動かす場合の最終防御。

注意点: ブラックリスト方式はバイパスされやすい。本気で守るならコンテナ化 / sandbox / 権限絞り込みを併用する。

レシピ4: テスト自動実行(PostToolUse → npm test)

実装ファイルを編集した直後に関連テストを走らせて、壊れていないか即座に確認します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path // empty' | grep -qE '\\.(ts|tsx|js)$' && (cd $(git rev-parse --show-toplevel) && npm test -- --silent --bail --findRelatedTests 2>&1 | tail -20) || true"
          }
        ]
      }
    ]
  }
}

使いどころ: 試行錯誤フェーズで「リグレッションを早期に拾いたい」とき。

注意点: テストスイートが重い場合、毎回フルテストを走らせると体感が悪くなる。--findRelatedTests 等で範囲を絞る。

レシピ5: サブエージェント完了でmacOS通知(SubagentStop)

長時間の調査タスクをサブエージェントに任せて他作業をしているとき、完了したらOS通知で知らせる構成。

{
  "hooks": {
    "SubagentStop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"サブエージェント完了\" with title \"Claude Code\"' 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

使いどころ: Exploreやgeneral-purposeをバックグラウンドで走らせる運用。Linuxなら notify-send、Windowsなら powershell -c New-BurntToastNotification。

注意点: 通知が頻発すると逆効果。マッチャやsubagent_typeで絞ると良い。

レシピ6: セッション開始時にプロジェクトコンテキストを注入(SessionStart)

毎回特定のドキュメントを読み込ませたい場合、SessionStart で出力を標準出力に流すと、それが追加コンテキストとして取り込まれます。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "cat $(git rev-parse --show-toplevel)/docs/current-sprint.md 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

使いどころ: スプリント目標 / 直近の障害メモなど、毎回最初に伝えたい一時情報がある場合。CLAUDE.mdは固定情報用。

注意点: 大きなファイルを毎回読むとコンテキストを食う。100〜500行程度に絞る。

レシピ7: ユーザープロンプトの記録(UserPromptSubmit)

ユーザーが投げたプロンプトを別ファイルに追記して、後で「あの時何を頼んだか」を辿れるようにします。

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.timestamp): \\(.prompt | .[0:200])\"' >> ~/.claude/prompt-log.txt"
          }
        ]
      }
    ]
  }
}

使いどころ: 振り返り / 学習用ログ。プロンプト改善の材料に。

注意点: 機密プロンプトを含む場合は保管場所のアクセス権を絞る。クラウドsync対象から除外する。

レシピ8: コンテキスト圧縮直前のスナップショット(PreCompact)

長時間セッションでcontextが圧縮される直前に、現状のコンテキストをファイル化しておく安全網。

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "mkdir -p ~/.claude/snapshots && jq '.' > \"$HOME/.claude/snapshots/$(date +%Y%m%d-%H%M%S).json\""
          }
        ]
      }
    ]
  }
}

使いどころ: 大きなリファクタや調査の途中でcontextが圧縮されると失われる情報がある場合の保険。

注意点: スナップショットファイルが溜まるので、定期的にクリーンアップする運用が必要。

レシピ9: 機微ファイル編集の警告(PostToolUse)

.env や認証情報ファイルへの編集を検出して、目視確認を促す警告を出します(ブロックではなく注意喚起)。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path // empty' | grep -qE '\\.env$|credentials|secrets' && echo '⚠️ 機微ファイルが編集されました。コミット前に内容を確認してください。' >&2 || true"
          }
        ]
      }
    ]
  }
}

使いどころ: 認証情報や環境変数ファイルへの誤コミットを防ぐ最終チェック。

注意点: あくまで警告。誤ってpushされたらgitの履歴から消す手間は別途必要。

避けたいアンチパターン

アンチ1: 毎回フルビルドを走らせる

PostToolUse に重い処理(フルビルド / 全テスト)を仕込むと、Claude Codeの応答が常に遅くなります。1ファイル編集で30秒待つような構成は、対話のテンポを崩します。重い処理は SessionEnd や Stop イベント、もしくは別CLIで手動起動する形に分離します。

アンチ2: hook内で標準出力に大量に書く

PostToolUse の標準出力はClaudeのコンテキストに取り込まれるため、ログを大量に流すとcontextが汚染されます。デバッグ目的なら 1>&2 でstderrに流し、contextには残さないのが原則です。

アンチ3: matcherを "*" に広げる

PreToolUse を全toolに対して走らせると、Read / Grep / LSの度に発火して対話が体感で遅くなる典型例です。Bash や Write といった「副作用のあるtool」にmatcherを絞るのが定石です。

著者の運用方針

実運用で使い始めてから感じた指針は次の3点です。

1. hookはゼロから増やす: settings.json に最初は何も書かず、「このタスクを毎回手で打つのが嫌だな」と感じた時点で1つだけ追加する。先に網羅しようとするとdebug地獄になる
2. stderrで会話、stdoutでコンテキスト: コンテキストに流したい情報のみstdoutに出す。それ以外は 1>&2 でstderrに閉じ込める
3. hookの中で git rev-parse --show-toplevel を起点にする: cwdは呼び出しごとに変わりうるので、絶対パスではなくリポジトリルート相対で書くと移植性が上がる

まとめ

Hooksは手動で繰り返している作業をClaude Codeに組み込む強力な機構ですが、書きすぎると応答性が落ちる性質も持ちます。本記事の9レシピは「実運用で効きが大きく、副作用が少ない」観点で選びました。アンチパターン3つを避けつつ、自分の作業フローで「毎回やっている地味な仕事」を1つずつ自動化していくのが現実的な始め方です。

関連:Claude Code Routines完全実践ガイドとMemory 3層モデルを読むと、Hooksを置く運用ポリシーを決めやすくなります。