メインコンテンツへスキップ
見出し画像

【設定3つで自動化】Claude Code Hooks入門——コード整形・危険コマンド防止・コミット検証

    Claude Codeがコードを編集するたびにPrettierが自動で走り、`rm -rf` を含むコマンドは実行前にブロックされ、コミットメッセージが規約に違反していたら即座に警告が出る。これらすべてが settings.json の設定3つで実現できます。

    この記事でわかること: Claude Code Hooksの仕組みと、「コード自動整形」「危険コマンドのブロック」「コミットメッセージ検証」の3つの実用的なHookを設定ファイルとスクリプトのコピペで構築する全手順を解説します。

    Claude Codeを使っていて「編集後のフォーマットを毎回手動で走らせるのが面倒」「意図しないコマンドが実行されないか不安」と感じている方向けです。

    このnoteでは、非エンジニア向けにAI活用を実務ベースで解説しています。

    Claude Code Hooksでできるようになること

    Hooksは「Claude Codeの特定のタイミングで自動的にシェルコマンドを実行する仕組み」です。

    スラッシュコマンド(Skills)が「ユーザーが明示的に呼び出す指示書」であるのに対し、Hooksは「イベントが起きたら自動で発動するルール」です。Claude Codeの判断を介さず、設定どおりに確実に実行されます。

    たとえば以下のことが設定だけで実現できます。

    • コード編集後 → Prettierやblackで自動整形

    • コマンド実行前 → `rm -rf` や `DROP TABLE` などの危険コマンドをブロック

    • gitコミット後 → コミットメッセージの規約チェック

    • セッション開始時 → プロジェクト固有のコンテキストを注入

    • ファイル変更時 → `.env` の変更を検知して警告

    私は記事制作パイプラインと並行してSaaS開発をしていますが、Hooksを導入してからClaude Codeが誤って危険なコマンドを実行するケースがなくなりました。特に「危険コマンドのブロック」と「コード整形の自動化」は、一度設定すれば以降の全プロジェクトで効果を発揮します。

    前提条件

    • Claude Code がインストール済み

    • `jq` コマンドがインストール済み(JSONパース用。macOSなら `brew install jq`)

    • Node.jsプロジェクトの場合、Prettierがインストール済み(`npm install -D prettier`)

    筆者の実行環境

    • OS: macOS Sequoia 15.x

    • ツール: Claude Code

    • 利用プラン: Claude Code Max $100/月

    Claude Code Hooks構築の手順

    Step 1: Hooksの仕組みを理解する

    Hooksは settings.json に設定を書くだけで動きます。基本的な構造は以下のとおりです。

    {
      "hooks": {
        "イベント名": [
          {
            "matcher": "対象ツール名",
            "hooks": [
              {
                "type": "command",
                "command": "実行するコマンド"
              }
            ]
          }
        ]
      }
    }

    主要なイベント(よく使う3つ + 1):

    • PreToolUse — ツール実行の直前に発動。コマンドのブロックや入力の検証に使う

    • PostToolUse — ツール実行の直後に発動。コード整形やログ出力に使う

    • SessionStart — セッション開始時に発動。コンテキスト注入に使う

    • Stop — Claude Codeの応答完了時に発動。最終チェックに使う(本記事では扱いません)

    matcher はどのツールに対してHookを発動するかを指定します。

    • `"Bash"` — Bashツールに発動

    • `"Edit|Write"` — EditまたはWriteツールに発動(`|` で複数ツールを指定)

    • 未指定または `""` — 全ツールに発動

    settings.jsonの配置場所で適用範囲が変わります:

    • `~/.claude/settings.json` — 全プロジェクトに適用

    • `.claude/settings.json` — そのプロジェクトだけに適用

    今回は全プロジェクトに適用したい設定(危険コマンドのブロック)とプロジェクト固有の設定(コード整形)を分けて説明します。

    Step 2: Hook 1——コード編集後の自動整形

    最初のHookは、Claude Codeがファイルを編集した直後にPrettierを自動で走らせる設定です。

    プロジェクトの `.claude/settings.json` に以下を追加します。

    {
      "hooks": {
        "PostToolUse": [
          {
            "matcher": "Edit|Write",
            "hooks": [
              {
                "type": "command",
                "command": "jq -r '.tool_input.file_path // empty' | xargs -I{} npx prettier --write '{}' 2>/dev/null || true",
                "statusMessage": "コードを整形中..."
              }
            ]
          }
        ]
      }
    }

    このHookが何をしているか:

    1. Claude CodeがEdit(編集)またはWrite(新規作成)ツールを使った直後に `PostToolUse` が発動

    2. Hookへの入力(JSON)から `tool_input.file_path`(編集されたファイルのパス)を `jq` で抽出

    3. そのファイルに対して `npx prettier --write` を実行(インプレースでフォーマット)

    4. Prettierが対応していないファイル(画像やバイナリ等)ではエラーを無視(`|| true`)

    なぜこの設定にしたか: 最初は PostToolUse のmatcherを `""` (全ツール)にしていましたが、Read(ファイル読み取り)やGlob(検索)のたびにもHookが走り、無駄な処理が増えました。`Edit|Write` に絞ることで、実際にファイルが変更された時だけ発動するようになります。

    Python プロジェクトの場合 は `prettier` の代わりに `black` を使います:

    {
      "command": "jq -r '.tool_input.file_path' | xargs black 2>/dev/null || true"
    }

    Step 3: Hook 2——危険コマンドのブロック

    2つ目のHookは、Claude Codeが危険なコマンドを実行しようとした時にブロックする設定です。

    まず、チェック用のスクリプトを作成します。

    mkdir -p .claude/hooks

    `.claude/hooks/block-dangerous.sh` を作成:

    #!/bin/bash
    INPUT=$(cat)
    COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
    
    # ブロック対象のパターン
    DANGEROUS_PATTERNS=(
      "rm -rf /"
      "rm -rf ~"
      "rm -rf \."
      "DROP TABLE"
      "DROP DATABASE"
      "git push.*--force.*main"
      "git reset --hard"
    )
    
    for pattern in "${DANGEROUS_PATTERNS[@]}"; do
      if echo "$COMMAND" | grep -qi "$pattern"; then
        echo "ブロック: 「${pattern}」に一致するコマンドの実行を防止しました" >&2
        exit 2
      fi
    done
    
    exit 0

    スクリプトに実行権限を付与:

    chmod +x .claude/hooks/block-dangerous.sh

    `.claude/settings.json` のhooksセクションに追加:

    {
      "hooks": {
        "PreToolUse": [
          {
            "matcher": "Bash",
            "hooks": [
              {
                "type": "command",
                "command": "bash .claude/hooks/block-dangerous.sh",
                "statusMessage": "コマンドの安全性を確認中..."
              }
            ]
          }
        ]
      }
    }

    このHookの仕組み:

    1. Claude CodeがBashコマンドを実行しようとすると PreToolUse が発動(実行前に割り込む)

    2. スクリプトがコマンド文字列を受け取り、危険パターンに一致するか検査

    3. 一致した場合は exit 2 で終了 → Claude Codeにブロック理由が表示され、コマンドは実行されない

    4. 一致しない場合は exit 0 で終了 → コマンドが通常どおり実行される

    ポイント: exit 2 がブロック、exit 0 が許可 です。exit 1 はHook自体のエラーとして扱われ、ツール実行はブロックされません(Hookのエラーメッセージが表示されるだけです)。

    なぜスクリプトに分離したか: 最初はsettings.jsonのcommandフィールドにワンライナーで書いていましたが、パターンが増えるとJSON内のエスケープが複雑になり、メンテナンスできなくなりました。外部スクリプトに切り出すことで、パターンの追加・削除がシンプルになります。

    Step 4: Hook 3——コミットメッセージの規約チェック

    3つ目のHookは、`git commit` 実行後にコミットメッセージが規約(Conventional Commits)に従っているかチェックする設定です。

    `.claude/hooks/check-commit-msg.sh` を作成:

    #!/bin/bash
    INPUT=$(cat)
    COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
    
    # git commit コマンドでなければスキップ
    if ! echo "$COMMAND" | grep -q "git commit"; then
      exit 0
    fi
    
    # 直近のコミットメッセージを取得
    MSG=$(git log -1 --pretty=%s 2>/dev/null)
    
    # Conventional Commits のプレフィックスチェック
    VALID_PREFIXES="feat|fix|docs|chore|refactor|test|perf|style|ci|build"
    
    if ! echo "$MSG" | grep -qE "^($VALID_PREFIXES)(\(.+\))?: .+"; then
      cat << EOF
    {
      "additionalContext": "警告: コミットメッセージ「${MSG}」がConventional Commits形式に従っていません。有効なプレフィックス: feat, fix, docs, chore, refactor, test, perf, style, ci, build。例: 'feat: ユーザー登録APIを追加'"
    }
    EOF
      exit 0
    fi
    
    exit 0
    chmod +x .claude/hooks/check-commit-msg.sh

    settings.json に追加:

    {
      "hooks": {
        "PostToolUse": [
          {
            "matcher": "Bash",
            "hooks": [
              {
                "type": "command",
                "command": "bash .claude/hooks/check-commit-msg.sh",
                "if": "Bash(git commit *)",
                "statusMessage": "コミットメッセージを検証中..."
              }
            ]
          }
        ]
      }
    }

    このHookのポイント:

    1. *`"if": "Bash(git commit )"` — matcherの `"Bash"` をさらに絞り込み、`git commit` を含むコマンドだけに発動。`git status` や `git log` では発動しません

    2. PostToolUse を使用 — コミット実行後に検証するため、PreToolUseではなくPostToolUseを使います。コミットをブロックするのではなく、規約違反を警告してClaude Codeに修正を促す方針です

    3. `additionalContext` — JSON出力の `additionalContext` フィールドに警告文を書くと、その内容がClaude Codeのコンテキストに注入されます。Claude Codeは警告を受けて「コミットメッセージを修正します」と自動で `git commit --amend` を実行してくれます

    なぜブロック(exit 2)ではなくコンテキスト注入にしたか: コミットをブロックすると、Claude Codeが混乱して同じコミットを繰り返し試みるケースがありました。ブロックせずに「メッセージが規約に違反している」という情報を与えると、Claude Code自身が判断して修正してくれます。

    Step 5: 3つのHookを統合する

    Step 2〜4で作成した3つのHookを1つの `.claude/settings.json` にまとめます。

    {
      "hooks": {
        "PreToolUse": [
          {
            "matcher": "Bash",
            "hooks": [
              {
                "type": "command",
                "command": "bash .claude/hooks/block-dangerous.sh",
                "statusMessage": "コマンドの安全性を確認中..."
              }
            ]
          }
        ],
        "PostToolUse": [
          {
            "matcher": "Edit|Write",
            "hooks": [
              {
                "type": "command",
                "command": "jq -r '.tool_input.file_path // empty' | xargs -I{} npx prettier --write '{}' 2>/dev/null || true",
                "statusMessage": "コードを整形中..."
              }
            ]
          },
          {
            "matcher": "Bash",
            "hooks": [
              {
                "type": "command",
                "command": "bash .claude/hooks/check-commit-msg.sh",
                "if": "Bash(git commit *)",
                "statusMessage": "コミットメッセージを検証中..."
              }
            ]
          }
        ]
      }
    }

    ディレクトリ構成:

    プロジェクトルート/
    ├── .claude/
    │   ├── settings.json          ← Hook設定
    │   └── hooks/
    │       ├── block-dangerous.sh ← 危険コマンドブロック
    │       └── check-commit-msg.sh ← コミットメッセージ検証
    └── ...

    設定を保存したらClaude Codeで `/hooks` と入力して、登録されたHookの一覧を確認できます。正しく登録されていれば、各イベントに紐づくHookの数が表示されます。

    Step 6: 動作を確認する

    各Hookが正しく動作するかテストします。

    Hook 1(コード整形)のテスト:
    Claude Codeに「src/test.js にサンプルコードを書いて」と依頼 → ファイル保存後にPrettierが自動で走ることを確認

    Hook 2(危険コマンドのブロック)のテスト:
    スクリプトを直接テストします:

    echo '{"tool_input":{"command":"rm -rf /"}}' | bash .claude/hooks/block-dangerous.sh
    echo $?  # 2 が返ればブロック成功
    echo '{"tool_input":{"command":"ls -la"}}' | bash .claude/hooks/block-dangerous.sh
    echo $?  # 0 が返れば許可(正常)

    Hook 3(コミットメッセージ検証)のテスト:

    git commit --allow-empty -m "bad message"
    echo '{"tool_input":{"command":"git commit"}}' | bash .claude/hooks/check-commit-msg.sh
    # additionalContext に警告が含まれることを確認

    Claude Code Hooksのトラブル対処法

    Hookが発動しない

    • 原因1: settings.jsonの構文エラー。JSON形式が壊れていると全Hookが無効になります

    • 対処法: `cat .claude/settings.json | jq .` で構文チェック。エラーが出たら修正

    • 原因2: matcherが一致していない。ツール名の大文字小文字は区別されます(`bash` ではなく `Bash`)

    • 対処法: Claude Code内で `/hooks` を実行し、登録状態を確認

    スクリプトが "command not found" になる

    • 原因: スクリプトのパスが相対パスで、作業ディレクトリが異なる

    • 対処法: 絶対パスを使うか、`$CLAUDE_PROJECT_DIR` 環境変数を使う

    {
      "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh"
    }

    jq が見つからない

    • 原因: jqがインストールされていない、またはPATHが通っていない

    • 対処法: `brew install jq`(macOS)または `apt install jq`(Linux)でインストール

    Claude Code Hooks設定の注意点

    Hookの実行はセッション全体に影響する

    Hookは設定されたイベントのたびに毎回実行されます。重いスクリプト(npm test の全件実行など)をPostToolUseに設定すると、Claude Codeが編集するたびに数分待たされます。

    私の基準: Hookは1秒以内に完了する処理だけにする。 テスト実行のような重い処理は、Hookではなくスラッシュコマンド(`/test`)で明示的に実行するほうが適切です。

    PreToolUse の exit 2 は慎重に使う

    PreToolUseで exit 2(ブロック)を返すと、Claude Codeはそのツール呼び出しを実行できません。正当なコマンドを誤ってブロックすると、Claude Codeが代替手段を探して迷走することがあります。

    最初はブロック対象を最小限(本当に危険なコマンドだけ)にして、徐々にパターンを追加するアプローチが安全です。

    スラッシュコマンドとHooksの使い分け

    混同しやすいですが、明確に使い分けられます。

    • Hooks: 「毎回確実に、自動で実行したい処理」に使う(コード整形、セキュリティチェック)

    • スラッシュコマンド(Skills): 「必要な時に、意図的に呼び出したい処理」に使う(記事生成、テスト実行)

    判断基準は「Claude Codeの判断を介さず、機械的に実行すべきか」です。Yesならhook、Noならスラッシュコマンドです。

    チームで共有する場合

    `.claude/settings.json` はGitにコミットできるため、チームで共有可能です。ただし、個人の環境に依存する設定(PATHやtool名等)がある場合は `.claude/settings.local.json` を使います。`.local.json` はgitignoreに含まれ、ローカルの設定がプロジェクト設定をオーバーライドします。

    次にやるべきこと

    1. まずHook 2(危険コマンドのブロック)から始める。 最も効果が高く、副作用が少ない。スクリプトをコピペして `chmod +x` するだけで動きます

    2. 動作確認後にHook 1(コード整形)を追加する。 プロジェクトでPrettierやblackを使っているなら、settings.jsonに3行追加するだけで即効果が出ます

    3. 慣れたらコミットメッセージ検証やセッション開始時のコンテキスト注入を追加する。 Hookは段階的に増やすのが安全です。「全部一度に設定→何が壊れたかわからない」を避けてください

    この記事が参考になったら、スキとフォローで応援お願いします。

    参考リソース

    関連記事

     
     
    「AI、実際どこまで仕事で使えるの?」を非エンジニア目線で検証しています。ChatGPT・Claude・Geminiを実務で試して、使えた/ダメだったを実測と失敗談つきで正直に書きます。

    あなたへのおすすめ