Claude Code hooksとは？設定と自動化の実例を全部見せる

Claude Code hooksとは、Claude Codeの操作前後に自作の処理を確実に割り込ませる仕組みです。ファイルの整形漏れや意図しないコマンド実行に悩む開発者にとって、最も確実な防壁になります。AIに文章でいくら「保存前に整形して」と指示しても、実行を忘れるケースはゼロになりません。hooksを使えば、AIの判断を介さず機械的にスクリプトを走らせることができます。

この仕組みはAIコーディングの実務で生じる手戻りを減らすために用意されています。設定ファイルの書き方と具体的な自動化の組み立て方を順番に解説します。

---

Claude Code hooksとはどんな機能なのか？

Claude Code hooksは、ターミナル上で自律動作するAIエージェントの処理フローに介入する機能です。指定したイベントの発生を検知し、ローカルのシェルコマンドを呼び出します。

Claude Codeはファイルの読み書きやコマンド実行を自律的に繰り返します。通常のチャット型ツールと異なり、作業が自動で進むため途中の確認がおろそかになりがちです。hooksを設定すると、AIがファイルを触った直後にフォーマッタを起動したり、ターミナルでコマンドを打つ直前に構文を検査したりできます。

AIへの指示文でルールを守らせる方法には限界があります。モデルの文脈が長くなると、初期の約束事を忘れる現象が起きるためです。hooksはプログラムによる決定論的な制御です。設定した条件に合致すれば、例外なく指定したスクリプトが動きます。

---

設定ファイルはどこに配置すればよいか？

hooksの設定は、JSON形式のファイルに記述します。適用したい範囲に応じて3つの置き場所が用意されています。

設定ファイルの場所によって、個人専用の設定にするかチーム共有にするかを切り替えます。

つまり、Gitでチームに配布したいルールはプロジェクト直下の.claude/settings.jsonに配置します。

個人だけで試したい設定は.claude/settings.local.jsonに書き込みます。このファイルは.gitignoreに登録しておけば、チームのリポジトリを汚しません。全リポジトリで同じ通知を受け取りたいときは、ホームディレクトリ側のファイルを選びます。

優先順位は、プロジェクト個別の設定がグローバル設定よりも優先されます。基本形は次の構造です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ]
  }
}

この記述は、ファイルを変更または作成した直後にPrettierを実行する指定です。構文を1箇所でも間違えると機能全体が動かないため、JSONのカンマや括弧の閉じ忘れに注意します。

---

hooksが起動する6つのタイミングと用途

hooksには複数のイベントが存在し、用途に合わせて使い分けます。

発火するタイミングを正しく選ぶことが、安全なワークフローを構築する出発点になります。

つまり、処理を止めたいときはPreToolUseを使い、変更後の後始末をしたいときはPostToolUseを選びます。

この中で最も強力なイベントはPreToolUseです。このイベントだけは、呼び出したスクリプトの終了コードによってClaude Codeの動作を中断させる権限を持ちます。異常終了コードとして1などを返すと、AIによるツールの実行そのものを未然に防げます。

---

実例1: ファイル変更直後の自動整形（PostToolUse）

コードの整形は、ファイル編集が終わった直後に行うのが最も効率的です。

AIが修正したファイルに対してPrettierやBiomeを自動で実行する設定を作ります。対象ツールを特定するためにmatcherを利用します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ]
  }
}

この設定では、Claude CodeがEdit（既存ファイルの修正）またはWrite（新規ファイル作成）ツールを使用した直後にコマンドが走ります。

環境変数$CLAUDE_FILE_PATHSには、変更されたファイルの絶対パスが自動で代入されます。リポジトリ全体を走査するのではなく、触ったファイルだけをピンポイントで整形するため、待ち時間は1秒未満で済みます。

Pythonプロジェクトの場合は、BlackやRuffを指定します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "ruff format $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ]
  }
}

AIに「インデントを整えて」と補足を打つ手間が丸ごと省けます。AI自動化の基本として、最初に入れておきたい設定です。

---

実例2: 危険なコマンドの実行遮断（PreToolUse）

誤ったコマンド実行によるデータ消失は、開発者が最も恐れる事故です。

AIがターミナルで危険なシェルコマンドを実行しようとした際に、即座にブロックするガードレールを構築します。PreToolUseイベントと正規表現のマッチングを組み合わせます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/scripts/guard-command.sh"
          }
        ]
      }
    ]
  }
}

実行されるシェルスクリプト.claude/scripts/guard-command.shの内容は以下のように記述します。

#!/usr/bin/env bash
set -euo pipefail

# AIが実行しようとしているコマンドを取得
COMMAND="$CLAUDE_TOOL_INPUT_COMMAND"

# 禁止したい危険パターンの判定
if echo "$COMMAND" | grep -Eq 'rm[[:space:]]+-(r|rf|fr)[[:space:]]+/|git[[:space:]]+push[[:space:]]+-[f|force]|DROP[[:space:]]+DATABASE'; then
  echo "エラー: 破壊的な可能性があるコマンドはhooksにより遮断されました: $COMMAND" >&2
  exit 1
fi

exit 0

スクリプトが終了コード1を返すと、Claude Codeはツールの実行を取りやめます。AIの画面にはスクリプトが出力した標準エラーメッセージがそのまま渡されます。

AIは「コマンドがブロックされた」という事実を学習し、別の安全な手段を探し始めます。人間の介入なしにAIセキュリティの最低限の境界を担保できる点が魅力です。

---

実例3: 編集後のテスト自動実行（PostToolUse）

コード修正後にユニットテストを自動化しておくと、デバッグ速度が大幅に上がります。

ファイル保存のたびにテストを回し、失敗した場合はその結果をClaude Codeにフィードバックさせます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --bail --findRelatedTests $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ]
  }
}

JestやVitestの--findRelatedTestsオプションを渡す点が工夫です。

変更されたファイルに関連するテストファイルだけが選ばれて実行されます。数千件のテストを抱えるプロジェクトでも、数秒で合否が判明します。

もしテストが落ちた場合、その出力ログがコンテキストに含まれます。指示を追加で与えなくても、AIは「テストが落ちたので直します」と自律的に修復作業へ移ります。人手を介さないテスト駆動開発のループがここで完成します。

---

実例4: 長時間タスクの完了を知らせるデスクトップ通知（Notification / Stop）

何十ファイルも書き換える作業を頼むと、完了までに数分かかることがあります。

画面を眺め続ける時間をなくすために、セッション停止時にMacやLinuxの通知センターへメッセージを飛ばします。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"作業が終了しました。結果を確認してください。\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

この設定はmacOS標準のAppleScriptを呼び出しています。Linux環境であればnotify-sendコマンドに置き換えます。

Windows環境のWSLを使用している場合は、powershell.exe -Command経由でトースト通知を出せます。バックグラウンドで作業を走らせ、完了通知が届いた時だけ画面を切り替える運用にすると、AI生産性が跳ね上がります。待ち時間のストレスを削る現実的な対策です。

---

実例5: セッション開始時の環境ヘルスチェック（SessionStart）

必要なツールやクレデンシャルが揃っていない状態で対話を始めると、途中でエラーが多発します。

開発を始める直前に、ローカル環境の前提条件をチェックしてAIに初期状況を伝える仕組みを作ります。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/scripts/check-env.js"
          }
        ]
      }
    ]
  }
}

スクリプト側で、Dockerコンテナの稼働状況やNode.jsのバージョン、依存ライブラリの整合性を確認します。標準出力に吐き出された内容は、セッションのシステムプロンプト的な情報として渡されます。

「ローカルのPostgreSQLが起動していません」といった警告を会話の冒頭で自動共有できます。無駄なトラブルシューティングにAPIトークンを浪費する事態を防げます。

---

利用可能な環境変数とフックのデータ構造

hooks内で実行されるシェルスクリプトには、Claude Codeから複数の環境変数が渡されます。

スクリプト側で状況を正しく判定するために、受け取れる主なパラメータを整理します。

つまり、どのファイルが触られたかを知りたいときは$CLAUDE_FILE_PATHSを参照し、実行コマンドを監視したいときは$CLAUDE_TOOL_INPUT_COMMANDを用います。

パスにスペースが含まれるケースに備えて、シェルスクリプト側では変数をダブルクォーテーションで囲む書き方を徹底します。引数の扱いに慣れておくと、複雑な検証ロジックもシェル1本で完結します。

---

hooks運用時にハマりやすい3つの注意点

強力な自動化機能ですが、設定の仕方を誤ると開発体験を損なう原因になります。

運用を破綻させないための重要な注意点を3点挙げます。

1. 重い処理をPostToolUseに入れない ファイルを1行直すごとにフルビルドやE2Eテストを走らせると、AIの応答が数十秒止まります。PostToolUseには1〜2秒以内で終わる軽量な整形やLinterだけを割り当てます。
2. PreToolUseの終了コード設計を厳密にする スクリプト内の意図しない構文エラーで終了コード1が出ると、安全なコマンドまで全てブロックされます。スクリプト単体での動作テストを必ず事前に実施します。
3. 対話型コマンドを呼び出さない ユーザーに入力を促すreadコマンドや対話型シェルを呼ぶと、プロセスが応答待ちでフリーズします。必ず非対話（バッチモード）で完結するツールを指定します。

自動化の範囲を広げすぎず、確実な処理だけに絞って組み込むことが長続きの秘訣です。

---

コストと利用枠への影響はあるか？

hooks自体を動かすことによって、AnthropicのAPI利用料が加算されることはありません。

スクリプトの実行はすべて手元の端末内（ローカル環境）で行われます。外部のモデルAPIを追加で呼び出しているわけではないため、Hooksの実行回数がどれだけ増えても費用は0円のままです。

ただし、スクリプトが大量の標準出力やエラーログを吐き出した場合は別です。その出力テキストはClaude Codeの次ターンのコンテキスト（入力トークン）として消費されます。不要に長いテストログを全件出力させると、コンテキスト枠を圧迫してAPI料金やトークン消費が増加します。

余計な出力を抑えるため、スクリプト内では> /dev/nullを活用したり、エラー時のみ要約を表示するような工夫を施します。

---

AI PICKS編集部の判定

Claude Code hooksは、日常的にAIと協調開発を行うエンジニアにとって一択の必須機能です。

自然言語による指示だけに頼る開発は、どうしても出力のブレが残ります。「コード規約を守らせる」「危険な操作を避ける」といった機械的に判断できる領域は、hooksに委任するのが最も合理的です。ローカルで動くため追加費用がかからず、月0円のまますぐに手戻りを激減させられます。

正直イマイチな点を挙げるとすれば、JSON設定の構文エラーに対するデバッグのしづらさです。設定ミスがあってもターミナルに明瞭なエラーが出ない場面があり、最初の数回は戸惑います。それでも一度スクリプトを整えてしまえば、チーム全体の開発基盤として圧倒的な恩恵をもたらします。

---

よくある質問（FAQ）

Q. hooksを使うのに追加料金は発生しますか？

追加料金は一切発生しません。hooksはローカル端末のシェルコマンドを呼び出す仕組みであるため、Anthropic APIのトークンを消費せずに動作します。ただし、スクリプトの標準出力をコンテキストに取り込む際は入力トークンが消費されるため、ログの出しすぎには注意が必要です。

Q. 設定を変更したのに反映されない場合はどうすればよいですか？

Claude Codeのセッションを一度終了し、再起動してください。設定ファイル（settings.json）の読み込みはセッション開始時に行われる仕様です。また、JSONファイル内の構文エラー（余分なカンマや閉じ括弧の不足）があると設定全体が無効化されるため、構文チェッカーで確認します。

Q. Windows環境でも動作しますか？

WSL（Windows Subsystem for Linux）上の環境であれば、LinuxやmacOSと同様にシェルスクリプトを含めて完全に動作します。PowerShellやコマンドプロンプトを直接使う場合は、パスの区切り文字や実行コマンドの構文をWindows形式に合わせる必要があります。

Q. エラーが出たときにClaudeに修正を続けさせることはできますか？

可能です。PostToolUseでテストやLinterがエラーを返した場合、その終了ステータスと標準エラー出力が自動的にClaude Codeへ送られます。AIはその失敗メッセージを読み取り、自律的にコードを直す次のアクションを起こします。

---

Hooksでコードの安全性を確保したら、自律的にタスクをこなす全体像の理解が役立ちます。基礎から学び直したい方は、AIエージェントの仕組みと選び方やAIコーディングのランキングをあわせて確認すると活用の幅が広がります。