Claude Code hooksとは？設定方法とイベント一覧・実用例と注意点を解説

Claude Codeに作業を任せていると、意図しないファイルが書き換わったり、フォーマットの実行を忘れたまま進んだりすることがあります。指示で防ごうとしても、守られるかどうかはモデルの判断に委ねられます。

この不確実さを解消する仕組みがhooksです。ライフサイクルの特定の地点で必ずシェルコマンドを実行させられるため、危険な操作の遮断や品質チェックを確実に効かせられます。本記事では、hooksの役割とイベントの種類、設定方法、実務で使える例、導入時の注意点までを整理します。

確認したいポイント	結論	詳細
hooksとは何か？	特定の場面で必ず動く仕組み	Claude Codeのライフサイクル上の地点でシェルコマンドを自動実行させる機能です。
CLAUDE.mdとの違いは？	強制力の有無が決定的に違う	CLAUDE.mdは指示にすぎませんが、hooksは判断を挟まず確実に実行されます。
どんなイベントがある？	ツール実行前後を中心に多数	実行前、実行後、セッション開始、応答完了など、20種類以上が用意されています。
設定はどこに書く？	settings.jsonのhooksブロック	ユーザー、プロジェクト、組織など、適用したい範囲に応じて置き場所を選びます。
処理を止めるには？	終了コード2でブロックする	実行前のイベントで終了コード2を返すと操作が中止され、理由がClaudeに伝わります。
実務では何に使える？	遮断・整形・通知・記録の4つ	危険なコマンドの遮断、編集後の自動整形、入力待ちの通知、操作ログの記録が定番です。
コマンド以外の書き方は？	判断が必要ならモデルに任せる	条件が定型化できない場面では、モデルに評価させるタイプのhookも用意されています。
導入で気をつける点は？	権限設定との優先関係を理解する	hookで許可を返しても、設定側の拒否ルールは優先される仕様になっています。

この記事でわかること

• hooksの役割と、CLAUDE.mdやCI/CDとの決定的な違い
• 主要なイベントの発火タイミングと、用途に応じた選び方
• 設定ファイルの書き方と、マッチャーで対象を絞る方法
• 終了コードと構造化出力による制御の使い分け
• 危険操作の遮断や自動整形など、実務で使える設定例と注意点

▼ AIを使った開発の進め方、社内で整理しませんか ネクストスケールでは、AI研修から開発支援までを一貫して提供しています。「導入はしたが安全に運用できているか不安」という段階からご相談いただけます。 ▶ 無料相談はこちら

Claude Code hooksとは

名前だけでは何をする機能なのか掴みにくい部分があります。位置づけを整理すると、使いどころは明確になります。

背景にあるのは、エージェント型のAIに作業を任せる際の不確実さです。指示を書いても守られるとは限らない状態では、業務のコードベースを触らせる判断がしづらくなります。この不確実さを技術的に埋めるのがhooksの役割です。

定義と役割

hooksは、Claude Codeのライフサイクル上の特定の地点で実行されるユーザー定義のシェルコマンドです。公式ドキュメントのhooksでアクションを自動化するでは、動作に対して決定論的な制御を提供する仕組みと説明されています。

重要なのは、モデルが実行を選ぶかどうかに依存しないという点です。設定した条件に合致すれば必ず動くため、プロジェクトのルールを確実に適用したり、繰り返しの作業を自動化したりできます。

できることは幅広く、編集後のフォーマット、実行前のコマンド遮断、入力待ちの通知、セッション開始時のコンテキスト注入などが挙げられます。既存のツールとの連携も可能です。

CLAUDE.mdやskillsとの違い

CLAUDE.mdは永続的な指示を与えるファイルですが、公式でも強制的な設定ではなくコンテキストとして扱われると明記されています。書いた内容に必ず従う保証はありません。

対してhooksは、Claudeの判断に関わらず実行されます。確実に守らせたいルールはhooks、方針として伝えたい内容はCLAUDE.mdという使い分けが基本です。公式でも、特定の時点で必ず実行すべき指示はhookとして書くよう案内されています。

skillsやsubagentsとも役割が異なります。skillsは追加の指示や実行可能なコマンドを与える仕組み、subagentsは分離された文脈でタスクを進める仕組みです。生成AI全般の基礎は生成AIとは？仕組みと従来AIとの違いを解説で整理しています。

整理すると、hooksは守りの仕組みであり、CLAUDE.mdは方向づけの仕組みです。両方をそろえて初めて、任せられる範囲が広がります。片方だけでは、緩すぎるか窮屈すぎるかのどちらかに寄ります。

GitフックやCI/CDとの違い

既存の自動化の仕組みと似た印象を受けますが、トリガーになる対象が違います。Gitフックはコミットやプッシュといったバージョン管理の操作、CI/CDはリポジトリへの反映が起点です。

hooksの起点は、AIエージェントの操作そのものです。ファイルを書き換える直前、コマンドを実行する直前という粒度で介入できるため、問題が起きる前の段階で止められる点が決定的な違いになります。既存の仕組みと排他ではなく、重ねて使う前提で考えてください。

▼ 自社の開発フローにどう組み込むか、整理しませんか 機能を並べても、自社の工程に当てはまるかは判断しづらいものです。現在の開発の流れをうかがい、効果の出やすい箇所を一緒に特定します。 ▶ 開発体制を相談する

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

イベントは20種類以上が用意されています。すべてを覚える必要はなく、用途に直結するものから押さえていきます。

ツールの実行に関わるイベント

最も使用頻度が高い領域です。PreToolUseはツールの呼び出し前に発火し、実行そのものをブロックできます。PostToolUseは呼び出しが成功した後、PostToolUseFailureは失敗した後に発火します。

ブロックできるのは実行前のイベントだけという点が要点です。PostToolUseはツールが動いた後のため、公式でも変更を元に戻すことはできないと明記されています。安全に関わるチェックは必ずPreToolUseに置いてください。

許可の判断に関わるイベントも用意されています。PermissionRequestは許可の判断が必要になったとき、PermissionDeniedは自動判定によって拒否されたときに発火します。

許可の判断に関わるイベントには制約もあります。対話を伴わないモードでは発火しないため、自動実行を前提とした環境で判定を効かせたい場合は、実行前のイベントを使う必要があります。

セッションと会話に関わるイベント

SessionStartはセッションの開始や再開時、SessionEndは終了時に発火します。UserPromptSubmitは指示を送信した直後、Claudeが処理を始める前のタイミングです。

Stopは応答を終えたときに発火します。注意点として、タスクの完了時だけでなく、応答が終わるたびに発火する仕様です。ユーザーが割り込んだ場合には発火しません。

文脈の圧縮に関わるPreCompactとPostCompact、サブエージェントの開始と終了に関わるSubagentStartとSubagentStopも用意されています。

タスクの作成や完了を捉えるイベントも用意されています。進捗の記録を外部の管理ツールに送るといった連携に使えるため、開発以外の工程とつなげたい場合の入口になります。

その他の主なイベント

Notificationは通知を出すタイミングで発火し、入力待ちを知らせる用途に使われます。ConfigChangeは設定ファイルが変更されたとき、FileChangedは監視対象のファイルが変わったときに動きます。

作業ディレクトリの変更を捉えるCwdChanged、指示ファイルが読み込まれたタイミングを記録するInstructionsLoadedなど、用途の細かいものも揃っています。まずは実行前後と通知の3つを押さえれば十分です。

hooksの設定方法

設定はJSONファイルに書きます。書式そのものは単純で、覚えるべき要素も多くありません。

決めるべきことは3つです。どのイベントで動かすか、どの対象に絞るか、何を実行するか。この3点が固まれば、記述そのものは数行で済みます。

設定ファイルの場所とスコープ

置き場所によって適用される範囲が変わります。ホームディレクトリ配下のファイルはすべてのプロジェクトに、リポジトリ内のファイルはそのプロジェクトだけに効きます。

リポジトリ内の設定はバージョン管理に含められるため、チーム全員に同じガードレールを適用できます。個人の環境だけに効かせたい設定は、gitの管理外となるローカル用のファイルに書きます。

組織全体に強制したい場合は、管理ポリシーの設定として配布する方法があります。プラグインやスキルの定義に含める形でも設定できるため、配布の手段は複数用意されています。

設定ファイルの階層と優先順位は、hooks以外の項目とも共通の仕組みです。どのレイヤーが読み込まれているかはセッション内で確認でき、詳しい仕様はClaude Codeの設定に関する公式ドキュメントにまとまっています。

基本の書き方

設定ファイルにhooksというブロックを作り、その中にイベント名をキーとして記述します。各イベントの下に、対象を絞るためのマッチャーと、実際に動かすコマンドを並べる構造です。

既にhooksのキーがある場合は、全体を置き換えるのではなく、既存のイベントと並ぶ形で追加します。JSONとして正しい形になっているかの確認は必須で、末尾のカンマやコメントが入っていると読み込まれません。

設定した内容は、セッション内で専用のコマンドを実行すると一覧で確認できます。イベントごとに登録数が表示されるため、意図した場所に入っているかをすぐ検証できます。この画面は閲覧専用で、編集はファイルを直接触る形になります。

同じイベントに複数のhookを登録することもできます。その場合はすべてが並行して実行され、結果がまとめられます。判断が分かれたときは最も制限の強いものが採用される仕様です。

マッチャーで対象を絞る

マッチャーを指定しないと、そのイベントのすべての発生で動きます。ファイル編集の後だけフォーマッターを走らせたい場合などは、対象のツール名を指定して絞り込みます。

縦棒で区切ると複数のツール名を指定でき、正規表現も使えます。大文字と小文字は区別されるため、発火しない場合はまずここを確認してください。イベントによっては、セッションの開始理由や通知の種類でフィルタリングする形になります。

ツール名だけでなく引数の内容でも絞り込みたい場合、条件を書けるフィールドが用意されています。すべてのコマンドではなく特定のコマンドのときだけ動かす、といった細かい制御が可能です。

入出力と終了コードの扱い

hookとClaude Codeは、標準入出力と終了コードでやり取りします。ここを理解すると、書ける処理の幅が一気に広がります。

入力はJSONで渡される

イベントが発火すると、そのイベント固有のデータがJSONとしてスクリプトの標準入力に渡されます。セッションの識別子や作業ディレクトリといった共通の項目に加え、イベントごとの情報が含まれます。

ツールの実行前であれば、呼び出そうとしているツールの名前と引数が入っています。スクリプト側でこの内容を解析し、条件に応じて処理を分岐させる形になります。解析には一般的なコマンドラインのツールが使えます。

スクリプトを書く前に、手元で動作を確かめておくと後が楽になります。想定される入力のJSONを流し込み、終了コードを確認するだけで、意図どおりに判定できているかが分かります。

終了コードの意味

終了コード0は、異議なしという意味です。処理は通常どおり進みます。実行前のイベントであっても、0を返すことは承認を意味せず、通常の許可の流れがそのまま適用されます。

終了コード2は、処理をブロックする合図です。標準エラー出力に理由を書いておくと、それがClaudeへのフィードバックとして渡され、別のやり方を検討させられます。遮断したい場合は2を返すと覚えておけば足ります。

それ以外のコードでは処理が続行され、エラーとして記録されます。ブロックできないイベントもあるため、安全に関わる処理を書く際は対象のイベントが遮断に対応しているかを確認してください。

指示の送信時や開始時のイベントでは、標準出力に書いた内容がそのままClaudeの文脈に追加されます。現在のブランチ名やリリースの状況といった情報を毎回渡す用途に使えます。

構造化した出力による制御

終了コードだけでは、遮断するか黙認するかの二択しかできません。より細かく制御したい場合は、終了コード0で終わりつつ、標準出力にJSON形式の判断を書き出します。

実行前のイベントでは、拒否、許可、確認を求めるといった判断を返せます。理由を添えればClaudeにその内容が伝わります。終了コード2と構造化出力は併用できない点には注意が必要で、片方を選んで使います。

▼ チームで安全に使える基準をつくりたい方へ 個人の設定に任せていると、メンバーごとに安全性の水準が変わります。組織としてのルールと標準設定の設計を支援します。 ▶ 標準化を相談する

実務で使える設定例

公式でも紹介されている、効果が分かりやすい使い方を整理します。まずはこの範囲から始めるのが安全です。

危険な操作をブロックする

実行前のイベントを使い、機密性の高いファイルへの編集を止める設定です。環境変数を書いたファイル、ロックファイル、バージョン管理の内部ファイルなどを対象にします。

スクリプト側で対象のパスを判定し、該当すれば終了コード2で止めます。Claudeにはブロックされた理由が伝わるため、別の方法を検討して作業を続けられます。削除系や強制的な反映のコマンドにも同じ考え方が使えます。

注意点として、Claudeはシェル経由でもファイルを変更できます。すべての変更を確実に捉えたい場合は、編集ツールだけでなくシェルの実行も対象に含めるか、応答完了時に作業ツリー全体を確認する構成にします。

編集後に自動でフォーマットする

実行後のイベントに、対象をファイル編集のツールに絞って設定します。編集されたファイルのパスを取り出し、整形ツールに渡す形です。

この設定を入れておくと、フォーマットの指摘がレビューから消えます。人が指摘して直させるより、生成された時点で揃えるほうが手戻りは確実に減ります。

入力待ちを通知する

通知のイベントを使い、デスクトップに知らせる設定です。長い処理を任せている間にターミナルを見続ける必要がなくなり、他の作業に切り替えられます。

通知の種類でフィルタリングもできます。許可を求められたときだけ、あるいは処理が完了したときだけ、といった絞り込みが可能です。使う環境に応じて通知のコマンドを選びます。

操作のログを残す

実行後のイベントで、動かしたコマンドをファイルに追記していく設定です。あとから何が行われたかを追えるようになり、監査の要件がある組織では特に価値が出ます。

設定ファイルの変更を記録するイベントも用意されています。誰かが設定を書き換えた事実を残せるため、統制の観点で運用しやすくなります。開発全体の進め方はAI開発とは？種類・費用相場・開発の流れと会社の選び方で整理しています。

圧縮後にコンテキストを戻す

会話が長くなると文脈が圧縮され、重要な前提が抜け落ちることがあります。圧縮を条件にセッション開始のイベントを発火させ、必要な情報を注入し直す設定が用意されています。

注入する内容は固定の文章でも、コマンドの実行結果でも構いません。直近のコミット履歴を渡すといった動的な使い方も可能です。毎回必要な情報であればCLAUDE.mdに書くほうが適切で、圧縮時だけ効かせたい内容をここに置きます。外部に開発を委託する場合の考え方はAI受託開発とは？依頼できること・費用相場・開発会社の選び方にまとめています。

コマンド以外のhookタイプ

シェルコマンドを動かす形が基本ですが、それ以外の選択肢も用意されています。条件が定型化できない場面で有効です。

モデルに判断させるタイプ

決まったルールでは判定しきれない場合、モデルに評価させる形式が使えます。プロンプトとイベントのデータをモデルに渡し、進めてよいかどうかの判断だけを返させる仕組みです。

たとえば、応答を終えるタイミングで「依頼された作業がすべて終わっているか」を確認させる使い方があります。未完了と判定されれば、その理由が次の指示として渡されて作業が続きます。指示文の設計はプロンプトの書き方と業務で使えるテンプレートも参考になります。

実行に時間がかかる点は踏まえておきます。モデルへの問い合わせが挟まるため、コマンド形式と比べると応答は遅くなります。頻繁に発火するイベントに設定すると、体感の速度が落ちます。

ファイルを調べさせるタイプ

判定にあたってファイルの中身を見たり、コマンドを実行したりする必要がある場合、サブエージェントを立ち上げて検証させる形式もあります。テストが通っているかを実際に確かめてから終了させる、といった使い方が可能です。

公式ではこの形式を実験的な位置づけとしており、仕様が変わる可能性があると注記されています。本番の運用ではコマンド形式を優先するよう案内されているため、試すのは検証環境からにしてください。

外部のサービスに送るタイプ

イベントのデータをHTTPで外部のエンドポイントに送る形式もあります。チーム全体の操作ログを集約するサービスを用意し、そこに集める構成が典型的な用途です。

受け取る側は、コマンド形式と同じ形のJSONを返して結果を伝えます。処理を止めたい場合、HTTPのステータスコードではなく本文の内容で指定する必要がある点に注意してください。

導入時の注意点とトラブル対処

強力な仕組みである分、設計を誤ると開発が止まります。押さえておくべき点を挙げます。

権限設定との優先関係

実行前のhookは権限モードの確認より先に発火します。そのため、拒否を返せば権限を緩めたモードで動いていてもブロックできます。ユーザー側の設定変更では回避できないルールを敷けるということです。

逆は成り立ちません。hookが許可を返しても、設定側の拒否ルールは優先されます。hooksは制限を厳しくできるが、緩める方向には働かないという原則を理解しておいてください。組織の管理設定による拒否は常に優先されます。

組織として運用する場合、この性質は重要な意味を持ちます。開発者ごとの判断で緩められない層を作れるため、統制の要件がある企業でもエージェント型のツールを導入しやすくなります。

よくあるつまずき

発火しない場合、まず一覧を表示するコマンドで登録されているかを確認します。表示されていなければ、JSONの記述か置き場所に問題があります。表示されていればマッチャーの綴りを疑います。

スクリプトが実行できない場合、実行権限が付いているかを確認します。パスが解決できないケースも多いため、プロジェクトのディレクトリを指す変数を使って絶対パスで指定するのが確実です。

応答完了のイベントで無限に作業が続くという問題も起きます。既にhookが動いたかどうかを示す項目が入力に含まれているため、これを見て早期に終了させる処理を入れておきます。上限に達すると自動的に打ち切られる仕組みも用意されています。

hookが正しいJSONを返しているのにエラーになる場合、シェルの初期設定が原因のことがあります。起動時にメッセージを出力する設定が入っていると、その内容がhookの出力に混ざります。対話時のみ表示する形に書き換えれば解消します。

段階的に導入する

最初からすべてのイベントに設定しようとすると破綻します。危険なコマンドの遮断から始め、動作が安定してから自動整形、通知、ログの記録と広げていく順序が現実的です。

処理の重さにも配慮が必要です。実行前のイベントには軽い判定だけを置き、テストの実行のような時間のかかる処理は実行後に回します。展開にあたっては使い方の共有も欠かせません。学習設計はAI人材の育成方法と社内研修の設計手順で解説しています。

▼ メンバーが使いこなせる状態まで持っていきたい方へ 研修は座学だけでは定着しません。実際のコードベースを題材に手を動かす形式で、翌日から使える状態までを設計します。 ▶ 研修プログラムを相談する

まとめ

Claude Code hooksは、ライフサイクル上の特定の地点で必ずシェルコマンドを実行させる仕組みです。モデルの判断に左右されない点が最大の特徴で、CLAUDE.mdによる指示とは強制力の面で決定的に異なります。

イベントは20種類以上ありますが、まずはツールの実行前、実行後、通知の3つを押さえれば実務では足ります。設定はJSONファイルにhooksブロックを作り、イベント名、対象を絞るマッチャー、実行するコマンドを記述します。遮断したい場合は終了コード2、細かく制御したい場合は構造化した出力を使います。

実用例としては、危険な操作の遮断、編集後の自動整形、入力待ちの通知、操作ログの記録が定番です。注意点として、hookは制限を厳しくできるものの、設定側の拒否ルールを覆すことはできません。危険操作の遮断から始めて段階的に広げる進め方が、最も失敗の少ない導入手順になります。

▼ 最初の一歩を、一緒に設計します AIを使った開発は、任せる範囲と守りの設計で成果が大きく変わります。愛媛・東京を拠点に、AI研修と開発支援の両面から企業のAI活用を伴走しています。 ▶ お問い合わせ・無料相談はこちら