コンテンツへスキップ

media AI活用の最前線

14

【2026年最新】Claude Code Hooksガイド｜自動フォーマット・セキュリティゲート・テスト実行を設定する

【2026年最新】Claude Code Hooksガイド｜自動フォーマット・セキュリティゲート・テスト実行を設定する

結論: Claude Code Hooksは、Claudeがコードを操作する前後に自動的にスクリプトを実行できる機能で、自動フォーマット・セキュリティゲート・テスト実行をベストプラクティスとして強制できます。

この記事の要点:

  • 要点1: PreToolUseフックで危険な操作をブロックし、PostToolUseフックで自動フォーマットやリントを実行できる
  • 要点2: 設定はsettings.jsonに記述するだけで、Python・Node.js・Shellスクリプト全てに対応
  • 要点3: ソロ開発者はauto-formatter+security gateから始め、エンタープライズはCI/CDパイプラインへの統合が効果的

対象読者: Claude Codeを業務で使うエンジニア・開発チームリーダー・DevOpsエンジニア

読了後にできること: 今日からsettings.jsonにフックを設定して、Claudeが触るたびにコードが自動整形される環境を作れる

「Claudeが書くコードって、品質が安定しないんですよね」

ある研修先のシニアエンジニアから、こんな悩みを相談されました。Claudeに実装を任せると、コーディング規約に準拠していなかったり、セキュリティチェックを素通りしたりすることがある、と。確かに、Claudeは優秀ですが「毎回確実に同じ品質基準を守る」という保証がないのは事実です。

そこで試してもらったのが、Claude Code Hooksです。「Claudeがファイルを触ったら自動でruffでリント」「コミット前に必ずセキュリティスキャン」という仕組みを設定ファイルに記述するだけで、AIコーディングを本番品質に引き上げられます。

この記事では、Claude Code Hooksの設定方法から実践的なユースケース、エンタープライズ向け活用まで完全解説します。

即効テクニック1：Pythonファイルを自動整形するPostToolUseフック

最も簡単に効果を実感できるのが、ファイル保存後の自動フォーマットです。Claudeが.pyファイルを編集するたびにblackが自動実行されます。

# ~/.claude/settings.json に追加
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$CLAUDE_TOOL_INPUT' | jq -r '.file_path' | grep -q '.py$'; then black "$(echo '$CLAUDE_TOOL_INPUT' | jq -r '.file_path')" 2>&1; fi"
          }
        ]
      }
    ]
  }
}

不足している情報があれば最初に質問してから作業を開始してください。

即効テクニック2：危険なコマンドをブロックするPreToolUseフック

本番データベースへの直接アクセスや危険なrm -rfを事前にブロックできます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '$CLAUDE_TOOL_INPUT' | python3 -c "nimport sys, jsonncmd = json.load(sys.stdin).get('command', '')ndangerous = ['rm -rf /', 'DROP TABLE', 'DELETE FROM users', 'format c:']nif any(d in cmd for d in dangerous):n    print(f'BLOCKED: Dangerous command detected: {cmd}')n    sys.exit(2)n""
          }
        ]
      }
    ]
  }
}

即効テクニック3：コミット前のリント品質ゲート

Claudeがgit commitを実行しようとするたびに、自動的にリントを走らせます。問題があればコミットを阻止し、Claudeが自動修正を試みます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "cmd=$(echo '$CLAUDE_TOOL_INPUT' | jq -r '.command'); if echo "$cmd" | grep -q 'git commit'; then ruff check . --select E,F,W 2>&1 || exit 2; fi"
          }
        ]
      }
    ]
  }
}

Hooksは”3種のライフサイクルポイント”で考える

Claude Code Hooksを理解するには、Claudeがどのタイミングでフックが発火するかを把握することが重要です。

フックの種類発火タイミングアクション可能主なユースケース
PreToolUseツール実行の直前ブロック（exit 2）可能セキュリティゲート、危険操作防止、パラメータ検証
PostToolUseツール実行の直後ブロック不可（実行後）自動フォーマット、リント、テスト実行、通知送信
Stopセッション終了時終了処理最終検証、クリーンアップ、ログ保存

重要なのはPreToolUseだけがブロックできるという点です。PostToolUseは「実行後」なので、コードの変更を取り消すことはできません。セキュリティゲートや重要な品質チェックはPreToolUseで設定しましょう。

Claude Codeのエージェント活用全般については、AIエージェント導入完全ガイドで体系的に解説しています。

フックの設定方法：settings.jsonの基本構造

基本構文

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "ToolName",  // Write, Edit, Bash, Read等
        "hooks": [
          {
            "type": "command",
            "command": "実行するシェルコマンド"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",  // パイプで複数ツール指定可
        "hooks": [
          {
            "type": "command",
            "command": "実行するシェルコマンド"
          }
        ]
      }
    ]
  }
}

環境変数でツール情報を取得

フック実行中は、実行されたツールの情報が環境変数で参照できます。

環境変数内容
$CLAUDE_TOOL_NAMEツール名（Write, Edit, Bash等）
$CLAUDE_TOOL_INPUTツールへの入力パラメータ（JSON形式）
$CLAUDE_TOOL_OUTPUTツールの実行結果（PostToolUseのみ）
$CLAUDE_SESSION_ID現在のセッションID

exit codeによる動作制御

# exit 0: 正常終了（処理を続行）
exit 0

# exit 1: エラー（Claudeに警告を表示するが処理は続行）
echo "警告: コードにセキュリティの懸念があります" && exit 1

# exit 2: ブロック（PreToolUseのみ有効 — ツールの実行を中断）
echo "ブロック: 危険な操作が検出されました" && exit 2

AI活用、何から始めればいい？

100社以上の研修実績をもとに、30分の無料相談で貴社の課題を整理します。

無料相談はこちら →資料ダウンロード（無料）

実践レシピ：すぐ使えるフック集

レシピ1：TypeScript/JavaScriptの自動フォーマット（ESLint + Prettier）

TypeScript・JavaScriptプロジェクトで最もよく使われる組み合わせです。研修先のフロントエンドチームで採用してから、「Claudeが書いたコードがチームのスタイルガイドを自動的に満たすようになった」と好評でした。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(echo '$CLAUDE_TOOL_INPUT' | jq -r '.file_path // .path // empty'); if [ -n "$file" ] && echo "$file" | grep -qE '.(ts|tsx|js|jsx)$'; then npx prettier --write "$file" 2>/dev/null && npx eslint --fix "$file" 2>/dev/null; fi"
          }
        ]
      }
    ]
  }
}

レシピ2：Pythonプロジェクトの3段階品質チェック

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(echo '$CLAUDE_TOOL_INPUT' | jq -r '.file_path // .path // empty'); if [ -n "$file" ] && echo "$file" | grep -q '.py$'; then black "$file" 2>&1 && isort "$file" 2>&1 && ruff check "$file" --fix 2>&1; fi"
          }
        ]
      }
    ]
  }
}

レシピ3：Secretsの流出防止ゲート

APIキーやパスワードのハードコードを自動検出してブロックします。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "content=$(echo '$CLAUDE_TOOL_INPUT' | jq -r '.content // .new_string // empty'); if echo "$content" | grep -qE '(api_key|apikey|secret|password|token)s*=s*["x27][^"x27]{8,}'; then echo 'BLOCKED: ハードコードされた認証情報が検出されました。環境変数を使ってください。' && exit 2; fi"
          }
        ]
      }
    ]
  }
}

レシピ4：テスト自動実行（変更ファイルに対応するテストのみ）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(echo '$CLAUDE_TOOL_INPUT' | jq -r '.file_path // .path // empty'); if [ -n "$file" ] && echo "$file" | grep -q 'src/'; then test_file=$(echo "$file" | sed 's|src/|tests/|' | sed 's|.py$|_test.py|'); [ -f "$test_file" ] && python3 -m pytest "$test_file" -x -q 2>&1 | tail -20; fi"
          }
        ]
      }
    ]
  }
}

レシピ5：Slack通知フック（長時間タスク完了を知らせる）

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST "$SLACK_WEBHOOK_URL" -H 'Content-type: application/json' -d '{"text":"Claude Codeのセッションが完了しました。確認してください。"}' 2>/dev/null"
          }
        ]
      }
    ]
  }
}

【要注意】よくある失敗パターンと回避策

失敗1：フックが全ての操作に重い処理をかける

❌ 全てのWrite/Editフックでプロジェクト全体のテストを実行する
⭕ 変更されたファイルに対応するテストのみを実行する（上記レシピ4参照）

なぜ重要か: 1ファイルの変更ごとに全テストが走ると、Claude Codeの応答が何十秒も遅くなります。フックは「軽く速く」が原則。重い処理は「コミット時のみ」に限定するのが実践的です。

失敗2：PreToolUseのブロックが誤作動する

❌ 文字列マッチングが甘くて正常なコードもブロックされる
⭕ パターンは十分に絞り込み、テスト環境で動作確認してから本番導入

なぜ重要か: 顧問先でSecretsブロックフックが誤作動し、APIキーの変数名が含まれる設定ファイルのテンプレートまでブロックされる事態が起きました。正規表現は最初から十分な精度で設計してください。

失敗3：エラー出力を握りつぶす

❌ コマンドの末尾に2>/dev/nullを全部つけてしまい、エラーが見えない
⭕ フォーマットツールはstderrを通してClaudeに見せ、重要なエラーを把握させる

なぜ重要か: フォーマットエラーはClaudeが自動修正を試みる材料になります。エラーを隠すとClaudeが問題に気づけません。

失敗4：設定変更後に再起動を忘れる

❌ settings.jsonを変更したのにフックが動かない→原因が分からずハマる
⭕ settings.json変更後は必ずClaude Codeを再起動する

エンタープライズ向け：CI/CDパイプライン統合

Claude Codeの品質フックをCI/CDパイプラインと統合することで、AI生成コードも人間が書いたコードと同じ品質基準で管理できます。

GitHub Actionsとの連携例

# .github/workflows/claude-code-review.yml
name: Claude Code Quality Gate

on:
  pull_request:
    branches: [main, develop]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Claude Code hooks simulation
        run: |
          # ローカルフックと同じチェックをCIで実行
          black --check src/
          ruff check src/ --select E,F,W
          python3 -m pytest tests/ -x --tb=short

      - name: Security scan
        run: |
          pip install bandit
          bandit -r src/ -ll  # 中・高リスクのみ報告

このように、ローカルのClaude Codeフックと同じロジックをCIに入れることで、ローカルで問題なく通ったコードがCIでも確実にパスするようになります。

Hooks活用の効果測定

フックを導入後、どれくらい効果があったかを測定するのも重要です。

事例区分: 想定シナリオ
以下は100社以上の研修経験をもとに構成した典型的な効果です。

指標フック導入前フック導入後変化
PRのリント指摘件数/日平均12件平均2件83%減少
コードレビュー時間/PR平均45分平均28分38%短縮
本番へのSecret流出インシデント月1〜2件0件100%防止

（測定期間の目安：2〜3ヶ月間。チーム規模・プロジェクトの種類により大きく変動します。）

よくある質問（FAQ）

Q: フックはどのツールに対して設定できますか？

Claude Codeが使用できる全てのツールに対してフックを設定できます。主要なものは以下の通りです。

  • Write: 新規ファイル作成時
  • Edit: ファイル編集（一部変更）時
  • Bash: シェルコマンド実行時
  • Read: ファイル読み込み時
  • Glob: ファイルパターン検索時
  • Grep: コード内検索時
  • WebSearch: ウェブ検索時（Claude Codeに統合されている場合）

複数ツールをまとめてマッチさせる場合はパイプ（|）で区切ります（例: "matcher": "Write|Edit"）。空文字列（""）は全ツールにマッチします。

Q: フックのデバッグ方法は？

フックが期待通りに動かない場合、以下の手順でデバッグします。

# 1. フックコマンドを直接ターミナルでテスト
export CLAUDE_TOOL_INPUT='{"file_path": "src/test.py", "content": "print(hello)"}'
# フックのコマンドをそのまま実行して動作確認

# 2. デバッグログを追加
{
  "type": "command",
  "command": "echo "HOOK TRIGGERED: $CLAUDE_TOOL_NAME" >> /tmp/claude-hooks.log && [実際の処理]"
}

Q: フックが重くてClaude Codeが遅くなった場合は？

フックは同期的に実行されるため、重いフックはClaude Codeの応答を遅らせます。対策として：

  • フックを特定のファイル種別（.py$等）に限定する
  • 変更ファイルのサイズが小さい場合のみ実行する（wc -l < 500等の条件追加）
  • テスト実行はコミット時のみに絞る（毎回のEdit後には実行しない）
  • タイムアウトを設定する（timeout 10 コマンド）

Q: チームメンバー全員に同じフックを適用するには？

プロジェクトルートに.claude/settings.jsonを置くことで、そのプロジェクトを開いた全員に共通のフックが適用されます。ただし、~/.claude/settings.json（ホームディレクトリ）は個人設定として、プロジェクト設定より優先されます。チーム標準のフックはリポジトリ管理が推奨です。

Hooksと他のClaude Code機能との組み合わせ

Claude Code Hooksは、他の機能と組み合わせることで威力が増します。

Adaptive Thinkingとの組み合わせ

複雑なリファクタリングをultrathinkで実行しつつ、フックで品質を自動保証するパターンです。Claudeが深く考えながらコードを書き、書いた瞬間に自動整形・リント・テストが走ります。

# プロンプト例
ultrathinkして、以下のレガシーコードを現代的なパターンにリファクタリングしてください。

[レガシーコードを貼り付け]

フックが自動的に品質チェックを行います。テストが失敗した場合は、その原因を分析して修正してください。

Agent Teamsとの組み合わせ

Agent Teamsで並列実装しつつ、各メンバーの出力にフックが適用されるため、複数のコードエリアが同時に品質保証されます。研修先では「チームで並列実装、全員の出力にフックが同時適用、最後に統合テスト」という流れを「AI流CIパイプライン」と呼んで運用しています。

参考・出典

まとめ：今日から始める3つのアクション

  1. 今日やること: settings.jsonにPostToolUseのauto-formatterフックを1つ追加して、Claudeが.pyや.tsファイルを触ったら自動整形される環境を作る
  2. 今週中: PreToolUseのSecrets検出フックを追加し、ハードコード認証情報の流出リスクをゼロにする
  3. 今月中: チームのClaude Code標準フックセットを~/.claude/settings.jsonテンプレートとして整備し、新メンバーが同じ品質基準で使えるようにする

あわせて読みたい:

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。早稲田大学法学部在学中に生成AIの可能性に魅了され、X（旧Twitter）で活用法を発信（@SuguruKun_ai、フォロワー約10万人）。100社以上の企業向けAI研修・導入支援を展開。著書『AIエージェント仕事術』（SBクリエイティブ）。

ご質問・ご相談はお問い合わせフォームからお気軽にどうぞ。

佐藤傑
この記事を書いた人 佐藤傑

株式会社Uravation代表取締役。早稲田大学法学部在学中に生成AIの可能性に魅了され、X（旧Twitter）で活用法を発信（@SuguruKun_ai、フォロワー10万人超）。100社以上の企業向けAI研修・導入支援を展開。著書累計3万部突破。SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。

@SuguruKun_ai SoftBank IT連載 詳しいプロフィール
この記事をシェア

Claude Codeを本格的に使いこなしたい方へ

週1回・1時間のマンツーマン指導で、3ヶ月後にはClaude Codeで自走できる実力が身につきます。
現役エンジニアが貴方の業務に合わせてカリキュラムをカスタマイズ。

✓ 1対1のマンツーマン ✓ 全12回・3ヶ月 ✓ 実務ベースの指導
Claude Code 個別指導の詳細を見る まずは無料相談

関連サービス

🎓

生成AI研修

ChatGPT・Claude・Copilot等の実践型カスタマイズ研修。助成金対応。累計4,000名以上の実績。

 💼

AI顧問

AI戦略策定・ツール選定・業務改善を月額制で継続支援。ライト〜プレミアムの3プラン。

 🛠

AI受託開発

チャットボット・画像生成・OCR等のカスタムAIソリューション開発。

 📱

AI×SNS運用支援

AI活用でSNSコンテンツ企画・投稿作成・分析改善を効率化。

 🤖

AIエージェント導入支援

Claude Code・OpenClaw・Codex等をハーネス設計で安全に導入。

 🎯

Claude Code 個別指導

週1回・1時間のマンツーマン指導。3ヶ月12セッションで自走力を獲得。

関連記事

【2026年最新】Claude Code Agent Teams完全ガイド｜複数Claude並列実行で開発速度を劇的に上げる
14

【2026年最新】Claude Code Agent Teams完全ガイド｜複数Claude並列実行で開発速度を劇的に上げる
【2026年最新】Claude Adaptive Thinking完全ガイド｜4段階推論でビジネス品質を劇的に上げる方法
14

【2026年最新】Claude Adaptive Thinking完全ガイド｜4段階推論でビジネス品質を劇的に上げる方法
【速報】GPT-5.4完全解説｜100万トークン×PC操作で仕事が変わる
14

【速報】GPT-5.4完全解説｜100万トークン×PC操作で仕事が変わる

他のカテゴリのおすすめ

ツール比較・実践ガイド

【2026年最新】Claude Code プロンプト集30選｜コピペ可能なテンプレートと出力例
ツール比較・実践ガイド

【2026年最新】Claude Codeでできること20選｜開発・ビジネス・クリエイティブ・運用の全カテゴリ解説
ツール比較・実践ガイド

【2026年最新】Claude Code営業活用ガイド｜提案書・メール・CRM分析を自動化する5つのシーン

よく読まれている記事

  1. 1
    【2026年最新】Claude Code プロンプト集30選｜コピペ可能なテンプレートと出力例
  2. 2
    【2026年最新】Claude Codeでできること20選｜開発・ビジネス・クリエイティブ・運用の全カテゴリ解説
  3. 3
    【2026年最新】Claude Code営業活用ガイド｜提案書・メール・CRM分析を自動化する5つのシーン
  4. 4
    【2026年最新】Claude法人プラン完全比較｜Team・Enterprise・ChatGPT Teamを徹底解説
    【2026年最新】Claude法人プラン完全比較｜Team・Enterprise・ChatGPT Teamを徹底解説
  5. 5
    【2026年最新】Claude Code始め方完全ガイド｜インストールから新機能まで全解説
    【2026年最新】Claude Code始め方完全ガイド｜インストールから新機能まで全解説
記事一覧へ

contact お問い合わせ

生成AI研修や開発のご依頼、お見積りなど、
お気軽にご相談ください。

無料相談 事例を見る 資料ダウンロード

Claude Code 個別指導（1対1・12セッション）をご希望の方はこちらから別途お申し込みください

Claude Code 個別指導 無料相談