公開日: 最終更新:
公式ドキュメント・公式発表などの一次情報を確認したうえで、株式会社Nexaが執筆・更新しています。AIツールの仕様や料金は変わることがあるため、導入判断の前に各公式サイトの最新情報もご確認ください。運営会社について
Claude Code Hooksは、ツール実行の前後や応答の完了時など決まった時点で、設定したコマンドを必ず実行する仕組みです。設定は settings.json の hooks に書きます。
- 要点1: イベントは公式リファレンスで33種類（2026年9月28日確認）。まず使うのは PreToolUse・PostToolUse・Stop など6つ
- 要点2: hookへの入力は、環境変数ではなく標準入力のJSONで渡される。ファイルパスやコマンドは jq で取り出す
- 要点3: exit code 2 を返すと、PreToolUse ではツールの実行、Stop では応答の終了、UserPromptSubmit ではプロンプトの処理を止められる
対象: Claude Codeを業務で活用しているエンジニア・DX推進担当者
今日やること: .claude/settings.json に PostToolUse の整形hookを1つ書き、/hooks で読み込まれたことを確認する
Claude Code Hooksは、設定ファイル（settings.json）の hooks に「どの時点で」「何を実行するか」を書くだけで使えます。Claude Codeがファイルを編集するたびにコードを整形する、危険なコマンドを実行前に止める、応答が終わったら通知する、といった処理を、AIの判断に任せず毎回実行できます。
この記事は2026年3月に公開し、2026年9月28日に公式ドキュメントの現在の仕様に合わせて全面的に見直しました。イベントの数、exit code 2 で止められる範囲、入力の受け取り方、/hooks コマンドの役割が、公開当初の説明から変わっています。以前の内容をもとに設定した方は、設定例を差し替えてください。
やりたいことと、使うイベントの対応は次のとおりです。
| やりたいこと | 使うイベント | 設定の要点 |
|---|---|---|
| 編集のたびにコードを整形する | PostToolUse | matcherは Edit|Write。ファイルパスは標準入力のJSONから取り出す |
| 危険なコマンドを実行前に止める | PreToolUse | matcherは Bash。スクリプトが exit code 2 を返すと実行されない |
| 承認待ち・入力待ちを知らせる | Notification | デスクトップ通知のコマンドを実行する |
| 応答が終わったら通知・コミットする | Stop | matcherは書かない（書いても無視される） |
| 条件を満たすまで作業を続けさせる | Stop | exit code 2、またはプロンプト型のhookで判定する |
Claude Code Hooksとは？3行でわかる仕組み
Claude Code Hooksは、Claude Codeの動作の決まった時点（イベント）で、ユーザーが定義した処理を自動で実行する仕組みです。実行できるのはシェルコマンドが基本で、現在はHTTPエンドポイントの呼び出しや、AIモデルによる判定なども設定できます。
通常、Claude Codeが「コードを整形する」「テストを実行する」といった作業を行うかどうかは、AIの判断に委ねられています。しかしHooksを使うと、「AIの判断に関係なく、設定したコマンドを必ず実行させる」ことができます。公式ドキュメントはこれを決定論的な制御（deterministic control）と説明しています。
たとえば「PostToolUse（ツール実行後）」というイベントにPrettierのコマンドを設定しておけば、Claude Codeがファイルを書き込むたびに自動でコード整形が走ります。AIが忘れたり、やり方を間違えたりすることはありません。
1回のやり取りの中では、入力を送信した時点で UserPromptSubmit、ツール実行の直前に PreToolUse、直後に PostToolUse、応答が完了した時点で Stop が順に発火します。このほか、Claude Codeが通知を送るときの Notification、サブエージェントが完了したときの SubagentStop があり、実務ではこの6つをまず押さえます。
ほかの自動化ツールとの違い
| 項目 | Claude Code Hooks | 従来のCI/CD | エディタのLinter設定 |
|---|---|---|---|
| 発火タイミング | AIのツール実行などに連動 | コミット/PR時 | ファイル保存時 |
| 制御の粒度 | ツール名・引数で絞り込み可 | ブランチ・ファイル種別 | ファイル種別のみ |
| ブロック機能 | あり（exit code 2 など） | あり | なし |
| 設定場所 | settings.json など | CIの設定ファイル | エディタ設定 |
CI/CDはコミット後の品質チェックが主目的であるのに対し、HooksはClaude Codeが動作している最中にリアルタイムで制御できる点が大きな違いです。
Hooksで何ができるのか（できることの全体像）
Claude Code Hooksで実現できる主な自動化は以下のとおりです。
- コード品質の自動担保: 整形・リント・テストを毎回の編集に連動させる
- セキュリティの強化: 危険なコマンドや、保護したいファイルへの書き込みを実行前に止める
- 通知: 承認待ち・入力待ち・応答の完了を、デスクトップ通知やチャットで知らせる
- Git操作の自動化: 応答の完了時に自動でコミットする
- ログと監査: 実行されたコマンドや設定の変更を記録し、後から確認できる状態にする
6つの主要ライフサイクルイベント一覧
公開当初のこの記事では、イベントを12種類と紹介していました。2026年9月28日に公式リファレンスを確認したところ、イベントは33種類に増えています。数は今後も変わる可能性があるため、最新の一覧は公式リファレンスで確認してください。まずは、実務でよく使う6つを押さえておきましょう。
| イベント | 発火タイミング | 主な用途 | exit code 2 を返したとき |
|---|---|---|---|
| PreToolUse | ツール実行の直前 | コマンドの事前チェック・ブロック | ○ ツールの実行を止める |
| PostToolUse | ツールが成功した直後 | コード整形・テスト実行・ログ記録 | × 実行済みのため止まらない（エラー出力はClaudeに伝わる） |
| Notification | Claude Codeが通知を送るとき | デスクトップ通知・チャット連携 | × 終了コードは無視される |
| Stop | Claudeの応答が完了したとき | 最終チェック・完了通知 | ○ 応答を終わらせず、作業を続けさせる |
| SubagentStop | サブエージェントが完了したとき | サブエージェントの成果の検証 | ○ サブエージェントを終わらせない |
| UserPromptSubmit | 入力を送信したとき（Claudeが処理する前） | 入力の前処理・検証 | ○ 処理を止め、そのプロンプトを消去する |
公開当初は「ブロックできるのは PreToolUse だけ」と説明していましたが、現在の公式リファレンスでは、Stop・SubagentStop・UserPromptSubmit も exit code 2 で止められます。
PreToolUse — ツール実行前に制御する
PreToolUseは、Claude Codeが何らかのツール（ファイル書き込み・コマンド実行など）を使おうとする直前に発火します。
最大の特徴はブロック機能です。exit code 2を返すと、そのツールの実行を止められます。止めた理由として標準エラー出力に書いた内容はClaudeに伝わるため、Claudeは別の方法を検討できます。「特定のディレクトリへの書き込みを禁止する」「本番環境への直接操作を防ぐ」といったセキュリティ用途で特に有効です。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-commands.sh"
}
]
}
]
}
}
上記の例では、Bashコマンドの実行前にプロジェクト内のスクリプトを呼び出します。スクリプトは、標準入力のJSONから実行予定のコマンドを取り出し、rm -rfやDROP TABLEなどが含まれていれば exit code 2 を返します。スクリプトの中身は、設定例③に掲載しています。
PostToolUse — ツール実行後に自動処理を行う
PostToolUseは、ツールの実行が成功した直後に発火します。コード整形・テスト自動実行・ログ記録といった「作業の後始末」に最適なイベントです。ツールが失敗した場合は、別のイベント（PostToolUseFailure）が発火します。
matcherに Edit|Write と設定すれば、ファイルの編集と書き込みのときだけ発火させることができます。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
編集されたファイルのパスは、標準入力のJSONの tool_input.file_path に入っています。上の例は、公式ガイドに掲載されている書き方で、jq でパスを取り出してPrettierに渡しています。
PostToolUseが動く時点でツールは実行済みのため、実行を取り消すことはできません。exit code 2 を返した場合は、エラー出力の内容がClaudeに伝わり、Claudeが修正に取りかかれます。実行を止めたい処理は PreToolUse、整形やテストなどの後処理は PostToolUse に設定するのが基本です。
Stop / SubagentStop — タスク完了後に後処理を行う
StopはClaude Codeが1つの応答を完了したタイミングで発火します。SubagentStopはサブエージェントが応答を完了したときに発火する点が異なります。
完了の通知・最終的な品質チェック・Git自動コミットなど、「一連の作業が終わったら実行したい処理」に向いています。ただし、Stopは作業全体が終わったときだけでなく、Claudeが応答を終えるたびに発火します。ユーザーが途中で中断した場合は発火しません。
Stopで exit code 2 を返すと、Claudeは応答を終えずに作業を続けます。条件がいつまでも満たされないと止まらなくなるため、入力のJSONにある stop_hook_active を確認し、すでにhookの指示で作業を続けている場合は終了を認めるようにします。Claude Code側にも、8回連続で止められた場合はhookを無視して終了する上限があります。
#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0 # すでにhookの指示で作業を続けている場合は、終了を認める
fi
# ここから下に、終了してよいかを確かめる処理を書く
そのほかのイベント
6つ以外で、業務で使う場面があるイベントの例です。
| イベント | 発火タイミング |
|---|---|
| SessionStart / SessionEnd | セッションの開始・再開時 / 終了時 |
| PermissionRequest | ツールの実行に権限の判断が必要なとき |
| PostToolUseFailure | ツールの実行が失敗した直後 |
| SubagentStart | サブエージェントが起動したとき |
| PreCompact / PostCompact | 会話履歴の圧縮の前 / 後 |
| ConfigChange | セッション中に設定ファイルが変更されたとき |
| FileChanged | 監視対象のファイルがディスク上で変更されたとき |
基本設定：settings.jsonの書き方
Hooksの設定はsettings.jsonに記述します。設定ファイルには複数の場所があり、どこに書くかで適用される範囲が決まります。
設定ファイルの場所と適用範囲
| ファイルパス | 適用範囲 | チームでの共有 |
|---|---|---|
~/.claude/settings.json |
自分の全プロジェクト | しない（自分のPCのみ） |
.claude/settings.json |
そのプロジェクト | する（Gitで管理） |
.claude/settings.local.json |
そのプロジェクト（自分のみ） | しない（Gitに含めない） |
公開当初は、この3つに「優先順位」があると説明していましたが、hookについては正確ではありませんでした。公式リファレンスによると、hookの設定は上書きではなくマージされ、各ファイルに書いたhookはどれも実行されます。同じ内容のhookを複数の設定ファイルに書いた場合は、1回だけ実行されます。
設定できる場所は、このほかに、組織の管理者が配布する管理ポリシー設定、プラグイン、スキルやサブエージェントの定義があります。チームで統一したいルール（コード整形・セキュリティチェックなど）は.claude/settings.jsonで管理し、個人の好みによる設定はsettings.local.jsonに書くのがおすすめです。
matcherで対象ツールを絞り込む方法（正規表現）
matcherは、hookを実行する対象を絞り込む項目です。PreToolUse や PostToolUse では、ツール名に対して判定されます。主なツール名は次のとおりです。
| ツール名 | 発火する操作 |
|---|---|
| Write | ファイルの新規作成・上書き |
| Edit | 既存ファイルの編集（文字列の置換） |
| Bash | シェルコマンドの実行 |
| Read | ファイルの読み込み |
| WebFetch | 指定したURLの内容の取得 |
| WebSearch | Web検索 |
mcp__サーバー名__ツール名 |
MCPサーバーのツールの実行 |
matcherの書き方によって、判定の方法が変わります。
| matcherの値 | 判定の方法 | 例 |
|---|---|---|
*、空文字列、または省略 |
すべてに一致 | そのイベントが起きるたびに実行 |
| 英数字・アンダースコア・ハイフン・空白・カンマ・縦棒のみ | 完全一致（縦棒やカンマで複数指定） | Bash、Edit|Write |
| 上記以外の文字を含む | 正規表現（部分一致） | mcp__memory__.*、^Notebook |
大文字と小文字は区別されます。また、UserPromptSubmit や Stop のように、matcherに対応していないイベントもあります。その場合、matcherを書いても無視され、イベントが起きるたびに実行されます。ツール名に加えて引数でも絞り込みたいときは、hookごとに if を指定します（例: Bash(git *)、Edit(*.ts)）。
settings.jsonの基本構造は以下のとおりです。「イベント名」「対象の絞り込み」「実行する処理」の3階層で書きます。
{
"hooks": {
"イベント名": [
{
"matcher": "対象の絞り込み（ツール名など）",
"hooks": [
{
"type": "command",
"command": "実行するシェルコマンド"
}
]
}
]
}
}
hookへの入力は標準入力のJSONで受け取る
公開当初の設定例では $CLAUDE_TOOL_INPUT_FILE_PATH などの環境変数を使っていましたが、公式リファレンスにこれらの記載はありません。hookへの入力は、標準入力にJSONで渡されます。たとえば、Bashコマンドの実行前（PreToolUse）には、次のような内容が渡されます（主な項目を抜粋）。
{
"session_id": "abc123",
"cwd": "/home/user/my-project",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
}
}
スクリプトでは、この内容を jq などで読み取ります。jq が入っていない場合は、macOSなら brew install jq、DebianやUbuntuなら apt-get install jq でインストールできます。スクリプトの場所を指定するときは、プロジェクトのルートを指す $CLAUDE_PROJECT_DIR が使えます。
hookの種類はcommandを含めて5つ
type に指定できる種類は、公開当初に紹介した command のほかに4つあります。
| type | 実行される処理 |
|---|---|
command |
シェルコマンドを実行する。入力は標準入力、結果は終了コードと標準出力で返す |
http |
入力のJSONを、指定したURLにHTTP POSTで送る |
mcp_tool |
設定済みのMCPサーバーのツールを呼び出す |
prompt |
プロンプトをClaudeのモデルに送り、1回の応答で判定させる |
agent |
ファイルの読み取りや検索ができるサブエージェントに検証させる（実験的な機能） |
たとえば、応答を終える前に「依頼された作業がすべて終わっているか」をモデルに判定させる設定は、次のように書きます（公式ガイドの例）。終わっていないと判定された場合、Claudeは作業を続けます。
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "prompt",
"prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
}
]
}
]
}
}
イベントによって、使える種類は異なります。明確なルールで判定できる処理は command、判断が必要な処理は prompt と使い分けます。
/hooksコマンドは確認専用
Claude Codeで /hooks を実行すると、設定済みのhookをイベントごとに確認できます。どの設定ファイルに書かれたhookかも表示されます。この画面は読み取り専用で、hookの追加・変更・削除はできません。設定ファイルのJSONを直接編集するか、Claudeに変更を依頼します。編集した内容は、通常は自動的に読み込まれます。
AI導入に関するお困りごとは、株式会社NexaのAI顧問がサポートします。「何から始めればいいか分からない」という段階からご相談いただけます。
実践！ユースケース別の設定例5選
ここからは、現場で使えるHooksの設定を5つ紹介します。いずれも、2026年9月28日に公式ドキュメントの仕様と照合し、設定のJSONが正しい形式であることを確認しています。設定は.claude/settings.jsonに書きます。すでに hooks がある場合は、全体を置き換えず、イベント名を並べて追加してください。
スクリプトを使う例では、スクリプトをプロジェクトの .claude/hooks/ に保存し、実行権限を付けます。
chmod +x .claude/hooks/block-dangerous-commands.sh
① コード整形を自動化（PostToolUse + Prettier/Black）
Claude Codeがファイルを書き込む・編集するたびに、自動でコード整形を行います。
JavaScript/TypeScriptプロジェクト用（Prettier）:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
Pythonプロジェクト用（Black + isort）:
拡張子で対象を絞るため、スクリプトに分けます。
#!/bin/bash
# .claude/hooks/format-python.sh
# 標準入力のJSONから、編集されたファイルのパスを取り出す
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
# Python以外のファイルは何もしない
if [[ "$FILE_PATH" != *.py ]]; then
exit 0
fi
black "$FILE_PATH" && isort "$FILE_PATH"
exit 0
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format-python.sh"
}
]
}
]
}
}
ポイントhookが成功したとき、会話には何も表示されません。動いたかどうかは、編集されたファイルが整形されているかで確認します。
② テスト自動実行（PostToolUse + pytest/npm test）
コードが変更されるたびに、テストを自動実行します。hookは通常、終わるまでClaudeの作業を待たせます。テストのように時間がかかる処理は、async を true にしてバックグラウンドで実行すると、Claudeは作業を続けられます。結果は、次のやり取りのときにClaudeへ伝わります。
#!/bin/bash
# .claude/hooks/run-tests-async.sh
# 標準入力のJSONから、編集されたファイルのパスを取り出す
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
# ソースファイル以外ではテストを実行しない
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
exit 0
fi
# テストを実行し、結果を additionalContext でClaudeに伝える
RESULT=$(npm test 2>&1)
EXIT_CODE=$?
if [ $EXIT_CODE -eq 0 ]; then
MSG="Tests passed after editing $FILE_PATH"
else
MSG="Tests failed after editing $FILE_PATH: $RESULT"
fi
jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
"args": [],
"async": true
}
]
}
]
}
}
公式リファレンスに掲載されている例です（コメントは日本語に直しています）。Pythonのプロジェクトでは、拡張子の判定を *.py に、npm test を pytest に置き換えます。
③ 危険なコマンドをブロック（PreToolUse + exit code 2）
rm -rfやデータベースのDROPコマンドなど、取り返しのつかない操作を事前にブロックします。
#!/bin/bash
# .claude/hooks/block-dangerous-commands.sh
# 標準入力のJSONから、実行されようとしているコマンドを取り出す
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
DANGEROUS_PATTERNS=(
"rm -rf /"
"rm -rf ~"
"DROP TABLE"
"DROP DATABASE"
"git push --force"
)
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
if echo "$COMMAND" | grep -qiF -- "$pattern"; then
echo "危険なコマンドをブロックしました: $pattern" >&2
exit 2 # exit code 2: ツールの実行を止める
fi
done
exit 0 # 判断なし: 通常の権限確認に進む
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-commands.sh"
}
]
}
]
}
}
exit codeの意味まとめ:
| exit code | 意味 |
|---|---|
| 0 | 正常終了。処理を継続（ツールの実行前なら、通常の権限確認に進む） |
| 2 | ブロック。何が止まるかはイベントによって異なる（PreToolUse はツールの実行、Stop は応答の終了、UserPromptSubmit はプロンプトの処理） |
| その他（1など） | ブロックにならないエラーとして扱われ、処理は継続 |
注意ルールを守らせるためのhookでは、必ず exit code 2 を使います。一般的なエラーを表す終了コード1では、処理は止まりません。また、文字列の一致による判定は、書き方を変えたコマンドを見逃すことがあります。確実に禁止したい操作は、権限設定（
permissionsのdeny）も併用してください。
④ タスク完了をSlackに通知（Stop + curl webhook）
Claude Codeの応答が完了したタイミングで、Slackチャンネルに自動通知を送ります。長時間のタスクを依頼した際に手元を離れても安心です。
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "curl -s -X POST -H 'Content-type: application/json' --data '{\"text\":\"Claude Codeの応答が完了しました\"}' \"$SLACK_WEBHOOK_URL\""
}
]
}
]
}
}
SlackのIncoming Webhook URLは、設定ファイルに直接書かず、環境変数 SLACK_WEBHOOK_URL に設定しておきます。hookは、Claude Codeを起動したシェルの環境変数を引き継ぎます。Stopはmatcherに対応していないため、matcherは書きません。
通知の文面を応答の内容に合わせて変えたい場合は、標準入力のJSONにある session_id や last_assistant_message（最後の応答の本文）を使います。応答のたびではなく、承認待ちや入力待ちのときだけ知らせたい場合は、Stopの代わりにNotificationを使います。
⑤ Git自動コミット（Stop + git commit）
応答の完了時に自動でGitコミットを行います。作業の区切りが明確になり、変更履歴の管理が楽になります。
#!/bin/bash
# .claude/hooks/auto-commit.sh
# プロジェクトのルートへ移動する（Gitの管理下でなければ何もしない）
cd "$CLAUDE_PROJECT_DIR" || exit 0
git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
# 変更がある場合のみコミットする（未追跡のファイルも対象）
if [ -n "$(git status --porcelain)" ]; then
TIMESTAMP=$(date '+%Y-%m-%d %H:%M')
git add -A
git commit -q -m "chore: Claude Code auto-commit at $TIMESTAMP"
fi
exit 0
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-commit.sh"
}
]
}
]
}
}
注意Stopは応答のたびに発火するため、コミットも応答のたびに作られます。
git add -Aはすべての変更を対象にするので、秘密情報を含むファイルは.gitignoreで除外しておきます。コミット前に変更内容を確認できるよう、プッシュは手動で行うことをおすすめします。
チームで使うときのベストプラクティス
個人での活用に慣れてきたら、次はチームでのHooks運用を検討しましょう。適切に設定することで、チーム全体のコード品質を均一に保てます。
個人用 vs プロジェクト共有の設定ファイル使い分け
チームでのHooks運用において最も重要なのが、設定ファイルの使い分けです。
プロジェクト共有設定（.claude/settings.json）に書くべきもの:
- コード整形（Prettier, Black, gofmt等）のルール
- チームで統一したセキュリティチェック
- テスト自動実行のルール
- プロジェクト固有の禁止コマンド
個人設定（~/.claude/settings.jsonまたは.claude/settings.local.json）に書くべきもの:
- 個人の通知設定（デスクトップ通知や、個人宛てのチャット通知）
- ローカル環境固有のパス設定
- 個人の好みによる補助的な整形ツール
.claude/settings.local.jsonは、Claude Codeが作成した場合は自動的にGitの管理対象から外れます。手作業で作成した場合は、.gitignoreに.claude/settings.local.jsonを追記してください。なお、Gitに含めないファイルであっても、webhookのURLやAPIキーなどの秘密情報は設定に直接書かず、環境変数から参照するほうが安全です。
セキュリティ：hooks経由でやってはいけないこと
Hooksは強力な自動化ツールですが、セキュリティ上の注意点もあります。commandのhookは、利用者本人の権限でシェルコマンドを実行します。設定に追加する前に、内容を確認し、動作を試してください。
避けるべき設定:
- シークレットキーやAPIキーをコマンド内に直接記述する（環境変数から参照する）
- 入力のJSONや外部から取得した内容を、検証せずにそのままシェルに渡す（コマンドインジェクションのリスク。シェル変数は必ず
"$VAR"のように引用符で囲む） - 全ツールに対して重い処理を設定する（Claude Codeの応答が遅くなる。時間がかかる処理は
asyncでバックグラウンドに回す）
他の人が作成したリポジトリを開くときは、.claude/settings.json にどのようなhookが書かれているかを先に確認します。対話形式で使う場合、そのフォルダを信頼するかどうかの確認に同意するまでhookは実行されませんが、claude -p による非対話の実行では確認が表示されず、hookが実行されます。
チェックリスト:
- □ APIキーなどの秘密情報は、コマンド内に直接書かず、環境変数から参照している
- □
.claude/settings.local.jsonが.gitignoreなどでGitの管理対象から外れている - □ ルールを守らせるhookは、exit code 2 を返している（終了コード1では処理が続く）
- □ matcherで発火対象を必要最小限に絞り、全ツールへの重い処理を避けている
- □ 入力や外部の内容を、検証せずにそのままシェルに渡していない
また、Claude Code HooksはClaude Code 始め方で解説している基本設定の理解があるとよりスムーズに活用できます。Claude Code CLIリファレンスも合わせて参照してください。権限設定（allow・deny）の書き方は、Claude Codeの設定ガイドで解説しています。
Claude Code Agent・サブエージェントと組み合わせると、SubagentStopを使ったより高度な自動化ワークフローが構築できます。Claude Code MCP連携と組み合わせることで、外部ツールとの連携もHooks経由で制御できます。
よくある質問
Q. Claude Code hooksはどのファイルに設定するのですか？
設定ファイルの hooks に書きます。自分の全プロジェクトに適用するなら ~/.claude/settings.json、チームで共有するならプロジェクトの .claude/settings.json、そのプロジェクトで自分だけが使うなら .claude/settings.local.json です。どれか1つが優先されるのではなく、各ファイルに書いたhookは併せて実行されます。このほか、組織の管理ポリシー設定、プラグイン、スキルやサブエージェントの定義にも書けます。
Q. PreToolUseとPostToolUseはどう使い分けるべきですか？
実行そのものを止めたい処理は PreToolUse、実行した後の後処理は PostToolUse に設定します。危険なコマンドや保護したいファイルへの書き込みを止めるのは PreToolUse、コード整形・テスト実行・ログ記録は PostToolUse が向いています。PostToolUse が動く時点でツールは実行済みのため、実行を取り消すことはできません。
Q. exit code 2で処理をブロックするとはどういう意味ですか？
hookのコマンドが終了コード2で終わると、Claude Codeはそれを「止める」という合図として扱います。何が止まるかはイベントごとに異なり、PreToolUse ではツールの実行、UserPromptSubmit ではプロンプトの処理、Stop と SubagentStop では応答の終了が止まります。PostToolUse はツールが実行済みのため止められませんが、エラー出力の内容がClaudeに伝わります。終了コード1など、0と2以外はブロックにならず、処理は続きます。
Q. hooksが実行されないとき、まず何を確認すべきですか？
次の順に確認します。①Claude Codeで /hooks を実行し、該当のイベントにhookが表示されるか。②設定ファイルのJSONが正しいか（末尾のカンマやコメントは使えません）。③matcherがツール名と一致しているか（大文字と小文字は区別されます）。④スクリプトに実行権限があるか（chmod +x）。それでも分からないときは claude --debug で起動し、デバッグログでhookの実行結果を確認します。
Q. $CLAUDE_TOOL_INPUT_FILE_PATH のような環境変数でファイルパスを受け取れますか？
2026年9月28日に公式リファレンスを確認した範囲では、この名前の環境変数は記載されていません。hookへの入力は、標準入力にJSONで渡されます。編集されたファイルのパスは tool_input.file_path、実行されるコマンドは tool_input.command に入っているため、jq などで取り出します。公式が案内している環境変数は、プロジェクトのルートを指す CLAUDE_PROJECT_DIR などです。
Q. /hooks コマンドからhookを追加できますか？
できません。/hooks は、設定済みのhookを確認するための読み取り専用の画面です。追加・変更・削除は、設定ファイルのJSONを直接編集するか、Claudeに変更を依頼します。編集した内容は、通常は再起動なしで自動的に読み込まれます。
Q. hooksを一時的に無効にするにはどうすればよいですか？
設定ファイルで disableAllHooks を true にすると、hookを削除せずにまとめて無効にできます。個別のhookだけを無効にする方法はないため、1つだけ止めたい場合はその項目を設定ファイルから削除します。組織の管理ポリシー設定で配布されたhookは、利用者側の設定では無効にできません。
＼ AI活用の「次の一手」を一緒に考えませんか ／
AI顧問の無料相談はこちらまとめ
Claude Code Hooksについて、基本概念から実践設定まで解説しました。重要なポイントをまとめます。
- Hooksは「決定論的な制御」：AIの判断に関係なく、設定したコマンドを必ず実行させられる
- イベントは33種類（2026年9月28日確認）：まずは PreToolUse・PostToolUse・Stop など6つを使い分ける
- 設定ファイルは併せて実行される：ユーザー・プロジェクト共有・ローカルのどこに書いたhookも実行される
- 入力は標準入力のJSON：ファイルパスやコマンドは jq で取り出す
- exit code 2：PreToolUse のほか、Stop・SubagentStop・UserPromptSubmit でも処理を止められる
- チーム運用のポイント：秘密情報は環境変数で管理し、settings.local.jsonはGitに含めない
最初の一歩としては、.claude/settings.json に PostToolUse のPrettierの設定（設定例①）を書くのがおすすめです。書いたあとに /hooks を実行し、PostToolUse にhookが表示されれば、設定は読み込まれています。
参考にした公式ドキュメント
この記事の仕様に関する記述は、次の公式ドキュメントを2026年9月28日に確認して書いています。仕様は更新されることがあるため、設定の前に最新の内容を確認してください。
- Hooks reference（Claude Code Docs）
- Automate actions with hooks（Claude Code Docs）
- Settings files and precedence（Claude Code Docs）
法人向けAI導入・活用の月額伴走サービス
AI導入の疑問を、週1回のMTGで相談できる「AI顧問」
株式会社Nexaでは、ChatGPT・Claude・Claude CodeなどのAI導入に関する質問や、社内活用・業務自動化の進め方を週1回相談できる 月額7万円（毎月3社限定で月額5万円）のAI顧問サービス を提供しています。
「自社では何から始めるべきか」「この業務はAI化できるか」「どのツールを選ぶべきか」を、無料相談で整理します。
この記事で参照した外部情報
- Hooks reference（Claude Code Docs）code.claude.com
- Automate actions with hooks（Claude Code Docs）code.claude.com
- Settings files and precedence（Claude Code Docs）code.claude.com
本文中でリンクしている外部ページの一覧です（自動生成）。最終確認日は本記事の最終更新日 2026-09-28 で、リンク先の内容はその後変わることがあります。
AI導入を検討中の方へ
