Claude Codeのフックとは?実例と使いどころ(2026年)

Claude Codeは開発ペースが速く、イベントの一覧も増え続けています。

Claude Codeのフックとは?

Claude Codeのフックとは、あらかじめ定義しておくコマンドで、セッションのライフサイクルの決まったポイントでClaude Codeが自動的に実行するものです。 Claudeに何かを「思い出させて」実行してくれることを期待するのではなく、フックはその動作を確定的(deterministic)なものに変えます。適切なタイミングが来れば、モデルの「気分」に関係なく必ず実行されます。

もしGitフック(コミットのたびにリンターを走らせるpre-commitなど)を使ったことがあれば、この考え方はなじみ深いはずです。唯一の違いは、これらのフックがGitではなくAIコーディングエージェントのライフサイクルに紐づく点だけです。Claudeがツールを実行しようとするとき、ファイルの編集を終えたとき、あるいは応答のターンを終えたとき、Claude Codeはそのイベントに登録されたフックがあるかを確認し、あれば実行します。

フックの最大の強みは、確定的であり、ブロックできることです。CLAUDE.mdに「ファイル編集後はPrettierを実行すること」と書いても、それは提案にすぎず、モデルは忘れることがあります。一方でPostToolUseフックは、例外なく毎回必ずPrettierを実行します。PreToolUseを使えば、フックは動作が起こる前にそれを拒否することさえできます。たとえば危険なrm -rfをブロックする、といった具合です。

このためフックはClaude Codeの自動化の中心的なツールになります。コードの整形、テストの実行、活動のログ記録、通知の送信、あるいは安全のためのガードレールの構築などです。この記事では、settings.jsonを使ったフックの仕組み、コピペで使える3つの実例、使うべき(あるいは使うべきでない)場面、そして多くのガイドが省略しがちな安全性のセクションを解説します。

フックの仕組み(settings.json)

フックはsettings.jsonファイルのhooksキーの下で宣言します。構造は3階層にネストしています。イベント名 -> マッチャーのリスト -> 実行するフックのリストです。具体的にはhooks > EventName > [{ matcher, hooks: [{ type, command }] }]となります。実際に動作する最小限のsettings.jsonは次のとおりです。

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

内側から読み解いてください。PostToolUseイベントが発火すると、Claude Codeはmatcher(Edit|Write)を、直前に実行されたツールの名前と照合します。一致すれば、hooks配列内の各commandを実行します。

3つの設定スコープ — これが重要なのは、フックがどこに適用されるか、そしてGitにコミットされるかどうかを決めるからです。

プラグインも、自身のhooks/hooks.jsonファイルを通じて独自のフックを提供できます。

typeフィールドは5種類をサポートします。command(シェルコマンドを実行 — 圧倒的に最も一般的)、http(URLを呼び出す)、mcp_tool(MCPサーバー上のツールを呼び出す — MCPとは何か、その使い方も参照)、prompt、agentです。この記事全体ではcommandに焦点を当てます。コピペですぐ使え、必要なことの90%をカバーするからです。(settings.jsonのフック構文を正しく書くことが前提です。JSONが無効だと、フックは何も言わずに実行されません。)

主なイベントタイプ(ライフサイクル)

すべてを暗記する必要はありません。始めるにあたっては、以下のいくつかだけでほとんどの状況をカバーできます。

2026年の最新情報(情報の追加): 古いガイドの多くは、いまだに従来の4つのイベントしか挙げていません。実際には、Claude Codeには現在30を超えるライフサイクルイベントがあり、PostToolUseFailure、SubagentStart/SubagentStop、PreCompact/PostCompact、SessionEndなどが追加されています(Anthropicの公式ドキュメント(code.claude.com/docs/en/hooks、2026-08-09にアクセス)より)。とはいえ心配は無用です。初心者に必要なのは上記の3〜4個の中心的なイベントだけで、残りは高度なシナリオ向けです。

マッチャーは、フックがどのツールに適用されるかを決めます。よく使う形は4つです。単一のツールに完全一致("Bash")、パイプで複数のツールに一致("Edit|Write")、正規表現(すべてのMCPツールを捕捉する"mcp__.*")、そして空または"*"ですべてに一致、です。以下の例でPreToolUseとPostToolUseを比べてみましょう。

例1 — PreToolUse:危険なコマンドをブロックする

これは最も印象的なユースケースであり、最も実用的な安全ガードレールでもあります。考え方はこうです。ClaudeがBashコマンドを実行する前に、フックがそのコマンドを検査し、rm -rfのような危険なパターンを見つけたら、フックがそれを拒否し、コマンドを一切実行させません。

PreToolUseにはブロックする方法が2つあります。「きれいな」方法は、permissionDecisionを3つの値のいずれかに設定したJSONを出力することです。"allow"(実行し、確認ステップを省略)、"deny"(完全にブロック)、"ask"(確認を強制)です。手っ取り早い方法は終了コードを使うことです。スクリプトがexit 2で終了するとブロックされ、その際に標準エラー出力(stderr)へ書いた内容がClaudeに返され、なぜブロックされたかが伝わります。設定は次のとおりです。

{
 "hooks": {
 "PreToolUse": [
 {
 "matcher": "Bash",
 "hooks": [
 {
 "type": "command",
 "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-danger.sh"
 }
 ]
 }
 ]
 }
}

そしてスクリプト.claude/hooks/block-danger.shはこちらです。

#!/usr/bin/env bash
# Read the JSON payload from stdin, pull out the command Claude wants to run
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command // empty')

if echo "$command" | grep -Eq 'rm[[:space:]]+-rf|git[[:space:]]+push[[:space:]]+--force'; then
 echo "Blocked: command matches a dangerous pattern ($command)" >&2
 exit 2 # exit 2 = block, stderr is sent back to Claude
fi
exit 0 # exit 0 = allow it to continue

結果はこうなります。Claudeがrm -rf build/を実行しようとすると、フックがそれを捕捉し、exit 2を返し、コマンドは実行されず、Claudeには理由を説明するメッセージが届きます。これはまさにCLAUDE.mdのルールでは保証できないことです。ルールはあくまで柔らかな提案にすぎませんが、フックは固いガードレールです。より高いレベルで権限を厳しくしたい場合は、Claude Codeの権限と安全な設定もあわせてお読みください。

例2 — PostToolUse:コードを自動整形する

私がどのプロジェクトでも最初に有効にするフックの1つがこれです。Claudeがファイルを編集するたびに、自動的にフォーマッターを実行します。スペースの抜けや改行の誤りによる乱雑な差分とはおさらばです。これはPostToolUse(ツールが成功した後に実行される)なので、何もブロックせず、後片付けをするだけです。

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

マッチャーEdit|Writeは、ファイルを編集する両方のツールを捕捉します。Pythonプロジェクトなら、コマンドをblack "$CLAUDE_FILE_PATHS"やruff formatに置き換えてください。Claude Codeがフックに渡す便利な環境変数をいくつか挙げます。

• ${CLAUDE_PROJECT_DIR} — プロジェクトルートへの絶対パス。コマンドが正しいディレクトリで実行されるようにします。
• $CLAUDE_FILE_PATHS — 直前に触れたファイルのパス。リポジトリ全体ではなく、正しいファイルだけを整形できます。
• (例1のように)stdinから完全なJSONペイロードを読み取り、tool_inputの詳細を取得することも常に可能です。

ヒント:コマンドは軽く速く保ちましょう。PostToolUseフックはすべてのファイル編集の後に実行されるため、遅いフォーマッターはセッション全体を重くします。

例3 — Stop:Claudeが完了したら通知する

Claudeに長いタスクを任せて別の作業に移ると、確認しに戻るのを忘れがちです。StopフックはClaudeが応答のターンを終えたときに実行されるので、通知を飛ばすのにぴったりです。ntfyを使ってスマートフォンにプッシュ通知を送る例を示します。

{
 "hooks": {
 "Stop": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "curl -s -d \"Claude Code finished the task\" ntfy.sh/your-topic-name"
 }
 ]
 }
 ]
 }
}

Stopはどのツールにも紐づかないため、matcherは不要です。macOSではosascript -e 'display notification "Done!" with title "Claude Code"'に、Linuxではnotify-sendに置き換えられます。小さな機能ですが、複数の作業を同時に進めているときには驚くほど役立ちます。

フックを使うべき場面・使うべきでない場面

フックは強力ですが、何にでも使えるツールではありません。線引きはシンプルです。フックは、常に必ず実行される確定的なもののためにあります — 整形、テスト、コマンドのブロック、ログ記録などです。必要なのが振る舞いの指針や能力(ケイパビリティ)であれば、より適したツールが別にあります。

間違えやすい例を挙げます。「Claudeに必ずテストを書くよう念押しする」ことは、フックではなくCLAUDE.mdのルールにすべきです — それは柔らかな指針だからです。一方、「src/内のファイルを編集した後にテストスイート全体を実行する」ことは、確定的なので本当にフック向きです。これら4つの概念がまだあいまいに感じるなら、スキル・サブエージェント・フック・MCPの違いについて専用の記事を用意しています。そこで全体像がひとつにまとまります。

⚠️ フックを使うときの安全上の注意

ここは多くのガイドが省略するセクションですが、最も重要です。公式ドキュメント(code.claude.com/docs/en/hooks、2026-08-09にアクセス)によれば、フックはあなたのユーザーアカウントの全権限で、サンドボックスなしに実行されます。つまり、バグのあるフックや、うっかりコピーしてきた悪意のあるフックが、ファイルを削除したり、秘密情報を漏らしたり、任意のコードをあなたのマシンで実行したりすることが、完全に自動で、確認もなく起こり得るということです。

私が常に守っているいくつかの原則です。

• 有効にする前にすべてのフックをよく読むこと — 特にプラグインやキット、他人のリポジトリから来たフックはそうです。root権限で動くコードだと考えて扱ってください。
• 秘密情報(トークン、APIキー)を絶対にハードコードしないこと。コマンドに直接書き込まず、環境変数から読み込みましょう。
• 機密性の高いフックは.claude/settings.local.json(Git無視)に置くこと。共有リポジトリに誤ってコミットしないためです。
• 緊急停止スイッチを知っておくこと。デバッグ中や何かが怪しいときは、disableAllHooksですべてのフックをオフにできます。企業ではallowManagedHooksOnlyやallowedHttpHookUrlsでさらに厳しく制限できます。
• 自動でallowするPreToolUseには注意すること。確認ステップを省略できて便利ですが、保護の層を1つ取り除くことになります。

結論として、フックは切れ味のよいナイフです。とても便利ですが、正しく握る必要があります。よくある問題とその対処については、Claude Codeのよくあるエラーのトラブルシューティングで詳しく紹介しています。

もっと速く:キットにある既製のフックとスキル

プロジェクトごとに自前のフック、スクリプト、スキルを書くのは相応の手間がかかります。特に、一貫した安全ガードレールとワークフローのセットをそろえたい場合はなおさらです。Claude Code向けのキットの中には、Claude Code向けのAgentKitキットのように、スキル・サブエージェント・ワークフローをまとめて提供し、すべてを一から作らずに済むものもあります。直接見てみたい場合は、AgentKitの価格を確認(リンク経由で20%オフ)できます。念のためお伝えすると、この記事の基本的なフックは自分で作れるもので、何かを買う必要はありません。キットは、既製のセット一式がほしいときにだけ検討する価値があります。

デバッグ:フックが実行されないのはなぜ?

「何も起きない」フックは最もよくある問題です。次のチェックリストをたどれば、ほぼ必ず原因が見つかります。

• JSONは有効ですか? settings.jsonに末尾カンマが1つあるだけで、ファイル全体が読み込めなくなります。JSONバリデーターに通してください。
• マッチャーは正しいツール名を使っていますか? 名前は大文字・小文字を区別します。正しくはBash、Edit、Writeであって、bashやeditではありません。
• スクリプトは正しい終了コードを返していますか? 通すならexit 0、(PreToolUseで)ブロックするならexit 2です。それ以外の終了コードは無視されることがあります。
• 標準出力(stdout)は「きれい」ですか? フックが制御用JSONを返す場合、stdoutにはそのJSONだけが含まれていなければなりません。余計なテキストがあるとパースが壊れます。
• スクリプトは実行可能ですか? macOS/Linuxではchmod +xを忘れずに。
• disableAllHooksがオンのままではありませんか? デバッグのために先ほどフックをオフにしたのなら、元に戻すのを忘れないでください。

よくある質問(FAQ)

フックはスラッシュコマンドやスキルとどう違いますか?

フックはライフサイクルの各ポイントで自動的に実行されます(自分で呼び出すものではありません)。スラッシュコマンドは、必要なときに自分で起動するアクションです。スキルはパッケージ化された能力(指示+スクリプト)で、文脈が合うときにClaudeが自ら読み込みます。ひとことで言えば、フック=自動かつ確定的、スラッシュコマンド=手動、スキル=再利用可能な能力、です。

フックはWindowsで動きますか?

はい。type: commandはシェルコマンドを実行するので、PowerShellスクリプト(powershell -File .claude\hooks\block-danger.ps1)を指定したり、Git BashやWSLを使ってbashスクリプトを実行したりできます。コマンドがあなたのマシンのシェルで有効でありさえすればよいのです。

フックはClaude Codeを遅くしますか?

コマンドが重ければ、遅くなり得ます。フックはイベントの瞬間に同期的に実行されるため、遅いフォーマッターやテストスイートは毎ターンを引き延ばします。フックは軽く保ち、リポジトリ全体ではなく変更のあったファイルだけ($CLAUDE_FILE_PATHS)を整形し、重いテストはPostToolUseから外すことを検討してください。

グローバルフックとプロジェクトフックの違いは何ですか?

グローバルフック(~/.claude/settings.json)はマシン上のすべてのプロジェクトに適用され、コミットされません。プロジェクトフック(.claude/settings.json)はそのプロジェクトだけに適用され、コミットしてチーム全体で共有できます。.local.json版はプロジェクトごとですがGit無視で、自分専用のプライベートな設定向けです。

フックで危険なコマンドをブロックできますか?

はい、それこそがPreToolUseの強みです。フックはコマンドを実行前に検査し、permissionDecision: "deny"または終了コード2で拒否します。たとえばrm -rfやgit push --forceをブロックします(上記の例1を参照)。

フックは安全ですか?

フックはあなたのユーザー権限すべてで、サンドボックスなしに実行されるため、バグのあるフックや悪意のあるフックは実害(ファイルの削除、秘密情報の漏洩)を及ぼし得ます。フックを慎重に書いてレビューすれば、仕組みそのものは安全です。リスクは、中身を読まずに未知のフックを有効にすることから生じます。フックは常に、最高権限で動くコードとして扱ってください。

まとめと次のステップ

3つの中心的なイベントを押さえれば、必要なことのほとんどにフックを使えます。危険なコマンドをブロックするPreToolUse、自動整形・テストのPostToolUse、通知を受け取るStopです。黄金律を忘れずに。フックは全権限・サンドボックスなしで実行されるので、有効にする前によく確認しましょう。さらに進むには、Claude Codeのスキルとは何かとClaude Codeのスラッシュコマンドを読むか、一歩引いて全体像としてスキル・サブエージェント・フック・MCPの違いとそれぞれの使いどころを確認してください。