結論：最初は通知、次に整形、最後にblockを設定する

先に答えると、Claude Code Hooksは、Claudeが編集した後、commandを実行する前、入力待ちになった時など、決めたeventで自動的に処理を起動する仕組みです。毎回promptで「忘れずに実行して」と頼むのではなく、再現可能なruleとして動かせます。ただし、最初から危険操作を止める複雑なHookを入れると誤blockで業務を止めるため、Notification、format、PreToolUseの順に影響を広げます。

読者の具体的な困りごとは、Claude Codeへ同じtestやformatを毎回頼んでも抜けが起き、逆に厳しい指示を増やしすぎて何が強制されるのか分からなくなることです。読了後は、指示で十分なこととHookで自動化することを分け、設定場所、event、matcher、test、停止条件を判断できます。次の行動は、「毎回同じ条件で必ず行いたい処理」を一つだけ選ぶことです。

HooksとCLAUDE.mdの役割を分ける

公式memory guideでは、CLAUDE.mdはcoding standard、build command、project構成など、sessionごとにClaudeへ持たせる文脈です。指示として読み込まれますが、強制設定ではありません。公式には、Claudeの判断にかかわらずactionをblockしたい場合はPreToolUse Hookを使うよう案内されています。

Hooksはlifecycle上のeventへ反応します。公式referenceでは、session開始・終了、prompt送信、tool実行前後、permission request、notification、compact、subagent、MCPなど複数のeventが定義されています。何でもHookへ移すのではなく、判断が必要なruleは短い指示、人に確認せず毎回同じ結果を求めるruleはHook、組織で上書き不可にするpolicyはmanaged settingsへ分けます。

たとえば「変更理由を説明する」は文脈判断を含むためCLAUDE.md向きです。「JavaScriptを編集したらformatterを実行する」はPostToolUse向きです。「特定の破壊的commandを実行前に拒否する」はPreToolUse向きです。この分離で、長すぎるinstructionと複雑すぎるscriptの両方を避けられます。

最初に知る4つの構成要素

  1. event：Notification、PostToolUse、PreToolUseなど、いつ起動するかを選びます。
  2. matcher：対象toolやnotification typeを絞り、不要な回で起動しないようにします。
  3. handler：shell command、HTTP endpoint、promptなど、何を実行するかを定義します。
  4. result：記録だけか、許可・拒否のdecisionを返すかを決めます。

command HookではeventのJSON contextが標準入力へ渡されます。handlerは必要なfieldだけを読み、成功時、対象外、失敗時のexitと出力を決めます。入力全体を無条件に別systemへ送る設計は避け、file path、command、promptなどに機密情報が含まれる可能性を確認します。

公式guideの/hooks画面では登録済みHookのevent、matcher、source file、commandを確認できますが、画面はread-onlyです。追加・変更・削除はsettings JSONを編集します。見えていることと動作することは別なので、対象eventを一度発生させて結果を確認します。

設定場所を個人・project・組織で選ぶ

user settingsの~/.claude/settings.jsonは個人の全project、project settingsの.claude/settings.jsonはrepositoryを共有するteam、local settingsの.claude/settings.local.jsonはその端末だけに適用します。組織で変更不可にする設定はmanaged settingsを使います。

通知音や個人editor連携はuserまたはlocal、team共通formatterはproject、security上必須の制限はmanagedを検討します。project settingsをcommitする場合、Hook script本体もreview対象です。設定だけが安全でも、呼び出すscriptが後から変更されれば挙動は変わります。owner、変更reviewer、test、versionを一緒に管理します。

Windows、macOS、Linuxでnotification commandやpath表記が異なります。複数OSのteamでは、一つのcommandを全員へ配る前にOS別の動作を確認します。headless serverやcontainerではdesktop notification daemonがない場合があるため、通知失敗をClaude Code本体の失敗と混同しません。

安全に導入する9手順

  1. 毎回同じ条件で必要な処理を一つ選び、期待結果を一文で書きます。
  2. 通知、整形、検査、blockのどれかへ分類し、影響を決めます。
  3. 適切なeventとmatcherを公式referenceで確認します。
  4. handler commandをClaude Code外で固定入力に対してtestします。
  5. 最初はlocal settingsへ入れ、/hooksでsourceを確認します。
  6. 対象event、対象外event、失敗入力を各一回試します。
  7. ログへ機密情報が出ないか、timeoutや誤blockがないか確認します。
  8. team共有前に設定とscriptをreviewし、ownerと戻し方を記録します。
  9. 一週間の失敗率と解除件数を見て、次のHookだけを追加します。

Notificationは結果を変えないため最初の練習に向きます。次にPostToolUseでformatを行い、対象fileだけが変更されることを確認します。PreToolUseでblockする段階では、危険な入力、似ているが許可すべき入力、空入力をtestし、誤block時の無効化手順を用意します。

PreToolUseを安全装置として使う注意点

PreToolUseはtool実行前に起動し、decisionを返してblockできます。これは強力ですが、文字列の部分一致だけで安全を判定すると、quote、subcommand、shell差、path差で漏れや誤検知が起きます。最初は対象toolをmatcherで絞り、JSONのfieldを構造として読み、block理由を利用者へ返します。

Hookだけに安全性を委ねません。Claude Codeのpermission rules、sandbox、repositoryの権限、secret管理、差分review、人の承認を重ねます。Hookが起動しない、scriptが壊れる、対象tool名が変わる、OS差でcommandが失敗する場合を前提にします。安全側へ失敗させるのか、処理を続けるのかは、業務影響から明示します。

外部HTTPへ送るHookでは、送信先、認証、timeout、再試行、保持、個人情報を確認します。format用Hookでもrepository内の未公開codeを外部serviceへ送る構成なら、単なる整形ではありません。自動化の名前ではなく、実際の入力と出力でriskを評価します。

運用チェックリスト

目的が一つか／eventを公式referenceで確認したか／matcherを最小化したか／設定scopeは適切か／handlerを単体testしたか／対象外も試したか／機密情報を出力しないか／timeoutを決めたか／Windows・macOS・Linux差を確認したか／script変更をreviewするか／ownerがいるか／誤block時に戻せるか／permissionとsandboxを併用するか、を確認します。

よくある質問

Hookは自然言語だけで設定できますか？

設定やscriptの作成をClaudeへ依頼できますが、生成された内容をそのまま共有せず、event、入力、command、送信先、失敗時の挙動を人が確認します。

PostToolUseで毎回testを実行すべきですか？

重いtestを全編集後に走らせると待ち時間が増えます。formatterや軽いlintから始め、full testはStop前やCIなど目的に合う場所へ分けます。

Hookが動かない時は何を確認しますか？

/hooksでsource、event、matcherを確認し、handler commandを単体実行します。設定JSON、path、実行権限、OS固有commandを順に切り分けます。

関連ガイドと公式情報

人間承認とdeny・ask・allowはClaude Codeの権限設定、企業導入全体は企業導入チェックリスト、結果の記録は監査ログと判断記録を参照してください。

設定例と導入手順は公式Automate actions with hooks、event、JSON、decisionの仕様は公式Hooks reference、CLAUDE.mdとの役割分担は公式memory guideで公開直前に確認してください。

Miraigentの無料診断では、指示、自動化、権限、記録、owner、停止条件を整理し、AI開発運用の抜けと過剰自動化を見える化します。