>>使うほど資産になる「JAPAN AI AGENT」の詳細はこちら<<

Claude Code Hooksとは？全30種イベントの設定方法と実践活用例を徹底解説

Claude Code Hooksとは？

Claude Code Hooksは、AIコーディングエージェント「Claude Code」のライフサイクル上で自動実行されるユーザー定義の処理です。2026年に入りイベント数は全30種へ拡大し、ハンドラータイプも5種に増えたことで、コード品質の自動担保からセキュリティ制御まで幅広い用途をカバーできるようになりました。

しかし、Claude Code Hooksとはそもそもどのような仕組みなのか、CLAUDE.mdとはどう使い分けるのか、具体的にどのイベントをどう設定すればよいのか、といった疑問を持つ方も多いのではないでしょうか。

本記事では、Claude Code Hooksの基本概念から全30種のイベント一覧、5種のハンドラータイプ、settings.jsonによる設定方法、実践的なユースケース集、そしてセキュリティ上の注意点やデバッグ手法まで、JAPAN AIが網羅的に解説します。

目次

Claude Code Hooksとは

Claude Code Hooksは、Claude Codeのライフサイクルにおける特定のタイミングで自動実行されるユーザー定義の処理です。セッションの開始・終了、ツールの呼び出し前後、応答完了時といったイベントに対して、シェルコマンドやHTTPリクエストなどの処理を紐づけることで、開発ワークフローを決定論的に制御できます。

ここで重要な点は「決定論的」という特性です。CLAUDE.mdに記述したルールはLLM（大規模言語モデル）の判断を介するため、指示が無視される可能性がゼロではありません。一方で、Claude Code Hooksはイベント発火時にプログラムとして確実に実行されるため、フォーマッターの自動適用や危険なコマンドのブロックといった処理を100%の確実性で担保できます。

なお、Claude Code Hooksは2026年に入り急速に機能が拡充されています。2026年6月時点でイベント数は全30種、ハンドラータイプは5種に拡大しており、従来のシェルコマンド実行に加えてHTTPリクエストやMCPツール呼び出し、サブエージェント生成まで対応しています。

開発現場においてAIエージェントの出力品質を安定させ、セキュリティリスクを低減するうえで、Claude Code Hooksは不可欠な基盤機能といえます。

Claude Codeとは？
Claude Codeとは？できること・料金・使い方を初心者向けに解説

Git Hooksとの違い

Claude Code Hooksは、エンジニアにとって馴染みの深いGit Hooksと設計思想を共有しつつ、紐づくライフサイクルが根本的に異なる仕組みです。

Git Hooksはリポジトリのライフサイクル、すなわちcommitやpush、mergeといったGit操作のタイミングで発火します。pre-commitフックでlintを走らせたり、pre-pushフックでテストを実行したりする使い方が一般的です。対してClaude Code Hooksは、AIエージェントのライフサイクルに紐づきます。プロンプトの送信やツールの呼び出し前後、応答の完了、セッションの開始・終了といった、AIが作業を進める各段階で発火する点が決定的な違いです。

つまり、Git Hooksが「人間の操作」を起点に発火するのに対し、Claude Code Hooksは「AIの動作」を起点に発火します。両者は競合するものではなく、Git Hooksでコミット前のチェックを行い、Claude Code Hooksでコード生成時の品質を担保するという形で補完的に運用できます。

CLAUDE.mdとHooksの使い分け

CLAUDE.mdとClaude Code Hooksは、確率的な「お願い」と決定論的な「強制実行」という本質的な違いで使い分けます。

CLAUDE.mdはプロジェクトのルールやコーディング規約をMarkdown形式で記述するファイルです。Claude Codeはこの内容をコンテキストとして読み込み、指示に従おうとします。しかし、あくまでLLMの推論を通じて解釈されるため、複雑な指示や長大なルールセットでは意図どおりに守られない場合があります。

一方、Claude Code Hooksはプログラムとして実行されるため、設定した処理は確実に動作します。「ファイル保存後にprettierを実行する」「rm -rfコマンドをブロックする」といった処理は、LLMの判断に関係なく毎回同じ結果を返します。

実務上の使い分け基準は明確です。コーディングスタイルの方針やアーキテクチャの指針など「守ってほしいが、文脈に応じた判断の余地がある」ルールはCLAUDE.mdに記述します。フォーマッターの実行や危険コマンドのブロックなど「例外なく必ず実行すべき」処理はClaude Code Hooksで定義します。この使い分けにより、AIの柔軟性を活かしながら品質とセキュリティの最低ラインを確実に守れます。

なぜClaude Code Hooksを設定したほうがいいのか

Claude Code Hooksを設定することで、AIエージェントの出力品質・安全性・運用効率を決定論的に底上げできます。以下の5つのメリットが、導入を推奨する主な理由です。

  • コード品質の自動担保
  • 危険な操作の即時防止
  • 通知による作業効率の向上
  • 監査ログの自動記録
  • チーム運用の標準化

まず、コード品質の自動担保です。PostToolUseイベントでフォーマッターやlintを自動実行すれば、Claude Codeが生成するすべてのコードに対してスタイルの統一と構文チェックが適用されます。手動でのフォーマット忘れや、レビュー時の指摘工数を大幅に削減できます。

そして、危険な操作の即時防止です。PreToolUseイベントでrm -rfやgit push –forceといった破壊的コマンドをブロックすれば、AIが誤って実行するリスクをゼロにできます。LLMの判断に依存しない安全弁として機能します。

通知による作業効率の向上も見逃せません。Stopイベントやnotificationイベントでデスクトップ通知やSlack通知を設定すれば、長時間タスクの完了を即座に把握できます。Claude Codeにタスクを任せている間、別の作業に集中できるようになります。

監査ログの自動記録は、チーム開発やコンプライアンス対応で威力を発揮します。PostToolUseやSessionEndイベントでツール実行履歴をJSONL形式で記録すれば、誰がいつどのような操作をAIに実行させたかを追跡可能です。

また、チーム運用の標準化も理由の一つです。.claude/settings.jsonをリポジトリにコミットすることで、チーム全員に同一のHooks設定を適用できます。個人の設定漏れや設定ミスによる品質のばらつきを防ぎ、開発プロセスの一貫性を確保できます。

Hookイベントの種類

Claude Code Hooksでは、2026年6月時点で全30種のイベントがAIエージェントのライフサイクル全体をカバーしています。各イベントはセッション系からプロンプト系、ツール系やエージェント系、コンテキスト系に大別でき、開発者は必要なタイミングに応じて適切なイベントを選択できます。

  • セッション系: SessionStart、SessionEnd、Setup、Stop、StopFailure
  • プロンプト系: UserPromptSubmit、UserPromptExpansion、MessageDisplay
  • ツール系: PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch、PermissionRequest、PermissionDenied
  • エージェント系: SubagentStart、SubagentStop、TeammateIdle、TaskCreated、TaskCompleted
  • コンテキスト系: InstructionsLoaded、ConfigChange、CwdChanged、FileChanged、WorktreeCreate、WorktreeRemove、PreCompact、PostCompact、Notification、Elicitation、ElicitationResult

以下では、開発現場で特に使用頻度の高いClaude Code Hooksの主要イベントについて詳しく解説します。

PreToolUse

PreToolUseは、Claude Codeがツールを実行する直前に発火するイベントであり、セキュリティ制御の要です。

このイベントの最大の特徴は、フックスクリプトの終了コード（Exit Code）によってツール実行の可否を制御できる点にあります。Exit Code 0をstdout出力なしで返せば、フックが報告する決定がないことを意味し、通常の権限フローに従って処理を続行します。

Exit Code 2を返せばツール実行をブロックし、stderrの内容がClaudeにエラーメッセージとしてフィードバックされます。0と2以外の終了コード（Exit Code 1など）は非ブロッキングエラーとして扱われ、stderrの最初の行が「hook error」通知としてユーザーに表示されたうえで処理が続行されます。

matcherフィールドでツール種別を指定できるため、Bashコマンドのみ、Editツールのみといった粒度で制御対象を絞り込めます。たとえば、matcherに「Bash」を指定してrm -rfを含むコマンドをブロックするフックを設定すれば、ファイル編集ツールには影響を与えずにBashコマンドだけを監視できます。

PreToolUseはツール実行を事前にブロックできるイベントであるため、破壊的操作の防止やアクセス制御の実装に最適です。

PostToolUse

PostToolUseは、ツールが正常に実行された直後に発火するイベントであり、コード品質の自動担保に最適です。

ファイル編集ツール（EditやWrite）が実行された直後にフォーマッターやlintを走らせることで、Claude Codeが生成・編集したコードに対して即座にスタイル統一と構文チェックを適用できます。matcherに「Edit|Write」を指定すれば、ファイル変更を伴うツールだけを対象にできます。

PostToolUseで受け取るstdin JSONにはtool_nameやtool_inputの情報が含まれるため、対象ファイルのパスや拡張子に応じて実行するフォーマッターを切り替える処理も実装可能です。たとえば、.pyファイルにはblackを、.tsファイルにはprettierを適用するといった条件分岐が実現できます。

コード品質を「生成時点で」担保する仕組みとして、PostToolUseは最も費用対効果の高いイベントです。

Stop

Stopは、Claudeの応答が完了した時点で発火するイベントであり、品質ゲートや通知の起点として活用されます。

Claude Codeが1つのタスクを完了するたびに発火するため、最終的な成果物に対するチェック処理を挿入するのに適しています。テストスイートの実行やビルドの検証、型チェックの実施といった「タスク完了時の品質ゲート」をStopイベントに設定すれば、不完全な状態での作業終了を防止できます。Exit Code 2を返すとClaudeに作業の継続を強制できるため、テストが失敗した場合に自動で修正を続けさせるといった運用も可能です。

また、Stopイベントはデスクトップ通知やSlack通知のトリガーとしても広く使われています。長時間のコード生成タスクをClaude Codeに任せている間に別の作業を進め、タスク完了を通知で受け取るという運用は、開発者の生産性を大きく向上させます。

Stopイベントはmatcherをサポートしておらず、すべての応答完了時に発火します。matcherフィールドを追加してもサイレントに無視されるため、発火条件を絞り込みたい場合はフックスクリプト内で条件分岐を実装する必要があります。

Notification

Notificationは、Claude Codeが通知を送信するタイミングで発火するイベントです。権限の確認待ちやアイドル状態など、ユーザーの注意を引く必要がある場面を検知できます。

matcherで通知タイプを指定でき、permission_prompt（権限確認ダイアログ）、idle_prompt（アイドル状態）、auth_success（認証成功）などのタイプに応じて異なる処理を実行できます。

macOSではosascriptコマンド、Linuxではnotify-sendコマンドを使ったデスクトップ通知が一般的な活用例です。Webhook URLへのHTTP POSTによるSlack通知と組み合わせれば、開発者がターミナルから離れていてもClaude Codeの状態変化を即座に把握できます。

Notificationイベントは「Claude Codeが助けを求めている」タイミングを逃さないための仕組みとして、特にバックグラウンド実行時に重宝します。

SessionStart・SessionEnd

SessionStartとSessionEndは、Claude Codeのセッション開始時と終了時にそれぞれ発火するイベントです。開発環境のセットアップと作業記録の自動化に適しています。

SessionStartのmatcherではstartup（新規開始）、resume（再開）、clear（クリア）、compact（圧縮）を指定でき、セッションの開始方法に応じて異なる処理を実行できます。たとえば、新規セッション開始時にのみ環境変数の設定やDockerコンテナの起動を行い、再開時にはスキップするといった制御が可能です。

SessionEndではセッション中の作業サマリーをログファイルに記録したり、一時ファイルのクリーンアップを実行したりする用途に活用できます。matcherにはclear、resume、logoutなどの終了理由を指定でき、正常終了と異常終了で異なる後処理を実装することも可能です。

セッション単位での環境管理と記録を自動化することで、開発者は作業の開始・終了時の定型作業から解放されます。

出典:Anthropic「Claude Code Hooks」

5種類のハンドラータイプ

Claude Code Hooksでは、イベント発火時に実行する処理の種類として5種類のハンドラータイプが用意されています。用途に応じて最適なタイプを選択することで、シンプルなシェルスクリプトから高度なAI判断まで柔軟に対応できます。

ハンドラータイプtype値特徴主な用途
コマンドcommandシェルコマンドを実行。stdin経由でJSON入力を受け取り、Exit Codeとstdoutで結果を返すフォーマッター実行、スクリプト実行、ログ記録
HTTPhttp指定URLへHTTP POSTでイベントJSONを送信。レスポンスボディで結果を返すSlack通知、外部API連携、Webhook
MCPツールmcp_tool接続済みMCPサーバー上のツールを呼び出す。テキスト出力をstdoutと同様に処理外部サービス連携、データベース操作
プロンプトpromptClaudeモデルへプロンプトを送信し、単一ターンの評価を実行。yes/no判定をJSONで返すコードレビュー、ポリシー準拠チェック
エージェントagentRead/Grep/Globなどのツールを使えるサブエージェントを生成し、条件検証と判定を行う複雑な条件判定、ファイル横断チェック

コマンドタイプは最も基本的なハンドラーで、多くのユースケースに対応します。HTTPタイプはSlack通知や外部サービスへのデータ送信に適しており、サーバー側でリクエストを処理する柔軟性を持ちます。MCPツールタイプは、すでにMCPサーバーを運用している環境で既存のツール資産を活用する場合に有効です。

プロンプトタイプとエージェントタイプは2026年に追加された新しいハンドラーで、AIの判断力をフック処理に組み込めます。プロンプトタイプはシンプルなyes/no判定に、エージェントタイプはファイルを横断した複雑な条件検証に適しています。ただし、エージェントタイプは実験的機能であり、今後仕様が変更される可能性がある点に留意が必要です。

各ハンドラーにはtimeoutフィールドで実行時間の上限を設定できます。デフォルト値はcommand/http/mcp_toolが600秒、promptが30秒、agentが60秒です。パフォーマンスへの影響を最小限に抑えるため、用途に応じた適切なタイムアウト値の設定が推奨されます。

出典:Anthropic「Claude Code Hooks」

AIを活用した業務自動化を実現するなら「JAPAN AI AGENT」

Claude Code Hooksのように、AIエージェントの動作を制御・自動化する仕組みは、開発現場だけでなくビジネス全般の業務効率化にも通じる考え方です。JAPAN AI AGENTは、特定のタスクを自律的に実行する「AI社員」を誰でも簡単に対話形式のノーコードで作成できるプラットフォームです。ChatGPTやClaude、Geminiなど最新のAIモデルに対応し、Microsoft 365やSlackなど20以上のツールとの連携により、業務フローの自動化を実現します。上場企業水準のセキュリティ体制のもと、10,000社以上の支援実績を持つ専任担当が導入から定着までを伴走します。

日本企業のための
最も実用的なAIエージェントへ！

AIが企業の様々な職種の
方々が
普段行っている
タスクを自律的に実行

JAPAN AI AGENT

実用性の高いAIエージェンを提供

無料の伴走サポート

高いカスタマイズ性

目標設定をだけで自律的にAIが各タスクを実行

資料請求はこちら

Claude Code Hooksの設定方法

Claude Code Hooksの設定は、settings.jsonファイルにJSON形式でフック定義を記述することで完了します。設定ファイルの配置場所によってスコープが変わるため、個人利用とチーム共有の使い分けが重要です。

設定ファイルの場所

Claude Code Hooksの設定ファイルは、開発者が直接設定する主要な3つの配置場所によって適用範囲が異なります。さらに、管理ポリシー設定（組織全体）、プラグイン、スキルやエージェントのフロントマターからもフックを定義できます。ここでは主要な3箇所を解説します。

配置場所パス適用範囲Git管理
ユーザー設定~/.claude/settings.jsonすべてのプロジェクト対象外
プロジェクト共有.claude/settings.json単一プロジェクトコミット可能
プロジェクトローカル.claude/settings.local.json単一プロジェクト.gitignore推奨

ユーザー設定（~/.claude/settings.json）は、マシン上のすべてのプロジェクトに適用されるグローバルな設定です。デスクトップ通知やSlack通知など、プロジェクトを問わず共通で使いたいフックを定義するのに適しています。

プロジェクト共有（.claude/settings.json）は、リポジトリにコミットすることでチームメンバー全員に同一のフック設定を適用できます。フォーマッターの自動実行や危険コマンドのブロックなど、プロジェクト固有のルールを定義する場所です。

プロジェクトローカル（.claude/settings.local.json）は、個人的な設定を記述するためのファイルです。.gitignoreに追加してバージョン管理から除外することで、個人の好みに応じたカスタマイズをチーム設定と分離できます。

基本的な設定構造

Claude Code Hooksの設定は、イベント名、マッチャー、ハンドラーの3層構造で記述します。最小構成のサンプルコードは以下のとおりです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/your-script.sh"
          }
        ]
      }
    ]
  }
}

最上位のhooksオブジェクトの中に、イベント名をキーとして配列を定義します。配列の各要素はマッチャーグループと呼ばれ、matcherフィールドで発火条件を絞り込み、hooksフィールドに実行するハンドラーを1つ以上定義します。

1つのイベントに対して複数のマッチャーグループを定義でき、1つのマッチャーグループに対して複数のハンドラーを定義できます。ハンドラーは定義順に実行されるため、フォーマッターを実行してからlintを走らせるといった順序制御も可能です。

マッチャーの指定方法

matcherフィールドは、フックが発火するツールやイベントの種類を絞り込むフィルターです。

matcherの記述ルールは3パターンに分かれます。「*」、空文字、または省略した場合はすべてのツールにマッチします。英数字とアンダースコア、パイプ（|）のみで構成される文字列は完全一致として評価されます。それ以外の文字を含む場合はJavaScript正規表現として評価されます。

matcher値評価方法マッチ対象の例
Bash完全一致Bashツールのみ
Edit|Write完全一致（OR）EditまたはWriteツール
^Notebook正規表現Notebookで始まるツール
mcp__memory__.*正規表現memoryサーバーの全ツール

MCPツールを対象にする場合は「mcp__サーバー名ツール名」の命名パターンに従います。サーバーの全ツールにマッチさせるにはmcpサーバー名.*のように正規表現を使用する必要があり、mcpサーバー名のような完全一致指定ではマッチしない点に注意が必要です。

環境変数の活用

Claude Code Hooksの実行時には、フックスクリプト内で参照可能な環境変数が自動的にエクスポートされます。

主要な環境変数として、CLAUDE_PROJECT_DIR（プロジェクトのルートディレクトリパス）が挙げられます。この環境変数を使うことで、フックスクリプト内でプロジェクト固有のファイルパスを動的に解決できます。設定ファイル内でも${CLAUDE_PROJECT_DIR}の形式でパスプレースホルダーとして参照可能です。

HTTPタイプのハンドラーでは、headersフィールド内で$VAR_NAMEまたは${VAR_NAME}の形式で環境変数を補間できます。ただし、セキュリティ上の理由からallowedEnvVarsフィールドに明示的に許可した変数のみが補間対象です。許可されていない変数は空文字に置換されます。

{
  "type": "http",
  "url": "https://example.com/hooks",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

環境変数を活用することで、APIトークンやWebhook URLなどの機密情報をsettings.jsonにハードコードせずに管理できます。

条件付き実行（ifフィールド）

ifフィールドは、ツールイベントにおいてフックの実行条件をさらに細かく制御するための機能です。

matcherがツールの種類（BashやEditなど）で発火対象を絞り込むのに対し、ifフィールドはツールの入力内容に基づいて実行可否を判定します。権限ルール構文で条件を記述し、条件にマッチした場合のみフックが実行されます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

上記の例では、Bashツールが呼び出される際に、コマンドがrm *にマッチする場合のみフックスクリプトが実行されます。ifフィールドがない場合はmatcherの条件を満たすすべてのツール呼び出しでフックが実行されるため、不要なプロセス起動を減らしパフォーマンスを改善できます。

ifフィールドはPreToolUseやPostToolUse、PostToolUseFailure、PermissionRequest、PermissionDeniedのツールイベントでのみ評価されます。それ以外のイベントでは、ifフィールドが設定されたフック自体が実行されないため注意が必要です。

出典:Anthropic「Claude Code Hooks」

入出力仕様とExit Codeによる制御

Claude Code Hooksの入出力は、stdin経由のJSON入力とExit Code・stdout JSONによる出力という統一的な仕様で設計されています。この仕様を正しく理解することで、フックスクリプトの実装精度が大きく向上します。

コマンドタイプのフックが実行されると、イベントに関するコンテキスト情報がJSON形式でstdinに渡されます。ツールイベントの場合、tool_name（ツール名）やtool_input（ツールへの入力内容）といったフィールドが含まれます。フックスクリプトはこのJSONをパースし、必要な情報を取り出して処理を行います。

フックの実行結果は、Exit Code（終了コード）とstdoutへのJSON出力の2つの経路で返されます。Exit Codeの仕様は以下のとおりです。

Exit Code動作用途
0成功（決定なし）。stdout出力がない場合はフックが報告する決定がないことを意味し、通常の権限フローに従って処理を続行する。stdoutにJSONを出力した場合はその内容に応じた制御（permissionDecisionによるapproveやdeny等）が行われるフック内でログ記録やフォーマッターを実行し、ツール実行自体は通常どおり進行させる場合
1（その他）非ブロッキングエラー。「hook error」通知としてstderrの最初の行がユーザーに表示され、処理は続行する。stdoutは無視されるエラーログの記録（ユーザーへの即時フィードバックにはExit Code 0 + stdout JSONが適切）
2ブロッキングエラー。stderrの内容がClaudeにエラーメッセージとしてフィードバックされる。ブロック可能なイベントではアクションをブロックし、ブロック不可のイベントではstderrを表示して処理を続行する危険コマンドの防止、アクセス制御、品質ゲート

Exit Code 2によるブロックは、PreToolUseやStop、UserPromptSubmit、SubagentStop、PreCompact、PostToolBatch、PermissionRequestなどのイベントで有効です。PreToolUseではツール実行をブロックし、Stopではクロードに作業の継続を強制します。PostToolUseなどブロック非対応のイベントでExit Code 2を返した場合は、非ブロッキングエラーとして処理が続行されます。イベントごとのExit Code 2の挙動は公式ドキュメントで確認してください。

stdoutにJSON形式で出力を返す場合、hookSpecificOutputフィールド内にhookEventName、permissionDecision、permissionDecisionReasonを含めることで、ブロック理由をClaude Codeに伝達できます。以下はPreToolUseでツール実行を拒否する出力の例です。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}

HTTPタイプのハンドラーでも同様のJSON形式でレスポンスボディを返すことで、ブロックや警告の制御が可能です。2xx以外のHTTPステータスコード、接続失敗、タイムアウトの場合は非ブロッキングエラーとして処理が続行されるため、外部サービスの障害がClaude Codeの動作を停止させることはありません。

入出力仕様を把握しておくことで、単純なコマンド実行からJSON解析を伴う高度な条件判定まで、目的に応じたフックスクリプトを正確に実装できます。

出典:Anthropic「Claude Code Hooks」

実践的な設定例・ユースケース集

Claude Code Hooksの設定方法と入出力仕様を理解したところで、開発現場ですぐに導入できる実践的な設定例を紹介します。各ユースケースにsettings.jsonのサンプルコードを掲載しているため、自身の環境に合わせてカスタマイズしてご活用ください。

ファイル編集後の自動フォーマット

PostToolUseイベントを使った自動フォーマットは、最も導入効果の高い基本的なHook設定です。

Claude Codeがファイルを編集するたびにフォーマッターを自動実行することで、コードスタイルの統一を手動作業なしで実現できます。以下の設定例では、EditまたはWriteツールの実行後にstdinのJSONからファイルパスを取得し、prettierを適用しています。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(cat | jq -r \".tool_input.file_path\"); if [ -n \"$FILE\" ] && [ -f \"$FILE\" ]; then prettier --write \"$FILE\" 2>/dev/null || true; fi'"
          }
        ]
      }
    ]
  }
}

このスクリプトでは、stdinで渡されるJSONのtool_input.file_pathフィールドからjqで対象ファイルのパスを抽出しています。公式にエクスポートされる環境変数にファイルパスは含まれていないため、stdin経由のJSON解析が正しい取得方法です。末尾の|| trueは、prettierが対応していないファイル形式でもExit Code 0を返すための記述です。

Pythonプロジェクトではprettierの代わりにblackを、Goプロジェクトではgofmtを指定するなど、言語やプロジェクトに応じてフォーマッターを差し替えてください。

危険なコマンドの実行ブロック

PreToolUseイベントを使った危険コマンドのブロックは、AIエージェントの暴走を防ぐ安全弁として機能します。

以下の設定例では、Bashツールの実行前にコマンド内容を検査し、rm -rfやgit push –forceなどの破壊的コマンドを検出した場合にExit Code 2でブロックします。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'CMD=$(cat | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"rm\\s+-rf|git\\s+push.*--force|sudo\\s+rm\"; then echo \"{\\\"hookSpecificOutput\\\":{\\\"hookEventName\\\":\\\"PreToolUse\\\",\\\"permissionDecision\\\":\\\"deny\\\",\\\"permissionDecisionReason\\\":\\\"Destructive command blocked\\\"}}\" && exit 2; fi'"
          }
        ]
      }
    ]
  }
}

このフックはstdinからJSON入力を受け取り、jqでコマンド文字列を抽出し、grepで危険パターンを検出しています。マッチした場合はstdoutにブロック理由をJSON形式で出力し、Exit Code 2で終了します。

ブロック対象のパターンはプロジェクトの要件に応じて追加・変更してください。本番環境への直接デプロイコマンドやデータベースのDROPコマンドなど、チームのポリシーに合わせたカスタマイズが推奨されます。

デスクトップ通知

StopイベントまたはNotificationイベントを使ったデスクトップ通知は、長時間タスクの完了を即座に把握するための設定です。以下はmacOS環境でosascriptを使用する設定例です。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Codeのタスクが完了しました\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Linux環境ではosascriptの代わりにnotify-sendコマンドを使用します。

"command": "notify-send 'Claude Code' 'タスクが完了しました'"

Stopイベントはすべての応答完了時に発火するため、短い質問への回答でも通知が表示されます。長時間タスクのみに通知を限定したい場合は、Notificationイベントのidle_promptマッチャーを使用するか、フックスクリプト内でセッションの実行時間を判定するロジックを追加してください。

Slack通知連携

StopイベントまたはNotificationイベントとコマンドハンドラーを組み合わせることで、Slack Webhookを通じたチーム全体への通知を実現できます。

HTTPハンドラーはイベントのJSON入力をそのままPOSTボディとして送信するため、Slack Incoming Webhookが期待する{“text”: “…”}形式とは異なります。Slackに直接通知する場合は、以下のようにコマンドタイプのハンドラーでcurlを使い、ペイロードを整形して送信する方法を推奨します。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST -H 'Content-type: application/json' --data '{\"text\":\"Claude Codeのタスクが完了しました\"}' $SLACK_WEBHOOK_URL"
          }
        ]
      }
    ]
  }
}

Webhook URLを環境変数で管理すれば、settings.jsonに機密情報を直接記述せずに運用できます。HTTPハンドラーを使用する場合は、Slack側でイベントJSONを受け取って整形するサーバーサイドの処理を別途用意するか、AWS LambdaやCloudflare Workersなどの中間レイヤーを挟む構成を検討してください。

監査ログの自動記録

PostToolUseやSessionEndイベントを使った監査ログの自動記録は、チーム開発やコンプライアンス対応に不可欠な仕組みです。

以下の設定例では、ツール実行のたびにタイムスタンプとツール情報をJSONL形式でログファイルに追記します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); echo \"{\\\"timestamp\\\":\\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\\",\\\"event\\\":\\\"PostToolUse\\\",\\\"data\\\":$INPUT}\" >> ${CLAUDE_PROJECT_DIR}/.claude/audit.jsonl'"
          }
        ]
      }
    ]
  }
}

JSONL（JSON Lines）形式は1行1レコードで追記できるため、ログの解析や集計が容易です。jqコマンドやPythonスクリプトで特定期間のツール実行回数を集計したり、特定のツールの使用頻度を分析したりする用途に活用できます。

チーム全体の監査ログを集約する場合は、HTTPハンドラーで社内のログ収集サーバーにデータを送信する構成も検討してください。

lint・型チェックの自動実行

PostToolUseイベントを使ったlintや型チェックの自動実行は、コード品質をリアルタイムに検証する仕組みです。

以下の設定例では、stdinのJSONからファイルパスを取得し、TypeScriptファイルに対してESLintと型チェックを自動実行しています。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(cat | jq -r \".tool_input.file_path\"); if [[ \"$FILE\" == *.ts || \"$FILE\" == *.tsx ]]; then npx eslint --fix \"$FILE\" 2>/dev/null; npx tsc --noEmit 2>/dev/null || true; fi'"
          }
        ]
      }
    ]
  }
}

自動フォーマットの設定例と同様に、対象ファイルのパスはstdinで渡されるJSONのtool_input.file_pathフィールドからjqで抽出しています。Pythonプロジェクトではflake8やmypyに、Goプロジェクトではgo vetやgolangci-lintに差し替えてください。

フォーマッターとlintを併用する場合は、フォーマッター→lintの順にハンドラーを定義することで、フォーマット後のコードに対してlintが実行される正しい順序を担保できます。

Claudeの利用制限やプラン別の機能差について詳しく知りたい方は、「Claudeの制限を徹底解説！5時間・週間制限の仕組みからプラン別比較・回避策まで」の記事で詳しく解説しています。

セキュリティに関する注意点

Claude Code Hooksを安全に運用するためには、設定ファイルの信頼性管理とパフォーマンスへの影響を適切にコントロールする必要があります。

Hookは軽量に保つ

Claude Code Hooksの処理が重いと、Claude Code全体の応答速度に直接影響するため、フックスクリプトは軽量に保つことが鉄則です。

フックはClaude Codeのイベントループ内で同期的に実行されるため、フックの処理時間がそのままClaude Codeの待機時間に加算されます。たとえば、PostToolUseでプロジェクト全体のテストスイートを毎回実行するような設定は、ファイル編集のたびに数十秒の待ち時間を生み出します。

軽量に保つためのベストプラクティスとして、フォーマッターやlintは対象ファイルのみに適用し、プロジェクト全体のスキャンは避けてください。重い処理はStopイベント（応答完了時）に集約し、ツール実行ごとに発火するPostToolUseでは最小限の処理に留めます。timeoutフィールドを適切に設定し、想定外の長時間実行を防止することも重要です。

フックの実行時間を定期的に計測し、ボトルネックを特定する習慣をつけておくと、開発体験の劣化を未然に防げます。

スコープの使い分け

Claude Code Hooksの設定ファイルは3つのスコープを持つため、個人開発とチーム開発で適切に使い分けることがセキュリティと利便性の両立につながります。

チーム開発では、.claude/settings.jsonにプロジェクト共通のフック設定を定義し、リポジトリにコミットします。フォーマッターの自動実行や危険コマンドのブロックなど、チーム全員が統一して適用すべきルールはここに記述します。

個人的な通知設定やデバッグ用のフックは、.claude/settings.local.jsonに記述し、.gitignoreに追加してバージョン管理から除外します。Webhook URLやAPIトークンなどの機密情報を含む設定も、ローカルファイルに分離することで情報漏洩リスクを低減できます。

信頼できないプロジェクトのリポジトリをクローンする際は、.claude/settings.jsonの内容を確認してからClaude Codeを起動してください。悪意のあるフック設定が含まれている場合、任意のコマンドが実行される可能性があります。ユーザー設定（~/.claude/settings.json）でグローバルな安全策を定義しておくことで、プロジェクト単位のリスクを軽減できます。

Hookのデバッグとトラブルシューティング

Claude Code Hooksが期待どおりに動作しない場合は、/hooksコマンドと–debug-fileオプションを使った段階的な原因特定が有効です。

まず、Claude Codeのセッション内で/hooksコマンドを実行してください。現在有効なフック設定の一覧が表示され、設定ファイルの読み込み状況やマッチャーの定義内容を確認できます。設定ファイルのパスが間違っている場合や、JSON構文エラーがある場合は、この段階で問題を特定できます。

次に、–debug-fileオプションを付けてClaude Codeを起動すると、フックの実行ログが指定したファイルに出力されます。どのイベントが発火し、どのマッチャーが評価され、フックスクリプトがどのようなExit Codeを返したかを時系列で追跡できます。

よくあるエラーパターンと対処法は以下のとおりです。

  • フックが発火しない: matcherの指定が正しいか確認する。完全一致と正規表現の評価ルールを再確認し、意図したツール名にマッチしているかテストする
  • JSON構文エラー: settings.jsonのJSON構文をjq .で検証する。カンマの過不足や括弧の対応関係が原因であることが多い
  • フックスクリプトの権限エラー: スクリプトファイルに実行権限（chmod +x）が付与されているか確認する
  • 環境変数が空になる: HTTPハンドラーの場合、allowedEnvVarsに変数名を明示的に追加しているか確認する
  • ifフィールドが機能しない: ifフィールドはツールイベント（PreToolUse、PostToolUseなど）でのみ評価される。それ以外のイベントではifフィールドが設定されたフック自体が実行されない

フックスクリプト自体のデバッグは、Claude Codeの外で単体テストを行うのが効率的です。想定されるJSON入力をファイルに保存し、echo ‘{“tool_name”:”Bash”,”tool_input”:{“command”:”rm -rf /”}}’ | ./your-hook.shのようにstdinからパイプで渡して動作を確認してください。

出典:Anthropic「Claude Code Hooks」

Claude Code Hooksに関してよくある質問

Hooksの設定はチームメンバーと共有できますか？

はい、.claude/settings.jsonをGitリポジトリに含めることでチーム全員に同一のフック設定を共有できます。フォーマッターの自動実行や危険コマンドのブロックなど、プロジェクト共通のルールはこのファイルに定義してください。個人固有の設定（通知先のWebhook URLやデバッグ用フックなど）は.claude/settings.local.jsonに記述し、.gitignoreに追加することでバージョン管理から除外できます。この2層構造により、チーム共通の品質基準と個人のカスタマイズを両立できます。

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

フックコマンドの失敗時の動作は、Exit Codeによって異なります。Exit Code 2はブロッキングエラーとして扱われ、PreToolUseではツール実行をブロックし、Stopでは作業の継続を強制するなど、イベントごとに異なる制御が行われます。ブロック非対応のイベントでExit Code 2を返した場合は、stderrを表示して処理が続行されます。0と2以外の終了コード（Exit Code 1など）は非ブロッキングエラーとして扱われ、stderrの最初の行が「hook error」通知としてユーザーに表示されたうえで処理が続行されます。フックスクリプト自体がクラッシュした場合やタイムアウトした場合も、Claude Codeの処理は中断されずに続行されます。–debug-fileオプションでログを確認すると、エラーの詳細を把握できます。

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

まずCLAUDE.mdでプロジェクトのルールやコーディング規約を定義し、その中で「例外なく必ず守らせたい」ルールをClaude Code Hooksで強制実行する段階的なアプローチを推奨します。最初に導入するフックとしては、PostToolUseでのフォーマッター自動実行が最も効果を実感しやすい設定です。フォーマッターの設定に慣れたら、危険コマンドのブロックやデスクトップ通知を段階的に追加していくことで、無理なくHooksの活用範囲を広げられます。CLAUDE.mdとHooksは競合するものではなく、確率的な指示と決定論的な制御を組み合わせることで、AIエージェントの出力品質を最大化できます。

Claude Code Hooksで開発ワークフローを強化しよう

本記事では、Claude Code Hooksの基本概念から全30種のイベント一覧、5種のハンドラータイプ、設定方法、実践的なユースケース、セキュリティ上の注意点、デバッグ手法までを解説しました。要点を以下にまとめます。

  • Claude Code Hooksは、AIエージェントのライフサイクル上で決定論的に処理を自動実行する仕組みであり、CLAUDE.mdの確率的な指示を補完する
  • 全30種のイベントと5種のハンドラータイプにより、コード品質の担保からセキュリティ制御、通知、監査ログまで幅広い用途をカバーする
  • settings.jsonの3つのスコープ（ユーザー、プロジェクト共有、プロジェクトローカル）を使い分けることで、個人設定とチーム設定を適切に分離できる
  • まずはPostToolUseでのフォーマッター自動実行から導入し、段階的にフックを追加していくアプローチが効果的である

Claude Code Hooksは、AIコーディングエージェントを「使いこなす」ための制御基盤です。適切に設定することで、コード品質の安定化、セキュリティリスクの低減、開発者体験の向上を同時に実現できます。まずは自動フォーマットの設定から始め、開発ワークフローの強化に取り組んでみてください。

公式ドキュメントの最新情報はClaude Code Hooks公式ドキュメントで確認してください。

前の記事

FDE（Forward Deployed Engineer）とは？
FDE（Forward Deployed Engineer）と…