Claude Code Hooksとは？CLAUDE.mdでは守れないルールを確実に動かす設定と使い方

Claude Code Hooksとは？指示ではなく設定でルールを確実に守らせる機能

Hooksの役割の図解。決まったタイミング、通知、自動整形と検証、ブロック、文脈の注入

Claude Code Hooksとは、Claude Codeの動作の節目で、ユーザーが決めた処理を自動実行する仕組みです。

節目にあたるのは、セッションの開始、ツールの実行前後、Claudeが応答を終えたときなどで、Anthropicの公式リファレンスでは「ライフサイクルの特定の時点で自動実行される、ユーザー定義のシェルコマンド、HTTPエンドポイント、MCPツール呼び出し、LLMプロンプト、またはサブエージェント」と説明されています。設定はJSON形式の設定ファイルに書き、Claude Code本体のプログラムを変更する必要はありません。

Hooksでできる4つのこと

Hooksの用途は、公式ガイドの例をたどると大きく4つに分かれます。

通知：Claudeが入力や許可を待っているときに、デスクトップ通知を出す
自動整形・検証：ファイルを編集した直後に、整形ツールやテストを自動で走らせる
ブロック：危険なコマンドや、触ってはいけないファイルへの編集を実行前に止める
コンテキストの注入：セッション開始時や要約の後に、プロジェクトの前提や最近の作業を自動で伝える

どれも「人が毎回思い出して指示する」作業を設定に置き換えるものです。通知は待ち時間の無駄を減らし、自動整形と検証は成果物の品質を一定に保ちます。ブロックは、オートモードのように承認を省く使い方をしていても、守らせたい一線を越えないための保険になります。

CLAUDE.md・Git Hooksとの違い

CLAUDE.mdは、プロジェクトの前提やルールを文章で伝える仕組みで、Claudeはそれを読んで判断します。Git Hooksは、コミットやプッシュといったGitの操作に反応する仕組みで、Claude Codeの動作そのものは見ていません。下表は、動く仕組み・確実性・向いている用途の3観点で3つを整理したものです。ルールの性質に合わせて使い分ける視点が欠かせません。

観点	Claude Code Hooks	CLAUDE.md	Git Hooks
動く仕組み	設定したイベントで、決めたコマンドが必ず実行される	Claudeが文章を読み、状況に応じて従うかを判断する	commitやpushなどGitの操作に反応して実行される
確実性	決定論的（設定どおりに毎回動く）	確率論的（守られないことがある）	決定論的（ただしGit操作の時点に限る）
向いている用途	整形・ブロック・通知など、例外を認めたくないルール	書き方の方針や背景説明など、判断を委ねたい指示	コミット前のテストやlintなど、Git中心の品質管理

公式ガイドは、Hooksの利点を「LLMが実行を選ぶのに頼らず、決まった処理が必ず起きること」と説明しています。たとえば「編集後にPrettierをかける」はCLAUDE.mdに書いても毎回は守られませんが、PostToolUseのHooksにすれば編集のたびに必ず動きます。一方で「変数名は意味が伝わるものにする」のような判断を伴う方針は、CLAUDE.mdに書く方が向いています。

利用できる条件とプランの扱い

Hooksは、Claude Codeの設定ファイルに書くだけで使える機能です。公式のガイドとリファレンスの範囲では、プランによる制限は示されていません。設定の置き場所は個人用・プロジェクト用・組織管理のmanaged設定などに分かれ、後述の運用設計の表で整理します。

注意したいのは、公式の設定例がJSONの読み取りにjqというコマンドラインツールを使っている点です。手元に無ければbrew install jqなどで入れます。また、クラウド上で動くセッションは個人用の~/.claude/settings.jsonを読みません。チームの共有ルールにしたいものは、プロジェクト側の設定に置くのが前提になります。

なぜ決定論的に動くことが業務で効くのか

AIエージェントに業務を任せるとき、いちばん困るのは「だいたい守るが、たまに守らない」状態です。CLAUDE.mdの指示は確率論的に扱われるため、10回に1回でも整形が抜けたり、触ってはいけない設定ファイルが書き換わったりすると、結局は人が毎回確認することになります。

Hooksはこの確認作業を設定に置き換えます。公式ガイドによると、PreToolUseのHooksは許可モードの判定より前に動き、permissionDecisionでdenyを返せばbypassPermissionsモードや--dangerously-skip-permissionsを付けた実行でもツールの実行を止められます。つまり、作業者が承認を省く設定にしていても、組織として越えさせたくない一線は設定側で守れます。

逆方向には働かない点も押さえておきます。Hooksがallowを返しても、設定ファイルの拒否ルールや、ネットワーク上のパスの読み取りに対する確認は省けません。Hooksは制限を厳しくする方向にだけ効く仕組みだと理解しておくと、設計で迷いません。

Claude Code Hooksの仕組み｜イベント・ハンドラー・matcherで動きが決まる

Hooksの設定は、3つの要素の組み合わせで決まります。

イベント：どのタイミングで動くか（ツールの実行前、応答の完了時など）
ハンドラー：何を実行するか（シェルコマンド、HTTPリクエスト、プロンプトなど）
matcher：どの対象に絞って動かすか（EditとWriteのときだけ、など）

イベントが発火すると、条件に合うHooksがすべて並列で実行され、結果が合成されます。ここからは3つの要素と、結果の伝え方になる終了コードを順に見ていきます。

AIエージェントの作り方

AIエージェントを「どう作り、どう育てるか」を、GiftX記事制作エージェントの実物で解説。

無料ダウンロード →

主なイベントと発火タイミング

公式リファレンスには30を超えるイベントが定義されています。最初に押さえるのは、下表の8つで十分です。

イベント	発火するタイミング	実行を止められるか
SessionStart	セッションの開始・再開時	止められない（コンテキストの注入に使う）
UserPromptSubmit	プロンプトの送信時、Claudeが処理する前	止められる
PreToolUse	ツール呼び出しの実行前	止められる
PermissionRequest	ツール呼び出しに許可の判断が必要なとき	代わりに許可・拒否を返せる
PostToolUse	ツール呼び出しの成功後	実行済みのため取り消せない
Notification	Claude Codeが通知を出すとき	対象外（通知に反応する）
Stop	Claudeが応答を終えたとき	続行を要求できる
SessionEnd	セッションの終了時	止められない

PreToolUseは「実行前に止める」、PostToolUseは「実行後に後処理する」と役割がはっきり分かれています。Stopは応答が終わるたびに発火し、タスク完了時だけに限りません。Stopで「まだ終わっていない」と返し続けると、Claude Codeは8回連続でブロックされた時点で上書きして終了します。

ハンドラーの種類とタイムアウト

ハンドラーは「何を実行するか」を決める部分で、typeで指定します。公式リファレンスにある5種類と、既定のタイムアウトは下表のとおりです。

type	実行する内容	既定のタイムアウト
command	シェルコマンドを実行する。stdinでJSONを受け取り、終了コードとstdoutで結果を返す	600秒
http	イベントのJSONをPOSTでURLに送る。応答はcommandと同じJSON形式	600秒
mcp_tool	設定済みのMCPサーバーのツールを呼び出す	600秒
prompt	Claudeのモデルに1回だけ評価を依頼し、JSONで判断を返させる	30秒
agent	サブエージェントを起動し、ファイルの読み取りなどで検証してから判断を返す（実験的）	60秒

実務で使うのは、ほとんどがcommandです。判断を伴うチェックにはpromptやagentが使えますが、公式ガイドはagentを実験的機能と位置づけ、本番の運用にはcommandを推奨しています。タイムアウトはtimeoutフィールドで個別に上書きできますが、UserPromptSubmitでは既定が30秒に、SessionEndでは全体で1.5秒に短くなる点に注意します。

matcherと終了コードで止める・通すを決める

matcherで反応する対象を絞り、終了コードとJSON出力で結果を伝えます。

matcherの書き方

matcherは、イベントの中でどの対象に反応するかを絞る文字列です。ツール系のイベントではツール名が対象で、Edit|Writeのように縦棒で並べると複数の完全一致になります。英数字以外の文字を含むと正規表現として評価され、mcp__github__.*のような書き方で特定のMCPサーバーのツール全体に反応させられます。空文字か省略ですべてに一致し、Stopのようにmatcherを持たないイベントでは指定しても無視されます。

終了コードとJSON出力

処理の結果は、終了コードで伝えます。exit 0は「異議なし」で、PreToolUseでは通常の許可フローに進みます。exit 2は「ブロック」で、stderrに書いた理由がClaudeへのフィードバックや画面への表示になります。それ以外の終了コードは非ブロッキングのエラーとして扱われ、処理は続行します。公式ガイドは、ルールを強制したい場面では慣習的なexit 1ではなくexit 2を使うよう注意しています。

終了コードだけでは「止める」か「黙る」かしか選べないため、細かい制御ではstdoutにJSONを書きます。PreToolUseならhookSpecificOutput.permissionDecisionにallow、deny、askのいずれかを入れ、denyなら理由をpermissionDecisionReasonで返します。

複数のHooksが同じイベントで異なる判断を返した場合は、deny、defer、ask、allowの順に厳しい方が採用されます。

Claude Code Hooksの使い方｜settings.jsonの書き方と最初の設定例

設定は、settings.jsonの中にhooksというキーを作り、イベント名ごとにmatcherとハンドラーの配列を並べる形で書きます。公式ガイドの手順に沿って、最初の1本から順に見ていきます。

最初の1本は通知Hooksから

公式ガイドが最初の例に挙げているのは、Claudeが入力待ちになったらデスクトップ通知を出すHooksです。macOSなら~/.claude/settings.jsonに次の1行を書きます。既存のhooksキーがある場合は、Notificationを並べて足します。

\{ "hooks": \{ "Notification": [ \{ "matcher": "", "hooks": [ \{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" \} ] \} ] \} \}

保存したら、Claude Codeのプロンプトで/hooksと打ち、一覧のNotificationの下に設定が見えれば登録は成功です。テストは、許可が必要な操作を頼んでから別のウィンドウに切り替え、通知が届くかで確かめます。

自動フォーマットと保護ファイルのブロック

2本目と3本目は、プロジェクトの.claude/settings.jsonに書く、品質と安全のためのHooksです。

編集のたびにPrettierをかける

PostToolUseイベントにmatcherEdit|Write、コマンド jq -r '.tool_input.file_path' | xargs npx prettier --write を登録します。編集ツールが成功した直後に、編集したファイルのパスを取り出して整形する流れです。成功時は会話に何も表示されないので、ファイルが整形されているかで動作を確かめます。

触ってはいけないファイルへの編集を止める

.envやpackage-lock.jsonへの編集は、対象のパスを保護パターンと照合してexit 2で終わるシェルスクリプトで止めます。公式ガイドの例では、スクリプトを.claude/hooks/protect-files.shに置いてchmod +xで実行権限を付け、PreToolUseのEdit|Writeから呼び出します。止めた理由はstderr経由でClaudeに渡り、Claudeは別の進め方に切り替えられます。

AI活用実態調査レポート

全国8,000人調査で、AIの活用方法によって生産性向上に約3.8倍の差が生まれることが判明。

無料ダウンロード →

動いたかどうかを確かめる方法

Hooksが動いたかは、Ctrl+Oで開くトランスクリプト表示で確認します。成功時は何も出ず、ブロック時はBlocked:のようなメッセージが、非ブロッキングのエラー時は「hook error」の通知が出ます。動かないときは、/hooksに出ているか、matcherがツール名と大文字小文字まで一致しているか、イベントを取り違えていないかの順に見直します。

終了コードやstdoutまで追うデバッグには、claude --debugで起動するか、セッション中に/debugでログを有効にします。どの業務のルールから設定に落とすかは、「職種別AI活用事例集」が参考になります。

Before/Afterで見るClaude Code Hooks導入の業務インパクト

Claude Codeで社内の提案文書や定例資料のドラフトを毎日作っている担当者を例に、Hooksを入れる前後の確認作業を比べます。

Before：編集のたびに人が確認する

Claude Codeがファイルを編集するたびに、フォーマットの崩れと、触ってはいけない設定ファイルの変更がないかを目視で確認し、崩れていれば手で直します。1日20回の編集に対して1回2分の確認で、1日40分、週にして約3.3時間を確認に使っている状態です。

After：確認は1日1回のログ確認だけ

PostToolUseのHooksで編集直後に整形コマンドが自動実行され、PreToolUseのHooksで保護ファイルへの編集はexit 2で止まります。担当者は1日1回、トランスクリプトでHooksの結果を見るだけになり、確認は1日8分、週に約40分まで減ります。削減率は約80%で、時給3,000円換算では週約8,000円、年約40万円相当です。

個人の設定で終わらせない｜Claude Code Hooksをチームの標準にする運用設計

Hooksは設定ファイルの置き場所で共有される範囲が決まります。チームで守らせたいルールは、プロジェクト側の設定に置かないと他のメンバーの環境では動きません。

置き場所	効く範囲	共有
`~/.claude/settings.json`	自分の全プロジェクト	されない
`.claude/settings.json`	そのプロジェクト	リポジトリにコミットして共有
`.claude/settings.local.json`	そのプロジェクト	されない（gitignore対象）
managed設定	組織全体	管理者が配布（各自では無効化できない）

起点は、ブロックや自動整形のように例外を認めないルールを.claude/settings.jsonに置いて共有することです。組織全体で揃える段階ではmanaged設定に移します。GiftXのAIエージェント構築支援でも、記事制作を自動化するリポジトリの.claude/settings.jsonにPreToolUseのHooksを置き、共有の設定フォルダを書き換える操作を止めています。

ビジネス職生成AI活用実態調査2026では、組織の課題として最も多かった回答が「AI活用が個人任せ」の25.9%（複数回答）でした。Hooksをプロジェクトの設定に置くことは、個人のコツをチームの標準に変える具体的な手段になります。

詳細な調査データは「ビジネス職生成AI活用実態調査（2026年版）」にてご覧ください。

Claude Code Hooksのよくある質問

Hooksを設定する前後で問い合わせが多い点を、公式リファレンスの記述に沿って整理します。

Hooksは有料プランでないと使えませんか

Hooksは設定ファイルで動くClaude Codeの機能で、公式のガイドとリファレンスにプラン別の制限は示されていません。ただし、組織の管理者がmanaged設定でallowManagedHooksOnlyを有効にしている場合、個人やプロジェクトのHooksは実行されず、/hooksの画面にも表示されません。

フックコマンドが失敗したら、Claude Codeの動作はどうなりますか

終了コードが0と2以外のときは非ブロッキングのエラーとして扱われ、処理は続行します。トランスクリプトに「hook error」の通知と、stderrの1行目が表示されます。失敗時にも実行を止めたい場合は、commandやhttpのハンドラーにonFailureをblockで設定します。

HooksとCLAUDE.mdのどちらを先に設定すべきですか

先に決めるのは、そのルールが「必ず守らせたいもの」か「判断を委ねたいもの」かです。整形やブロックのように例外を認めないものはHooksに、書き方の方針や背景説明はCLAUDE.mdに置きます。両方を併用する前提で、最初はCLAUDE.mdで守られずに困っている指示を1つ選び、Hooksに置き換えるのが進めやすい順序です。

PreToolUseでexit 0を返せば、そのツールは許可されますか

許可にはなりません。exit 0は「Hooksとしては異議がない」という意味で、そのあと通常の許可フローに進み、設定の許可ルールや確認ダイアログが従来どおり適用されます。確認を省いて許可したい場合は、stdoutにpermissionDecisionをallowにしたJSONを書きます。

まとめ｜Claude Code Hooksは最初の1本から

Claude Code Hooksは、Claude Codeの動作の節目で決めた処理を必ず実行する仕組みで、CLAUDE.mdの指示では守りきれないルールを設定に置き換えます。

イベント・ハンドラー・matcherの3要素と、exit 2でブロックする終了コードの意味を押さえれば、通知、自動整形、保護ファイルのブロックといった設定は公式ガイドの例をなぞるだけで動きます。チームで効かせるには、個人用ではなくプロジェクトの.claude/settings.jsonに置いて共有し、組織全体で揃えたい段階でmanaged設定へ移す流れが現実的です。

Hooksを含めてClaude Codeを業務に組み込む段階では、GiftXが1業務単位のAIエージェント構築を伴走支援しています。詳細は AIエージェント構築支援サービスをご覧ください。

Claude Codeに業務ルールを組み込みたい方へ

本記事で紹介したHooksのように、Claude Codeを自社の業務ルールに沿って動かしたい、どの業務から任せるかを相談したいとお考えの方は、ぜひGiftX AIエージェント構築支援までお問い合わせください。

GiftX AIエージェント構築支援では、貴社の業務に合わせて1業務単位のスモールスタートから本番運用まで、AIエージェント構築をワンストップで支援します。ユースケースの洗い出しから、PoC、本番運用、社内ナレッジ化まで伴走します。

AI活用にご関心のある方は、ぜひ一度ご相談ください。

▶ GiftX AIエージェント構築支援の詳細・お問い合わせはこちら

詳細をみる

Claude Code Hooksとは？CLAUDE.mdでは守れないルールを確実に動かす設定と使い方