Claude Code Hooksとは？設定方法や活用例を解説

「Claude Codeに毎回フォーマッターをかけるよう頼むのが手間」「機密ファイルをAIが誤って編集しないか不安」「チームで統一したルールを守らせたい」
こうした悩みを持つ開発者の方は少なくないでしょう。Claude Code Hooksは、こうした課題を「決定論的な自動化」で解決する機能です。プロンプトでの指示と異なり、設定したルールは100%確実に実行されます。

本記事では、Claude Code Hooksの基本概念から17種類のライフサイクルイベント、具体的な設定手順、実践的な活用パターン、そしてセキュリティ対策や料金体系まで、公式ドキュメントの情報に基づいて徹底的に解説します。

✅Claude Codeの基本的な使い方や全体像については、以下の記事で詳しく解説しています。あわせてご覧ください。
Claude Codeとは？主な特徴や使い方、料金体系・拡張機能まで徹底解説

Claude Code Hooksとは？

このセクションでは、Claude Code Hooksの基本概念と、なぜこの機能が開発ワークフローにおいて重要なのかを解説します。

Claude Code Hooksとは、Claude Codeのライフサイクルの特定のタイミングで自動実行される、ユーザー定義のシェルコマンドです。Anthropicの公式ドキュメント（Hooksリファレンス）では、「Claude Codeの動作に対して決定論的な制御を提供し、LLMに実行を選択させるのではなく、特定のアクションが常に実行されることを保証する」機能と説明されています。

たとえば、「ファイルを編集した後に必ずフォーマッターを実行する」「機密ファイルへの書き込みをブロックする」「すべてのBashコマンドをログに記録する」といった処理を、プロンプトで毎回指示するのではなく、設定ファイルに一度書いておくだけで自動化できます。

Claude Code Hooksの設計思想

Claude Code Hooksの最大の特徴は、決定論的な動作保証にあります。プロンプトでの指示はLLMの判断に依存するため、忘れたり無視されたりする可能性があります。一方、Hooksで設定したルールは、対応するイベントが発生するたびに必ず実行されます。

つまり、「お願い」を「ルール」に変えるのがHooksの役割です。この違いは、特にチーム開発やセキュリティ要件が厳しい環境で大きな意味を持ちます。

Claude Code Hooksの3つのタイプ

公式ドキュメント（Hooksリファレンス）によると、Claude Code Hooksには3つのタイプがあります。以下の表で、それぞれの特性を整理しました。

ここで注目すべきは、用途に応じて3つのタイプを使い分けられる点です。明確なルール（「.envファイルへの書き込みは常にブロック」など）にはコマンド型が適しており、文脈に応じた柔軟な判断（「すべてのタスクが完了しているか」など）にはプロンプト型が適しています。さらに、テスト実行やコードレビューなど複数ステップの検証が必要な場面では、エージェント型がサブエージェントをスポーンしてマルチターンで検証を行うことで、より高度な自動化を実現できます。

Claude Code Hooksが解決する課題

このセクションでは、従来のAIコーディングワークフローにおける課題と、Claude Code Hooksがどのようにそれらを解決するのかを説明します。

AIコーディングツールの利便性は飛躍的に向上していますが、その一方で次のような課題が開発現場で繰り返し発生しています。

• 手動の繰り返し作業
  
  ファイルを編集するたびにフォーマッターやリンターを手動で実行する必要がある。プロンプトで「prettierを実行して」と毎回指示しても、LLMが忘れることがある
  
  

• セキュリティの不確実性
  
  .envファイルやpackage-lock.jsonなど、AIが誤って変更してはいけないファイルを確実に保護する仕組みがない。プロンプトで「触らないで」と伝えても、複雑なタスクの途中で無視されるリスクが残る
  
  

• チーム全体のルール統一が困難
  
  コーディング規約やコミット前のチェックをチームメンバー全員に徹底させることが難しい。個人の設定漏れや、プロンプトの書き方のばらつきが品質のムラにつながる
  
  

• 監査・ログの不足
  
  AIが実行したコマンドや変更の履歴を自動的に記録する仕組みがなく、後からの追跡やコンプライアンス対応が難しい
  
  

Claude Code Hooksは、これらの課題に対して「プロンプトへの依存」から「設定ファイルによる確実な自動化」への転換を実現します。一度設定すれば、対応するイベントが発生するたびに必ず実行されるため、人為的な忘れやLLMの判断揺れを排除できるのです。

Claude Code Hooksのライフサイクルイベント一覧

このセクションでは、Claude Code Hooksが対応する全17種類のイベントと、それぞれの用途を解説します。どのタイミングでHooksを発火させるかを正しく選ぶことが、効果的な自動化の第一歩です。

公式ドキュメント（Hooksリファレンス）によると、Claude Code Hooksは以下の17種類のライフサイクルイベントに対応しています。以下の表で各イベントの概要と想定される活用シーンをまとめました。

ここで注目すべきは、イベントの粒度の細かさです。「ツール実行前」と「ツール実行後」を分けることで、たとえば「ファイル書き込み前に保護対象かチェックし、書き込み後にフォーマッターを実行する」という一連の流れを自然に構築できます。

頻出イベントの詳細

17種類のうち、最もよく使われるのは以下の3つです。

PreToolUse は、Claudeがツールを使う直前に発火します。ここでHooksが終了コード2を返すと、そのツール呼び出し自体がブロックされます。つまり、機密ファイルの保護やコマンド検証といった「ガードレール」の設置に適しています。マッチャーには Bash、Write、Edit、Read などのツール名を指定でき、正規表現にも対応しています。

PostToolUse は、ツールが正常に完了した直後に発火します。ファイルの自動フォーマットや、変更内容のログ記録など、「後処理」の自動化に向いています。ツールはすでに実行済みのため、この段階でブロックすることはできませんが、Claudeに対するフィードバックの送信は可能です。

Stop は、Claudeが応答を終えようとするタイミングで発火します。プロンプト型のHooksと組み合わせることで、「すべてのタスクが完了したか」をLLMに評価させ、不十分であれば作業を続行させることができます。

Claude Code Hooksの設定方法

このセクションでは、Claude Code Hooksの具体的な設定手順を、初めて使う方にもわかりやすく解説します。

設定ファイルの保存場所

公式ドキュメント（Hooksリファレンス）によると、Claude Code Hooksの設定は以下の6箇所に保存できます。チームで共有するルールと個人の設定を分離できる点が特徴です。

ここで注目すべきは、プロジェクト設定（.claude/settings.json）はGitで管理できるため、チーム全体でHooksのルールを共有・統一できる点です。一方、個人的な通知設定やデバッグ用のHooksはローカル設定に入れることで、他のメンバーに影響を与えません。さらに、管理ポリシー設定を活用すれば、IT管理者が組織全体に統一されたフックルールを適用でき、プラグインフックやスキル/エージェント内の定義も含めると、幅広い粒度での管理が可能です。

/hooksコマンドを使った対話的な設定

最も手軽な方法は、Claude Code上で /hooks スラッシュコマンドを使う方法です。公式ガイド（フックの使い始め）では、以下の手順が紹介されています。

1. Claude Codeを起動し、/hooks と入力する
2. フックイベント（例：PostToolUse）を選択する
3. マッチャーを追加する（例：Edit|Write でファイル編集・書き込み時のみ発火）
4. 実行するコマンドを入力する
5. 保存先（ユーザー設定 / プロジェクト設定 / ローカル設定）を選択する
6. Escキーで戻る

JSON設定ファイルを直接編集する方法

より細かい制御が必要な場合は、設定ファイルを直接編集します。以下は、TypeScriptファイルの編集後にPrettierを自動実行するHooksの設定例です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

このアプローチの利点は、複数のHooksを一括で管理できることと、Gitでバージョン管理できることです。チームメンバーがリポジトリをクローンすれば、同じルールがすぐに適用されます。

マッチャーの指定方法

マッチャーは、どのツール呼び出しでHooksを発火させるかを制御します。以下の表にパターンをまとめました。

マッチャーは大文字小文字を区別するため、Write と write は異なるツールとして扱われます。正確なツール名は公式ドキュメントで確認することを推奨します。

Claude Code Hooksの実用パターンと活用例

このセクションでは、実際の開発現場で役立つHooksの設定パターンを、難易度別に紹介します。公式ガイド（フックの使い始め）に掲載されている例を中心に、実務で想定される場面を解説します。

パターン1：ファイル編集後の自動フォーマット（初級）

最も基本的かつ効果の大きい活用パターンです。Claude Codeがファイルを編集・作成するたびに、自動的にフォーマッターを実行します。

使用するイベントは PostToolUse で、マッチャーは Edit|Write です。以下は公式ガイドに掲載されている設定例です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

この設定では、stdinから受け取ったJSONデータからファイルパスを抽出し、拡張子が .ts の場合にのみPrettierを実行します。Go言語であれば gofmt、Pythonであれば black など、言語に応じたフォーマッターに差し替えることも可能です。

このパターンの利点は、フォーマッターの実行忘れを完全に防げることです。プロンプトで「フォーマットもお願い」と依頼する必要がなくなるため、開発のテンポも改善します。

パターン2：機密ファイルの保護（初級）

.envファイルやpackage-lock.json、.gitディレクトリなど、AIが編集すべきでないファイルへの書き込みをブロックするパターンです。

使用するイベントは PreToolUse で、マッチャーは Edit|Write です。以下は公式ガイドに掲載されている設定例です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

終了コード2を返すことで、Claudeに対してツール呼び出し自体をブロックし、その理由をフィードバックします。Claude側はブロック理由を受け取り、別のアプローチを試みます。

パターン3：Bashコマンドのログ記録（初級）

コンプライアンスやデバッグのために、Claude Codeが実行するすべてのBashコマンドをファイルに記録するパターンです。

使用するイベントは PreToolUse で、マッチャーは Bash です。公式ガイドのクイックスタートで紹介されている設定です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

監査要件のある環境では、このログ機能は大きな安心材料になります。タイムスタンプを付与する拡張も容易です。

パターン4：セッション開始時の環境変数設定（中級）

SessionStartイベントを使い、セッション開始時に必要な環境変数を自動的に読み込むパターンです。

公式ドキュメントによると、SessionStart Hooksでは CLAUDE_ENV_FILE という環境変数にアクセスでき、このファイルに書き込んだ変数はセッション中のすべてのBashコマンドで利用可能になります。

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"
fi
exit 0

この仕組みを使えば、nvmでのNode.jsバージョン切り替えや、プロジェクト固有の環境変数の設定を自動化できます。

パターン5：インテリジェントなStop Hook（上級）

プロンプト型のHooksを使い、Claudeが作業を終了する前に「本当にすべてのタスクが完了したか」をLLMに評価させるパターンです。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

このパターンでは、デフォルトではHaikuモデルが呼び出され（modelフィールドで変更可能）、会話の文脈を分析してタスクの完了度を判定します。ただし、公式ドキュメントでは stop_hook_active フラグを確認して無限ループを防ぐことが推奨されています。

手動ワークフローとClaude Code Hooksの比較

このセクションでは、Hooksを使わない従来の手動ワークフローと、Hooksを導入した場合の違いを具体的に比較します。

以下の表で、代表的な作業における違いを整理しました。

この表からわかるように、Hooks導入の最大の利点は「確実性」と「省力化」です。とくに、手動で行っていた反復的な作業を自動化することで、開発者はより本質的なタスクに集中できるようになります。

一方で、Hooksが向かない場面も存在します。一回限りの特殊な作業や、頻繁に変わるルールについては、プロンプトで都度指示するほうが柔軟です。Hooksの設定変更にはセッションの再起動やレビューが必要になるため、固定的なルールの自動化に適していると言えるでしょう。

Claude Code Hooksの注意点とセキュリティ対策

このセクションでは、Claude Code Hooksを安全に運用するための注意点と、公式が推奨するセキュリティ対策を解説します。

セキュリティ上のリスク

公式ドキュメント（Hooksリファレンス）では、Hooksのセキュリティについて以下の免責事項が明記されています。

• Hooksはシステム上で任意のシェルコマンドを自動的に実行する
• 設定したコマンドについては、ユーザーが単独で責任を負う
• 悪意のある、または不適切に書かれたHooksはデータ損失やシステム損害を引き起こす可能性がある
• Anthropicはhookの使用から生じるいかなる損害についても責任を負わない

つまり、Hooksは強力な機能である反面、設定ミスや悪意あるスクリプトの混入には十分な注意が必要です。

公式が推奨するセキュリティのベストプラクティス

公式ドキュメントでは、以下のベストプラクティスが推奨されています。

• 入力を検証およびサニタイズする
  
  stdinから受け取るJSONデータを盲目的に信頼せず、想定外の値に対する処理を実装する
  
  

• シェル変数を常にクォートする
  
  VAR ではなく "VAR" を使い、スペースを含むパスなどでのエラーを防ぐ
  
  

• パストラバーサルをブロックする
  
  ファイルパスに .. が含まれていないかを検証し、意図しないディレクトリへのアクセスを防止する
  
  

• 絶対パスを使用する
  
  スクリプトの参照にはフルパスを指定する。プロジェクト内のスクリプトには $CLAUDE_PROJECT_DIR 変数を活用する
  
  

• 機密ファイルへのアクセスを避ける
  
  Hooks内で .env や .git/、APIキーファイルなどを読み取らないよう設計する
  
  

設定変更の安全機構

Claude Code Hooksには、設定ファイルの改ざんを防ぐ仕組みが組み込まれています。具体的には、Claude Codeはセッション開始時にHooksのスナップショットを取得し、セッション中はそのスナップショットに基づいて動作します。セッション中にHooksが外部から変更された場合は警告が表示され、/hooks メニューでのレビューが必要になります。

この仕組みにより、悪意のあるHook変更が現在のセッションに即座に影響することを防いでいます。

エンタープライズ向けの管理機能

企業向けには、管理ポリシー設定で allowManagedHooksOnly を有効にすることで、ユーザーが独自にHooksを追加することを禁止し、管理者が承認したHooksのみを実行させることが可能です。これにより、組織全体のセキュリティポリシーとの整合性を確保できます。

デバッグと動作確認

Hooksが正しく動作しているかを確認する方法として、公式ドキュメントでは以下が推奨されています。

1. /hooks コマンドでHooksの登録状態を確認する
2. JSON設定の構文が正しいかを検証する
3. Hookコマンドを手動で実行してテストする
4. スクリプトに実行権限があるかを確認する
5. claude --debug で詳細なログを確認する

特に、新しいHooksを追加した際は、本番環境に適用する前にテスト環境で十分に動作を検証することが重要です。

Claude Code Hooksの料金

このセクションでは、Claude Code Hooksに関連する料金体系を解説します。

Claude Code Hooks自体に追加料金は発生しません。 HooksはClaude Codeの標準機能として含まれており、設定や利用にあたって個別の課金はありません。

ただし、Claude Code Hooks を利用するには、Claude Code本体が使えるプランに加入している必要があります。2026年2月時点のプラン構成は以下の通りです。

なお、プロンプト型のHooks（type: prompt）を使用する場合、内部的にHaikuモデルへのAPIコールが発生しますが、これもプランの利用枠に含まれます。Hooksの利用頻度が非常に高い場合は、利用枠の消費が通常より早まる可能性がある点にご留意ください。

最新の料金情報は、公式の料金ページ（https://claude.com/pricing ）でご確認ください。

【関連記事】
▶︎Claude Codeの料金体系ガイド！利用制限や確認・可視化方法を解説

まとめ

本記事では、Claude Code Hooksの基本概念から設定方法、活用例、セキュリティ対策、料金体系までを解説しました。最後に、要点を振り返ります。

Claude Code Hooksは、AIコーディングツールの動作を**「お願い」から「ルール」に変える**ための仕組みです。プロンプトに依存した不確実な指示ではなく、設定ファイルに基づく決定論的な自動化により、開発ワークフローの品質と効率を向上させます。

導入を検討される方には、以下のステップをおすすめします。

1. まずは /hooks コマンドから、ファイル編集後の自動フォーマット（PostToolUse）を1つ設定してみる
2. 効果を実感できたら、機密ファイルの保護（PreToolUse）やコマンドログの記録を追加する
3. チームで運用する場合は、プロジェクト設定（.claude/settings.json）にHooksを定義し、Gitで共有する

Hooks自体に追加料金は不要で、Claude Codeのプランに含まれています。まずは小さなルールから始めて、徐々に自動化の範囲を広げていくのがよいでしょう。

より詳しい設定方法やイベントの仕様については、公式ドキュメント（Hooksリファレンス、フックの使い始め）をご参照ください。