AIエージェント

Claude Code Hooksとは？設定方法・活用事例・主要イベントを徹底解説

Claude Codeを使ったAI開発で、「フォーマッターを毎回手動で実行するのが面倒」「危険なコマンドをうっかり承認してしまった」「タスク完了の通知が来なくて放置していた」といった経験はないでしょうか。

こうした課題を根本から解決するのが、Claude Code Hooksという機能です。Hooksは、Claude Codeのライフサイクル上の特定タイミングで、あらかじめ設定したシェルコマンドやスクリプトを自動実行できる仕組みです。プロンプトでの「お願い」とは異なり、設定した処理は確実に実行されるため、開発ワークフローの品質と安全性を大きく向上させます。

この記事では、Claude Code Hooksの基本的な仕組みから、settings.jsonへの設定方法、主要なライフサイクルイベントの種類、実務で使える活用事例、チーム開発での運用ポイントまで、体系的に解説していきます。

確認したいポイント	結論	詳細
Claude Code Hooksとは？	ライフサイクルに処理を差し込む自動化機能	特定のタイミングでシェルコマンドやスクリプトを自動実行し、プロンプトに依存しない確定的な制御を実現する
設定方法はどうすればいい？	settings.jsonにJSON形式で記述する	グローバル・プロジェクト・ローカルの3階層があり、用途に応じてスコープを使い分けられる
主要なイベントは何がある？	PreToolUse・PostToolUseなど20種類以上	ツール実行前後のほか、セッション開始・終了、通知、コンテキスト圧縮前後など多彩なイベントが用意されている
どんな場面で活用できる？	自動整形・ブロック・通知・ログ記録など	コードの自動フォーマットや危険コマンドの遮断、作業完了時のデスクトップ通知など日常開発の効率化に直結する

この記事でわかること
・Claude Code Hooksの基本概念と、プロンプト指示との決定的な違い
・settings.jsonへの具体的な設定手順と3つのスコープの使い分け
・PreToolUse・PostToolUseなど主要ライフサイクルイベントの種類と役割
・自動フォーマットや危険コマンドブロックなど、実務で即使える活用事例5選
・チーム開発でのHooks共有方法とセキュリティ上の注意点

AIエージェントの導入事例や、PoCから本番化までの進め方をまとめた資料を無料でダウンロードいただけます。Claude Codeの活用を検討されている方は、ぜひご覧ください。
▶ 資料請求フォームはこちら

Claude Code Hooksとは？基本の仕組みを理解する

Claude Code Hooksは、Claude Codeの動作中に発生する特定のイベントに対して、ユーザーが定義したコマンドやスクリプトを自動で実行できる仕組みです。Anthropic社が提供するClaude Codeの公式機能として実装されており、2026年7月時点で20種類以上のライフサイクルイベントに対応しています。

たとえば「Claudeがファイルを編集したら自動でフォーマッターを実行する」「rm -rfのような危険なコマンドをブロックする」「タスクが終わったらデスクトップ通知を送る」といった処理を、設定ファイルに記述するだけで実現できます。

Hooksが解決する課題：プロンプト指示の限界

Claude Codeにプロンプトで「フォーマッターを実行してください」「.envファイルは触らないでください」と指示する方法は、あくまでLLMへの「お願い」に過ぎません。LLMは確率的に動作するため、指示を忘れたり、長いタスクの途中で優先度が下がったりすることがあります。

一方、Hooksは「仕組み」として処理を保証します。設定ファイルに書かれたコマンドはイベント発生時に必ず実行され、LLMの判断に依存しません。ある開発者が表現したように、「プロンプトはリクエスト、Hooksはギャランティー（保証）」という違いがあります。

この「確率的な制御」と「決定論的な制御」の違いこそが、Hooksの最大の価値です。特に本番環境のコードベースや、コンプライアンス要件のある開発プロジェクトでは、「たぶん守られる」ではなく「必ず守られる」ことが求められるため、Hooksの導入が強く推奨されます。

Hooksの基本構造：イベント・マッチャー・ハンドラー

Hooksの設定は、3つの要素で構成されます。

1つ目は「イベント（Event）」です。これは「いつフックを発火させるか」を定義します。たとえばPreToolUseはツール実行の直前、PostToolUseはツール実行後、SessionStartはセッション開始時にそれぞれ発火します。

2つ目は「マッチャー（Matcher）」です。イベントの中でも、どの条件に一致した場合にフックを実行するかを絞り込む役割を果たします。たとえばPreToolUseイベントにmatcher: “Bash”と指定すれば、Bashツールの実行時だけフックが動作し、ファイル読み取りなど他のツール実行時には反応しません。

3つ目は「ハンドラー（Handler）」です。「何を実行するか」を定義する部分で、シェルコマンドの実行（command）、HTTPリクエストの送信（http）、LLMによる判断（prompt）、サブエージェントによる検証（agent）の4種類から選択できます。多くの場合はcommandタイプを使用します。

これら3要素を組み合わせた設定は、JSON形式でsettings.jsonに記述します。以下は基本的な構造の例です。

{“hooks”: {“PostToolUse”: [{“matcher”: “Edit|Write”, “hooks”: [{“type”: “command”, “command”: “npx prettier –write $CLAUDE_FILE_PATH”}]}]}}

この例では、PostToolUseイベント（ツール実行後）のうち、EditまたはWriteツールが使われたときだけ、Prettierによるコード整形を自動実行する設定です。マッチャーに「Edit|Write」と記述することで、対象ツールを絞り込んでいます。

Claude Code Hooksの設定方法と配置場所

Hooksの設定は、JSONファイルに記述する方式を採用しています。設定ファイルの配置場所によってHooksの適用範囲（スコープ）が変わるため、個人利用とチーム利用で適切に使い分けることが重要です。

settings.jsonの3つのスコープ（グローバル・プロジェクト・ローカル）

Hooksの設定ファイルは、3つの階層に分かれています。

まずグローバル設定（~/.claude/settings.json）は、ユーザーのすべてのプロジェクトに共通で適用されます。デスクトップ通知やBashコマンドのログ記録など、プロジェクトに依存しない汎用的なフックはここに配置します。

次にプロジェクト設定（.claude/settings.json）は、特定のプロジェクトのリポジトリルートに配置する設定です。Gitにコミットすることでチーム全員に同じHooksを適用でき、コードフォーマッターの自動実行や保護ファイルの編集ブロックなど、プロジェクト固有のルールを共有するのに適しています。

最後にローカル設定（.claude/settings.local.json）は、プロジェクト単位の個人設定です。Claude Codeが生成時に自動でgitignoreするため、個人的な通知音の設定やデバッグ用フックなど、チームに共有する必要がない設定に使います。

これら3つの設定は共存でき、同じイベントに対して複数のフックが登録されている場合はすべてが並列に実行されます。もし複数のPreToolUseフックが異なる判定（allowとdeny）を返した場合は、最も厳しい判定が優先されます。

/hooksメニューと設定の確認・デバッグ方法

設定したHooksが正しく登録されているかを確認するには、Claude Codeのセッション内で「/hooks」コマンドを実行します。このコマンドで、すべてのイベントに紐づけられたフック一覧が表示され、各フックの設定内容（イベント名、マッチャー、コマンド、設定元ファイル）を確認できます。

なお、/hooksメニューは読み取り専用です。フックの追加・変更・削除を行うには、settings.jsonファイルを直接編集するか、Claude Codeに「通知フックを追加して」と依頼してください。Claude Code自身がフックを生成して設定に書き込んでくれます。

デバッグ時には、「claude –debug-file /tmp/claude.log」でClaude Codeを起動すると、フックの実行結果（exit code、stdout、stderr）がログファイルに記録されます。別のターミナルでtail -f /tmp/claude.logを実行すれば、リアルタイムにフックの動作を確認できます。セッション途中からデバッグを開始したい場合は、「/debug」コマンドでログ出力を有効化することも可能です。

Claude Code Hooksの導入やAIエージェントを活用した開発体制の構築について、専門のコンサルタントが無料でご相談を承ります。自社の開発フローに合わせた最適な活用方法を一緒に検討しませんか。
▶ 無料相談フォームはこちら

主要ライフサイクルイベント一覧と使い分け

Claude Code Hooksで利用できるライフサイクルイベントは、2026年7月時点で20種類以上が公式に定義されています。すべてを覚える必要はなく、まずは利用頻度の高い主要イベントを押さえれば、実務上の大半のユースケースに対応できます。

イベントは大きく「ブロック可能なイベント」と「情報系イベント」に分類できます。ブロック可能なイベントは、exit code 2を返すことで処理を中断できるもの（PreToolUse、Stop、UserPromptSubmitなど）です。情報系イベントは、処理を止めることはできないものの、ログ記録や通知送信に活用できるもの（PostToolUse、SessionStart、Notificationなど）を指します。

PreToolUse：ツール実行前のブロック・検証

PreToolUseは、Claude Codeがツール（Bash、Edit、Writeなど）を実行する直前に発火するイベントです。Hooksの中でもっとも利用頻度が高く、セキュリティ制御の中核となるイベントといえます。

最大の特徴は、exit code 2を返すことでツール実行を確実にブロックできる点です。たとえば、rm -rfを含むBashコマンドを検知した場合にexit 2を返せば、そのコマンドはClaude Codeによって実行されず、stderrに書き込んだブロック理由がClaudeへのフィードバックとして渡されます。

マッチャーにはツール名を正規表現で指定でき、「Bash」でBashツールのみ、「Edit|Write」で編集系ツールのみ、「mcp__github__.*」でGitHub連携MCPツールのみ、といった粒度で制御対象を絞り込めます。

PostToolUse：ツール実行後の自動処理

PostToolUseは、ツール実行が成功した直後に発火するイベントです。ファイル編集後の自動フォーマットやリンター実行、テスト自動実行など、「ツールが何かを変更した後のクリーンアップ処理」に最適です。

注意点として、PostToolUseはブロック非対応のイベントです。ツールはすでに実行済みのため、結果を取り消すことはできません。もしツール実行そのものを防ぎたい場合は、PreToolUseを使う必要があります。

PostToolUseのstdoutに書き込んだ内容は、Claudeのコンテキストにフィードバックとして注入されます。たとえば、リンターのエラー結果を返せば、Claudeがそのエラーを認識して自動修正を試みるワークフローも構築できます。

SessionStart・Stop・Notification：セッション管理と通知

SessionStartは、Claude Codeのセッションが開始・再開・クリア・コンパクション後に発火するイベントです。matcherに「startup」「resume」「compact」などを指定することで、発火タイミングを絞り込めます。

SessionStartの重要な用途のひとつが、コンテキストの自動注入です。stdoutに書き込んだ内容はClaudeのコンテキストに挿入されるため、git logの最新コミットやプロジェクト固有のルールを毎回自動で読み込ませることができます。特にコンパクション（コンテキスト圧縮）後の再注入は、重要な指示が失われることを防ぐ効果があります。

Stopイベントは、Claudeが応答を完了した時点で発火します。exit code 2を返すことでClaudeに作業の継続を強制でき、「テストが通るまで終了させない」といったワークフローが実現できます。ただし、無限ループを防ぐため、連続8回のブロック後は自動的にオーバーライドされる上限が設けられています。

Notificationイベントは、Claude Codeが入力待ちや権限確認を必要とするときに発火します。macOSならosascript、Linuxならnotify-send、WindowsならPowerShellのMessageBoxで通知を表示でき、Claude Codeにタスクを任せて別の作業に集中するワークスタイルが可能になります。

実務で使えるHooksの活用事例5選

ここからは、Claude Code Hooksの代表的な活用事例を5つ紹介します。いずれもsettings.jsonに数行のJSONを追加するだけで導入でき、日常の開発ワークフローを大きく改善できるものです。

活用事例①：自動フォーマット（Prettier連携）

もっとも基本的かつ効果の大きい活用事例が、ファイル編集後の自動コードフォーマットです。PostToolUseイベントにmatcher「Edit|Write」を指定し、ハンドラーでPrettierを実行する設定を追加します。

この設定により、ClaudeがTypeScriptやJavaScriptのファイルを編集するたびに、Prettierが自動的にコード整形を行います。手動でのフォーマット実行が不要になるだけでなく、チーム全体でコードスタイルの統一が保証されます。

Go言語のプロジェクトであればgofmt、PythonであればBlackやRuffなど、言語に応じたフォーマッターに差し替えることで同様の自動化が実現できます。コマンド部分を書き換えるだけなので、導入コストは極めて低いといえるでしょう。

活用事例②：危険コマンドのブロック（rm -rf防止など）

PreToolUseイベントとBashマッチャーを組み合わせることで、破壊的なコマンドの実行を事前にブロックできます。たとえば、rm -rf、DROP TABLE、terraform destroyといったコマンドが入力に含まれているかどうかをスクリプトで検査し、該当する場合はexit 2でブロックします。

ブロック時にstderrに理由を書き込めば、その内容がClaudeにフィードバックされます。Claudeは「なぜブロックされたか」を理解したうえで、より安全な代替コマンドを提案してくれます。プロンプトによる「やらないで」という指示では防ぎきれない誤操作を、仕組みとして確実に排除できる点が大きな強みです。

活用事例③：デスクトップ通知の設定

NotificationイベントにOS標準の通知コマンドを設定することで、Claude Codeが入力待ち状態になったときにデスクトップ通知を受け取れます。長時間のタスクをClaude Codeに任せている間に別の作業に集中でき、タスク完了や権限確認の必要性を見逃すリスクがなくなります。

macOSではosascriptコマンド、Linuxではnotify-sendコマンド、WindowsではPowerShellのMessageBoxクラスを使用します。マッチャーを空にすればすべての通知に反応し、「permission_prompt」や「idle_prompt」で特定の通知種別だけに絞ることも可能です。

活用事例④：保護ファイルへの編集防止

PreToolUseイベントのEdit|Writeマッチャーと、外部のシェルスクリプトを組み合わせれば、.envやpackage-lock.json、.gitディレクトリ内のファイルなど、保護対象のファイルへの書き込みを自動的にブロックできます。

スクリプト側では、stdinから受け取ったJSONのtool_input.file_pathを取得し、あらかじめ定義した保護パターン（.env、.git/など）と照合します。パターンに該当した場合はexit 2で終了し、stderrにブロック理由を出力します。Claudeは代替手段を探すよう動作を切り替えるため、開発の流れが完全に止まることはありません。

活用事例⑤：監査ログの自動記録

PostToolUseイベントですべてのツール実行を対象に、コマンド内容・実行時刻・セッションIDなどをJSONL形式でログファイルに追記する運用事例です。金融・医療・会計法務など、監査対応が求められる業界では、「誰が・いつ・どのファイルに・何をしたか」の記録がAIツール業務利用の前提となります。

さらに、httpタイプのフックを活用すれば、ログをSplunkやDatadogなどのSIEM（セキュリティ情報イベント管理）に直接POSTすることも可能です。人間の操作ログとAIエージェントの操作ログを同じ基盤で管理できるため、コンプライアンス体制の構築が大幅に効率化されます。

経済産業省と総務省が公表している「AI事業者ガイドライン」でも、AIシステムの透明性や説明責任の確保が求められており、監査ログの整備はガイドラインへの対応としても有効です。

参考：経済産業省「AI事業者ガイドライン検討会」

4種類のフックタイプと選び方

Claude Code Hooksでは、フックのハンドラーとして4種類のタイプが用意されています。用途に応じて適切なタイプを選択することで、より柔軟なワークフロー自動化が可能になります。

commandタイプ：シェルコマンド実行

もっとも基本的で利用頻度の高いタイプがcommandタイプです。シェルコマンドを直接実行し、stdinでJSON入力を受け取り、stdout/stderrとexit codeで結果を返します。

commandタイプの強みは、既存のシェルスクリプトやCLIツール（jq、prettier、eslintなど）をそのまま活用できる点です。新しいツールの学習コストがほとんどなく、開発者が日常的に使い慣れたツールチェーンをそのままHooksに組み込めます。

exit codeの意味は統一されており、0は「異議なし（通常続行）」、2は「ブロック」、それ以外は「非ブロッキングエラー」として扱われます。2以外の非ゼロexit codeでは処理は停止せず、stderrの1行目が警告通知として表示されます。

prompt・agent・httpタイプの特徴と使い分け

commandタイプ以外の3つのタイプは、それぞれ異なる目的で設計されています。

promptタイプは、LLM（デフォルトではHaiku）に対して単一ターンの評価を依頼するものです。ユーザーが書いたプロンプトとフックの入力データがモデルに送られ、{“ok”: true}または{“ok”: false, “reason”: “…” }の形式で判定結果が返されます。「確定的なルールでは判断できないが、AIの判断を入れたい」場面に適しています。たとえば、Stopイベントで「すべてのタスクが完了しているか」をAIに確認させる、といった使い方があります。

agentタイプは、promptタイプの拡張版です。サブエージェントを生成し、ファイルの読み取りやコマンド実行など複数のツールを使いながら、多段階の検証を行えます。「テストを実行して結果を確認する」「コードベース全体を検索して規約違反がないか確認する」など、複雑な検証が必要な場面で力を発揮します。ただし、agentタイプは2026年7月時点で実験的機能とされており、今後の仕様変更の可能性があります。

httpタイプは、イベントデータをHTTPのPOSTリクエストとして外部のエンドポイントに送信するものです。ローカルのログ収集サービスやクラウドの監視基盤、Slack WebhookなどのAPIに対して、フックの実行結果を直接連携できます。チームの共有監査サーバーにログを集約する用途や、CI/CDパイプラインとの統合に向いています。

使い分けの目安として、確定的なルール判定にはcommand、AIの判断が必要な場面にはpromptまたはagent、外部サービスとの連携にはhttpを選択するのがベストプラクティスです。

チーム運用とセキュリティ上の注意点

Claude Code Hooksは個人利用だけでなく、チーム開発における品質基準の統一やセキュリティ統制にも大きな効果を発揮します。一方で、任意のコマンドを実行できるという強力な機能ゆえに、セキュリティ面での注意も必要です。

チーム開発でのHooks共有と標準化

チーム全員に同一のHooksを適用するには、プロジェクト設定（.claude/settings.json）をGitリポジトリにコミットするのがもっとも効果的です。これにより、新しいメンバーがリポジトリをクローンした時点で、フォーマッターの自動実行や保護ファイルのブロック設定が自動的に適用されます。

個人の環境依存の設定（通知音のカスタマイズやローカルパスを含むスクリプトなど）は.claude/settings.local.jsonに記述し、gitignoreで管理から外すことで、チーム設定との競合を防ぎます。

また、大規模な組織では管理者ポリシー設定（Managed Settings）を使い、組織全体に強制適用するフックを定義できます。管理者が設定したdenyルールはユーザー側で上書きできないため、セキュリティポリシーの確実な運用が可能です。

セキュリティリスクと対策のポイント

Hooksは任意のシェルコマンドを実行できるため、設定ファイルの信頼性管理が極めて重要です。信頼できないリポジトリをクローンした場合、そのリポジトリに含まれる.claude/settings.jsonのフックが自動的に読み込まれるリスクがあります。

対策として、Claude Codeは初回実行時にプロジェクト設定のフックを検知すると承認を求める仕組みになっています。ただし、一度承認したあとに設定が書き換えられるケースもあるため、定期的に/hooksコマンドで登録済みフックの内容を確認する習慣をつけることが推奨されます。

PreToolUseフックのdeny判定は、bypassPermissionsモード（–dangerously-skip-permissions使用時）でも有効に機能します。つまり、ユーザーが権限チェックをスキップしていても、Hooksによる制御は常に最優先で適用されます。これにより、チームのセキュリティポリシーをHooksで定義しておけば、個人の設定変更では回避できないガードレールを構築できます。

反対に、Hooksのallow判定は設定ファイルのdenyルールを上書きできません。「Hooksは制限を厳しくできるが、緩めることはできない」というのが基本原則です。この非対称な設計により、管理者が設定した禁止ルールが確実に維持されます。

まとめ

Claude Code Hooksは、AIコーディングツールの動作に対して確定的な制御を加えるための重要な機能です。プロンプトによる「お願い」ではなく、設定ファイルに書かれたルールとして必ず実行される点が、通常のLLM指示との決定的な違いです。

本記事では、Hooksの基本構造（イベント・マッチャー・ハンドラー）、settings.jsonへの設定方法と3つのスコープ、PreToolUse・PostToolUse・SessionStartなど主要イベントの使い分け、自動フォーマットや危険コマンドブロックなど5つの実践的な活用事例、そして4種類のフックタイプの選び方までを解説しました。

Hooksの導入は、小さなところから始めるのが効果的です。まずはデスクトップ通知やコードフォーマットの自動化など、リスクの低い設定から試してみてください。効果を実感できたら、危険コマンドのブロックや監査ログの記録など、セキュリティ面の強化に段階的に進めていくのがおすすめです。

チーム開発においては、.claude/settings.jsonをリポジトリにコミットしてルールを共有し、品質基準の統一とセキュリティガードレールの確立を目指しましょう。Hooksを適切に活用することで、Claude Codeは「便利だけど制御が難しいAIツール」から「チームの開発基盤として信頼できるエージェント」へと進化します。