Claude Code Hooks完全ガイド｜自動化ワークフロー構築法【2026年版】

Q: Claude Code hooksはどのファイルに設定するのですか？

設定ファイルには3つの場所があります。プロジェクト全体で共有する設定は`.claude/settings.json`（プロジェクトルートの`.claude/`フォルダ内）、全プロジェクト共通の設定は`~/.claude/settings.json`、個人のローカル設定は`.claude/settings.local.json`に記述します。優先度は「ローカル設定 > プロジェクト共有 > グローバル設定」の順です。

Q: exit code 2で処理をブロックするとはどういう意味ですか？

PreToolUseのhookスクリプトが`exit 2`（exit code 2）を返すと、Claude Codeは「このツールの実行を中止してください」というシグナルと解釈し、実行をキャンセルします。この動作はPreToolUseのみで機能します（PostToolUseなどでは機能しません）。exit code 0は正常終了、1などはエラーとして記録されますが処理は継続します。

Claude Code Hooksを使うと、コード整形・テスト実行・Slack通知などを12のライフサイクルイベントで完全自動化できます。

要点1: PreToolUse/PostToolUseなど12のイベントで、AIの動作に連動したシェルコマンドを自動実行可能
要点2: exit code 2を返すことで危険なツール実行をブロックする「決定論的な制御」が実現できる
要点3: settings.jsonの3行追加で、コード整形の自動化が今日から始められる

対象: Claude Codeを業務で活用しているエンジニア・DX推進担当者

今日やること: /hooksコマンドを実行し、PostToolUseにPrettierを設定してみる

この記事の目次

Claude Code Hooksとは？3行でわかる仕組み
6つの主要ライフサイクルイベント一覧
基本設定：settings.jsonの書き方
実践！ユースケース別の設定例5選
チームで使うときのベストプラクティス
よくある質問
まとめ

Claude Code Hooksを活用すれば、AIがコードを編集するたびにコード整形・テスト実行・通知送信を自動で行えます。

「Claude Codeを使っているが、毎回手動でフォーマットしなければならない」「AIが変更したコードにバグが入っていないか、自動でチェックしたい」——そうした課題を抱える方は多いのではないでしょうか。

本記事では、Claude Code Hooksの基本概念から実践的な設定例5選、チームでの運用ベストプラクティスまでを解説します。設定はJSONに数行追記するだけで始められます。

Claude Code Hooksとは？3行でわかる仕組み

Claude Code Hooksは、Claude Codeのライフサイクルの特定のタイミングで、ユーザーが定義したシェルコマンドを自動実行する仕組みです。

通常、Claude Codeが「コードを整形する」「テストを実行する」といった作業を行うかどうかは、AIの判断に委ねられています。しかしHooksを使うと、「AIの判断に関係なく、設定したコマンドを必ず実行させる」ことができます。これを「決定論的な制御」と呼びます。

たとえば「PostToolUse（ツール実行後）」というイベントにPrettierのコマンドを設定しておけば、Claude Codeがファイルを書き込むたびに自動でコード整形が走ります。AIが忘れたり、やり方を間違えたりすることはありません。

ほかの自動化ツールとの違い

項目	Claude Code Hooks	従来のCI/CD	エディタのLinter設定
発火タイミング	AIのツール実行に連動	コミット/PR時	ファイル保存時
制御の粒度	ツール名・ファイルパスで絞り込み可	ブランチ・ファイル種別	ファイル種別のみ
ブロック機能	あり（exit code 2）	あり	なし
設定場所	settings.json（1ファイル）	CIの設定ファイル	エディタ設定

CI/CDはコミット後の品質チェックが主目的であるのに対し、HooksはClaude Codeが動作している最中にリアルタイムで制御できる点が大きな違いです。

Hooksで何ができるのか（できることの全体像）

Claude Code Hooksで実現できる主な自動化は以下のとおりです。

コード品質の自動担保: 整形・リント・テストを毎回の編集に連動させる
セキュリティの強化: 危険なコマンドや特定ファイルへのアクセスを事前ブロックする
チームへの通知: タスク完了やエラー発生をSlackやメールで即時通知する
Git操作の自動化: 作業完了後に自動コミット・自動プッシュを行う
ログと監査: AIの全操作を記録し、後から確認できる状態にする

6つの主要ライフサイクルイベント一覧

2026年2月時点で、Claude Code Hooksは12のライフサイクルイベントに対応しています。まず実務でよく使われる6つを押さえておきましょう。

イベント	発火タイミング	主な用途	ブロック可否
PreToolUse	ツール実行直前	コマンドの事前チェック・ブロック	○（exit code 2）
PostToolUse	ツール実行直後	コード整形・テスト実行・ログ記録	△（処理後のため限定的）
Notification	Claude通知時	デスクトップ通知・Slack連携	×
Stop	Claude応答完了時	最終チェック・レポート生成	×
SubagentStop	サブエージェント完了時	マルチエージェント処理後の検証	×
UserPromptSubmit	ユーザー入力送信時	入力内容の前処理・バリデーション	×

PreToolUse — ツール実行前に制御する

PreToolUseは、Claude Codeが何らかのツール（ファイル書き込み・コマンド実行など）を使おうとする直前に発火します。

最大の特徴はブロック機能です。exit code 2を返すと、そのツールの実行をキャンセルできます。「特定のディレクトリへの書き込みを禁止する」「本番環境への直接操作を防ぐ」といったセキュリティ用途で特に有効です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/block-dangerous-commands.sh"
          }
        ]
      }
    ]
  }
}

上記の例では、Bashコマンド実行前にカスタムスクリプトを呼び出し、rm -rfやDROP TABLEなどの危険なコマンドが検出された場合にexit code 2を返してブロックします。

PostToolUse — ツール実行後に自動処理を行う

PostToolUseは、ツールの実行が完了した直後に発火します。コード整形・テスト自動実行・ログ記録といった「作業の後始末」に最適なイベントです。

matcherには正規表現が使えます。"Write|Edit|MultiEdit"と設定すれば、ファイルの書き込みや編集操作のみに絞って発火させることができます。

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

PostToolUseでブロックはできませんが、処理完了後の品質維持に非常に効果的です。

Stop / SubagentStop — タスク完了後に後処理を行う

StopはClaude Codeが1つの応答を完了したタイミングで発火します。SubagentStopはサブエージェントがタスクを完了したときに発火する点が異なります。

タスク全体の完了通知・最終的な品質チェック・Git自動コミットなど、「一連の作業が終わったら実行したい処理」に向いています。

基本設定：settings.jsonの書き方

Hooksの設定はsettings.jsonに記述します。設定ファイルには3種類の場所があり、用途に応じて使い分けます。

設定ファイルの場所と優先順位（3層構造）

優先度	ファイルパス	用途
高	`.claude/settings.local.json`	個人のローカル設定（Gitに含めない）
中	`.claude/settings.json`	プロジェクト共有設定（Gitで管理）
低	`~/.claude/settings.json`	全プロジェクト共通のグローバル設定

チームで統一したいルール（コード整形・セキュリティチェックなど）は.claude/settings.jsonで管理し、個人の好みによる設定はsettings.local.jsonに書くのがおすすめです。

matcherで対象ツールを絞り込む方法（正規表現）

matcherには正規表現が使えます。以下の主要なツール名を覚えておくと便利です。

ツール名	発火する操作
Write	ファイルの新規作成
Edit / MultiEdit	ファイルの編集
Bash	シェルコマンドの実行
Read	ファイルの読み込み
WebFetch	Web検索・URL取得

"Write|Edit|MultiEdit"のようにパイプ（|）で複数のツールを指定できます。空文字列（""）にすると全ツールにマッチします。

settings.jsonの基本構造は以下のとおりです。

{
  "hooks": {
    "[イベント名]": [
      {
        "matcher": "[ツール名（正規表現）]",
        "hooks": [
          {
            "type": "command",
            "command": "[実行するシェルコマンド]"
          }
        ]
      }
    ]
  }
}

Claude Codeの活用、何から始めればいい？

無料でClaude Codeの活用について相談に乗ります。お気軽にお問い合わせください。

無料相談はこちら →

実践！ユースケース別の設定例5選

ここからは、現場でそのまま使えるHooks設定を5つ紹介します。いずれもコピーして.claude/settings.jsonに貼り付ければ動作します。

① コード整形を自動化（PostToolUse + Prettier/Black）

Claude Codeがファイルを書き込む・編集するたびに、自動でコード整形を行います。

JavaScript/TypeScriptプロジェクト用（Prettier）:

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

Pythonプロジェクト用（Black + isort）:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_TOOL_INPUT_FILE_PATH\" == *.py ]]; then black \"$CLAUDE_TOOL_INPUT_FILE_PATH\" && isort \"$CLAUDE_TOOL_INPUT_FILE_PATH\"; fi"
          }
        ]
      }
    ]
  }
}

ポイント2>/dev/null || trueを末尾に追記することで、整形対象外のファイルでエラーが出ても処理を継続させられます。

② テスト自動実行（PostToolUse + pytest/npm test）

コードが変更されるたびに、関連するテストを自動実行します。問題を即座に検知できます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_TOOL_INPUT_DIR\" && npm test -- --passWithNoTests 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}

テストの実行が重い場合は、PostToolUseではなくStopイベントに移動し、一連の作業が終わってからまとめて実行する設計も有効です。

③ 危険なコマンドをブロック（PreToolUse + exit code 2）

rm -rfやデータベースのDROPコマンドなど、取り返しのつかない操作を事前にブロックします。

# ~/.claude/hooks/block-dangerous-commands.sh
#!/bin/bash

COMMAND="$CLAUDE_TOOL_INPUT_COMMAND"

DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "DROP TABLE"
  "DROP DATABASE"
  "git push --force origin main"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    echo "⛔ 危険なコマンドをブロックしました: $pattern" >&2
    exit 2  # exit code 2でClaude Codeの処理をブロック
  fi
done

exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/block-dangerous-commands.sh"
          }
        ]
      }
    ]
  }
}

exit codeの意味まとめ:

exit code	意味
0	正常終了。処理を継続
2	ブロック。Claude Codeの処理をキャンセル（PreToolUseのみ有効）
その他（1など）	エラーとして記録されるが、処理は継続

④ タスク完了をSlackに通知（Stop + curl webhook）

Claude Codeの応答が完了したタイミングで、Slackチャンネルに自動通知を送ります。長時間のタスクを依頼した際に手元を離れても安心です。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST -H 'Content-type: application/json' --data '{\"text\":\"✅ Claude Codeのタスクが完了しました\"}' YOUR_SLACK_WEBHOOK_URL"
          }
        ]
      }
    ]
  }
}

YOUR_SLACK_WEBHOOK_URLの部分をSlackのIncoming Webhook URLに置き換えるだけで動作します。通知内容を$CLAUDE_SESSION_IDや完了時刻などの変数で動的に変えることも可能です。

⑤ Git自動コミット（Stop + git commit）

タスク完了後に自動でGitコミットを行います。作業の区切りが明確になり、変更履歴の管理が楽になります。

# ~/.claude/hooks/auto-commit.sh
#!/bin/bash

cd "${CLAUDE_WORKING_DIRECTORY:-$(pwd)}"

# 変更がある場合のみコミット
if ! git diff --quiet || ! git diff --staged --quiet; then
  TIMESTAMP=$(date '+%Y-%m-%d %H:%M')
  git add -A
  git commit -m "chore: Claude Code auto-commit at $TIMESTAMP"
  echo "✅ 自動コミット完了"
fi

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/auto-commit.sh"
          }
        ]
      }
    ]
  }
}

注意自動コミットを有効にする場合は、コミット前に変更内容を確認できるよう、プッシュは手動で行うことをおすすめします。

チームで使うときのベストプラクティス

個人での活用に慣れてきたら、次はチームでのHooks運用を検討しましょう。適切に設定することで、チーム全体のコード品質を均一に保てます。

個人用 vs プロジェクト共有の設定ファイル使い分け

チームでのHooks運用において最も重要なのが、設定ファイルの使い分けです。

プロジェクト共有設定（.claude/settings.json）に書くべきもの:

コード整形（Prettier, Black, gofmt等）のルール
チームで統一したセキュリティチェック
テスト自動実行のルール
プロジェクト固有の禁止コマンド

個人設定（~/.claude/settings.jsonまたは.claude/settings.local.json）に書くべきもの:

個人のSlack通知設定（webhookが個人依存のため）
ローカル環境固有のパス設定
個人の好みによる補助的な整形ツール

.claude/settings.local.jsonはGitに含めないため、個人情報（webhookトークン等）を書いても安全です。.gitignoreに.claude/settings.local.jsonを追記しておくことを忘れないようにしましょう。

セキュリティ：hooks経由でやってはいけないこと

Hooksは強力な自動化ツールですが、セキュリティ上の注意点もあります。

避けるべき設定:

シークレットキーやAPIキーをコマンド内に直接記述する（環境変数や専用の設定ファイルを使う）
Hookスクリプト内で外部から取得したコンテンツをそのままシェルに渡す（コマンドインジェクションのリスク）
全ツールに対して重い処理を設定する（Claude Codeの応答が遅くなる）

チェックリスト:

[ ] APIキー等は環境変数または~/.envから参照している
[ ] .claude/settings.local.jsonは.gitignoreに追記している
[ ] フックスクリプトにset -eを入れてエラーを確実に検知している
[ ] matcherで発火対象を必要最小限に絞っている

また、Claude Code HooksはClaude Code 始め方で解説している基本設定の理解があるとよりスムーズに活用できます。Claude Code CLIリファレンスも合わせて参照してください。

Claude Code Agent・サブエージェントと組み合わせると、SubagentStopを使ったより高度な自動化ワークフローが構築できます。Claude Code MCP連携と組み合わせることで、外部ツールとの連携もHooks経由で制御できます。

よくある質問

Q. Claude Code hooksはどのファイルに設定するのですか？

設定ファイルには3つの場所があります。プロジェクト全体で共有する設定は.claude/settings.json（プロジェクトルートの.claude/フォルダ内）、全プロジェクト共通の設定は~/.claude/settings.json、個人のローカル設定は.claude/settings.local.jsonに記述します。優先度は「ローカル設定 > プロジェクト共有 > グローバル設定」の順です。

Q. PreToolUseとPostToolUseはどう使い分けるべきですか？

PreToolUseは「ツール実行前に何かをチェックし、場合によってはブロックしたい」ときに使います。PostToolUseは「ツールが実行された後に後処理をしたい」ときに使います。コード整形・テスト実行などの品質チェックはPostToolUseが適しており、危険なコマンドのブロックはPreToolUseが適しています。

Q. exit code 2で処理をブロックするとはどういう意味ですか？

PreToolUseのhookスクリプトがexit 2（exit code 2）を返すと、Claude Codeは「このツールの実行を中止してください」というシグナルと解釈し、実行をキャンセルします。この動作はPreToolUseのみで機能します（PostToolUseなどでは機能しません）。exit code 0は正常終了、1などはエラーとして記録されますが処理は継続します。

Q. hooksが実行されないとき、まず何を確認すべきですか？

以下の点を順番に確認してください。①settings.jsonのJSONフォーマットが正しいか（カンマ漏れや括弧の不一致がないか）、②hookスクリプトに実行権限があるか（chmod +x スクリプト名）、③matcherの正規表現が実際のツール名と一致しているか、④/hooksコマンドでhooksの設定一覧に表示されているかを確認することで、問題の多くが特定できます。