Claude Code Hooks 完全ガイド — 保存時自動整形・コミット前チェックの実装

「lint を通すのを忘れて push したら CI が落ちた」「コミット前にテストするのを忘れた」「うっかり本番 DB に向けて作業していた」——個人開発でやらかしがちな事故です。

これらを Claude Code レベルで強制する のが Hooks 機能です。Claude が特定のアクションを取る前後に、シェルコマンドを自動実行できます。人間が忘れても、Claude が忘れても、Hooks は忘れません。

この記事では、Hooks の基本仕様と、筆者が実運用している5つのパターンを実 JSON 設定付きで解説します。

結論：Hooks は「Claude のアクション前後に走る自動処理」

Hooks とは 「Claude Code が特定のツールを使うときに、自動的に実行されるシェルコマンド」 です。

例えば：

• ファイルを 保存する前 に lint を走らせる
• ファイルを 保存した後 に prettier をかける
• コミットを作る前 にテストを実行する
• bash コマンド実行前 に「rm -rf」が含まれていないか確認する

設定は ~/.claude/settings.json または <project>/.claude/settings.json に書きます。コードを書く必要はなく、JSON 1ファイルで完結します。

Hooks の構造

Hooks は次のような JSON 構造で定義します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --quiet"
          }
        ]
      }
    ]
  }
}

要素の意味は次のとおりです。

キー	意味
PreToolUse	ツール実行前 に走る Hooks
PostToolUse	ツール実行後 に走る Hooks
matcher	どのツールに反応するか（正規表現可）
hooks	実行するコマンド配列

matcher で Edit|Write|MultiEdit のように複数指定できます。ファイル編集系のツール全般に同じ Hook を適用するときに便利です。

実用パターン5選

筆者が ~/.claude/settings.json で実運用している Hooks を5つ紹介します。

パターン1：保存後に prettier を自動実行

最もシンプルかつ効果が大きい Hook です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

$CLAUDE_FILE_PATH は Claude が編集したファイルのパスが入る環境変数です。これで「Claude がコードを書いた直後に整形される」状態が作れます。

パターン2：危険なコマンド実行前に確認

rm -rf や本番 DB への接続コマンドを自動実行されると事故になります。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE '(rm -rf|DROP TABLE|DELETE FROM)' && exit 1 || exit 0"
          }
        ]
      }
    ]
  }
}

危険パターンを検出したら exit 1 で中断します。Claude には「Hook によって中断された」という情報が返り、別のアプローチを取るようになります。

パターン3：本番 DB の URL を含むコマンドをブロック

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'PROD_DATABASE_URL|prod-db.example.com' && (echo 'BLOCKED: production DB access' >&2; exit 1) || exit 0"
          }
        ]
      }
    ]
  }
}

「うっかり本番に繋がる」事故を完全に防げます。安全装置として最も効く Hook です。

パターン4：コミット前に型チェック

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'git commit' && (npx tsc --noEmit || exit 1) || exit 0"
          }
        ]
      }
    ]
  }
}

git commit コマンドを Claude が実行する直前に tsc --noEmit を走らせます。型エラーがあればコミット自体が中断されます。

パターン5：編集後に Slack 通知

長時間作業のときに「Claude が今何をしているか」を Slack に流す Hook です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST $SLACK_WEBHOOK_URL -d \"{\\\"text\\\":\\\"Claude edited: $CLAUDE_FILE_PATH\\\"}\""
          }
        ]
      }
    ]
  }
}

リモート運用時の監視に便利です。次のエピソードで扱う「VPS 常駐型 Claude Crew」と相性抜群です。

ハマりやすい落とし穴

筆者がHook運用で実際に踏んだ地雷を3つ。

1. matcher が大文字小文字を区別する

matcher: "edit|write" と書くとマッチしません。Claude Code のツール名は PascalCase（Edit, Write, Bash）なので、それに合わせます。

2. exit 1 とエラーメッセージの順序

Hook がエラーで中断するときは、標準エラー出力（>&2）にメッセージを書いてから exit 1 の順序が大事です。逆だと Claude にメッセージが届きません。

3. 重い Hook が体感を悪くする

毎回 npm test を走らせる Hook を入れたら、ファイル編集のたびに30秒待たされる事態になりました。重い処理は コミット前限定 の matcher で発動を絞るべきです。

で、どう稼ぐ？ — Hooks が事故損失を直接回収する

Hooks の経済的価値は 「事故による損失を未然に防ぐ」 ことにあります。これは目に見えにくいですが、個人開発では特に効きます。

1. データ消失事故を防ぐ＝復旧コストの回避

本番 DB の事故1回で半日〜1日の復旧時間が消えます。時給5,000円換算で¥20,000〜40,000の損失です。これを Hook 1個で防げるなら、ROI は無限大に近い。

2. CI 失敗によるデプロイ遅延を防ぐ

「lint を通さずに push → CI 失敗 → 修正 → 再 push」のループは、1回あたり10〜15分のロス。週5回起きていたら月20回、約5時間の損失です。Hook 1個で防げます。

3. クライアント案件での信頼維持

受託案件で本番事故を起こすと、信用が回復不能なほど傷つきます。Hooks による安全装置を組み込んでいることをクライアントに伝えれば、発注のハードルが下がり、継続案件に繋がりやすくなります。

まとめ

Hooks は「人間が忘れがちな処理を Claude Code に強制する」仕組みです。重要ポイントは次のとおり。

• JSON 1ファイルで設定完結。コードは書かなくてよい
• PreToolUse / PostToolUse で発動タイミングを制御
• 危険コマンドのブロック Hook が最優先。これだけで事故損失を直接回収できる

最初に入れるべきは「本番 DB ブロック Hook」と「コミット前型チェック Hook」の2つです。15分の設定で、1件の本番事故を防げば元が取れます。

次のエピソードからは 有料記事 に入ります。Ep.05 は「リモートサーバー運用術 — VPS 常駐型 Claude Crew の構築」です。本記事で扱った Hooks を組み込んだ、24時間動く Claude 環境の構築手順を全公開します。

次に読む

→ Claude Code Hooks で事故を防ぐ — git secrets / 本番 DB 保護の実装 (¥500)

Hooks の基本パターンを理解したら、次は実運用で本当に必要な「9 つの安全装置」の実装です。本番 DB 保護、git secrets 検出、CI/CD 組み込みまで、事故防止に特化した本格運用ガイドを有料記事で全公開しています。