Claude Code Hooksとは？仕組みと設定・おすすめの3つを徹底解説
Claude CodeにCLAUDE.mdでルールを書いたのに、AIが守らないことがある。あるいは、危険なコマンドを勝手に実行しないか不安で、確認を任せきれない。解決策になるのが、公式機能のHooks(フック)です。設定は少し技術的ですが、押さえるべき勘所は多くありません。
この記事では、Claude Code Hooksの仕組み・使えるイベントの一覧・設定方法・まず入れるべきおすすめの3つを網羅的に解説します。技術者でない導入判断者にも伝わるよう、Hooksが何を保証してくれるのかから始めます。読み終えるころには、自分の環境やチームに必要なフックを組めるはずです。結論から言うと、Hooksは「お願い」ではなく「必ず実行される仕組み」で、ルールの強制・通知・自動処理を確実に効かせられます。
Claude Code Hooksとは【お願いではなく強制の仕組み】
まず本質を以下の3つで押さえます。
- Hooksは特定の場面で必ず実行されるコマンド
- CLAUDE.mdは確率的なお願いで強制ではない
- 導入判断者にとってはガバナンスの手段になる
Hooksは特定の場面で必ず実行されるコマンド
Hooksとは、Claude Codeが動作の決まった場面で自動的に実行する、利用者が定義したコマンドです。公式ドキュメントは、Hooksがライフサイクルの特定地点で実行され、AIの判断に頼らず「特定のアクションが必ず起きる」決定論的な制御を与えると説明しています。
たとえば、ファイルを編集した直後に整形コマンドを走らせる動作を仕込めます。危険なコマンドの実行前に必ず点検する動作も同じように設定が可能です。AIの気分や解釈に左右されず、決めた処理が確実に走る点が特徴です。
CLAUDE.mdは確率的なお願いで強制ではない
Hooksの価値は、CLAUDE.mdと比べると際立ちます。CLAUDE.mdに「本番のファイルは触らないで」と書いても、記述はAIへのお願いにすぎず、状況によっては守られないことがあります。確率的な指示だからです。
対してHooksは、条件に一致したら必ず実行される決定論的な仕組みです。「守ってくれたら嬉しい」ではなく「守らせる」ための道具、と理解すると使いどころが見えてきます。CLAUDE.md自体の書き方は次の記事で解説しています。
Claude Codeの権限設定を徹底解説！自動承認を安全に使う方法も紹介
導入判断者にとってはガバナンスの手段になる
Hooksは、コードを書かない立場の人にとっても重要です。チームでAIコーディングを進めるとき、「機密ファイルを入力させない」「危険な操作を止める」「作業ログを残す」といったルールを、個人の注意任せではなく仕組みとして全員に効かせられるためです。
つまりHooksは、開発者向けの便利機能であると同時に、組織の統制と監査を支える手段でもあります。ルールを文書で配るだけでなく、破れない形で技術的に配布する。最後のピースがHooksです。社内展開の全体像は次の記事にまとめています。
Claude Codeの社内利用ルールを徹底解説！商用利用の規約と設定配布も紹介
Hooksで使える主なイベント
Hooksは、発火するタイミング(イベント)を選んで設定します。代表的なものは以下の3グループです。
- ツールの実行前後に発火するイベント
- セッションやプロンプトに関わるイベント
- 通知や停止に関わるイベント
ツールの実行前後に発火するイベント
最もよく使うのが、AIがツールを使う前後のイベントです。公式ドキュメントによると、PreToolUseはツール呼び出しの実行前に発火し、その操作をブロックできます。PostToolUseは、ツール呼び出しが成功した後に発火するイベントです。
PreToolUseは危険な操作を止める役、PostToolUseは編集後の整形やログ記録の役、と覚えるとわかりやすくなります。どちらも、Bashやファイル編集など、対象のツール名で発火条件を絞れる点は共通です。
セッションやプロンプトに関わるイベント
作業の開始や指示の場面にもフックを仕込めます。SessionStartはセッションの開始や再開時に発火します。UserPromptSubmitは利用者がプロンプトを送信してAIが処理する前、PreCompactは長い会話を圧縮する前が発火のタイミングです。SessionEndはセッションの終了時に発火します。
たとえばSessionStartで、プロジェクトの前提情報をAIのコンテキストへ毎回読み込ませる、といった使い方が可能です。作業の区切りごとに決まった準備や後始末を自動化できます。
通知や停止に関わるイベント
AIの状態変化を捉えるイベントも便利です。Notificationは、AIが入力や許可を待っているときに発火します。Stopはやりとりが終わったとき、SubagentStopはサブエージェントが終了したときに発火します。
Notificationが向くのは、長い作業の途中で許可待ちになったことを通知する用途です。放置していた作業が止まっていたことに、後から気づく事態を防げます。なお、公式ドキュメントには上記以外にも多くのイベントが用意されており、必要に応じて選べます。
Hooksの設定方法【settings.jsonの構造】
設定の基本は以下の3点です。
- 設定ファイルの置き場所で適用範囲が決まる
- イベント・matcher・commandの3階層で書く
- 終了コードとJSONで動作を制御する
設定ファイルの置き場所で適用範囲が決まる
Hooksは、Claude Codeのsettings.jsonに記述します。置き場所は3階層です。個人の全プロジェクトに効かせる場合はホームフォルダの設定、チームで共有する場合はプロジェクトの.claude/settings.json、自分だけの一時的な設定はsettings.local.jsonを使います。
チームで統制したいルールはプロジェクト共有の設定に置き、リポジトリで配布するのが基本です。置き場所を分けることが、個人利用とチーム統制を両立させる土台になります。
イベント・matcher・commandの3階層で書く
設定は、イベント名の下にmatcher(対象の絞り込み)とコマンドを並べる3階層の構造です。公式ドキュメントの例では、ファイルの編集後に整形を走らせる設定を次のように書きます。
{"hooks": {"PostToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"}]}]}}
matcherは、EditやWriteのようにツール名で指定し、縦棒で複数を並べられます。空欄にすれば、そのイベントのすべてで発火する扱いです。フックにはコマンド実行のほか、HTTP呼び出しなどの種類も選べます。
終了コードとJSONで動作を制御する
フックの結果は、コマンドの終了コードでAIに伝わります。公式ドキュメントによると、終了コード0は異議なしの合図です。終了コード2はアクションのブロックで、標準エラー出力に書いた理由がAIへのフィードバックになります。
より細かく制御したい場合は、フックがJSONを出力して判断を返す方法もあります。PreToolUseでは、permissionDecisionにdenyを返せば、操作を拒否して理由も添えられる仕組みです。終了コードとJSONの二重の制御で、止める・通す・理由を伝えるを使い分けられます。
まず入れるべきおすすめのHooks3つ
数あるフックの中で、最初に入れる価値が高いのは以下の3つです。
- 危険なコマンドを実行前にブロックする
- 編集後にコードを自動で整える
- 許可待ちや完了を通知する
危険なコマンドを実行前にブロックする
1つ目は、取り返しのつかない操作の防止です。PreToolUseでBashコマンドを対象にする設定です。rm -rfのような危険なコマンドや.envなどの機密ファイルへの操作を検知したら、終了コード2でブロックします。公式ガイドにも、保護ファイルの編集や危険コマンドを止める例が載っています。
重要なのは、PreToolUseフックが確認スキップの設定より先に発火する点です。公式ドキュメントは、Hooksが制限を強化できるが緩和はできない仕組みだと説明しています。確認を全部飛ばす設定にしていても、フックのdenyは有効です。最後の安全網として機能します。
編集後にコードを自動で整える
2つ目は、品質の自動維持です。PostToolUseでEditとWriteを対象にし、編集されたファイルに整形ツールを自動で走らせます。設定は、公式ガイドのprettierの例をそのまま使えば十分です。
人が毎回整形を指示する必要がなくなり、コードのスタイルが自動でそろいます。フックが成功すれば会話には何も表示されず、品質が静かに保たれる仕組みです。
許可待ちや完了を通知する
3つ目は、放置時間の削減です。Notificationイベントを使えば、AIが許可や入力を待っているときに、デスクトップ通知やSlackへの通知を飛ばせます。公式ガイドに載っているのは、macOSのosascriptを使う例です。
長い作業を任せて別のことをしていると、許可待ちで止まっていることに気づけません。通知フックは、待ち時間をなくす地味だが効く1手です。
Hooksを使うときのセキュリティ注意
強力な機能ゆえの注意点は以下の3つです。
- Hooksは任意のコマンドを自分の権限で実行する
- 他人のプロジェクトの設定は必ず確認する
- 最小権限と定期レビューを徹底する
Hooksは任意のコマンドを自分の権限で実行する
最も重要な注意点です。公式ドキュメントは、Hooksが任意のコマンドを実行できると明記しています。悪意あるフックや誤設定のフックは、機密の読み取り・ファイルの改変・情報の流出を、Claude Codeを実行する利用者の権限で行いうる存在です。公式は「USE AT YOUR OWN RISK(自己責任で使うこと)」とまで書いています。
つまりフックは、便利さと危険さが表裏一体の機能です。完全に信頼できるフックだけを有効にする原則を、最初に共有してください。
他人のプロジェクトの設定は必ず確認する
見落としやすいのが、他人のリポジトリを開くときです。プロジェクトのsettings.jsonにフックが仕込まれていると、開いただけで自分の権限で自動実行される可能性があります。
信頼できないプロジェクトを扱うときは、設定ファイルのフックを有効化する前に中身を精査してください。公式もベストプラクティスとして、有効化前の全フックの精査を筆頭に挙げています。
最小権限と定期レビューを徹底する
公式が示す運用の原則は、次のとおりです。フックに与える権限は必要最小限にし、シークレットはコードに書かず環境変数の許可リストで扱い、フックの実行はデバッグログで監査します。
一度作ったフックも、放置せず定期的に見直すことが推奨されています。強力な自動化ほど、設定した後の点検が効くものです。全体の安全設計は次の記事で解説しています。
Claude Codeのセキュリティを徹底解説！安全に使う設定と企業運用も紹介
Claude Code Hooksに関するよくある質問
導入時に迷いやすい点への回答は以下の3つです。
- CLAUDE.mdとHooksはどう使い分けますか？
- プログラミングが苦手でも設定できますか？
- 設定したフックが動かないときは？
CLAUDE.mdとHooksはどう使い分けますか？
方針や好みのような、多少の揺れが許される指示はCLAUDE.mdに書きます。一方、必ず守らせたいルールや、破られると困る禁止事項はHooksで強制します。
たとえば「コメントは丁寧に」はCLAUDE.md向きで、「本番設定ファイルは絶対に触らせない」はHooks向きです。確率的なお願いと決定論的な強制を、重要度で振り分けてください。
プログラミングが苦手でも設定できますか？
基本のフックなら、公式ガイドの例をコピーして始められます。整形の自動実行や通知は、掲載されているコマンドをほぼそのまま使えます。
一方で、複雑な条件分岐を伴うフックはシェルスクリプトの知識が必要です。導入判断者の立場なら、自分で書くよりエンジニアに依頼する形が現実的です。必要なフックを作ってもらい、チームの設定として配布します。
設定したフックが動かないときは？
まず、settings.jsonのイベント名とmatcherの記述を確認します。matcherの綴りが対象のツール名と一致していないと、フックは発火しない点に注意してください。セッション内の/hooksコマンドで、現在有効なフックを確認できます。
それでも動かない場合は、フックのコマンドを単体で実行してエラーが出ないかを試します。フックはあくまで普通のコマンドのため、コマンド自体の動作確認が近道です。
Claude Code Hooksはルール強制・通知・自動処理を確実に効かせる仕組みです
Claude Code Hooksは、決まった場面で必ず実行される、決定論的な自動化の仕組みです。CLAUDE.mdの確率的なお願いと違い、決めたルールを確実に効かせられます。危険コマンドのブロック・編集後の自動整形・許可待ちの通知が代表例です。設定はイベント・matcher・commandの3階層で書き、終了コードやJSONで動作を制御する構造です。
一方で、任意のコマンドを利用者の権限で実行する強力さも忘れてはいけません。信頼できるフックだけを使い、他人の設定は精査してください。まずは危険コマンドのブロック・自動整形・通知の3つから、公式ガイドの例を土台に組み始めましょう。
