【広告・PR】 本記事には A8.net のアフィリエイトリンクが含まれます。評価は筆者の独立した判断によるものです。

この記事でわかること

• Claude Code Hooks の 5 つのイベント（SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop）の使い分け
• 110+ skill を運用する本番リポジトリで実証した hooks 設計パターン 5 つ
• settings.json の hooks エントリ書式と、よくある落とし穴（exit code 2 によるブロック、stdin 経由のコンテキスト受け渡しなど）
• 「自動化したいが暴走させたくない」を両立する3層ガードレールの設計
• hooks と Subagent・Skill の責務分離 — どれを使うべきかの判断基準

想定読者: Claude Code を bypassPermissions モードで日常運用しており、エディタ操作や CI 連動を自動化したい個人開発者・小規模チーム。読了目安: 約7分。

---

Claude Code Hooks とは

Claude Code Hooks は、Claude Code セッション中の特定イベント（ツール実行前後・セッション開始時・ユーザープロンプト送信時・終了時）に任意のシェルコマンドを発火させる仕組みです。~/.claude/settings.json または プロジェクトの .claude/settings.json に hooks エントリを書くだけで、Claude 側からは見えない「OS レイヤーの自動化」を差し込めます。

公式リファレンス（docs.claude.com - Hooks）が定義する5つのイベントは以下です。

イベント	発火タイミング	主な用途
SessionStart	セッション起動直後	環境チェック・状態通知
UserPromptSubmit	ユーザーがプロンプト送信	プロンプト前処理・監査ログ
PreToolUse	ツール呼び出し直前	危険コマンドブロック
PostToolUse	ツール呼び出し直後	フォーマット・git 連動
Stop	セッション終了時	サマリ生成・cleanup

Hooks vs Skills vs Subagents の境界: Hooks は OS シェルで動く「不可視の自動化」、Skills は Claude が能動的に呼び出す「指示書」、Subagents は別 context で動く「並列タスク」。自動化したい = Hooks / 指示したい = Skills / 委任したい = Subagents が判断軸です。

---

設定書式（settings.json）

Hooks は settings.json の "hooks" キーに、イベント名をキーとして配列で記述します。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "bash ~/.claude/hooks/session-start.sh" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "node ~/.claude/hooks/block-dangerous.mjs" }
        ]
      }
    ]
  }
}

matcher フィールドはイベントごとに意味が変わります。PreToolUse / PostToolUse ではツール名（Bash / Edit / Write / Read 等）の正規表現マッチ、SessionStart では "startup" / "resume" / "clear" などのサブイベント識別子です。

終了コードによる制御

Hook スクリプトの終了コードが Claude の挙動を左右します。

• exit 0 — 正常。stdout が <system-reminder> ブロックとして Claude のコンテキストに注入される
• exit 2 — PreToolUse のみ「ブロック」を意味し、当該ツール呼び出しがキャンセルされる
• それ以外 — エラー扱い。Claude にエラー通知が届くがツール呼び出し自体は継続

exit 2 の挙動を PostToolUse 等で期待すると debug 沼に陥ります。ブロックは PreToolUse でのみ機能します。

---

本番運用で実証した5パターン

筆者は 110+ skill / 49+ launchd plist を運用するリポジトリで、以下5パターンの hooks を本番稼働させています。

パターン1: SessionStart で外部リソース疎通確認

セッション起動直後に「Debian サーバー疎通」「Chrome CDP ポート稼働」「chat-daemon プロセス生存」を一括チェックし、結果を <system-reminder> として注入します。Claude は起動時に環境の健康状態を知った状態でタスクを始められます。

#!/usr/bin/env bash
# session-start.sh
DEBIAN_OK=$(ssh -o ConnectTimeout=3 debian "echo OK" 2>/dev/null || echo NG)
CDP_OK=$(curl -sf http://localhost:9222/json/version >/dev/null && echo Open || echo Closed)
DAEMON_OK=$(pgrep -f chat-daemon >/dev/null && echo Running || echo Down)
echo "[DEBIAN] $DEBIAN_OK / [CDP] $CDP_OK / [CHAT] $DAEMON_OK"
exit 0

パターン2: PreToolUse で破壊的コマンドをブロック

git push --force / rm -rf / / DROP TABLE 等を PreToolUse + Bash matcher でフックし、本番ブランチで検出したら exit 2 でキャンセルします。

// block-dangerous.mjs
import { readFileSync } from 'fs';
const input = JSON.parse(readFileSync(0, 'utf-8'));  // stdin から JSON 受領
const cmd = input.tool_input?.command || '';
const dangerous = [
  /git\s+push\s+.*--force/,
  /rm\s+-rf\s+\/(?!tmp|var\/tmp)/,
  /DROP\s+TABLE/i,
];
if (dangerous.some(re => re.test(cmd))) {
  console.error(`BLOCKED: ${cmd.slice(0, 80)}`);
  process.exit(2);  // ← PreToolUse でのみキャンセル発火
}

stdin から JSON でツール入力が渡される設計は公式の hooks 仕様に従っています。tool_input のキー名はツールごとに違うので、ツール名（input.tool_name）でディスパッチするのが安全です。

パターン3: PostToolUse で Edit 後に自動フォーマット

Edit / Write ツール直後に prettier / gofmt / black を発火し、Claude がコミットする前にフォーマットを整えます。差分が出ても次の Read で Claude が自動再取得するため、内部状態の不整合は起きません。

#!/usr/bin/env bash
# postedit-format.sh
input=$(cat)
file=$(echo "$input" | jq -r '.tool_input.file_path // empty')
case "$file" in
  *.ts|*.tsx|*.js|*.mjs) npx prettier --write "$file" 2>/dev/null ;;
  *.py) ruff format "$file" 2>/dev/null ;;
  *.go) gofmt -w "$file" 2>/dev/null ;;
esac
exit 0

パターン4: UserPromptSubmit で監査ログ

各ユーザー発話を SQLite に追記し、docs/handover/ 生成や品質トレースに使います。Claude の挙動には干渉せず、純粋に observability 用です。

パターン5: Stop で完了通知

セッション終了時に Google Chat 等へ完了通知を流します。複数 cron / launchd 経由の autonomous 運用では、終了報告の自動化が運用負荷を激減させます。

---

よくあるハマりどころ

1. matcher の正規表現は完全マッチではない

matcher: "Bash" は BashOutput 等も部分マッチで拾います。厳密にしたいなら matcher: "^Bash$" のように boundary を明示してください。

2. hook の標準出力は Claude の context を消費する

<system-reminder> ブロックとして注入されるため、長文を出すと毎ターン context を食い続けます。1行〜数行に収めるのが鉄則。詳細はファイルへ書き出し、hook の stdout はパスのみ通知します。

3. exit 2 を PostToolUse で出してもブロックされない

ツールはすでに実行済なので、PostToolUse の exit 2 はエラー扱いになるだけです。「実行を取り消したい」用途は PreToolUse へ。

4. SessionStart は --resume でも発火する

セッション再開時にも matcher: "resume" で発火します。startup のみフックしたい処理は matcher で明示しましょう。

---

💡 中級者向けの体系学習: Hooks 設計は Bash・正規表現・JSON 処理に加え、DevOps 全般の知識が問われます。中級〜上級者向けに体系化された買い切り講座を探すなら Coloso（コロソ） の DevOps / AI 活用カテゴリが選択肢です。サブスクではなく買い切り型なので、必要なテーマだけ単発で深掘りできます（筆者は A8.net 経由でアフィリエイト報酬を受け取ります）。

---

3層ガードレール設計（暴走防止）

bypassPermissions モードで Claude を運用すると速度は出ますが、コマンドミスや暴走でリポジトリを壊すリスクが増えます。本番運用では以下3層で守ります。

層	仕組み	守る対象
Layer 1	PreToolUse hook で正規表現ブロック	破壊的コマンド（既知パターン）
Layer 2	.gitignore + commit pre-hook	機密漏えい（.env / 認証情報）
Layer 3	git reflog + nightly snapshot	万一の commit reset 事故

Layer 1 だけでは「想定外のコマンド」に弱く、Layer 3 だけでは「気付いた頃には commit 済」になります。3層併用が現実的です。

---

ベストプラクティス3つ

1. hook は冪等にする — PostToolUse が同じファイルで複数回走っても安全な処理だけを書く
2. stdout は最小限 — 1行原則。詳細はファイル、stdout はサマリ
3. 失敗を握りつぶさない — exit 0 を強制するなら、失敗を別経路（log / chat 通知）で必ず可視化

---

キャリア面の補足

Claude Code を活用した開発を本業として独立・転職したい個人開発者向けには、エンジニア専門の転職エージェントを経由するのが効率的です。

💼 エンジニア転職支援: TechGo（テックゴー） は AI 活用や DevOps スキルを評価する企業との接続が強く、無料カウンセリングで現状スキルと市場価値の擦り合わせができます。Claude Code 等の最新ツールチェーンを使いこなせる開発者は希少価値が上がっているフェーズです（筆者は A8.net 経由でアフィリエイト報酬を受け取ります）。

---

まとめ

• Claude Code Hooks は OS シェルで動く「Claude から見えない自動化レイヤー」
• 5 イベント（SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop）を用途で使い分ける
• ブロック発火は PreToolUse の exit 2 のみ有効
• stdout は 1行原則で context 消費を抑える
• 3層ガードレール（hook + commit pre-hook + reflog）で暴走を防ぐ

Hooks は導入コストが低く、効果が大きい機能です。まず SessionStart と PreToolUse の2つから本番運用に組み込んでみてください。

---

関連記事

• Claude Code 大規模リファクタを安全に進める Monorepo Practices 2026
• Claude Opus 4.7 Fast Mode 実践活用ガイド
• CLAUDE.md 3層ガードレール暴走防止

さらに深掘り版

• note 有料記事「Claude Code 本番運用ノウハウ集 — 110+ skill / 49+ launchd plist の実装パターン」（ezark_company の noteで順次公開予定）でリポジトリ規模の実装パターン全集を深掘りしています。本記事の hooks 設計だけでなく、Skill 設計指針・launchd plist と hooks の責務分離・Rule ベースの暴走防止アーキテクチャを通しで解説します。

参考一次情報

• Claude Code Hooks 公式ドキュメント (docs.claude.com)
• Claude Code Settings 公式ドキュメント (docs.claude.com)