Claude Code Hooksで開発を自動化する方法｜フック設計パターンと実装ガイド

——Claude Codeを使い込んでいくと、「ファイルを保存するたびにlintを走らせたい」「Bashコマンド実行前にセキュリティチェックを挟みたい」といった要望が必ず出てきます。そんなときに威力を発揮するのが、Claude Code Hooksです。詳しくは「Claude Codeでチーム開発を効率化する方法」で解説しています。

Hooksは、Claude Codeのライフサイクルの特定のタイミングでユーザー定義のシェルコマンドを自動実行できる仕組みです。Gitのpre-commitフックに馴染みがある方なら、その概念をClaude Codeの操作全体に拡張したものだとイメージしてください。LLMの承認を介さず、決定論的に実行されるため、セキュリティゲートや品質チェックの自動化に最適です。AI活用完全ガイドで、AI活用の全体像を把握できます。

出典: Anthropic公式ドキュメント: Hooks

本記事では、Claude Code Hooksの全フックポイントを体系的に整理し、コードレビュー自動実行・テスト自動起動・Slack通知連携などの実装パターンを、実際の設定ファイル（.claude/settings.json）のコード例とともに解説します。詳しくは「Claude Codeの企業導入セキュリティガイド」で解説しています。

この記事でわかること

• Claude Code Hooksの基本的な仕組みと、従来のGitフックやCI/CDとの違い
• PreToolUse / PostToolUse / Notification / Stop など全フックポイントの役割と使い分け
• .claude/settings.json でのフック定義の書き方と、マッチャーによる条件分岐
• コードレビュー自動実行、テスト自動起動、Slack通知連携などの実装パターン10選
• HubSpot CMS開発やCRM連携プロジェクトでのHooks活用シーン

Claude Code Hooksとは何か

従来のワークフロー自動化との違い

開発の自動化といえば、Gitフック（pre-commit, pre-push）やCI/CDパイプライン（GitHub Actions, CircleCI）が一般的です。これらは「Gitの操作」をトリガーとして処理を走らせます。詳しくは「Claude Code × CI/CD」で解説しています。

Claude Code Hooksは、それとはトリガーのレイヤーが異なります。「AIエージェントの操作」をトリガーとして処理を走らせるのです。

ここが結構ミソなのですが、Claude Code HooksはLLMの判断を経由しません。設定した条件に合致すれば、シェルコマンドが決定論的に実行されます。つまり、AIが「実行しなくても大丈夫そう」と勝手に判断してスキップすることがないのです。セキュリティチェックや必須テストの実行を確実に担保したい場面で、これは非常に重要な特性です。

Hooksのアーキテクチャ

Claude Code Hooksの動作原理はシンプルです。

1. Claude Codeが特定のアクション（ファイル書き込み、Bash実行など）を行おうとする
2. そのアクションに対応するフックポイントが発火する
3. 設定されたマッチャー条件を評価する
4. 条件に合致すれば、定義されたシェルコマンドを実行する
5. フックの結果（成功/失敗/出力）に応じて、Claude Codeの後続動作が決まる

フックコマンドには、環境変数として$CLAUDE_TOOL_NAME（使用ツール名）、$CLAUDE_TOOL_INPUT（ツール入力のJSON）、$CLAUDE_FILE_PATHS（対象ファイルパス）などが渡されるため、コンテキストに応じた条件分岐が可能です。

全フックポイントの一覧と使い分け

Claude Code Hooksには、以下のフックポイントが用意されています。

PreToolUse — 「実行前にゲートを設ける」

PreToolUseは、Claude Codeがツール（Write, Bash, Edit など）を実行する直前に発火します。フックコマンドが非ゼロの終了コードを返した場合、そのツール実行はブロックされます。

実務で最も使用頻度が高いフックポイントです。本番環境への誤操作防止、禁止コマンドの実行ブロック、特定ディレクトリへの書き込み制限など、「やってはいけないこと」をハードウェア的に防止できます。

PostToolUse — 「実行後に自動チェックを走らせる」

PostToolUseは、ツール実行が完了した直後に発火します。ファイル書き込みの後にlintを実行する、Bashコマンド実行後にテストを走らせるといった「事後チェック」に使います。

フックの標準出力はClaudeのコンテキストに注入されるため、lintエラーの内容をClaudeがそのまま認識して自動修正に取り掛かる、という流れを作れます。

Notification — 「通知を外部に飛ばす」

Notificationフックは、Claude Codeがユーザーに対して通知を送る際に発火します。長時間タスクの完了通知やエラー通知を、Slackやメール、デスクトップ通知として転送するのに使います。

Stop — 「応答完了時に最終処理を実行する」

Stopフックは、Claude Codeが応答を完了した（ターンが終わった）タイミングで発火します。作業結果の最終バリデーション、ログ記録、後続タスクのトリガーに使います。

settings.jsonでのフック定義の書き方

Hooksは.claude/settings.json（プロジェクトスコープ）または ~/.claude/settings.json（ユーザースコープ）で定義します。

基本構造

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validation-script.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ]
  }
}

マッチャーの仕組み

matcherフィールドは、どのツール呼び出しに対してフックを発火させるかを指定します。

マッチャーはツール名の部分一致で評価されます。たとえば"Bash"はBashツールにマッチしますが、"Read"には当然マッチしません。

環境変数の活用

フックコマンド内では、以下の環境変数が利用できます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"ファイル書き込み検知: $CLAUDE_FILE_PATHS\" >> /tmp/claude-audit.log"
          }
        ]
      }
    ]
  }
}

実装パターン10選 — 実務で使えるHooks設計

パターン1: 本番環境への誤操作防止

最も基本的かつ重要なパターンです。rm -rfやgit push --forceなど、破壊的コマンドの実行をブロックします。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo $CLAUDE_TOOL_INPUT | jq -r '.command' | grep -qE '(rm -rf /|git push.*--force.*main|DROP TABLE)' && echo 'BLOCKED: 破壊的コマンドの実行は禁止されています' && exit 1 || exit 0"
          }
        ]
      }
    ]
  }
}

このフックは、Bashツールの入力をパースし、危険なパターンにマッチした場合に非ゼロで終了することで実行をブロックします。

パターン2: ファイル保存時の自動lint

ファイルを書き込んだ直後にESLintやPrettierを自動実行し、コードスタイルを統一します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo $CLAUDE_FILE_PATHS | tr '\\n' ' ' | xargs -I{} npx eslint --fix {}"
          }
        ]
      }
    ]
  }
}

ここが結構ミソなのですが、PostToolUseの標準出力はClaudeのコンテキストに自動注入されます。つまり、lintエラーがあればClaudeがそれを認識し、次のアクションで自動修正に動いてくれます。人間が介在しなくても「書く→検証→修正」のループが自動で回るのです。

パターン3: テスト自動実行

ソースコードが変更されたら、関連するテストを自動実行します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo $CLAUDE_FILE_PATHS | grep -qE '\\.(ts|tsx|js|jsx)$'; then npm test -- --related $CLAUDE_FILE_PATHS 2>&1 | tail -20; fi"
          }
        ]
      }
    ]
  }
}

--relatedフラグ（Jest）を使うことで、変更されたファイルに関連するテストだけを実行し、フィードバックループを高速に保ちます。

パターン4: Slack通知連携

Claude Codeの通知をSlackチャンネルに転送します。長時間タスクの完了を待つ間、別の作業に集中できます。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL -H 'Content-Type: application/json' -d \"{\\\"text\\\": \\\"Claude Code: $CLAUDE_NOTIFICATION\\\"}\""
          }
        ]
      }
    ]
  }
}

Shopifyのエンジニアリングチームは、このパターンを応用して開発通知の一元管理を実現しています。チーム全体でClaude Codeを活用する場合、通知の集約は運用効率を大きく左右します。

パターン5: 特定ディレクトリへの書き込み制限

設定ファイルやインフラ定義など、変更を制限したいディレクトリへの書き込みをブロックします。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo $CLAUDE_FILE_PATHS | grep -qE '(^\\.env|/\\.env|\\.credentials/|/secrets/)'; then echo 'BLOCKED: 機密ファイルへの書き込みは禁止されています' && exit 1; fi"
          }
        ]
      }
    ]
  }
}

パターン6: コミット前の自動コードレビュー

Stopフックを使い、Claude Codeの作業完了時に変更差分のレビューサマリーを自動生成します。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "git diff --stat HEAD 2>/dev/null | tail -5"
          }
        ]
      }
    ]
  }
}

パターン7: 監査ログの自動記録

全ツール実行を監査ログとして記録します。コンプライアンス要件がある環境や、チームでの利用状況を把握したい場合に有効です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date -Iseconds) | Tool: $CLAUDE_TOOL_NAME | Files: $CLAUDE_FILE_PATHS\" >> ~/.claude/audit.log"
          }
        ]
      }
    ]
  }
}

パターン8: HubSpot CMS開発でのHubL構文チェック

HubSpot CMSのテーマ開発では、HubLテンプレートの構文ミスが厄介です。PostToolUseでHubLファイルの変更を検知し、構文チェックを走らせます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo $CLAUDE_FILE_PATHS | grep -qE '\\.(html|hubl)$'; then echo '=== HubLテンプレート変更検知 ===' && grep -c '{%\\|{{' $CLAUDE_FILE_PATHS && echo 'HubL構文要素を検出しました。hs preview で表示確認を推奨します。'; fi"
          }
        ]
      }
    ]
  }
}

HubSpot CMSのテーマ開発にClaude Codeを活用する方法については、Claude CodeとMCPサーバー連携の実践ガイドでも詳しく解説しています。

パターン9: TypeScript型チェックの自動実行

TypeScriptプロジェクトでは、ファイル変更のたびに型チェックを走らせることで、型エラーの早期発見が可能です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo $CLAUDE_FILE_PATHS | grep -qE '\\.tsx?$'; then npx tsc --noEmit --pretty 2>&1 | tail -15; fi"
          }
        ]
      }
    ]
  }
}

パターン10: macOSデスクトップ通知

Slackを使わない個人開発の場合は、macOSのネイティブ通知を使うのが手軽です。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e \"display notification \\\"$CLAUDE_NOTIFICATION\\\" with title \\\"Claude Code\\\"\""
          }
        ]
      }
    ]
  }
}

HubSpot開発・CRM連携での活用シーン

Claude Code Hooksは、HubSpotエコシステムでの開発にも自然に組み込めます。

API呼び出しのレートリミット監視

HubSpot APIには、1日あたりのリクエスト上限（Professional以上で500,000リクエスト/日）があります。PostToolUseフックでAPI呼び出し回数をカウントし、閾値に近づいたら警告を出すことで、レートリミットへの到達を未然に防げます。

CRMプロパティ変更の監査

HubSpot CRMのプロパティ設計は、一度運用が始まると変更の影響範囲が大きくなります。プロパティ作成・更新のAPIコールをPreToolUseフックで検知し、変更内容をログに記録することで、「誰がいつ何を変えたか」のトレーサビリティを確保できます。

CRMプロパティ設計のベストプラクティスについては、Claude Codeを非エンジニアが活用する方法でも触れていますので、あわせてご参照ください。

ワークフロー定義ファイルの保護

HubSpotのワークフロー設定をコードで管理している場合、ワークフロー定義ファイルへの意図しない変更をPreToolUseフックでブロックできます。本番環境のワークフローが予期せず変更されるリスクを構造的に排除できるため、チーム開発での安全性が大幅に向上します。

Hooks設計のベストプラクティス

スコープの使い分け

Hooksの設定は3つのスコープで管理できます。

チームで統一すべきルール（セキュリティチェック、lint設定）はプロジェクトスコープに、個人の通知設定やローカル環境固有の設定はユーザースコープまたはプロジェクトローカルに配置します。

フックコマンドの実行時間に注意する

フックコマンドは同期的に実行されるため、時間のかかるコマンドはClaude Codeの応答速度に直接影響します。以下の指針を意識してください。

• PreToolUse: 1秒以内に完了するコマンドに限定する。ブロック判定はシンプルなgrep/jqで行う
• PostToolUse: 長時間かかるテストは--relatedなどで対象を絞る。フルテストスイートはStopフックで実行する
• Stop: フルビルドやE2Eテストなど、重い処理はここに集約する

エラーハンドリングの設計

PreToolUseフックが失敗（非ゼロ終了）した場合、そのツール実行はブロックされ、標準エラー出力（stderr）がClaude Codeのコンテキストに注入されます。これにより、Claudeは「なぜブロックされたか」を理解し、代替手段を提案できます。

一方、PostToolUseフックの失敗はツール実行自体には影響しません（既に実行済みのため）。ただし、出力はコンテキストに注入されるので、Claudeが問題を認識して修正アクションを取ることは可能です。

Hooksの制約と注意点

正直に言えば、Claude Code Hooksにはいくつかの制約があります。導入前に把握しておくべきポイントを整理します。

シェルコマンドに限定される

フックで実行できるのはシェルコマンドのみです。複雑なロジックを実装したい場合は、外部スクリプト（Python、Node.js等）を作成し、そのスクリプトをフックから呼び出す構成にする必要があります。

デバッグが難しい場合がある

フックの実行はClaude Codeのセッション内で行われるため、フックが期待通りに動作しない場合のデバッグが難しいことがあります。開発中はログファイルへの出力を追加し、動作を確認しながら設定を詰めていくアプローチが有効です。

チーム間での設定共有に注意

.claude/settings.jsonをGitリポジトリにコミットすることでチーム共有が可能ですが、メンバーのローカル環境（OS、インストール済みツール）の違いにより、フックコマンドが動作しない場合があります。クロスプラットフォーム対応が必要な場合は、フックコマンド内で環境判定を行うか、ラッパースクリプトを用意してください。

過剰なフック設定はパフォーマンスに影響する

全ツール呼び出しに対してフックを発火させると、Claude Codeの応答速度が低下します。マッチャーを適切に設定し、必要なツールに対してのみフックを発火させることが重要です。

今枝拓海の実務から見たHooks活用の勘所

私は日常的にClaude Codeを使ってHubSpot CRM連携やAPI開発を行っていますが、Hooksを導入して最も効果を感じたのは「ミスの構造的な排除」です。

たとえば、HubSpot APIの認証トークンを含む.envファイルへの書き込みをPreToolUseでブロックする設定は、一度入れてしまえば二度とそのミスは起きません。人間の注意力に頼るのではなく、仕組みで防ぐ。この考え方は、CRM運用の設計思想とも通じます。

HubSpotのワークフローやリードスコアリングも、「人間が毎回判断する」のではなく「ルールを設定して自動で動く」仕組みを作ることが本質です。Claude Code Hooksは、まさにその思想をAI開発ワークフローに持ち込んだものだと言えます。

Claude Codeのチーム開発への導入を検討されている方は、Claude Codeによるチーム開発の実践ガイドもあわせてご覧ください。

よくある質問

Q1. Claude Code HooksとGitフック（pre-commit等）は何が違いますか？

Gitフックはgit commitやgit pushといったGit操作をトリガーとしますが、Claude Code HooksはAIエージェントのツール呼び出し（ファイル書き込み、Bash実行など）をトリガーとします。つまり、コミット前だけでなく、AIがファイルを編集した瞬間や、コマンドを実行しようとした瞬間にチェックを挟めるのがClaude Code Hooksの特徴です。

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

はい。.claude/settings.jsonをGitリポジトリにコミットすることで、プロジェクト単位でチーム共有できます。個人固有の設定は.claude/settings.local.json（Git除外推奨）に分離できます。

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

PreToolUseフックが失敗（非ゼロ終了）した場合、そのツール実行はブロックされます。PostToolUseフックの場合は、ツール実行自体は完了しており、フックの出力がClaudeのコンテキストに注入されるだけです。いずれの場合も、Claude Codeのセッション全体がクラッシュすることはありません。

Q4. Windows環境でもHooksは使えますか？

Claude Code自体がmacOS / Linux / WSL2（Windows Subsystem for Linux）をサポートしており、Hooksもこれらの環境で動作します。フックコマンドはシェルで実行されるため、Windows環境ではWSL2経由での利用が前提となります。

Q5. Hooksの実行ログを確認する方法はありますか？

フックコマンド内でログファイルへの出力を明示的に記述する必要があります。たとえば >> ~/.claude/hooks.log 2>&1 をコマンド末尾に追加することで、実行ログを蓄積できます。Claude Codeの対話セッション内では、フックの標準出力がコンテキストに表示されるため、動作確認に利用できます。

Q6. 1つのフックポイントに複数のフックを設定できますか？

はい。各フックポイントの配列に複数のフック定義を追加できます。フックは定義順に実行され、PreToolUseの場合はいずれか1つが失敗すれば操作がブロックされます。

まとめ

Claude Code Hooksは、AIエージェントの操作をトリガーとした自動化レイヤーです。PreToolUseによるセキュリティゲート、PostToolUseによる品質チェックの自動実行、Notificationによる外部通知連携など、開発ワークフローの「守り」を構造的に強化できます。このテーマの全記事はClaude Code実践ガイドでご覧いただけます。

特にHubSpot CRM開発やAPI連携プロジェクトでは、認証情報の保護・APIレートリミットの監視・プロパティ変更の監査といった場面でHooksが力を発揮します。

Claude Codeの導入を検討中の方、あるいは既に使い始めている方は、まず「破壊的コマンドのブロック」と「ファイル保存時の自動lint」の2つから始めてみてください。この2つだけでも、日常の開発体験は大きく変わります。

CRM導入や開発ワークフローの自動化についてのご相談は、HubSpot認定パートナーである株式会社StartLinkまでお気軽にお問い合わせください。

関連記事:

• Claude Code × CI/CD｜パイプライン設計ガイド
• Claude CodeとMCPサーバー連携の実践ガイド
• Claude Codeによるチーム開発の実践ガイド
• Claude Codeを非エンジニアが活用する方法

外部参考リンク:

• Anthropic公式ドキュメント: Hooks
• Anthropic公式ドキュメント: Claude Code Overview