Claude Code Hooks入門｜通知と活用3選

Claude Code Hooksは、CLAUDE.mdのように「読ませて守ってもらう」指示ではなく、特定のタイミングで処理を必ず走らせる仕組みです。
筆者は最初にNotification Hookを入れて、長い実装を任せている間に別作業へ集中できるようになってから、この機能の価値をはっきり実感しました。
この記事では、/hooks から通知を1本作るところまでを最短で押さえつつ、.claude/settings.json の構造、matcher と JSON 入出力の読み方まで整理します。
あわせて、PreToolUsePostToolUseNotificationSessionStartの役割差、終了コードや無限ループでつまずく地点も解きほぐします。
さらに、信頼できないリポジトリの .claude/ を先に確認すべき理由も、『Hooks リファレンス』（参照日: 2026-03-18）と『Caught in the Hook』（参照日: 2026-03-18）に沿って解きほぐします。
PostToolUseでフォーマッタを自動実行すると毎回言わなくても整う感覚が生まれ、PreToolUseで危険コマンドを止めてからは承認ボタンを押すときの不安も目に見えて小さくなりました。
Hooks は「便利な小技」ではなく、Claude Code を実運用の道具に変える土台です。

Claude Code Hooks とは何か

Claude Code Hooks は、Claude Codeのライフサイクルの特定ポイントで、ユーザー定義の処理を決定論的に自動実行する仕組みです。
ここでいう決定論的とは、「今回はたまたま走った」「モデルが気を利かせて実行した」という曖昧なものではなく、対象イベントが発生したら設定した処理が必ず起動する、という意味です。
私自身、ルールを文章で読ませるだけの運用ではどうしても抜け漏れが出ましたが、Hooks に置き換えてからは「決定論的に走る」ことが、そのままルールの取りこぼしを防ぐ感覚につながりました。

最短で触るなら、CLI で /hooks と入力して対話メニューを開くのが入り口です。
ここからイベントを選び、実行コマンドを登録すると、.claude/settings.json あるいは個人用の .claude/settings.local.json に設定が保存されます。
初手として相性がいいのはNotification Hookです。
たとえば通知コマンドを登録しておくと、Claude Codeが入力待ちになったタイミングや注意喚起が必要な場面でデスクトップ通知を飛ばせます。
長い生成や修正を任せている間、ずっとターミナルを見張る必要がなくなり、別の作業に頭を切り替えやすくなります。
設定後は、フック一覧に対象イベントとコマンドが並び、どのタイミングで何が走るかを CLI 上で追える状態になります。

たとえば通知用の設定を 1 本追加すると、「Notification に対してこのコマンドを実行する」という形で一覧に現れます。
実際の処理本体はシェルコマンドやスクリプトで書けるので、最初は OS 標準の通知コマンドを呼ぶだけでも十分です。

CLAUDE.md と Hooks の違い

CLAUDE.mdと Hooks は、どちらもClaude Codeの振る舞いを整える手段ですが、役割ははっきり分かれます。
CLAUDE.mdは毎セッション参照される指示ファイルで、方針や規約、背景知識を伝える用途に向いています。
一方の Hooks は、特定イベントで処理を必ず走らせる実行機構です。
『Claude Code のベストプラクティス』でも、毎回必須の処理は Hooks に寄せる考え方が示されています。

この違いをひと言で言えば、CLAUDE.mdは「守ってほしいことを書く場所」、Hooks は「守らせる処理を置く場所」です。
たとえば「保存後はフォーマッタを通す」「危険なコマンドは止める」「作業完了時は通知する」といった内容は、文章でお願いするより Hooks にしたほうが安定します。

Claude Code のベストプラクティス - Claude Code Docs

環境設定から並列セッションでのスケーリングまで、Claude Code を最大限に活用するためのヒントとパターン。

code.claude.com

ライフサイクルとイベントの全体像

Hooks はイベント駆動で動きます。
外部記事ではイベントを細かく数えた解説もありますが、本稿では学習コストを抑えるため、まず主要な 4 つに絞って捉えるのが近道です。
正式な一覧は 2026 年時点のHooks リファレンスで確認する前提として、初心者はPreToolUsePostToolUseNotificationSessionStartの役割差を押さえれば十分に導入できます。

流れとしては、セッション開始時にSessionStartが走り、作業中にツール実行前ならPreToolUse、成功後ならPostToolUse、ユーザーへの注意喚起や入力待ちではNotificationが発火します。
各イベントでは JSON コンテキストが渡され、command hook の場合は stdin から受け取ります。
ここで matcher を使うと、たとえば特定ツールだけ、特定コマンドだけ、といった絞り込みも可能です。

初心者が最初に混乱しやすいのは、「どこで設定して、設定後に何が見えるのか」がイメージしにくい点です。
/hooks で追加した内容は、メニュー上でも設定ファイル上でもイベント単位で確認できます。
つまり「通知を入れたつもりが、実際には別イベントに付いていた」というズレに気づきやすく、あとから .claude/settings.json を読んだときも構造を追いやすくなります。

何が自動化できるか：代表ユースケース早見

Hooks の価値は、毎回同じことを言わなくてよくなる点にあります。
代表的なのは通知送信、自動フォーマット、危険コマンドの遮断、ルール検証です。
どれも「人が覚えていればできる」作業ですが、運用ではそこが抜けます。
Hooks はその抜けをイベント単位で埋めます。

Notification Hook は、導入効果がもっとも体感しやすい例です。
長いコード生成や修正をClaude Codeに任せているあいだ、進捗を気にして何度もターミナルへ戻る必要がなくなります。
入力待ちになった瞬間だけ通知を受け取れるので、作業の区切りがはっきりします。
私も最初はこの用途から入りましたが、「いま見に行くべきか」を自分で判断し続ける負担が減るだけで、作業の流れが途切れにくくなりました。

PostToolUseでは、たとえばコード整形や軽い検証を自動で差し込めます。
保存や編集のたびにフォーマッタを通す運用は、手動だと忘れますが、成功後に必ず走る形にしておけば体裁の揺れが減ります。
PreToolUseはより強い制御向けで、危険なコマンドを止めたり、許可したパターンだけ通したりする場面に向きます。
文章で「削除系コマンドは注意」と書くより、実行前にブロックするほうが事故を減らせます。

SessionStartも見逃せないポイントで、セッション冒頭に環境確認やルール検証を入れておくと、作業に入る前の抜けを拾えます。
副作用の強い処理より、依存の不足検知や前提条件の表示のような軽いチェックと相性がいい領域です。
さらに、前処理で Claude に渡す文脈を絞る設計にすると、『Manage costs effectively』で説明されている通り、トークン消費を抑える方向にもつながります。

つまり Hooks は、「自動で便利になる機能」というより、「毎回守りたい運用をイベントに固定する機能」です。
設定後に一覧へイベントとコマンドが並び、実際にそのタイミングで処理が走るのを見ていくと、Claude Codeの挙動が文章ベースのお願いから、再現性のあるワークフローへ切り替わっていきます。

Manage costs effectively - Claude Code Docs

Track token usage, set team spend limits, and reduce Claude Code costs with context management, model selection, extende

code.claude.com

始める前の前提条件と安全確認

インストール確認と更新

Hooks を触り始める前提として、Claude Code本体がすでにインストール済みで、CLI から起動できる状態である必要があります。
まずはターミナルでバージョンを確認して、今の環境で claude コマンドが通るかを見ておくと、その後の切り分けが楽になります。

claude --version

ここでバージョンが返ってくれば、少なくとも実行パスは通っています。
逆にコマンドが見つからない場合は、Hooks の設定ではなくインストールや PATH 周りから確認する流れになります。
実際にこうした前提確認を飛ばすと、設定ファイルを書いたのに反映されないように見えて、原因調査が遠回りになりがちです。

更新も先に済ませておくと安心です。
Claude Codeは自動更新前提ではないため、古いバージョンのまま使っていると、公式ドキュメントの画面や設定例と噛み合わないことがあります。
更新手順を案内しているので、初回導入時だけでなく、Hooks を本格的に組む前にも一度そろえておくと流れが安定します。

macOS の Homebrew、Windows の WinGet などパッケージマネージャを使う場合、配布元やリポジトリによってパッケージ名やコマンドが異なります。
以下は一般的な更新手順の例（プレースホルダを使った示例）です。

例（参考）:

# パッケージマネージャの情報を更新
brew update # macOS(Homebrew) の例
# 実際のパッケージ名は公式案内を参照して置き換えてください
brew upgrade <package-name>

例（参考、Windows PowerShell）:

# WinGet の例
winget upgrade <package-identifier>

winget upgrade

操作としては地味ですが、ここを先に整えるだけで「その設定は現行の仕様か、古い記事の名残か」を判断しやすくなります。Hooks は決定論的に動く仕組みなので、本体のバージョン差分がそのまま挙動差として表に出やすいんですよね。仕様確認にはClaude Codeの概要やhooks でワークフローを自動化するの説明を見比べると、現行の導線をつかみやすくなります。

### 設定ファイルの場所とスコープ

Hooks の保存先として最初に押さえたいのが、プロジェクト配下の `.claude/settings.json` と `.claude/settings.local.json` の役割の違いです。どちらも Hook 定義を持てますが、スコープが異なります。

`.claude/settings.json` は、そのリポジトリで共有したい設定を置く場所です。チーム全員で同じ Hook を動かしたいときはこちらが中心になります。たとえば `PostToolUse` で `prettier` や `ruff format` を走らせるような、プロジェクトルールとして統一したい処理はここに置くと整理しやすくなります。

一方の `.claude/settings.local.json` は、個人のローカル用途に寄せた設定ファイルです。Git 管理に乗せない前提で扱えるので、デスクトップ通知やローカル環境依存のコマンドなど、共有すると逆に困る処理はこちらに分けるのが自然です。たとえば macOS の `osascript` 通知は自分には便利でも、Windows 利用者が混ざるチーム設定には入れにくい、という場面があります。そういう差分を無理なく逃がせるのが `settings.local.json` です。

`/hooks` で作成した設定を保存したあとにこれらのファイルを開いてみると、「対話メニューで選んだ内容が JSON ではこう入るのか」がつながります。最初は UI から入り、保存後に `.claude/settings.json` をのぞく流れにすると、イベント名や `matcher` の位置関係が頭に入りやすく、後から手編集へ移るときも迷いません。

なお、毎セッション読ませる指示は `CLAUDE.md`、毎回必ず実行したい処理は Hooks、という分担です。この線引きはClaude 。ルール文章と自動処理を同じ場所に詰め込まないほうが、設定の意図を追いやすくなります。

### 信頼できないリポジトリのフットチェック

Hooks まわりで見落としやすいのが権限モデルです。Hook はClaude Codeの内部だけで閉じた安全な仕組みではなく、**ユーザー権限でそのままコマンドを実行します**。つまり、便利な自動化を書ける反面、悪意ある処理も同じ権限で動き得ます。Hooks リファレンスや Check Point Research のCaught in the Hookが触れている通り、プロジェクト内設定ファイルを起点にしたリスクは実際に研究対象になっており、CVE-2026-21852 も 2026-01-21 に公開されています。

この前提があるので、信頼できないリポジトリを開いたときは、作業に入る前に `.claude/` 配下を目視で確認するフローが欠かせません。見る場所は狭く、確認対象も明確です。`.claude/settings.json`、`.claude/settings.local.json`、必要なら関連するスクリプト参照先まで見て、どのイベントで何が走るのかを把握します。とくに `PreToolUse` や `SessionStart` に外部コマンドがぶら下がっていると、起動直後や操作前に処理が動くので注意が必要です。

> [!NOTE]
> Hook はユーザー権限で実行されます。リポジトリに含まれる `.claude/` の設定は、単なるメモではなく実行可能な運用ルールとして読む必要があります。

筆者は、リポジトリをクローンした直後に `.claude/` を開いて確認する流れをチームで共通化してから、導入時の不安が一段減りました。レビュー対象が `package.json` や `Dockerfile` だけでなく `.claude/` にも広がるので、あとで「知らない Hook が動いていた」という事態を避けやすくなります。確認作業そのものは数分ですが、安心感はそれ以上です。

ここでの視点は「危険だから使わない」ではなく、「自動で走る設定だから、コードと同じ粒度で読む」です。Hooks はうまく使えば通知、整形、検証を安定して回せますが、その強さはそのまま影響範囲の広さでもあります。とくに外部から取得したリポジトリでは、`.claude/` を開くこと自体が最初のセキュリティチェックになります。

{{related:claude-code-mcp}}
## /hooks で最初の Hook を作る手順

### ステップ1: を開く

最短で 1 本目を入れるなら、CLI の対話メニューから始めるのがいちばん素直です。Claude Code を開いた状態で `/hooks` と入力すると、Hook の追加や編集に入れる画面が出ます。

ここで初心者向けに相性がいいのがNotificationです。`PreToolUse` のように処理を止めたり、`PostToolUse` のように別コマンドを走らせたりする設定より、まずは「Claude が人間を呼ぶ」動きを 1 回作るほうが、Hook の価値をつかみやすいからです。ターミナルを凝視し続けなくても、入力待ちになった瞬間だけ気づける状態を先に作ると、以降の自動化も発想しやすくなります。

実際、長いリファクタリングを任せている間に別タブでドキュメントを書けるようになるだけでも体感は変わります。通知がない状態だと、数分おきにターミナルへ視線を戻して進捗を確認しがちです。Notification Hook を入れてからは、Claude が止まった瞬間だけ呼ばれるので、作業の主導権を取り戻しやすくなりました。集中が途切れにくい、という価値が最初の 1 本でそのまま出ます。

{{ogp:https://code.claude.com/docs/ja/hooks-guide|hooks でワークフローを自動化する - Claude Code Docs|Claude Code がファイルを編集したり、タスクを完了したり、入力が必要な場合に、シェルコマンドを自動的に実行します。コードをフォーマットし、通知を送信し、コマンドを検証し、プロジェクトルールを適用します。|https://claude-code.mintlify.app/_next/image?url=%2F_mintlify%2Fapi%2Fog%3Fdivision%3DClaude%2BCode%2B%25E3%2581%25A7%25E6%25A7%258B%25E7%25AF%2589%25E3%2581%2599%25E3%2582%258B%26appearance%3Dsystem%26title%3Dhooks%2B%25E3%2581%25A7%25E3%2583%25AF%25E3%2583%25BC%25E3%2582%25AF%25E3%2583%2595%25E3%2583%25AD%25E3%2583%25BC%25E3%2582%2592%25E8%2587%25AA%25E5%258B%2595%25E5%258C%2596%25E3%2581%2599%25E3%2582%258B%26description%3DClaude%2BCode%2B%25E3%2581%258C%25E3%2583%2595%25E3%2582%25A1%25E3%2582%25A4%25E3%2583%25AB%25E3%2582%2592%25E7%25B7%25A8%25E9%259B%2586%25E3%2581%2597%25E3%2581%259F%25E3%2582%258A%25E3%2580%2581%25E3%2582%25BF%25E3%2582%25B9%25E3%2582%25AF%25E3%2582%2592%25E5%25AE%258C%25E4%25BA%2586%25E3%2581%2597%25E3%2581%259F%25E3%2582%258A%25E3%2580%2581%25E5%2585%25A5%25E5%258A%259B%25E3%2581%258C%25E5%25BF%2585%25E8%25A6%2581%25E3%2581%25AA%25E5%25A0%25B4%25E5%2590%2588%25E3%2581%25AB%25E3%2580%2581%25E3%2582%25B7%25E3%2582%25A7%25E3%2583%25AB%25E3%2582%25B3%25E3%2583%259E%25E3%2583%25B3%25E3%2583%2589%25E3%2582%2592%25E8%2587%25AA%25E5%258B%2595%25E7%259A%2584%25E3%2581%25AB%25E5%25AE%259F%25E8%25A1%258C%25E3%2581%2597%25E3%2581%25BE%25E3%2581%2599%25E3%2580%2582%25E3%2582%25B3%25E3%2583%25BC%25E3%2583%2589%25E3%2582%2592%25E3%2583%2595%25E3%2582%25A9%25E3%2583%25BC%25E3%2583%259E%25E3%2583%2583%25E3%2583%2588%25E3%2581%2597%25E3%2580%2581%25E9%2580%259A%25E7%259F%25A5%25E3%2582%2592%25E9%2580%2581%25E4%25BF%25A1%25E3%2581%2597%25E3%2580%2581%25E3%2582%25B3%25E3%2583%259E%25E3%2583%25B3%25E3%2583%2589%25E3%2582%2592%25E6%25A4%259C%25E8%25A8%25BC%25E3%2581%2597%25E3%2580%2581%25E3%2583%2597%25E3%2583%25AD%25E3%2582%25B8%25E3%2582%25A7%25E3%2582%25AF%25E3%2583%2588%25E3%2583%25AB%25E3%2583%25BC%25E3%2583%25AB%25E3%2582%2592%25E9%2581%25A9%25E7%2594%25A8%25E3%2581%2597%25E3%2581%25BE%25E3%2581%2599%25E3%2580%2582%26logoLight%3Dhttps%253A%252F%252Fmintcdn.com%252Fclaude-code%252Fc5r9_6tjPMzFdDDT%252Flogo%252Flight.svg%253Ffit%253Dmax%2526auto%253Dformat%2526n%253Dc5r9_6tjPMzFdDDT%2526q%253D85%2526s%253D78fd01ff4f4340295a4f66e2ea54903c%26logoDark%3Dhttps%253A%252F%252Fmintcdn.com%252Fclaude-code%252Fc5r9_6tjPMzFdDDT%252Flogo%252Fdark.svg%253Ffit%253Dmax%2526auto%253Dformat%2526n%253Dc5r9_6tjPMzFdDDT%2526q%253D85%2526s%253D1298a0c3b3a1da603b190d0de0e31712%26primaryColor%3D%25230E0E0E%26lightColor%3D%2523D4A27F%26darkColor%3D%25230E0E0E%26backgroundLight%3D%2523FDFDF7%26backgroundDark%3D%252309090B&w=1200&q=100}}

### ステップ2: Notification Hook を作成する

`/hooks` を開いたら、新規作成でイベント種別にNotificationを選びます。ここでは「どこへ、どう通知するか」を決めて保存します。対話 UI ではイベントを選んで、送信先やチャネルを埋める流れになるので、JSON を最初から手で書く必要はありません。

通知先としては、まずローカルのデスクトップ通知が扱いやすいです。自分の作業端末だけで完結するので、共有設定にするか個人設定にするかも判断しやすく、動作確認もその場で済みます。チームの運用に寄せるなら Slack のような外部チャネルへ送る構成もありますが、最初の導入では「自分に届く」状態を 1 回作るほうが理解が早いです。

保存したあとに `.claude/settings.json` を開くと、対話 UI で選んだ内容が Hook 定義として反映されています。ここで見たいのは、Notification というイベント名の下に、送信設定が JSON として並ぶということです。前のセクションで触れた通り、`/hooks` は初心者向けの入口で、`.claude/settings.json` は共有設定の実体です。UI で作ってから JSON を見る順番にすると、「自分はいま何を追加したのか」が頭の中で対応づけやすくなります。

この確認を入れておくと、後続の手動編集セクションにもつながります。たとえば通知文を細かく調整したい、条件を足したい、共有用と個人用で保存先を分けたい、といった場面で、どこを編集すればいいかが見えてきます。対話メニューは導入のハードルを下げ、設定ファイル確認は構造の理解を補います。この 2 段構えが、最初の Hook ではちょうどいいです。

{{product:7}}

### ステップ3: テストと反映の見え方

設定を保存したら、短いタスクを Claude に投げて通知のタイミングを見ます。たとえば「このファイルを要約して」「小さな関数をリファクタリングして」といった、数十秒から数分で区切りがつく作業が向いています。Claude が処理を進め、追加の入力を待つ段階や注意を促したい場面に入ると、Notification Hook が発火します。

見え方は、スクリーンショットを思い浮かべるとつかみやすいです。ターミナル側では Claude の処理ログが流れ、その外側でデスクトップ通知が右上や右下にポップアップ表示される構図です。通知文には「入力待ちになった」「確認が必要」といった合図が出るので、ターミナルを前面に置いていなくても、戻るタイミングがわかります。Slack に送る構成なら、同じ合図が自分の DM や指定チャンネルに届くイメージです。

この段階で見るべきなのは、通知が「処理開始時」ではなく「人の判断が必要になった時点」で届くということです。ずっと鳴る監視アラームではなく、戻るべき瞬間だけ知らせる呼び鈴に近い動きになります。だからこそ、別タブで文章を書いたり、ブラウザで仕様確認を進めたりしていても、注意を持っていかれる回数が増えません。ターミナルを見張る負担を減らす、という最初の目的にまっすぐ効きます。

反映確認としては、通知が届いたあとで `.claude/settings.json` をもう一度見ると、さきほど UI で保存した設定がそのまま残っています。この「UI で作成した設定がファイルに定着している」状態を 1 回見ておくと、次に JSON を直接編集するときの心理的な壁が下がります。『Hooks リファレンス』にある設定スキーマを読むときも、空の仕様書としてではなく、自分が作った Hook の延長として理解できます。

{{ogp:https://code.claude.com/docs/ja/hooks|Hooks リファレンス - Claude Code Docs|Claude Code のフック イベント、設定スキーマ、JSON 入出力形式、終了コード、非同期フック、HTTP フック、プロンプト フック、MCP ツール フックのリファレンス。|https://claude-code.mintlify.app/_next/image?url=%2F_mintlify%2Fapi%2Fog%3Fdivision%3D%25E3%2583%25AA%25E3%2583%2595%25E3%2582%25A1%25E3%2583%25AC%25E3%2583%25B3%25E3%2582%25B9%26appearance%3Dsystem%26title%3DHooks%2B%25E3%2583%25AA%25E3%2583%2595%25E3%2582%25A1%25E3%2583%25AC%25E3%2583%25B3%25E3%2582%25B9%26description%3DClaude%2BCode%2B%25E3%2581%25AE%25E3%2583%2595%25E3%2583%2583%25E3%2582%25AF%2B%25E3%2582%25A4%25E3%2583%2599%25E3%2583%25B3%25E3%2583%2588%25E3%2580%2581%25E8%25A8%25AD%25E5%25AE%259A%25E3%2582%25B9%25E3%2582%25AD%25E3%2583%25BC%25E3%2583%259E%25E3%2580%2581JSON%2B%25E5%2585%25A5%25E5%2587%25BA%25E5%258A%259B%25E5%25BD%25A2%25E5%25BC%258F%25E3%2580%2581%25E7%25B5%2582%25E4%25BA%2586%25E3%2582%25B3%25E3%2583%25BC%25E3%2583%2589%25E3%2580%2581%25E9%259D%259E%25E5%2590%258C%25E6%259C%259F%25E3%2583%2595%25E3%2583%2583%25E3%2582%25AF%25E3%2580%2581HTTP%2B%25E3%2583%2595%25E3%2583%2583%25E3%2582%25AF%25E3%2580%2581%25E3%2583%2597%25E3%2583%25AD%25E3%2583%25B3%25E3%2583%2597%25E3%2583%2588%2B%25E3%2583%2595%25E3%2583%2583%25E3%2582%25AF%25E3%2580%2581MCP%2B%25E3%2583%2584%25E3%2583%25BC%25E3%2583%25AB%2B%25E3%2583%2595%25E3%2583%2583%25E3%2582%25AF%25E3%2581%25AE%25E3%2583%25AA%25E3%2583%2595%25E3%2582%25A1%25E3%2583%25AC%25E3%2583%25B3%25E3%2582%25B9%25E3%2580%2582%26logoLight%3Dhttps%253A%252F%252Fmintcdn.com%252Fclaude-code%252Fc5r9_6tjPMzFdDDT%252Flogo%252Flight.svg%253Ffit%253Dmax%2526auto%253Dformat%2526n%253Dc5r9_6tjPMzFdDDT%2526q%253D85%2526s%253D78fd01ff4f4340295a4f66e2ea54903c%26logoDark%3Dhttps%253A%252F%252Fmintcdn.com%252Fclaude-code%252Fc5r9_6tjPMzFdDDT%252Flogo%252Fdark.svg%253Ffit%253Dmax%2526auto%253Dformat%2526n%253Dc5r9_6tjPMzFdDDT%2526q%253D85%2526s%253D1298a0c3b3a1da603b190d0de0e31712%26primaryColor%3D%25230E0E0E%26lightColor%3D%2523D4A27F%26darkColor%3D%25230E0E0E%26backgroundLight%3D%2523FDFDF7%26backgroundDark%3D%252309090B&w=1200&q=100}}

## settings.json で Hooks を設定する方法

### 基本構造と最小サンプル

前のセクションで/hooksからNotificationを1本作る流れを見たので、ここではその設定がファイル上でどう表現されるかを最短距離で押さえます。対話メニューで作った内容は、共有したいものなら `.claude/settings.json` に、個人用に閉じたいものなら `.claude/settings.local.json` に保存されます。前者はチームで揃えたい Hook、後者は自分のデスクトップ通知やローカル専用コマンドの置き場、と覚えると混乱しません。

導入順としては、まず CLI で/hooksを開いてNotificationを1つ作り、そのあと設定ファイルを開いて JSON を読むのが素直です。いきなり手書きするより、UI で一度成功体験を作ってから中身を見るほうが、`event` と `handler` が何を表しているかが頭に入りやすいからです。保存後のファイルには、Hook の定義が `hooks` 配列の中に並びます。Claude Code対話メニューと設定ファイルの両方から構成できる前提になっています。

最小構造は次の形です。

{ "hooks": [ { "event": "Notification", "handler": { "type": "command", "command": "notify-send 'Claude Code' '入力待ちです'" } ] }

見る場所は3つだけです。`hooks` は Hook 定義の配列、`event` はいつ動くか、`handler` は何を実行するかです。`handler` の中では `type` と `command` が最初の基本になります。これで「Claude が通知タイミングに入ったら、ローカルコマンドを呼ぶ」という最小の1本になります。

設定後にどう見えるかも、先に知っておくと理解が早まります。/hooksで作成した直後は、CLI 側では登録済み Hook として一覧に見え、ファイル側では今のような JSON が残ります。実際の動作では、Claude が入力待ちになった瞬間にデスクトップ通知が出るので、ターミナルをずっと監視し続ける必要が薄れます。私も最初はこの通知だけ入れて、別タブで文章を書きながら待てる状態にしてから他の Hook へ広げました。

手で編集するときは、最小例から1フィールドずつ増やす進め方が向いています。いきなり `matcher` や複数イベントを足すと、どの条件で発火したのか切り分けに手間がかかります。まずは `event` と `handler` だけで1回鳴らし、そのあと条件を足すと、意図しない動きが出たときも原因の位置を追いやすくなります。

### matcher での対象絞り込みパターン

Hook は「動かせる」だけでなく、「どこで動かすか」を絞ってこそ扱いやすくなります。そこで使うのが `matcher` です。役割は、対象ファイル、使うツール、ブランチ名などの条件を指定して、不要なタイミングで Hook が走るのを防ぐということです。通知でも整形でも、毎回すべてに反応させるとノイズになりやすいので、ここで粒度を整えます。

たとえば、特定のファイル群だけに反応させたいなら、次のように `matcher` を追加します。

{ "hooks": [ { "event": "PostToolUse", "matcher": { "tool": "Edit", "filePaths": ["src/**/*.ts", "src/**/*.tsx"] }, "handler": { "type": "command", "command": "npm run format:changed" } ] }

この形なら、編集ツールが使われ、なおかつ `src` 配下の TypeScript 系ファイルに触れたときだけコマンドが走ります。対象を狭くしているぶん、保存のたびに無関係な処理が混ざることを避けられます。通知 Hook でも同じ発想で、「このツールのときだけ知らせる」「この作業だけ別チャネルに送る」といった組み方ができます。

よく使う絞り込み方は、だいたい次の3系統に分かれます。

1. **ファイル単位で絞る**
 フォーマットや lint の Hook に向いています。`docs/**/*.md` だけに通知を出す、`src/**/*.ts` だけテストを走らせる、といった分け方です。

2. **ツール単位で絞る**
 `Edit`、`Write`、`Bash` など、どの操作で発火させるかを限定する考え方です。コマンド実行時だけ警告を出したい場面で効きます。

3. **ブランチや作業文脈で絞る**
 main 系ブランチでは厳しめ、作業ブランチでは軽め、という運用に向きます。共有設定に入れるときも、対象を絞っておくと意図しない発火を抑えられます。

初心者向けの導入では、最初から複数条件を重ねないほうが流れをつかみやすくなります。まず `matcher` なしで1回動かし、次にファイル条件だけ足す、そのあと必要ならツール条件を加える、という順番だと「何を追加したら、どこで反応しなくなったか」が見えます。Hook は決定論的に動くぶん、条件が1つ増えるだけで結果が変わるので、段階的に育てるほうが迷いません。

### command hook の stdin/stdout 仕様

`type: "command"` を使う Hook で最もつまずきやすいのが、コマンドの入出力仕様です。『Hooks リファレンス』にある通り、イベント発火時のコンテキストは **stdin で JSON として渡され**、Hook 側が **stdout に返してよいのは JSON のみ** です。ここにデバッグ用の文字列や `echo "start"` のような余計な出力が混ざると、Claude 側の JSON 解析が失敗します。

最初に覚えておきたいのは、「標準出力は会話用ではなく機械用」という点です。人間向けのログを見たいなら stderr に逃がすか、ファイルへ書きます。stdout は JSON 専用のレーンだと考えると事故が減ります。シェルの初期化ファイルが起動時にメッセージを吐く構成でも失敗要因になるので、Hook 用コマンドは静かな実行を前提にしたほうが安定します。

たとえば、stdin の JSON を受け取り、そのまま必要な情報だけ返すイメージは次のようになります。

{ "hooks": [ { "event": "Notification", "handler": { "type": "command", "command": "python3 .claude/hooks/notify.py" } ] }

このとき `notify.py` は stdin から JSON を読み、stdout には JSON オブジェクトだけを返します。もし `print("debug")` を標準出力に混ぜると、それだけで失敗の原因になります。最初の検証段階では、戻り値を作らずに通知だけ送る単純なスクリプトから始めると、JSON の形で悩む場所が減ります。

動作の見え方も把握しておくと切り分けが速くなります。設定が正しければ、Claude が対象イベントに入ったときに Hook が実行され、Notification なら画面の外側で通知が出ます。一方で、何も起きない、あるいは Hook 失敗の扱いになるときは、まず stdout に余計な文字が出ていないかを見るのが近道です。私も最初は凝ったスクリプトを書くより、1行コマンドで鳴る状態を作ってから stdin の JSON を読む処理へ広げたほうが、問題の位置をすぐ特定できました。

この仕様を押さえると、通知だけでなく整形や検証の Hook にも横展開できます。入力は JSON、出力も JSON、ログは別経路という線引きができると、設定ファイルを読んだときに「これはどこで壊れうるか」が見えるようになります。

## まず設定したい活用例3選

導入でまず効くのは、毎回の作業に自然に溶け込む Hook です。通知で見落としを減らし、整形で差分を整え、危険操作を入口で止める。この3本を入れるだけで、Hooks を「設定しただけ」で終わらせず、日々の開発フローに組み込めます。Claude Codeの公式ドキュメント「『hooks でワークフローを自動化する』」でも、通知や自動化、ルール適用が代表例として挙がっており、最初の一歩として筋がいい構成です。

### 例1: Notification Hook

最初の1本として扱いやすいのはNotificationです。Claude が入力待ちになったときや、長めの処理の区切りでデスクトップ通知を出すだけでも、ターミナルを見張り続ける時間が減ります。ローカル作業なら macOS の `osascript` や Linux の `notify-send`、チーム運用なら Slack の webhook に投げる形が定番です。

たとえば、コード生成やテスト修正を任せている間に別作業へ移っても、完了時だけ通知が来れば復帰のタイミングを逃しません。エラー系の文言だけ別チャンネルに流す構成にすると、失敗の見落としも減らせます。通知は処理そのものを変える Hook ではないので、導入直後でも挙動を把握しやすく、設定ミスの切り分けもしやすい部類です。

Slack 通知を使う場合は、メッセージ本文にイベント名や対象ツール名、失敗時の要約だけを載せると十分実用になります。情報を詰め込みすぎるより、「何が終わったか」「何で止まったか」が一目でわかる構成のほうが運用で残ります。

{{product:7}}

### 例2: PostToolUse でprettier/eslintを自動実行

次に効果が見えやすいのがPostToolUseです。TypeScript プロジェクトなら、`Edit` や `Write` の成功後に `prettier` や `eslint --fix` を走らせるだけで、手元の修正と整形をひと続きにできます。前のセクションで触れた `matcher` と組み合わせて `src/**/*.ts` や `src/**/*.tsx` に限定しておくと、関係ないファイルまで巻き込まずに済みます。

イメージとしては、Claude が TypeScript ファイルを書き換えた直後に、次のような整形コマンドを呼ぶ形です。
`prettier --write` で見た目をそろえ、`eslint --fix` で機械的に直せるルール違反を吸収する、という分担がわかりやすいです。プロジェクト側に `npm run format` や `npm run lint:fix` があるなら、それを Hook から呼ぶだけでも十分回ります。

私自身、TypeScript の案件でPostToolUseにフォーマッタを入れてから、PR の差分が目に見えて整いました。空白や import 並び替えのようなレビュー価値の低い指摘が減り、変更の本筋だけを追えるので、レビューにかかる時間も短くなった感覚があります。Hooks の利点は、開発者ごとのエディタ設定に依存せず、Claude が触った直後に同じ整形を通せるということです。

一方で、整形のたびに重い lint やテストまで同期実行すると、編集のテンポが鈍ります。重い処理は後段に逃がす設計のほうが、普段の操作と衝突しません。

{{product:6}}

### 例3: PreToolUse で危険コマンドと敏感領域を書き換え不可に

事故を減らす目的なら、PreToolUseがいちばん効きます。`rm -rf` のような破壊的コマンド、`.env` の変更、本番設定ディレクトリへの書き込みを、実行前に判定して止める構成です。ここでは「警告を出す」だけでなく、条件に合致したら `exit 2` を返して実行を中止する設計が実用的です。Claude 。

たとえば、`Bash` ツールで `rm -rf` を含むコマンドが来たら即中止、`config/production/` や `infra/prod/` への書き込みならブロック、`.env` や `.env.production` に触れようとしたら差し戻し、というルールは導入しやすい部類です。人間が打つコマンドだけでなく、Claude が提案・実行する操作にも同じ門番を置けるので、「うっかり通る」が起きにくくなります。

この手の Hook は厳しくしすぎると日常作業まで止めるので、最初は対象を絞るのがコツです。本番相当ディレクトリ、秘密情報ファイル、破壊的コマンドという3種類から始めると、守りたい場所が明確です。私の環境でも、本番設定ディレクトリへの書き込みをPreToolUseで止めてから、誤操作でひやっとする場面がなくなりました。レビュー前に気づくのではなく、実行前に止まるので、精神的な負荷のかかり方が違います。

> [!TIP]

{{product:5}}
### 重い処理は非同期実行を検討

### exit 0 と exit 2 の意味と使い分け

Hooks が「動いているのに効かない」と感じたとき、真っ先に見るべきなのが終了コードです。Hooks リファレンスにある通り、`exit 0` は成功扱いで、このとき **stdout に出した JSON をClaude Codeが処理**します。これに対して `exit 2` は中止またはスキップの扱いで、**stdout の JSON は無視**されます。ここを取り違えると、JSON 自体は正しく見えるのに反映されない、という混乱に入りがちです。

実務では、`exit 0` は「この Hook の結果を採用してよい」と伝えるコード、`exit 2` は「ここで止める、またはこの処理は採用しない」と伝えるコードとして分けると整理できます。たとえばPreToolUseで危険コマンドを検知した場面では `exit 2` が自然です。一方、入力を検査して補足情報を返す、整形結果を JSON で返す、といった場面では `exit 0` で終える必要があります。見た目は小さな差ですが、Hook 全体の振る舞いはここで切り替わります。

私が切り分けるときは、まず Hook の末尾で **どの条件で 0 を返し、どの条件で 2 を返しているか**を確認します。条件分岐が増えると、意図せず `exit 2` に落ちていることが珍しくありません。JSON の内容を疑う前に終了コードを見るほうが、原因に早くたどり着けます。公式仕様を前提に考えると、「JSON が無視されるのはフォーマット不正だけではなく、終了コードの選択ミスでも起こる」と捉えるのが実践的です。仕様の確認先としては『Hooks リファレンス』が基準になります。

### stdoutはJSONのみ／プロファイル出力が壊す罠

Hook の stdout は、**JSON オブジェクトだけ**で構成されていなければいけません。ここにログ行やデバッグ用の `echo`、起動メッセージのような余計な文字列が混ざると、受け取る側は JSON として解釈できなくなります。たとえ Hook スクリプト本体に `echo "start"` を書いていなくても、`.zshrc` や `.bashrc` のような shell profile が勝手に一行出力して失敗するケースがあります。

> [!TIP]
> Hook の調査では、stdout（機械向け出力）と人間向けのログを分けると原因切り分けが速く進みます。stdout は JSON のみを出力し、調査用ログは stderr や一時ファイルに書く運用に固定すると、問題を特定しやすくなります。

### Stop hook と stop_hook_active の無限ループ注意
Stop hookまわりでは、再入制御を意識していないとループに入り込みます。そこで出てくるのが `stop_hook_active` です。これは Stop hook が自分自身を呼び直すような流れを避けるための制御フラグで、実質的に「今は Stop hook の処理中か」を示すガードとして働きます。ここを考えずに設計すると、止めるための Hook が再び Hook を呼び、また止めに行く、という循環が起こります。

とくに気をつけたいのが、Stop hook で不適切に `exit 2` を返す設計です。`exit 2` 自体が悪いのではなく、**どの条件で返すか**が曖昧なまま使うと、停止処理のたびに再評価が走り、結果として抜け道のないループを作ります。この点は実践上の注意点として触れられていて、Stop hook を使うなら `stop_hook_active` を前提にした分岐が欠かせません。単に「危なそうなら 2 を返す」ではなく、「再入中なら素通しする」「初回だけ止める」「代替処理へフォールバックする」といった出口を明示しておく必要があります。

私の感覚では、Stop hook は便利な反面、通知 Hook や整形 Hook より一段階だけ設計負荷が高いです。原因はロジックそのものより、制御フローが見えにくいことにあります。動かないときは Hook の本体だけでなく、`stop_hook_active` の状態、返した終了コード、どのイベントから再度呼ばれたかを並べて追うと、輪の形が見えてきます。入力 JSON、返却 JSON、終了コードを一時ファイルに残して時系列で見るやり方は、この種の詰まりにも効きます。

## Claude Code Hooks の注意点とベストプラクティス

### 設計の指針：小さく始めて段階導入

初心者が最短で入るなら、最初の1本はNotification Hookが向いています。CLI で `claude` を開いたら `/hooks` と入力し、対話メニューからNotificationを選んで、OS の通知コマンドを1つ登録する流れです。たとえば macOS なら `osascript` を使った通知、Windows ならローカル通知用のコマンドを結びつける形にすると、入力待ちや注意喚起のタイミングで画面外から戻るきっかけが作れます。設定後は `.claude/settings.json` に Hook 定義が入り、チーム共有ならそのまま PR に載せられますし、個人用なら `.claude/settings.local.json` に分ける運用も取りやすくなります。

この最初の通知だけでも、ターミナルをずっと見張る時間が減ります。私も最初は「通知くらいで変わるのか」と思っていたのですが、実際には別ウィンドウでドキュメントを書いたり、ブラウザで仕様を確認したりしている間に、Claude が入力待ちへ戻ったことを即座に拾えるので、作業の切れ目が整います。Hooks の価値は派手な自動化より、こういう小さな待ち時間の削減にまず表れます。

役割分担も最初に決めておくとぶれません。ルールや背景、なぜその運用にしているかはCLAUDE.mdに書き、毎回必ず走らせたい処理だけを Hooks に置く、という線引きです。たとえば「コミット前はこういう観点で確認してほしい」はCLAUDE.md向きで、「保存後に必ず整形する」「入力待ちになったら通知する」は Hooks 向きです。『Claude Code のベストプラクティス』でも、この使い分けが前提になっています。全部を Hooks に寄せると設定が読みにくくなり、全部をCLAUDE.mdに寄せると実行保証が消えます。

SessionStartも便利ですが、最初から重い処理を入れないほうが安定します。以前、私は SessionStart で `npm install` を自動実行する構成にしたことがありました。セッション開始のたびに依存解決が走るので待ち時間が伸び、作業を始める前から足が止まります。その経験以降は、依存のインストールではなく「不足している依存があるか」「必要なコマンドが通るか」を調べる検証だけに切り替えました。セッション開始時は、環境チェックやバリデーションのような副作用の薄い処理に留めたほうが、再現性も保ちやすくなります。

> [!TIP]
> 迷ったら `/hooks` からNotificationを1本だけ作り、次にPostToolUseで軽い整形を足す順番が収まりやすいです。最初の段階でブロック系や Stop hook まで広げないほうが、トラブル時の切り分けが短く済みます。

### パフォーマンス配慮

Hooks は動くたびに効く仕組みなので、1回あたりの重さがそのまま体感速度に乗ります。毎回の Hook にテスト一式や依存更新のような処理を入れると、便利さより待ち時間が前に出ます。とくにPostToolUseは成功のたびに走るので、フォーマットや軽いログ出力のように終わりが読みやすい処理へ絞ると流れが崩れません。重い処理は定期実行へ逃がす、バックグラウンドジョブへ分離する、あるいは明示コマンドで起動する設計のほうが、開発中のテンポを守れます。

Notification Hook のような軽い処理は、パフォーマンス面でも導入しやすい部類です。設定後の見え方もわかりやすく、入力待ちになるとデスクトップ通知が出る、あるいはローカル通知センターに積まれる、という形で効果がすぐ見えます。反対に、重い Hook は「何が遅いのか」が見えにくく、Claude 本体が遅いのか、Hook が足を引っ張っているのかを区別しづらくなります。最初のうちは「目に見える結果があり、処理時間が短いもの」を優先すると、設定の良し悪しを判断しやすくなります。

CLI 自体の更新も見落としやすいポイントです。挙動確認や不具合切り分けの前に、公式のインストール/アップデート手順に従って CLI バージョンを揃えておくと、古い挙動を追いかける無駄が減ります。実際のパッケージ名やコマンドは配布元の公式ページで確認してください（参照日: 2026-03-18）。

### セキュリティ実務：レビュー運用と権限の考え方

Hooks はローカルで決定論的に動くぶん、設定ファイルに入った処理がそのまま実行されます。しかもフルユーザー権限で走るので、信頼できない Hook を読み込まないという前提が欠かせません。外部から入ってきたリポジトリや、内容を理解していない `.claude/` 配下の設定を無警戒で使うと、意図しないコマンド実行を招くことがあります。情報の取り扱いに関する問題につながる恐れもあります。プロジェクトファイル由来の設定が攻撃面になりうることが指摘されています。

実務では、`.claude/settings.json` をコードレビュー対象へ明示的に入れるだけでも効果があります。私のチームでは settings.json を PR で必ずレビューする運用にしてから、善意で足された自動化や、意図が曖昧な Hook が混ざり込みにくくなりました。なお、CLI の配布やアップデートで示されるパッケージ名やコマンドは配布元で異なります。インストール/更新手順を記載する場合は、公式ガイドの該当ページ（参照日: 2026-03-18）を確認のうえ、正確な識別子を載せてください。

秘密情報の扱いも、通常のスクリプト以上に神経を使います。通知先に環境変数をそのまま流す、ログへ入力内容を丸ごと書き出す、といった設計は避けたほうが安全です。Slack 通知や外部コマンド連携を組む場合でも、送る内容は最小限に絞り、トークンや API キーが標準出力やファイルへ残らない形に寄せるのが基本です。権限の強い仕組みだからこそ、「何を自動化するか」より先に「どこまで自動実行してよいか」を決めるほうが事故を防げます。

{{ogp:https://research.checkpoint.com/2026/rce-and-api-token-exfiltration-through-claude-code-project-files-cve-2025-59536/|Caught in the Hook: RCE and API Token Exfiltration Through Claude Code Project Files ｜ CVE-2025-59536 ｜ CVE-2026-21852 - Check Point Research|By Aviv Donenfeld and Oded Vanunu Executive Summary Check Point Research has discovered critical vulnerabilities in Anth|https://research.checkpoint.com/wp-content/uploads/2026/02/image-20-1.png}}

### コスト最適化メモ

Hooks は便利さだけでなく、トークン消費の整理にも効きます。『Manage costs effectively』 では、Claude Code の平均コストが Sonnet 4.6 利用で開発者1人あたり月額約 $100〜200 と案内されています。対してClaude Proは複数の料金ガイドで $20/月 とされており、日常的に Claude Code を回す開発運用では、どこで不要なコンテキストを減らすかが効いてきます。

効くのは、毎回の入力を長くする工夫ではなく、渡す前に削れるものを削る工夫です。たとえば Hook 側でログのノイズを落とす、巨大な差分から対象ファイルだけを抜き出す、通知には要点だけを載せる、といった前処理はそのまま不要トークンの圧縮につながります。試算の置き方として、月額 $150 の利用が前処理で3割ぶん削れれば $105 程度まで下がる計算になります。さらに5人規模で同じ削減幅が出ると、年間では $2,700 の差になります。もちろん削減率そのものは Hook の設計次第ですが、「少し賢く前処理するだけで固定費に効く」という感覚は持っておいたほうがよいです。

ここでも、最初の一歩は Notification Hook で十分です。ターミナル監視の手間を減らしつつ、`.claude/settings.json` にどう記録されるかを確認でき、レビュー運用にも乗せやすいからです。そこから軽い整形や検証へ広げると、パフォーマンス、セキュリティ、コストの3点を崩さずに育てていけます。

{{related:claude-code-claudemd}}
## まとめ

### 最初は1〜3個のHookに絞る。推奨順は「通知 → フォーマット → 安全制御」

入り口は広げすぎないほうが定着します。私も通知、整形、安全制御の3つだけ入れた段階で、見落としと無駄、動かしてよいか迷う不安が目に見えて減りました。到達点は、主要4イベントが何を担うのかを言葉で説明できて、`exit 0` と `exit 2` の違い、`Stop hook` の再入罠を外さずに運用できる状態です。

### 次のアクション

最初の一歩は `/hooks` で通知Hookを1本作るということです。次にPostToolUseでフォーマッタをつなぎ、手作業の整形を減らします。その後にPreToolUseで危険なコマンドだけを止め、`.claude/settings.json` をレビュー対象に含める流れへ進むと、運用が崩れません。イベント一覧や設定スキーマの細部は、執筆時点での最新仕様に合わせてClaude Code Docsの公式リファレンスで締めに確認しておくと、手戻りを防げます。