Hooks（フック）とは？Claude Codeの自動化フック機能の仕組み・使い方・設定例を徹底解説

Hooks（フック）とは

Hooks（フック）とは、Claude Codeで特定のイベント発生時に自動でシェルコマンドを実行するための仕組みである。具体的には、ツール実行前・実行後・ユーザー入力送信時・会話終了時など、Claude Codeのライフサイクル上に定義されたイベントに紐付けてスクリプトを差し込める機能を指す。プラグインを作らず、~/.claude/settings.json や .claude/settings.json に JSON で設定するだけで導入できる点が特徴で、lint 実行・タイプチェック・Slack 通知・監査ログ記録など、開発ワークフロー上の定型処理を Claude Code の動作に織り込める。

身近な例えで言うと、Hooks は「Claude Codeの動作に挟み込める関所」のようなもの。Claude がコードを編集した直後に自動で prettier を走らせる、 Bash を実行する前にコマンドをチェックして危険なら止める、会話が終わったらコミットログを保存するといった「ちょっとした自動化」を、プラグインやサブエージェントを書かずに実現できるのが Hooks の大きな価値である。2025 年前半に導入されて以来、Anthropic 公式ドキュメントでも重要機能として整備されており、実務の Claude Code ワークフローには欠かせない存在になりつつある。

Hooksの読み方

Hooksの仕組み

Claude Code の Hooks は、公式ドキュメント上で定義された「Hook Event（フックイベント）」と「Matcher（マッチャ）」、そして「Command（コマンド）」の 3 要素から構成されている。Claude Code は内部的にセッションのライフサイクルを細かなイベントに分割しており、ユーザーやツールの操作が発生するたびに対応するイベントを発火する。ここに設定ファイル上で定義したコマンドを差し込める仕組みである。

主なHookイベント

ここがポイントです。Hooks はシェルコマンドを単に呼ぶだけでなく、$CLAUDE_PROJECT_DIR などの環境変数や stdin 経由の JSON で詳細なコンテキストを受け取れる。exit code でブロック・許可・コメント注入を切り替えられるため、単なるフックではなく「Claudeの動作を動的に誘導するゲート」として機能する点が Hooks 固有の強みである。

アーキテクチャ図

JSON入力とJSON出力

フックコマンドは stdin から JSON を受け取り、stdout に JSON を返すことでより高度な制御ができる。具体的には hookSpecificOutput というキーに hookEventName と additionalContext や permissionDecision を含めた JSON を返すと、Claude Code 側がそれを解釈してコンテキスト注入や許可判断に反映する。この仕組みを使うと、たとえば UserPromptSubmit フックで社内規程を毎回コンテキストに追加する、といった高度な介入ができる。

ここで注意しておきたいのは、JSON 出力はスキーマが厳密だということ。フックが壊れた JSON を吐くと Claude Code は警告を出して無視するため、jq や Python でしっかり構造化した出力を作ることが実装上のコツになる。覚えておきたいのは、exit code 単体での制御（0: 許可 / 2: ブロック）と、JSON 出力による詳細制御（permission の粒度、追加コンテキスト注入）を使い分けると、柔軟性と安全性の両立が図れる点である。

フックのスコープと優先順位

Claude Code のフックは 3 種類の設定ファイルで管理される。~/.claude/settings.json（ユーザー共通）、.claude/settings.json（プロジェクト共有）、.claude/settings.local.json（個人ローカル、Git に含めない）がそれぞれ読み込まれ、後者ほど優先度が高い。実務では、プロジェクト共有の設定に標準のリントとガードレールを置き、個人設定では Slack 通知先などを上書きする運用が定番です。

Hooksの使い方・実例

実際に Hooks を設定するには ~/.claude/settings.json（ユーザー設定）または .claude/settings.json（プロジェクト設定）に JSON を書くだけでよい。実務ではプロジェクト設定に入れてチームで共有するケースが多い。下記は Python ファイルの保存時に自動で black を走らせる例である。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && black --quiet ."
          }
        ]
      }
    ]
  }
}

危険コマンドブロックの例

PreToolUse で Bash の引数を検査し、rm -rf や git push –force を検出したら exit code 2 で拒否する、という安全装置をフックで実装できる。覚えておきたいのは、exit code 2 を返すと Claude Code はそのツール実行を止めて理由を Claude に伝えるため、意図した経路で止めたいときに便利な仕組みだという点である。

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
if echo "$CMD" | grep -Eq "rm -rf /|git push --force|:(){"; then
  echo "危険なコマンドを検出したためブロックしました" >&2
  exit 2
fi
exit 0

Slack 通知フック

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST $SLACK_URL -d 'payload={\"text\":\"Claude Code session finished\"}'"
          }
        ]
      }
    ]
  }
}

高度な例: スクリーンショット取得フック

注意しておきたいのは、フックはシンプルなシェル実行に留まらず、Playwright や Puppeteer を呼び出して E2E テストの一部として使うケースも増えている点である。たとえば PostToolUse に組み込んで、コード変更直後にローカルサーバーのスクリーンショットを取得し、画像を監査ログとして残す、といった用途が可能である。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {"type": "command", "command": "npx playwright screenshot http://localhost:3000 audit/$(date +%s).png"}
        ]
      }
    ]
  }
}

環境変数で挙動を分岐させる

フックから $CLAUDE_PROJECT_DIR や $CLAUDE_USER_ID を参照して、ディレクトリやユーザーごとに異なる処理を走らせることもできる。実務では、本番ブランチでは strict モード、開発ブランチではゆるめのルールというように、ブランチ依存の品質ゲートにも活用できる。ここが重要なポイントです。フックを書く際は「機械的に実行するだけ」で終わらせず、環境変数とブランチ情報を組み合わせて意味ある自動化に仕上げる設計を意識すると、Hooks の価値を最大化できます。

Hooksのメリット・デメリット

メリット

• プラグインを作らずに自動化を差し込める。JSON 数行で完結する手軽さが最大の強み
• PreToolUse で危険操作をブロックできるため、エージェント運用のガードレールとして機能する
• exit code と標準出力の組み合わせで Claude にフィードバックを返せるため、Claude の挙動を能動的に誘導できる
• プロジェクト単位・ユーザー単位の両方で設定可能。実務ではチーム共有型が実用的

デメリット

• シェルコマンドを自由に実行できるため、設定ミスでセキュリティホールになり得る
• フックが遅いとセッション全体のレスポンスが悪化する
• イベントタイミングを正しく理解しないとフックが発火しないか意図しない場所で走る
• 環境依存（jq や Python など）に注意しないと他メンバーの端末で動かない

HooksとSubagentの違い

Hooks と Subagent（サブエージェント）はしばしば混同されやすい。実務では役割が明確に異なる。

よくある誤解

誤解1: Hooks は React Hooks と同じ仕組みだ

別物です。React の useState・useEffect などの Hooks はフロントエンドの状態管理のための関数で、Claude Code の Hooks はシェルコマンドの実行機構です。名前は同じ「フック」でも設計思想も用途も異なります。

誤解2: Hooks を書けばプラグインは不要

実務では Hooks とプラグインは併用する設計が多いです。定型の前処理・後処理は Hooks、配布したい機能群は Plugin にまとめる、という使い分けが基本です。

誤解3: Hooks は安全だ

Hooks はシェルコマンドを任意に実行できるため、信頼できる設定ファイルかどうかを常に確認する必要があります。第三者のリポジトリを clone して Claude Code を起動した途端に悪意あるフックが走る、という事故はゼロではありません。

実務での活用シーン

実務では次の 4 つのユースケースが定番になっている。ここが重要なポイントです。Hooks はあくまで「ガードレール」と「自動化」の 2 面を兼ね備えた機能として位置付け、Claude に判断を任せるべき処理は Hooks に書かないようにする運用が望ましい。

• 保存時のフォーマット・リント自動化（Python は black・ruff、JS は prettier・eslint）
• 危険コマンドのブロック（rm -rf、force push、本番 DB への DELETE など）
• セッション終了時の Slack 通知・監査ログ記録
• セッション開始時の環境変数ロード・秘密情報マウント

よくある質問（FAQ）

Q. Hooks はどのプラットフォームで動きますか？

macOS・Linux・Windows（WSL 含む）で動作します。公式ドキュメントではシェルコマンドを前提としているため、Windows ネイティブで使う場合は PowerShell 互換のシンタックスに調整してください。

Q. フックが発火しない場合はどこを見れば良い？

まず claude --debug でイベントログを確認します。次に matcher の正規表現が正しいか、command の終了コードが 0 を返しているかを確認してください。

Q. チーム共有するにはどこに置く？

プロジェクトルートの .claude/settings.json に置き、リポジトリにコミットします。個人用の設定は ~/.claude/settings.json に分ける運用が一般的です。

まとめ

• Hooks は Claude Code のライフサイクルイベントにシェルコマンドを差し込む機能
• PreToolUse・PostToolUse・UserPromptSubmit・Stop など複数イベントに対応
• JSON 数行で導入でき、プラグインより軽量
• リント・フォーマット・監査・通知・ガードレールに幅広く使える
• exit code と標準出力で Claude 本体にフィードバック可能
• Subagent とは役割が異なるため混同しないこと
• シェル実行権限を持つため、第三者製フックの導入時は監査が必要

参考文献・出典