Claude Code Hooksで開発作業を自動化する実践設定

Claude Code Hooksで自動化できる開発作業と設定ファイルの書き方

Claude Code Hooksは、AIがツールを呼び出す前後や応答の終了時に、任意のシェルコマンドを自動実行する仕組みです。「編集のたびに手でLintを回す」「危険なrmを止めたい」といった手作業を、設定ファイル一枚で機械化できます。まず押さえるべきは、どのタイミングで発火し、どこに書くかの二点です。

PreToolUse・PostToolUse・Stopなど発火タイミング別の使い分け

用途に応じてイベントを選びます。PreToolUseはツール実行の直前に走り、ツール実行を事前に止められるのはPreToolUseだけです。PostToolUseは実行後なので整形やテスト向き。Stopは応答完了時に走るため、通知やコミット確認をまとめて挟むのに適します。

PreToolUse:実行前チェック・拒否(安全装置向き)
PostToolUse:編集後のフォーマット・Lint・テスト
Stop:応答終了時の通知やサマリ出力

settings.jsonへのフック定義とmatcherの記述パターン

フックは~/.claude/settings.jsonか、プロジェクト直下の.claude/settings.jsonに書きます。肝はmatcherでのツール名の絞り込みで、Edit|Writeのように正規表現で複数指定できます。空文字にすると全ツールにマッチし、意図しない実行にまで割り込む事故が起きやすいので注意してください。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
    }]
  }
}

コード整形・テスト・通知を実現する実践的なフック設定例

実務で効くのは「編集直後の自動整形」と「破壊的操作の遮断」です。前者は差分ノイズを減らしてレビューを軽くし、後者は事故そのものを防ぎます。いずれもClaudeの出力を待たず確実に走らせられる点が、Hooksの強みです。

ファイル編集後に自動でLintとフォーマッタを走らせる

PostToolUseでeslint --fixや、Laravelなら./vendor/bin/pintを対象ファイルに適用します。編集対象は標準入力で渡されるJSONに含まれるため、jq -r '.tool_input.file_path' | xargsで受け取れます。プロジェクト全体を舐めず差分ファイルだけを整形でき、実行時間を短く保てます。整形後の内容は、Claudeの次の判断にもそのまま反映されます。

危険なコマンドをPreToolUseでブロックする安全装置の作り方

PreToolUseフックが終了コード2を返すと、そのツール実行はキャンセルされ、標準エラーの内容がClaudeにフィードバックされます。この挙動を使えば、rm -rfや本番向けphp artisan migrate:freshを検知したらexit 2で止める、という判断ロジックを組めます。

フックが発火しない・意図せず処理が止まる原因と検証手順

「設定したのに動かない」の大半は、matcherのツール名不一致かJSONの記述ミスです。保存しても既存セッションには反映されないので、変更後はClaude Codeを起動し直すのが基本。/hooksコマンドで現在ロードされている定義を確認すれば、そもそも読み込まれていないケースをすぐ切り分けられます。

終了コードとexit 2の挙動を理解して制御する

混乱しやすいのが終了コードの意味です。0は成功、2はブロックしてClaudeへエラーを返す。それ以外の非ゼロは「非ブロッキングエラー」で、ユーザーに表示されるだけで処理は続行します。フォーマッタが失敗しても作業を止めたくないなら、あえてexit 2を返さない設計にする、という選択が必要です。

EC-CUBEやLaravel開発でHooksを本番運用する際の注意点

チーム運用で最も効くのは、フックをプロジェクトの.claude/settings.jsonに置いてGit管理し、整形ルールを全員で共有することです。ただしフックは任意コマンドを自動実行するため、リポジトリを共有する以上、悪意ある定義が紛れ込んでいないかをレビュー対象に含めるべきです。

また、EC-CUBEやLaravelはvendorやvar/cacheなど自動生成物が多く、matcherを絞らないとキャッシュファイルまで整形対象になりビルドが壊れます。パスで除外条件を持たせ、まずローカルで一日回してから共有するのが安全でしょう。