Claude Code Hooks入門｜HTTP対応の設定と自動化レシピ5選

結論: Claude Code Hooksは、CLAUDE.mdやスキルでは「お願い」にとどまる処理を、100%確実に実行する確定的な自動化の仕組みです。2026年夏にHTTP hooks・Agent hooksが加わり、外部連携まで1つの設定ファイルで完結するようになりました。

この記事の要点:

• 31種のイベント×5つのハンドラー型で、セッション開始からファイル変更まで自動化できます（出典: Anthropic公式ドキュメント、参照日: 2026-08-21）
• HTTP hooksで外部サービスへの通知・セキュリティ検査が、コードを書かずに設定だけで動きます（出典: Dickson Tsai氏 X投稿、参照日: 2026-08-21）
• CLAUDE.md→Skills→Hooksの3層を使い分けることで、AI判断と確定処理を分離できます

対象読者: Claude Codeを週に数回以上使っていて、フォーマットの手動実行やルール違反の見逃しを減らしたいエンジニア

読了後にできること: settings.jsonに5つの自動化レシピを設定し、コード整形・危険コマンド防止・外部通知を自分のプロジェクトで動かせます

デュスクではClaude CodeとCodexを併用してAI秘書FRIDAYを運用しており、hooks設定は35個のスキルと組み合わせて日常的に使っています。この記事では公式ドキュメント（2026-08-21参照）を基に、5つのハンドラー型の違いから実践レシピまで整理します。

Claude Codeの基本操作は「Claude Code autoモード完全ガイド」、スキル機能の設計方法は「Agent Skillsの作り方｜5分で始める7つの実践設計ルール」を参照してください。

Hooksの正体 — CLAUDE.mdでは届かない「確実な実行」

Claude Codeを使い込むと、「CLAUDE.mdにルールを書いたのに守られなかった」という場面に遭遇します。CLAUDE.mdはLLMへのプロンプトです。つまり「お願い」であり、モデルが読み飛ばしたり、文脈が長くなって優先度が下がったりする余地が残ります。

Hooksはこの問題を構造で解決します。

CLAUDE.mdとHooksは何が違うのか

CLAUDE.mdに「ファイルを編集したらPrettierを実行して」と書いても、モデルが忘れることがあります。一方、HooksはClaude Codeのライフサイクル上の特定タイミングで必ず発火するシェルコマンドやHTTPリクエストです。LLMの判断を経由しないため、設定すれば100%実行されるという確定性があります。

整理すると、CLAUDE.mdは「こう振る舞ってほしい」という期待の表明、Hooksは「このタイミングでこの処理を実行する」という確定的なトリガーです。

設定ファイルは3つの場所に置ける

Hooksの設定はJSON形式で、3つのファイルに書けます（出典: Anthropic公式ドキュメント、参照日: 2026-08-21）。

このほかに、マネージドポリシー（組織全体）、プラグインのhooks/hooks.json、スキルやサブエージェントのfrontmatterにも書けます。最初は上の3つだけ覚えれば十分です。

設定の基本構造

Hooksの設定は3階層で構成されます。「いつ（イベント名）→ 何に対して（matcher）→ 何をする（hooks配列）」の順番です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Bashツールが呼ばれます'"
          }
        ]
      }
    ]
  }
}

この例では、Bashツールが実行される直前に、シェルコマンドが走ります。matcherに"Bash"と指定しているので、EditやWriteでは発火しません。

31種のイベント — 発火タイミングの早見表

Hooksを設定するとき、最初に選ぶのは「いつ発火するか」です。2026年8月時点で31種のイベントが定義されています（出典: Anthropic公式ドキュメント、参照日: 2026-08-21）。

イベント一覧

実務でよく使う6つのイベント

31種すべてを覚える必要はありません。実務で頻繁に使うのは次の6つです。

PreToolUse — ツール呼び出しの直前に発火し、危険なコマンドのブロックや機密ファイルの保護に使えます。exit code 2を返すとツール実行が止まる仕組みです。

PostToolUse — ツール実行の直後に発火するイベントで、フォーマッターの自動実行やテストの自動実行に向いています。

Stop — エージェントの応答完了をトリガーに発火し、作業完了通知をSlackやメールへ送る用途に適しています。

SessionStart — セッション開始時に1度だけ走るため、環境変数のチェックやツールのバージョン確認を挟むのに便利です。

FileChanged — ファイルの変更を検知して発火します。Claude Code自身の編集だけでなく、外部エディタからの変更も対象に含まれるのが特徴です。

UserPromptSubmit — ユーザーがプロンプトを送った直後に発火し、入力のバリデーションやログ記録を差し込めます。

matcherの書き方

matcherは「どのツールに対して発火するか」を指定するフィルターです（出典: Anthropic公式ドキュメント、参照日: 2026-08-21）。

注意: matcherは大文字小文字を区別するため、"Bash"が正しく、"bash"ではマッチしません。詳しくは後述の「落とし穴」セクションで扱います。

5つのハンドラー型 — command・HTTP・MCP・prompt・agent

イベントとmatcherで「いつ・何に対して」を決めたら、次は「何をするか」です。2026年8月時点で5つのハンドラー型が用意されています（出典: Anthropic公式ドキュメント、参照日: 2026-08-21）。

ハンドラー型の比較

command型 — 最も基本のハンドラー

command型はシェルコマンドを実行します。stdinでJSON形式のイベント情報を受け取り、stdoutでJSON形式の結果を返せます。フォーマッターやテストランナーなど、既存のCLIツールをそのまま呼び出せるのが強みです。

{
  "type": "command",
  "command": "npx prettier --write $CC_TOOL_ARG_FILE_PATH",
  "timeout": 30
}

Claude Codeは実行時に環境変数をセットします。$CC_TOOL_ARG_FILE_PATHにはツールが操作したファイルパスが入るため、Prettierの対象ファイルを動的に指定できます。

http型 — 外部サービスとの連携

http型は2026年夏に追加されたハンドラーです（出典: Dickson Tsai氏 X投稿、参照日: 2026-08-21）。HTTP POSTリクエストでJSON本文を外部サービスに送信します。Slackへの通知、セキュリティスキャナーへの問い合わせ、ログ集約サービスへの記録など、シェルスクリプトを書かずに外部連携ができるのが利点です。

{
  "type": "http",
  "url": "https://hooks.slack.com/services/T.../B.../xxx",
  "headers": {
    "Authorization": "Bearer $SLACK_TOKEN"
  },
  "allowedEnvVars": ["SLACK_TOKEN"],
  "timeout": 30
}

http型で押さえるべきポイントは3つです。

allowedEnvVarsが必須: ヘッダーやURLに環境変数を使う場合、allowedEnvVars配列に変数名を列挙しなければ空文字に置換されてしまいます。この漏れがあると認証が通らず、原因の切り分けに無駄な時間を費やしがちです。

レスポンスの扱い: 2xxなら成功で、レスポンスボディにJSONがあれば解析されます。非2xxは非ブロッキングエラーとして扱われ、処理は継続。接続失敗も同様に非ブロッキングなので、外部サービスが落ちていてもClaude Code側の作業が止まることはありません。

ヘッダーの環境変数展開: "Authorization": "Bearer $SLACK_TOKEN"のように、ヘッダーの値に$変数名を書くと自動的に展開されます。ただしallowedEnvVarsへの登録が前提であり、登録なしでは空文字に置き換わる点に注意してください。

mcp_tool型 — MCPサーバーとの直接連携

mcp_tool型は、接続中のMCPサーバーのツールをhookから直接呼び出します。MCPでデータベースやナレッジベースに接続している場合、hookの中からそのツールを使って更新やクエリを実行できます。

{
  "type": "mcp_tool",
  "server": "my-mcp-server",
  "tool": "update_record",
  "arguments": {
    "table": "audit_log",
    "data": "{\"event\": \"tool_used\"}"
  }
}

prompt型 — AIに1ターンだけ判断させる

prompt型はClaudeモデルに1ターンの評価を依頼します。安全性の判定やコンテンツの分類など、ルールベースでは書きにくい判断をhookの中で使いたいときに有効です。タイムアウトの既定値が30秒と短い点に注意してください。

{
  "type": "prompt",
  "prompt": "このコード変更にセキュリティ上の懸念があるか1文で判定してください"
}

agent型 — サブエージェントで複雑な検証を実行する

agent型はサブエージェントを起動して、ファイルを横断した条件確認や複雑な検証を行います。実験的な機能であり、タイムアウト既定値は60秒です。安定性の確認が取れるまでは、本番環境での利用は慎重に判断してください。

{
  "type": "agent",
  "prompt": "変更されたファイルに関連するテストファイルが存在するか確認してください",
  "timeout": 120
}

自動化レシピ5選 — settings.jsonにコピペで始める

ここからは、すぐに使える5つのレシピを紹介します。すべて.claude/settings.jsonにコピペして使える形式です。複数のレシピを使う場合は、同じイベント名の配列にオブジェクトを追加してください。

レシピ1: ファイル編集後にPrettierを自動実行する

EditやWriteでファイルが変更されたら、自動的にPrettierを実行します。「フォーマットし忘れた」がゼロになるレシピです。

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

ポイント: 2>/dev/null || trueを付けることで、Prettierが対応していないファイル形式でもエラーにならず処理が続行します。環境変数$CC_TOOL_ARG_FILE_PATHに編集対象のファイルパスが自動で入ります。

レシピ2: rm -rf や git push --force をブロックする

破壊的なコマンドの実行を事前にブロックするレシピです。CLAUDE.mdに「やらないで」と書くだけでは不安な操作を、exit code 2で確実に止められます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CC_TOOL_ARG_COMMAND\" | grep -qE 'rm\\s+-rf|git\\s+push\\s+--force|git\\s+reset\\s+--hard|git\\s+clean\\s+-f'; then echo '{\"decision\": \"block\", \"reason\": \"破壊的コマンドはブロックされました\"}'; exit 2; fi",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

ポイント: PreToolUseイベントでexit code 2を返すと、そのツール呼び出し自体がブロックされる仕組みです。exit code 1は非ブロッキングエラー（処理続行）のため、ブロック目的なら必ず2を指定してください。

レシピ3: .envやcredentialsを編集から保護する

機密情報が入ったファイルをClaude Codeが編集できないようにするレシピです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CC_TOOL_ARG_FILE_PATH\" | grep -qE '\\.env$|\\.env\\.|credentials|secrets|.*\\.pem$|.*\\.key$'; then echo '{\"decision\": \"block\", \"reason\": \"機密ファイルの編集はブロックされました\"}'; exit 2; fi",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

ポイント: matcherを"Edit|Write"にすることで、EditツールとWriteツールの両方をカバーします。Readツールでの読み取りはブロックしないため、参照だけなら可能です。保護対象のパターンは自分のプロジェクトに合わせて追加してください。

レシピ4: HTTP hooksでSlackへ作業完了通知を送る

エージェントの応答が完了したタイミングで、SlackにHTTP POSTで通知を送ります。長時間の作業を任せて別の仕事をしているときに便利です。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.slack.com/services/T.../B.../xxx",
            "headers": {
              "Content-Type": "application/json"
            },
            "timeout": 10
          }
        ]
      }
    ]
  }
}

ポイント: Slack Incoming Webhooksを使う場合、認証ヘッダーは不要です（URLにトークンが含まれるため）。API経由で送る場合はAuthorizationヘッダーとallowedEnvVarsを追加してください。Stopイベントのmatcherは空文字で全マッチにしています。

レシピ5: コード変更後にテストを自動実行する

ファイルが編集されたら、対象ファイルに関連するテストを自動実行します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CC_TOOL_ARG_FILE_PATH\" | grep -qE '\\.(js|ts|jsx|tsx)$'; then cd \"$(git rev-parse --show-toplevel)\" && npx jest --findRelatedTests \"$CC_TOOL_ARG_FILE_PATH\" --passWithNoTests 2>&1 | tail -5; fi",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

ポイント: --findRelatedTestsオプションで変更されたファイルに関連するテストだけを実行します。全テストを回すと時間がかかるため、影響範囲を絞るのがコツです。--passWithNoTestsを付けると、テストファイルが見つからない場合でもエラーになりません。タイムアウトは120秒に設定していますが、プロジェクトのテスト規模に応じて調整してください。

CLAUDE.md・Skills・Hooks — 3つの仕組みをどう使い分けるか

Claude Codeには、AIの振る舞いを制御する仕組みが3つあります。それぞれ得意な領域が異なるため、適切に使い分けることで「AIの判断に委ねる部分」と「確実に実行させる部分」を分離できます。

使い分けの判断表

判断の原則

迷ったときは次の1文で判断できます。**「AIの判断が必要な処理はCLAUDE.mdかSkills、確実に実行したい処理はHooks」**です。

CLAUDE.mdは「常に守ってほしいルール」を置く場所で、命名規則やコーディングスタイルなどAIが文脈を理解して判断に反映する内容に向いています。ただしLLMへのプロンプトである以上、100%の遵守は保証されない点に注意が必要です。

Skillsは「特定の仕事の進め方」を定義する仕組みです。手順の順序、参照すべきドキュメント、出力形式など1つの業務フローをまとめるのに適しており、AIが判断しながら手順を進めるため柔軟な対応ができます。

Hooksは「特定のタイミングで必ず実行する処理」であり、LLMの判断を経由しません。確定的に動作するのが最大の強みで、フォーマット、ブロック、通知、ログ記録など例外なく走らせたい処理の受け皿です。

組み合わせの具体例

実際には、3つを組み合わせて使うのが効果的です。

想定シナリオ: チームでTypeScriptプロジェクトを開発している場合

1. CLAUDE.mdに「TypeScriptの命名はcamelCaseで統一。型定義はinterfaceを優先」と書く
2. Skillsに「新しいAPIエンドポイントを作るときの手順（ルーティング→バリデーション→テスト→ドキュメント更新）」を定義する
3. Hooksに「ファイル編集後にPrettier実行」「rm -rfのブロック」「テスト自動実行」を設定する

こうすることで、命名やコーディングの判断はAIに任せつつ、フォーマットとテストは人間が確認しなくても必ず実行される状態を作れます。

設定でつまずく4つの落とし穴と直し方

Hooksの設定でよくあるミスを4つ紹介します。いずれも設定上のミスであり、ドキュメントを見れば防げるものですが、実際にはハマりやすいポイントです。

落とし穴1: exit codeの使い分けを間違える

PreToolUseでツール呼び出しをブロックしたいのに、exit code 1を返してしまうケースです。

直し方: ブロックしたいならexit 2を使います。exit 1は「エラーは出たが止めるほどではない」という扱いになり、ツール実行は止まりません。シェルスクリプトの慣習でexit 1をエラーに使いがちですが、Hooksでは2がブロックと覚えてください。

落とし穴2: matcherの大文字小文字を間違える

matcherは大文字小文字を区別します。"bash"と書いてもBashツールにはマッチしません。

直し方: ツール名は先頭が大文字です。"Bash"、"Edit"、"Write"、"Read"のように正確に書いてください。MCPツールの場合は"mcp__サーバー名__ツール名"の形式で、すべて小文字になることが多いですが、MCPサーバーの定義に依存します。

落とし穴3: asyncフラグを誤って使う

hookに"async": trueを設定すると、hookの完了を待たずに処理が続行されます。これは通知やログ記録には便利ですが、ブロック判定ができなくなるという副作用があります。

直し方: ツール呼び出しのブロック（exit 2）を使いたいhookでは、asyncを設定しない（既定はfalse）か、"async": falseを明記します。通知やログなど結果を待つ必要がないhookだけに"async": trueを使ってください。

落とし穴4: HTTP hooksのallowedEnvVars漏れ

http型のhookでヘッダーに$MY_TOKENと書いたのに、allowedEnvVarsに"MY_TOKEN"を入れ忘れると、トークンが空文字に置換されます。認証が通らず、「URLは合っているのに403が返る」という状態になります。

直し方: http型で環境変数を使うときは、必ずallowedEnvVars配列に変数名を列挙します。

{
  "type": "http",
  "url": "http://localhost:8080/hooks/event",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

このallowedEnvVarsはセキュリティ上の設計です。明示的にリストに入れた変数だけが展開されることで、意図しない環境変数の漏洩を防いでいます。

1日で導入する3ステップ

「全部理解してから始めよう」とすると手が止まります。まずは1つだけ設定して体感するのがおすすめです。

ステップ1: Prettier自動実行を1つだけ入れる

プロジェクトの.claude/settings.jsonに、レシピ1（ファイル編集後にPrettier自動実行）を追加します。これだけで、Claude Codeがファイルを編集するたびにフォーマットが自動で整うようになります。

確認方法は単純です。Claude Codeにファイルを編集させた後、git diffでフォーマットの差分が出ないことを確認します。出なければ、hookが正しく動いています。

プロジェクトにPrettierが入っていない場合は、eslint --fixやお使いのフォーマッターのコマンドに置き換えてください。フォーマッターを使っていないプロジェクトなら、レシピ2（危険コマンドブロック）から始めるのも手です。

ステップ2: 危険コマンドブロックを追加する

初日のPrettier hookが問題なく動くことを確認したら、レシピ2（rm -rfやgit push --forceのブロック）を追加します。

これは個人設定（~/.claude/settings.json）に入れるのがおすすめです。どのプロジェクトでも破壊的コマンドを一律ブロックできる汎用ルールだからです。追加後、Claude Codeにrm -rf /tmp/testを実行させてみて、ブロックされることを確認してください。

ステップ3: 安定したらHTTP hooksで外部通知を試す

command型のhookが安定して動くようになったら、HTTP hooksに進みます。Slack Incoming Webhooksを使えば、Slack側の設定が5分、hook側の設定がレシピ4のコピペで完了します。

長時間のリファクタリングやテスト実行を任せている間に、完了通知がSlackに届くのは想像以上に便利です。ここまで来れば、prompt型やagent型など高度なハンドラーにも無理なく進めます。

次に読むなら: CLAUDE.mdの書き方とプロジェクト全体の設定を整理したい方は「Claude Code autoモード完全ガイド」、スキルの設計方法を知りたい方は「Agent Skillsの作り方｜5分で始める7つの実践設計ルール」を参照してください。

参考・出典

• Claude Code Hooks — Anthropic公式ドキュメント（https://code.claude.com/docs/en/hooks）（参照日: 2026-08-21）
• Claude Code Hooks入門ガイド — Anthropic公式（https://code.claude.com/docs/en/hooks-guide）（参照日: 2026-08-21）
• Dickson Tsai（Anthropicエンジニア）HTTP hooks告知 — X投稿（https://x.com/dickson_tsai/status/2029235808235078095）（参照日: 2026-08-21）
• Claude Code Hooksとは？全30種イベントの設定方法と実践活用例 — JAPAN AI ラボ（https://japan-ai.co.jp/media/7458/）（参照日: 2026-08-21）