Claude Code Hooks 完全ガイド｜自動化と品質ゲートを仕込む方法

Q: 既存プロジェクトに後から導入できますか？

できます。`.claude/settings.json` を作成し、`.claude/hooks/` 配下にスクリプトを置くだけで有効化されます。Claude Code 再起動不要です。

Q: Hooks 内で外部APIを叩いてもいいですか？

可能ですが、タイムアウト管理が重要です。3秒以内に応答が返らない場合は `--max-time 3` 等でカットしてください。同期処理が長引くと Claude セッションが固まります。

Claude Code Hooks は、ツール実行の前後に シェルスクリプトを自動起動する仕組み で、コスト管理・品質チェック・PII マスキング等を強制できます。本記事では PreToolUse / PostToolUse / Stop の3種類のHooksの違いと、自社運用に即組み込める実装例6本を実機検証付きで紹介します。

「Claude が暴走してAPI コストが青天井になった」「機密情報を漏らした」というよくある失敗を、Hooks で物理的にブロックできるようになります。

週1ニュースレター（無料）に登録すると、Hooks の最新パターンと運用事例が毎週木曜に届きます。

Claude Code Hooks とは何か

Hooks は .claude/settings.json に登録するシェルスクリプトで、Claude Code がツール（Bash / Write / Edit / WebFetch 等）を実行する 前後に自動起動 されます。実行内容を検査・改変・拒否（exit 1）できるため、安全装置として機能します。

ChatGPT のような対話型AIとClaude Codeの最大の違いの1つが、この 「実行前に止める仕組みが組み込める」 点です。

Hooks の3種類と使い分け

Claude Code には現状3種類のHooks があります。

種類	起動タイミング	主な用途
PreToolUse	ツール実行前	危険コマンドのブロック / コスト閾値チェック / 引数の検証
PostToolUse	ツール実行後	自動フォーマット / 品質スコア / ログ記録
Stop	セッション終了時	PII マスキング / 監査ログ / 最終チェック

Claude Code 完全ガイドのピラー記事から、関連サブトピックへも参照ください。

PreToolUse — 暴走を物理的に止める

PreToolUse は最もよく使う Hook です。tool と command_prefix でマッチ条件を絞り、シェルスクリプトを起動します。

例: 危険コマンドのブロック

{
  "hooks": {
    "PreToolUse": [
      {
        "match": { "tool": "Bash", "command_prefix": ["rm -rf", "drop database"] },
        "command": ".claude/hooks/block-dangerous.sh"
      }
    ]
  }
}

block-dangerous.sh で exit 1 を返せば、Claude のコマンドは実行されません。

例: コスト閾値チェック

#!/usr/bin/env bash
TODAY_USD=$(sqlite3 db/agent_ops.sqlite "SELECT COALESCE(SUM(estimated_cost_usd),0) FROM agent_costs WHERE DATE(created_at)='$(date +%Y-%m-%d)';")
if (( $(echo "$TODAY_USD > 35" | bc -l) )); then
  echo "[block] today cost \$${TODAY_USD} exceeded limit"
  exit 1
fi

これで「1日 $35 超過したらClaude を物理的に停止」が実現できます。

PostToolUse — 品質ゲートを後段で

ツール実行後に検査するパターン。MDX や TypeScript ファイルを書いた直後に自動フォーマット・型チェック・リンク検証を走らせます。

例: MDX 品質チェック

{
  "hooks": {
    "PostToolUse": [
      {
        "match": { "tool": "Write", "path_glob": "apps/*/content/**/*.mdx" },
        "command": ".claude/hooks/post-mdx-quality.sh"
      }
    ]
  }
}

post-mdx-quality.sh で以下を検査:

本文文字数 ≥ 1500
H2 数 ≥ 3
内部リンク ≥ 2
外部リンクが 200 OK か

失敗時は exit 1 で Claude に通知され、Claude が自動修正を試みます。

週1ニュースレター（無料）で、品質ゲートのテンプレ集を継続キャッチアップできます。

Stop — セッション終了時の最終チェック

Stop Hook はセッション終了時に必ず実行されます。PII マスキングや監査ログ収集に最適です。

{
  "hooks": {
    "Stop": [
      { "command": ".claude/hooks/stop-pii-mask.sh" },
      { "command": ".claude/hooks/stop-record.sh" }
    ]
  }
}

stop-pii-mask.sh でメールアドレスや電話番号を自動的にマスキングできます。

当メディアでの実装例（実機検証済み）

claude-code-media.com 自身の .claude/hooks/ 配下に以下を稼働させています。

Hook	タイミング	目的
`pre-cost-gate.sh`	PreToolUse (sqlite3/psql)	日次コスト超過時のブロック
`pre-mdx-write.sh`	PreToolUse (Write/Edit .mdx)	frontmatter 必須項目チェック
`pre-webfetch-sanitize.sh`	PreToolUse (WebFetch)	プロンプトインジェクション検出
`post-mdx-quality.sh`	PostToolUse (Write/Edit .mdx)	文字数・H2・リンク検証
`post-mdx-seo-validate.sh`	PostToolUse (Write/Edit .mdx)	E-E-A-T・Featured Snippet 構造
`stop-pii-mask.sh`	Stop	PII マスキング
`stop-record.sh`	Stop	dialogue_logs 記録

これらにより、Claude Code エージェント30本以上が安全に自律稼働しています。

よくある詰まりポイント

症状	原因	対処
Hook が起動しない	パス間違い / `chmod +x` 忘れ	`.claude/hooks/` への正確なパス + 実行権限付与
Hook の標準出力が見えない	stderr に書く必要あり	`echo "..." >&2` を使う
Hook のタイムアウト	重い処理（API呼出等）	5秒以内に完了させる、非同期化

まとめ

Claude Code Hooks は 暴走を物理的に止める安全装置 であり、本番運用には必須です。

PreToolUse: 危険コマンド・コスト閾値の事前ブロック
PostToolUse: 自動フォーマット・品質ゲート
Stop: PII マスキング・監査ログ

今すぐ実装するなら、まず pre-cost-gate.sh（日次予算超過ブロック）と post-mdx-quality.sh（書込み品質チェック）の2本から始めるのが効果的です。

Hooks のパターン集は週1ニュースレター（無料）で配信中です。毎週木曜に最新の実装事例と失敗パターンをお届けします。

Claude Code Hooks に関するよくある質問

Claude Code Hooks に関する質問は以下の4つです。

Hooks を仕込むとどれくらい遅くなりますか？
既存プロジェクトに後から導入できますか？
Hooks 内で外部APIを叩いてもいいですか？
Hooks の失敗（exit 1）時の挙動は？

それぞれの回答を確認して、本番運用の参考にしてください。

Claude Code 使い方完全ガイド — Hooks を仕込む前の基本セットアップ
Claude Code Skills 完全ガイド — Hooks と組み合わせる業務手順定義
Claude Code × MCP 完全ガイド — Hook + MCP で外部システム自動化
Claude Code × GitHub 完全ガイド — Hook で GitHub Actions の品質ゲートを補強