インサイトトップ/記事一覧/Claude CodeのHooksとは?設定方法と使い分けを解説

SHARE

Claude CodeのHooksとは?設定方法と使い分けを解説

Claude CodeのHooksとは?設定方法と使い分けを解説

下岡 稔
2026.11.16

「コミット前にテストを回す」とCLAUDE.mdに書いても、Claude Codeが毎回そのとおりに動くとは限りません。Hooksは、決まった時点でClaude Codeが毎回自動で実行する処理です。

この記事では、仕組み・書き方・設定例・確認方法・安全上の注意を解説します。

Claude CodeのHooksとは?決まった時点で自動実行される処理

CLAUDE.mdは読んで従おうとする設定、Hooksはイベントが起きたらClaude Codeが実行する処理という違いを上下2段で示した図

Hooksは、Claudeの判断に任せず、決まった時点でClaude Code自身が実行する機能です。「ファイルを保存したら整形する」「このコマンドは実行前に止める」といったルールを、毎回同じように働かせたいときに使います。

Claude Code全体の使い方は「Claude Codeの使い方——インストールから基本操作・つまずき対処を解説」で、製品の概要は「Claude Codeとは——コードだけじゃない「AI業務エージェント」」で解説しています。

Hooksは、Claude Codeの動作の途中に差し込む自動処理

Hooksは、ユーザーが定義したシェルコマンドなどを、Claude Codeの動作の決まった時点で自動実行する機能です。決まった時点は「イベント」と呼ばれ、ファイルの編集前後やセッションの開始など、節目ごとに用意されたものです。

ターミナル・IDE拡張・デスクトップアプリ・クラウドのセッションのどこで使っても、同じイベントが発火します。

CLAUDE.mdは「コンテキスト」、Hooksは「毎回動く」

CLAUDE.mdの内容は、強制される設定ではなく、コンテキスト(Claudeが参照する情報)として渡されるものです。Claudeは読んで従おうとしますが、厳密な遵守は保証されません。

毎回必ず実行したい処理の置き場所は、フックです。公式ドキュメントも、この分け方を示しています。詳しくは「CLAUDE.mdとは?書き方・置き場所・ベストプラクティスを解説」を参照してください。

Hooksは、判断が要らず毎回同じにしたい処理に向く

判断が要らず、毎回同じ動きにしたい処理が、Hooksに向いています。保存のたびの整形、rm -rf /のような危険コマンドの拒否、入力待ちの通知などがあります。

Claudeに考えて適用させたい作業はスキル、毎回同じにしたい処理はHooksが基本の分け方です。

出典:Claude Code Docs「Memory」(冒頭の説明)/Claude Code Docs「Features overview」(Hook vs Skill)

Hooksはいつ動く?主要イベントと、止められるイベント・止められないイベント

Claude Code Hooksが動く主要イベントを時間順に並べ、終了コード2でブロックできるイベントとできないイベントを色分けして示した図

フックイベントは、Claude Codeが決まった節目で出す合図です。フックは、この合図を受けて動きます。

イベントは追加が続いているため、全体は現行のドキュメントで確認してください(2026年11月時点で33種類)。

イベントは「セッション」「ターン」「ツール呼び出し」の3つの周期で並ぶ

イベントは、発生の周期で3つに分かれます。1つ目は、セッションごとのSessionStartとSessionEndです。

2つ目は、1回のやり取り(ターン)ごとのUserPromptSubmit・Stop・StopFailureです。3つ目は、Claudeがツールを呼び出すたびに発火するPreToolUseとPostToolUseで、作業の途中で何度も繰り返されます。

主要イベントの発火タイミング

下の表は、主要なイベントを選んだものです。Stopが発火するのは、タスクが完了したときではなく、Claudeの応答が1回終わるごとです。ユーザーが割り込んだときは発火しません。

TaskCompleted・PostToolUseFailure・FileChangedなど、ほかにも多数あるため、全体は公式の一覧で確認してください。

イベント 動くタイミング 業務での使いどころ
PreToolUse ツール実行の前 危険なコマンドや機密ファイルの編集を、実行前に止める
PostToolUse ツール呼び出しが成功した直後 編集後の自動フォーマット、実行したコマンドの記録
UserPromptSubmit プロンプトの送信後、Claudeが処理する前 プロンプトの検査、追加情報の付与
Stop Claudeが応答を終えるたび(ユーザーの割り込みでは発火しない) 応答の後に毎回走らせる確認処理
SubagentStop サブエージェントが応答を終えたとき サブエージェントの作業後の処理
SessionStart セッションの開始時と再開時 開発の状況や直近の変更の読み込み
SessionEnd セッションの終了時 後片づけ、セッション情報のログ記録
Notification Claude Codeが通知を送るとき デスクトップ通知
PreCompact コンテキストの圧縮(コンパクション)の前 圧縮の前に走らせたい処理

止められるイベントと、止められないイベントがある

ツール呼び出しのように、まだ実行されていない動作は止められますが、すでに起きたことは止められません。可否はイベントごとに違います。

Stopの「止められる」は、Claudeが止まるのを妨げて、会話を続けさせる意味です。PermissionRequestは終了コード2が効かず、JSONのdecisionで拒否します。

イベント 止められるか 終了コード2で起きること
PreToolUse 止められる ツール呼び出しをブロックする
UserPromptSubmit 止められる プロンプトがClaudeに届かない
Stop 止められる Claudeが止まるのを妨げ、会話を続ける
SubagentStop 止められる サブエージェントが止まるのを妨げる
PreCompact 止められる コンパクションをブロックする
PostToolUse 止められない ツールは実行済み。stderrがClaudeに表示される
Notification 止められない 終了コードとstderrは無視される
SessionStart・SessionEnd 止められない stderrはユーザーにだけ表示される
PermissionRequest 終了コード2は効かない 権限の確認はそのまま進む。decisionオブジェクトで拒否する

出典:Claude Code Docs「Hooks reference」(Hook lifecycle/Exit code 2 behavior per event)

settings.jsonへの書き方:イベント・matcher・command

Hooksの設定がイベント・matcher・ハンドラーの3階層になっていることを、Notificationの最小例に対応づけて示した図

Hooksの設定は、イベント、matcher、ハンドラー(実行する処理)の3階層で書きます。settings.jsonのhooksキーの下にイベント名を置き、その下にmatcherのグループ、さらにその下にハンドラーを並べる構造です。

すでにhooksキーがある設定ファイルでは、置き換えずに同じhooksの中へイベントを足します。

基本の形:イベントの下にmatcherとcommandを入れる

公式ガイドの最小構成は、Claudeが入力を待つたびにmacOSの通知を出す設定です。Notificationがイベント、空のmatcherがすべての通知への一致、typeのcommandがシェルコマンドの実行を表します。

typeは主にcommandを使い、ほかにhttp・mcp_tool・prompt・agentがあります。実験的な機能のagentは、変更される場合があるので注意してください。

設定例(macOSの通知)

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

matcherは「どのツールに反応させるか」を決める

matcherは、フックを動かす対象を絞る条件です。判定のしかたを決めるのは、書いた値の文字の種類です。

matcherの値 判定のしかた
空欄、または* すべてに一致する
英数字・_・-・空白・,・|だけで書いた値 完全一致。|か,で区切ると、区切った名前のどれかに一致する(Edit|WriteならEditかWrite)
それ以外の文字を含む値 正規表現として扱う

大文字小文字は区別されます。UserPromptSubmitやStopなど、matcherが効かず毎回発火するイベントもあります。

イベント別の対象は次の表です。

イベント matcherが見る対象 値の例
PreToolUse・PostToolUse ツール名 Bash、Edit|Write
SessionStart セッションの始まり方 startup、resume、clear、compact、fork
SessionEnd 終了の理由 clear、resume、logout、prompt_input_exit、other
Notification 通知の種類 permission_prompt、idle_promptなど
PreCompact 圧縮のきっかけ manual、auto

フックはツールの情報を標準入力のJSONで受け取る

標準入力(stdin)は、プログラムが外から受け取るデータの入り口です。コマンドフックには、session_id、cwd(作業ディレクトリ)、tool_name、tool_inputなどがJSONで渡されます。

シェルスクリプトでは、編集対象のパスをjq -r '.tool_input.file_path'で取り出します(jqは別途インストールが必要)。下は、PreToolUseの入力例です。

PreToolUseに渡されるJSONの例(公式リファレンスの例から項目を絞った形)

{
  "session_id": "abc123",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  },
  "tool_use_id": "toolu_01ABC123..."
}

出典:Claude Code Docs「Hooks reference」(Configuration/Matcher patterns/Common input fields)/Claude Code Docs「Hooks guide」(Get notified when Claude needs input)

フックの結果を返す:終了コードとJSON出力

フックの終了コード0(正常終了)・2(ブロック)・それ以外(ブロックしないエラー)で起きることを3つに分けて示した図

終了コードは、スクリプトが終わるときに返す数字で、結果の種類をClaude Codeに伝えます。フックが結果を返す方法は、終了コードと、標準出力へのJSON出力の2つです。

どのイベントで止められるかは前章の表のとおりで、ここでは返し方そのものを扱います。

終了コードは0・2・それ以外の3区分で意味が決まる

0は成功で、処理はそのまま進みます。2はブロックを表す終了コードです。

ブロックできるイベントでは、Claude Codeが動作を止めます。それ以外の終了コードは、動作を原則として続行させる「ブロックしないエラー」です。

慣習では1が失敗を表しますが、Claude Codeではexit 1でもブロックになりません。ポリシーを強制したいフックには、exit 2を使ってください。

ブロックの理由は標準エラー出力でClaudeに返る

終了コード2のとき、ブロックに添えるメッセージは、フックの標準エラー出力(stderr)です。Claudeはその理由を受け取り、別の方法を考えられます。

終了コード0で出力したstderrは、Claudeには見えません。次の2行が公式の例です。

echo "Blocked: rm commands are not allowed" >&2
exit 2

JSON出力を使うと、許可・拒否・確認を細かく選べる

終了コード0でJSONを標準出力に出すと、許可・拒否・確認を細かく選べます。JSONの形はイベントによって違い、下の表のとおりです。

終了コードとJSONは、どちらか一方で使い、標準出力にはJSON以外を混ぜないでください。階層を間違えると、エラーも出ずにフィールドが無視されます。

イベント JSONでの返し方
PreToolUse hookSpecificOutputの中のpermissionDecision(allow・deny・ask・defer)とpermissionDecisionReason
UserPromptSubmit・PostToolUse・Stop・PreCompactなど トップレベルの"decision": "block"とreason
Notification・SessionEndなど 判断の制御はなく、ログや後片づけなどの副作用に使う

PreToolUseで拒否するJSONの例(公式ガイドの形)

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

出典:Claude Code Docs「Hooks reference」(Exit code output/Exit code 2 behavior per event/JSON output)

Claude Codeの設定ファイルはどこに置く?Hooksのスコープと優先順位

Hooksを書く設定ファイルの置き場所ごとの効く範囲とチームと共有できるかを、優先順位の順に示した表

スコープは、その設定が効く範囲のことです。

Claude Code全体の設定は、「Claude Codeの使い方——インストールから基本操作・つまずき対処を解説」を参照してください。なお、インストールしただけでは設定ファイルは作られません。

設定ファイルは4種類あり、共有できるかが違う

Claude Codeが読む設定ファイルは、次の4種類です。

設定ファイル 効く範囲 チームと共有できるか
ユーザー:~/.claude/settings.json 自分のすべてのプロジェクト できない(自分のマシンだけ)
プロジェクト共有:.claude/settings.json そのプロジェクト できる(リポジトリにコミットして共有)
プロジェクトローカル:.claude/settings.local.json 自分の、そのプロジェクトのみ できない(Claude Codeが作る場合はgit管理から外される)
管理者ポリシー(managed settings) 組織全体 できる(管理者が管理)

Windowsでは、~/.claudeが%USERPROFILE%\.claudeにあたります。クラウドセッションは手元の~/.claude/settings.jsonを読みません。このほか、プラグインやスキル、サブエージェントの定義も、フックを書ける場所です。

設定ファイルのフックは、サブエージェントの中でも同じように動きます。

同じ設定が複数あるときの優先順位

同じキーが複数の場所にあるときは、最も上位のレベルの値が採用されます。高い順に、管理者ポリシー、コマンドライン、プロジェクトローカル、プロジェクト共有、ユーザーです。

フックは上書きされず、結合される

フックは上書きではなく結合され、各レベルのフックがすべて動きます。同じハンドラーを複数の設定ファイルに書いても、動くのは1回です。プラグインやスキルにある同じハンドラーは、別に動きます。管理者ポリシーのフックは、ユーザー側のdisableAllHooksでは無効にできません。

読み込まれた設定ファイルは/statusで確認する

現在のセッションで読み込まれた設定ファイルを確かめる場所は、/statusのStatusタブにあるSetting sourcesの行です。ただし、この行で分かるのは読み込まれたファイルまでです。

どのファイルがどのキーを出したかは分かりません。登録されたフックの確認には、別のコマンド/hooksを使います。

出典:Claude Code Docs「Settings」(Settings files and who they affect/Settings precedence)/Claude Code Docs「Hooks reference」(Hook locations/Disable or remove hooks)

すぐ使える設定例4つ:危険コマンド・機密ファイル・自動整形・通知

すぐ使えるHooksの設定例4つを、イベント・matcher・結果の3列で並べた一覧図

ここから紹介する4つの設定例は、公式のHooks guideとHooks referenceに載っている例です。そのまま貼って終わりにせず、自分の環境で試してから使ってください。

①〜③の例はjqを使うため、jqのインストールが前提です。

① rmで始まるコマンドを実行前に止める

rm -rfのような削除コマンドを止める例で、PreToolUseのBashに登録するフックです。スクリプトは、コマンドがrmで始まると、理由をstderrに書いてexit 2で止めます。

検出できるのは先頭がrmのコマンドで、sudo rmやecho x && rmは通ります。

設定(settings.json)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

設定のifは、ツール名と引数を合わせて対象をさらに絞る条件です。判定は完全ではない(best-effort)ため、確実に拒否したい操作は、permissionsのルールにも書いてください。

スクリプト(.claude/hooks/block-rm.sh。公式リファレンス「Exit code 2」の例)

#!/bin/bash
# Reads JSON input from stdin, checks the command
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Blocking error: tool call is prevented
fi

exit 0  # No decision: the normal permission flow applies

スクリプトには、chmod +x .claude/hooks/block-rm.shで実行権限を付けておきます。

② .envなどの機密ファイルの編集を止める

EditとWriteで、編集先のパスが保護パターン(.env・package-lock.json・.git/)に当てはまればexit 2で止める例です。スクリプトには実行権限を付けておきます。

EditとWriteの呼び出しは止まりますが、Claudeがシェルコマンドで書き換える場合は止まりません。permissions.denyにEdit(/.env)のようなルールを足して、補ってください。

設定(settings.json)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

スクリプト(.claude/hooks/protect-files.sh)と実行権限の付与

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0
chmod +x .claude/hooks/protect-files.sh

③ ファイル編集の後に自動でフォーマットする

PostToolUseのEdit|Writeで、編集されたファイルのパスをjqで取り出し、フォーマッタのPrettierに渡して整形します。Bashでファイルが書き換えられた場合、この設定は動きません。その場合は、ディスク上のファイルの変更をきっかけに動くイベントFileChangedを使ってください。

設定(.claude/settings.jsonに追加)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\""
          }
        ]
      }
    ]
  }
}

動作を確かめるには、JavaScriptのファイルにシングルクォートの文字列を足させます。Prettierの既定設定なら、ダブルクォートに変われば成功です。

④ Claudeが入力を待っているときに通知を出す

Notificationは、Claudeが入力や許可を待つときに発火し、先に示した最小構成のcommandを入れ替えるだけで使える設定です。Windowsの例は通知ではなくダイアログで、ターミナルの後ろに隠れることがあります。

下の表はシェルで実行するコマンドそのものです。settings.jsonのcommandに入れるときは、先の最小構成の例のように、文字列の中の"を\"と書きます。

OS commandに書く内容(公式の例) 注意点
macOS osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"' Script Editorに通知の権限がないと、何も表示されずに失敗する
Linux notify-send 'Claude Code' 'Claude Code needs your attention' デスクトップ通知デーモンが必要で、ヘッドレスのサーバー・SSH接続・多くのコンテナでは動かない
Windows(PowerShell) powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')" 通知ではなくダイアログで、ターミナルの後ろに隠れることがある。WSLではpowershell.exeをPATHに通しておく必要がある

出典:Claude Code Docs「Hooks guide」(Automate actions with hooks)/Claude Code Docs「Hooks reference」(How a hook resolves/Exit code 2)

続けて使える設定例:セッション開始時の情報渡しとコマンドログ

コンパクション後にSessionStart(matcher: compact)で注意書きをClaudeの文脈に渡し直す流れを示した図

ここで取り上げる例は、セッション開始時に情報を渡す設定と、コマンドのログの2つです。スクリプトの要らない固定の内容は、CLAUDE.mdに書けば足ります。

スクリプトで中身を作りたい場合や、コンパクション後に渡し直したい場合は、フックが役立ちます。

コンパクションの後に、決めておいた注意書きを渡し直す

コンパクションは、会話の履歴を要約に置き換えて、コンテキストの空きを作る処理です。実行のきっかけは、上限に近づいたときの自動と、/compactによる手動です。

要約では、会話の早い段階にあった詳細な指示が失われることがあります。失いたくない注意書きは、matcherをcompactにしたSessionStartで標準出力に書けば渡し直せます。処理は短時間で終わるものにしてください。

設定例(SessionStartのcompact)

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

実行したBashコマンドをログに残す

PostToolUseは成功したツール呼び出しの後に発火するため、Bashに絞ると、成功したコマンドが1つずつファイルに追記されます。失敗したコマンドは別のイベントPostToolUseFailureの対象で、このフックには記録されません。

PowerShellツールのコマンドも残すなら、BashとPowerShellの両方に一致するBash|PowerShellがmatcherです。

設定例(PostToolUseのBash)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

出典:Claude Code Docs「Hooks guide」(Re-inject context after compaction/Log successful Bash commands)/Claude Code Docs「Hooks reference」(How a hook resolves)

設定後の動作確認とHooksが動かないときの見直し点

Hooksの動作確認を登録確認・単体実行・実操作・見直しの4ステップで示した図

成功したフックは、会話に何も表示しません。動いたかどうかを確かめる手がかりは、目に見える効果です。

確認は、登録されているか、スクリプトが単体で動くか、実際の操作で効くかの順に進めると、切り分けやすくなります。

① 登録の確認:/hooksで一覧を開く

/hooksは、設定済みのフックを閲覧する読み取り専用の画面です。追加したフックは該当するイベントの下に表示され、ユーザー設定・プロジェクト設定・プラグインなど、どこから来たフックかも分かります。

一覧に出ないフックは、Claude Codeが読み込んでいない状態です。スキルのフロントマターに書いたフックは、そのスキルを起動した後に登録されます。

② スクリプトを単体で動かす:標準入力にJSONを流す

サンプルのJSONをパイプで流し、echo $?で終了コードを見る手順です。流したJSONはPreToolUseの最小形で、実際の入力はもっと多くの項目を持ちます。

Stopのように別の項目を使うフックは、その項目を足したJSONを自分で作ってください。

実行例と、動かないときの対処

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?  # Check the exit code
症状 対処
スクリプトがまったく動かない chmod +xで実行権限を付ける
「command not found」と出る 絶対パスか${CLAUDE_PROJECT_DIR}でスクリプトを指定する
「jq: command not found」と出る jqをインストールするか、PythonやNode.jsでJSONを解析する

③ 実際に操作して効果を確認する

フックの結果を見る場所は、Ctrl+Oで開くトランスクリプト表示です。成功したフックは何も表示せず、ほとんどのイベントではブロックされるとメッセージが、ブロックしないエラーでは「hook error」の通知が出ます。自動整形はファイルを開いて変化を確かめ、通知はShift+Tabで権限確認を求めるモード(manual mode)に切り替えて、許可が必要な操作を頼んで試します。

Notificationのように、失敗しても通知が出ないイベントには注意してください。

④ 動かないときは、matcher・JSON・出力・再読み込みの順に見る

動かないときの見直し点は、次の表のとおりです。

症状 見直す点
/hooksに出ない 設定ファイルに構文エラーがないか(起動時にSettings Errorとして報告される)
出ているのに動かない matcherがツール名と完全に一致しているか(大文字小文字を区別する)
JSON出力が効かない 標準出力にJSON以外が混ざっていないか(シェルのプロファイルの出力など)。デバッグログでHook output does not start with {を探す
原因が分からない claude --debug-file <path>でログを書き出して読む。起動後なら/debugでも有効にできる

claude --debugはログを端末に出さず、~/.claude/debug/<session-id>.txtに書き込みます。ログの場所を決めたいときは、claude --debug-file <path>を使ってください。

出典:Claude Code Docs「Hooks guide」(Limitations and troubleshooting/Check what a hook did)/Claude Code Docs「Hooks reference」(The /hooks menu)

CLAUDE.md・skills・permissionsとの使い分けとチーム展開

CLAUDE.md・skills・permissions・Hooksの何を書くか・守られ方・向いているものを比べた4つの仕組みの比較表

CLAUDE.mdとHooksの違いは前述のとおりです。ここでは、何をどこに書くかの判断、フックとpermissionsの重ね使い、チームへの配り方を扱います。

スキルの作り方は、「Claude Code Skillsとは?仕組みと作り方を解説」で解説しています。

何をどこに書くかの判断基準

下の表は、公式ドキュメントの使い分けをまとめたものです。

仕組み 何を書くか 守られ方 向いているもの
CLAUDE.md 考え方・前提・方針 コンテキストとして読まれる。遵守は保証されない プロジェクトの前提や方針を伝える
skills Claudeに考えて適用してほしい手順・知識 Claudeが解釈して適用するため、結果は変わりうる 再利用する作業手順
permissions 許可・拒否のルール 設定による技術的な強制 ツールやファイルの許可・拒否
Hooks 判断が要らず毎回同じにしたい処理 イベントごとに、Claudeの判断なしで実行される 整形・通知・ブロック・ログ記録

「.envを編集しない」という規則は、CLAUDE.mdやスキルに書いても依頼にとどまり、必ず守られる保証はありません。守らせたい規則は、フックかpermissionsに置いてください。

Hooksとpermissionsは役割が違うので併用する

PreToolUseフックのdenyは、bypassPermissionsや--dangerously-skip-permissionsを含むすべての権限モードで効き、ユーザーが権限モードを変えても回避できないポリシーを強制できます。一方、フックがallowや終了コード0を返したときの扱いは、下の表のとおりです。

フックとpermissionsのルールは働き方が違うため、併用してください。

フックの返答 結果
allow 設定側のdenyルールは破れない
終了コード0 承認にならず、通常の権限確認に進む

チーム全員に同じHooksを配るには

チームには、.claude/settings.jsonをリポジトリにコミットして配ります。組織全体には管理者ポリシーで配り、管理者はallowManagedHooksOnlyで、ユーザー・プロジェクト・ローカル・プラグインのフックを止められます。

出典:Claude Code Docs「Features overview」(Hook vs Skill)/Claude Code Docs「Hooks guide」(Hooks and permission modes/Configure hook location)

Hooksのセキュリティ上の注意:守れる範囲と守れない範囲

フックで止められることと、フックでは止められないことを左右に対比し、permissionsで補う前提を示した図

コマンドフックは、自分のユーザー権限のまま実行されるシェルコマンドで、アカウントがアクセスできるファイルを変更・削除・参照できます。導入前に中身を読み、動作を確認することが前提です。

Hooksだけで安全が保証されるわけではなく、止められる範囲には限りがあります。

フックは自分の権限でそのまま動く

フックのコマンドは、ユーザー自身の全権限で実行されます。自分で書いたフックも、共有されたリポジトリの.claude/settings.jsonに入っていたフックも、実行される権限は同じです。

他人が書いた設定は、中身を読まずに取り込まないでください。

信頼確認と、非対話モードの注意

対話型セッションでは、フォルダの信頼ダイアログを承諾するまで、自分の設定ファイルを含むすべてのフックが動きません。-pやSDKのセッションでは信頼ダイアログが出ず、リポジトリの.claude/settings.jsonにあるフックが確認なしで動きます。自分が書いていないリポジトリでclaude -pを使う前に、.claude/の設定ファイルを確認してください。

フックが動かない・止まらないケース

フックが動かない、または止まらない場面は、次の4つです。

場面 起きること 補う方法
プロンプトで@参照したファイル(既定) ツール呼び出しなしで読み込まれるため、Read対象を含むPreToolUseのフックが動かない Readのdenyルールをpermissionsに書く
PreToolUseのタイムアウト 止まらず、通常の権限確認に進む "onFailure": "block"を指定する(v2.1.295以降)
終了コード1 ブロックにならない 強制したいときはexit 2を使う
Bash経由のファイル変更 Edit・Writeを対象にしたフックは動かない permissions.denyのルールを併用する

どの場面も、フックだけに頼らず、permissionsのルールで補う前提で組んでください。タイムアウトの既定値は、command・http・mcp_toolで600秒で、UserPromptSubmitなどでは30秒に短縮されます(2026年11月時点)。

書くときの基本:パスは絶対パス、変数は引用符で囲む

書くときの基本は、次の5点です。

注意点 書き方
入力を信用しない 標準入力のJSONの値は、検証してから使う
変数は引用符で囲む "$VAR"と書き、$VARは避ける
..を弾く ファイルパスに..が含まれていれば止める(上位のフォルダへ抜ける指定を防ぐ)
絶対パスで指定する スクリプトは絶対パスで指定する。${CLAUDE_PROJECT_DIR}を使い、シェル形式では二重引用符で囲む
機密ファイルを避ける .env・.git/・鍵などは対象にしない

出典:Claude Code Docs「Hooks reference」(Security considerations)

Claude Code Hooksについてよくある質問

Q1. Hooksを一時的に無効にするには?

設定ファイルに"disableAllHooks": trueを書くと、削除せずにすべてのフックを一時的に無効にできます。個別のフックだけを無効にする方法はなく、無効化は全フックが対象です。1回の実行だけ無効にしたいときは、claude --settings '{"disableAllHooks": true}'で渡してください。

Q2. WindowsでHooksを使うとき、Git Bashは必要ですか?

Git Bashは必須ではありませんが、入っているかどうかでフックの既定のシェルが変わります。Git Bashがないと、シェル形式のフックはPowerShellで動き、PreToolUseとPermissionRequestでは0と2以外の終了コードが失敗として扱われ、ツール呼び出しがブロックされます。PowerShellで書くフックには"shell": "powershell"を指定し、$CLAUDE_PROJECT_DIRをそのまま書かないでください(${CLAUDE_PROJECT_DIR}か$env:CLAUDE_PROJECT_DIRと書きます)。

Q3. 同じイベントに複数のフックを登録すると、どの順で動きますか?

一致したフックは、順番に動くのではなく並列で動きます。1つのフックがdenyを返しても、ほかのフックの実行は止まらない仕様です。PreToolUseの判断が食い違うときは、最も厳しい答えが採用されます(厳しい順にdeny、defer、ask、allow)。

Q4. Stopフックで「テストが通るまで続ける」とき、無限ループになりませんか?

ツール呼び出しを挟まずに8回連続でブロックすると、Claude CodeがStopフックの指示を上書きします。入力JSONのstop_hook_activeがtrueなら早めに終了させるのが、公式の例の書き方です。既定ではこの上限があるため、無限には続きません。上限を引き上げる手段は、環境変数CLAUDE_CODE_STOP_HOOK_BLOCK_CAPです。

Q5. settings.jsonにコメントを書いてもかまいませんか?

コメントは書けません。settings.jsonは厳密なJSONのため、//のコメントや末尾のカンマは構文エラーです。エラーは、次回の起動時にSettings Errorとして報告されます。

不明なイベント名のような個別の項目の誤りは、警告にとどまり、無視されるのはその値だけです。

出典:Claude Code Docs「Hooks reference」(Disable or remove hooks/Stop)/Claude Code Docs「Settings」

まとめ:毎回必ず実行したい処理は、Claude CodeのHooksに書く

CLAUDE.mdは強制ではなくコンテキストのため、毎回必ず実行したい処理はHooksに書きます。ただし、どのイベントでも止められるわけではない点に注意してください。設定はsettings.jsonに「イベント→matcher→フック」の3階層で書き、ブロックには終了コード2を使います。

確認は/hooks、単体実行、実際の操作の順です。Bash経由の変更、既定での@参照、タイムアウトでは止まらないため、permissionsのルールも併用します。

まず通知や自動整形など影響の小さい例を試し、危険コマンドのブロックは自分の環境で確認してから入れましょう。

Claude CodeのHooks設計からチーム展開まで伴走しますパンハウスは、Claude Codeを日々の業務で使い倒しているAI開発会社です。どこまでClaude Codeに任せ、どこを人が確認するかの線引きから、Hooksやpermissionsの設計、ビジネス職・開発組織向けの研修まで、実務に即して支援します。まずはお気軽にご相談ください。詳しくはこちら