Claude Code Hooks実践例とテンプレ集

Claude CodeのHooksは、開発フローの節目でシェルコマンドを自動実行できる仕組みです。
通知、コード整形、検証、ルール強制などの処理を会話フローの中へ差し込みやすくなります。
Claude Code Docsの hooks ガイドにある通り、/hooks から対話的に設定できるため、最初の1本は数分で動かせます。

Hooks / Tasks とは何かを最初に整理する

Claude Code Hooksの定義と位置づけ

仕組みはシンプルで、まずイベントという起点があります。
そこに対して「何を実行するか」という Action を結びつけ、実際の処理はシェルコマンドで書きます。
多くの実装では実行結果を標準出力や終了コードで確認しますが、実際の取り扱いは Hook の実装やイベントスキーマによって異なることがあります。
公式ドキュメントの仕様を確認しつつ、本記事では「シェルコマンド実行の一般的な扱い」を前提に設計例を示します。
最短で1つ試すなら、導入は /hooks から始めるのがいちばん早いです。
Claude Codeのセッション内で /hooks を実行すると、対話形式で hook を追加できます。
ここでは最小構成として Notification hook を1本だけ入れるのが向いています。
たとえば macOS なら osascript -e 'display notification \"Claude Code finished\" with title \"Claude Code\"'、Linux なら notify-send \"Claude Code\" \"Claude Code finished\"。
Windows ならBurntToast導入後に New-BurntToastNotification -Text \"Claude Code\", \"Claude Code finished\" のような通知コマンドが使えます。

設定が終わると、対象イベントが発生したタイミングでそのコマンドが自動実行されます。
動作確認では、長めの処理を1回流して完了を待つとわかりやすく、処理終了時にデスクトップ通知が出れば hook はつながっています。
確認場所は二つあります。
ひとつは OS 側の通知センターです。
もうひとつはClaude Code側の hook 実行結果で、設定したコマンドの実行痕跡や場合によっては標準出力・終了コードが参照できることがあります。
ただし、出力の取り扱いや終了コードの表現は Hook の実装やイベントスキーマに依存します。
実装の詳細は公式ドキュメントの実行結果仕様を参照してください。
最初の1本は「通知が出たか」を見れば十分で、ここで成功体験を作ると次の整形 hook や検証 hook に進みやすくなります。
Hook は「いつ走るか」の定義で、Task は「何をやるか」の単位、と分けて考えると整理できます。
Hook はイベント起点、Task は実行したい作業です。
通知、コード整形、lint、テスト、危険コマンドの抑止といった個々の処理が Task に当たります。
さらに複数の Hook と Task を並べると、全体としてひとつの“シナリオ”のように振る舞います。

この考え方は、RPA や MA のシナリオ設計で使われる「トリガー、アクション、条件分岐」の発想に近いものです。
『MAのシナリオ設計とは？作り方のポイントと事例・雛形』でも、トリガーに対してアクションをつなぎ、必要に応じて条件分岐を置く構成が基本として説明されています。
Claude Codeの hook も同じです。
まず発火点を決め、次に単機能の Task を割り当て、分岐や例外が必要なら設計で吸収していく流れになります。

実務では、通知と整形を1本の hook に詰め込むより、別 hook に分離したほうが扱いやすい場面が多いです。
私も実際に“通知”と“整形”を分けてから、どちらが原因で期待どおりに動かなかったのかを切り分けやすくなりました。
整形コマンドが失敗しているのか、通知コマンドが通っていないのかが一目で追えるので、意図の競合が起きにくくなります。
最初から大きな自動化を作るより、「1 hook = 1責務」に寄せたほうが、修正も追加も迷いません。

判断が曖昧な処理では、固定ルールだけで押し切らない設計も必要です。
英語版の『Automate workflows with hooks』では、deterministic な hook だけでなく、prompt-based hooks や agent-based hooks という選択肢にも触れています。
たとえば「この変更は危険か」を単純な文字列一致だけで判定すると取りこぼしや過検知が出ます。
こういう曖昧な判定は deterministic な shell hook に詰め込まず、後者に寄せるほうが自然です。
反対に、通知、整形、決まったコマンドの検証のように条件が明確なものは deterministic にすると動作が読みやすくなります。

もうひとつ押さえておきたいのが、hook の経路は現在の会話コンテクストを保持するという点です。
まったく新しい実装セッションとして切り離されるわけではないので、hook を「毎回会話履歴を参照しない仕組み」とは捉えないほうが実態に合います。
セッションの流れを引き継いだうえで自動処理が挟まる、と見ておくと設計の前提がぶれません。

Salesforce Marketing Cloudのマーケティングソフトウェア

Salesforceが提供するマーケティングプラットフォーム、Marketing Cloudで、より多くの顧客を獲得し、エンゲージメントの向上、売上拡大を実現しましょう。

www.salesforce.com

React Hooksとの違い

React Hooksは、Reactが 16.8 で導入した UI 開発用の仕組みで、関数コンポーネントから state や lifecycle 相当の機能を扱うための API です。
つまり、コンポーネントのレンダー文脈で使うものです。
一方で本記事のClaude Code Hooksは、CLI 上の作業フローに対してシェルコマンドを差し込む自動化機能です。
名前は同じでも、動く場所も目的もまったく違います。

混同しやすいのは、「Hook」という単語がどちらも「何かの節目に差し込む拡張点」を連想させるからです。
ただしReactでは useState や useEffect のように UI の状態管理が中心で、Claude Codeでは通知や整形や検証のように外部コマンド実行が中心です。
たとえば『Prettier』で npx prettier --write . を流す処理や、ESLintで npx eslint --ext .js,.jsx,.ts,.tsx --fix ./ を走らせる処理は、Claude Code Hooksの文脈では自然ですが、React Hooksとは無関係です。

そのため、「Hooks を設定する」と言ったときに本記事では /hooks で追加するClaude Codeの設定を意味します。
設定後に起きることも UI 状態の変化ではなく、イベント発火時のコマンド実行です。
通知なら OS の通知センターに結果が現れ、整形なら対象ファイルの内容が書き換わり、検証ならコマンドの終了コードで成否が返ります。
最初の1本として Notification hook を入れる意義はここにあって、Trigger と Action の関係を最短で目視できるからです。
名前の印象に引っ張られず、「Reactの API ではなく、Claude Codeの自動化フック」と切り分けておくと、その後の設定で迷いません。

Claude Code で Hooks を設定する基本手順

セットアップ3ステップ

Claude Codeで最初の Hook を作るなら、入力欄から /hooks を開く方法が最短です。
ここからインタラクティブに追加できます。
画面遷移を覚えるより、まず 1 本登録してイベントで反応させるほうが全体像をつかみやすいのが利点です。

手順は 3 つです。

1. Claude Codeの入力欄で /hooks と入力して実行します。
2. 表示された UI でイベント種別を選びます。最初は Notification hook を選ぶと挙動を確認しやすく、成功か失敗かを目で追えます。
3. 実行したいシェルコマンドを登録して保存します。保存後はその Hook が有効になり、対象イベントが起きたタイミングでコマンドが走ります。

実際に /hooks を開いて通知 Hook を登録してみると、イベント発火のタイミングでトースト通知がすぐ上がるはずです。
最初の 1 個は通知系にしておくと、設定した瞬間に「確かに動いた」と分かるので、成功体験を作りやすいと筆者は感じています。

ここで押さえたいのは、Hook が登録されるとClaude Codeがそのイベントでシェルコマンドを実行するようになることです。
つまり、設定作業そのものは短くても、保存したあとから自動化が始まります。
/hooks の画面を開き直せば、有効・無効の切り替えや編集もできます。

hooks でワークフローを自動化する - Claude Code Docs

Claude Code がファイルを編集したり、タスクを完了したり、入力が必要な場合に、シェルコマンドを自動的に実行します。コードをフォーマットし、通知を送信し、コマンドを検証し、プロジェクトルールを適用します。

code.claude.com

最小の通知Hook

最初の 1 本として扱いやすいのは、macOS の osascript を使った通知です。
osascript は macOS 標準のコマンドなので、追加インストールなしで試せます。
Notification hook の実行コマンド欄には、たとえば次の 1 行を入れます。

osascript -e 'display notification "Claude Codeの処理が終わりました" with title "Claude Code"'

この設定を保存すると、選んだ通知イベントが起きたタイミングで macOS のネイティブ通知が表示されます。
ターミナルに張り付いていなくても処理完了に気づけるので、テスト実行や生成待ちのように少し席を外す作業と相性が良いです。

もし最初から凝った処理を入れると、Hook 自体が動かないのか、コマンドの中身で失敗しているのかが分かりにくくなります。
1 行の通知コマンドなら切り分けが単純で、Hook の仕組みだけを確認できます。
ここで 1 回通しておくと、あとから npx prettier --write . や npx eslint --fix ./ のような実用コマンドに広げるときも迷いません。

動作確認とログの見方

設定後は、「保存できたか」ではなく「イベントで実行されたか」を見るのが判断材料になります。
まず対象イベントを明示的に発火させて、通知が出るかを確認します。
通知が出れば、Hook の登録とコマンド実行の流れは通っています。

反応がないときは、いきなり Hook 側だけを疑うより、登録したコマンドをターミナルで単独実行してみると切り分けが進みます。
たとえば macOS なら、先ほどの osascript をそのままターミナルで実行して通知が出るかを見ます。
ここで失敗するなら、問題は Hook ではなくコマンド側です。
逆に単独では成功するのに Hook 経由で動かないなら、イベント選択や保存内容を見直す流れになります。

Hook の成否は、実行したシェルコマンドの標準出力と終了コードで追えます。
終了コードが 0 なら成功、0 以外なら失敗という Unix 系コマンドの基本ルールで見れば整理できます。
最初は通知だけでも十分ですが、少し複雑な Hook を作る段階では、失敗時にメッセージを出すようにしておくと原因を追いやすくなります。
通知が出ないケースでも、echo "hook failed" のように出力を残す形にしておくと、何も起きない状態を避けられます。

たとえば通知手段がまだ整っていない環境では、まず次のようなコマンドで Hook 自体の発火だけ確かめる方法もあります。

echo "Claude Code hook fired"

この確認は地味ですが、Windows で通知モジュール導入前にまず echo で流れを通しておくと、どこで詰まっているかが見えます。
筆者も Windows では最初から通知に進むより、いったん echo で Hook の発火を確認してから PowerShell 通知に移したほうが手戻りが少なかったです。

Mac/Windows/Linuxの通知差分

通知 Hook は OS ごとに使うコマンドが違います。
考え方は同じで、「イベントが起きたらシェルコマンドを実行する」という軸は変わりません。
違うのは通知を表示するためのコマンドだけです。

macOS では osascript がいちばん手軽です。
標準搭載なので、追加準備なしで通知 Hook を試せます。
最初の 1 本として向いているのはこのためです。
すぐにトーストが出るので、Hook の価値を体感しやすいんですよね。

Linux では notify-send を使うのが定番です。
Debian や Ubuntu 系なら libnotify-bin に含まれていて、コマンドは次の形です。

notify-send "Claude Code" "Claude Codeの処理が終わりました"

Windows では PowerShell から通知を出します。
手軽さではBurntToastモジュールを使う方法が分かりやすく、たとえば New-BurntToastNotification を呼ぶ構成です。
ただ、Windows はこのモジュール導入が最初の一段になるので、macOS より入口が一つ増えます。
筆者も Mac では osascript ですぐ動きましたが、Windows では PowerShell モジュールの準備が必要で、まずは echo で Hook 発火だけ確認してから通知導入に進めるほうが流れをつかみやすかったです。

コマンド例としては次のような形です。

New-BurntToastNotification -Text "Claude Code", "Claude Codeの処理が終わりました"

Linux でも Windows でも、最初から通知表示にこだわらなくても Hook の理解は進みます。
通知手段がまだ入っていない段階なら、まず echo でイベント発火を確認し、そのあと OS に合った通知コマンドへ置き換える流れのほうが迷いません。
Claude Code側の設定は /hooks で共通なので、違いは実行コマンドの部分だけだと捉えると整理できます。

すぐ使える実践テンプレート集

このセクションでは、UI で対象イベントを選び、そこにそのまま貼れる形のコマンドを並べます。
細かな条件分岐まで最初から作り込むより、まずは 1 本通して、必要になったら育てるほうが Hook の価値が見えます。
Claude Codeイベントに対して任意のコマンドを差し込む発想が基本になっています（Automate workflows with hooks - Claude Code Docs）。

テンプレ1: 完了通知

長めの生成やテスト実行を眺め続けたくないときは、完了通知が最初の 1 本に向いています。
席を外していても結果を取りこぼしにくく、Hook が「ちゃんと走った」感触も得やすいからです。
イベントは、作業完了や応答完了に当たるものを UI で選び、そのイベントに応じて以下を登録します。

macOS ならosascriptが標準搭載なので、そのまま通知を出せます。

if command -v osascript >/dev/null 2>&1; then
  osascript -e 'display notification "Claude Codeの処理が終わりました" with title "Claude Code"'
else
  echo "Claude Codeの処理が終わりました"
fi

Linux ならnotify-sendです。Debian / Ubuntu 系では libnotify-bin に含まれます。

if command -v notify-send >/dev/null 2>&1; then
  notify-send "Claude Code" "Claude Codeの処理が終わりました"
else
  echo "Claude Codeの処理が終わりました"
fi

Windows は PowerShell から通知します。BurntToastを入れている前提なら次の形です。

if (Get-Command New-BurntToastNotification -ErrorAction SilentlyContinue) {
  New-BurntToastNotification -Text "Claude Code", "Claude Codeの処理が終わりました"
} else {
  Write-Output "Claude Codeの処理が終わりました"
}

BurntToastが未導入でも、とりあえず発火確認だけなら echo や Write-Output で十分です。
通知が使えない端末でも、Hook 自体の接続確認までは同じ流れで進められます。
筆者も長めの処理ではこの通知を入れておくことが多く、画面に張り付かずに別作業へ移れるぶん、Hook の恩恵を最初に実感しやすいテンプレートでした。

テンプレ2: 保存後の整形

変更後にフォーマッタを走らせる Hook は、日々の差分を静かに整えてくれます。
イベントは、保存後や変更適用後に相当するものを UI で選びます。
プロジェクトの既定コマンドがあるならそれを優先し、なければツールを直接呼ぶ構成にすると迷いません。

JavaScript / TypeScript 系で package.json に整形用スクリプトがあるなら、まずはこれで十分です。

if command -v npm >/dev/null 2>&1; then
  npm run format
else
  echo "npm が見つからないため format をスキップしました"
fi

『Prettier』を直接使うなら、公式ドキュメントにある --write をそのまま使えます。

if command -v npx >/dev/null 2>&1; then
  npx prettier --write .
else
  echo "npx が見つからないため Prettier をスキップしました"
fi

Lint の自動修正までまとめたいときはESLintの --fix を追加します。

if command -v npx >/dev/null 2>&1; then
  npx eslint --ext .js,.jsx,.ts,.tsx --fix ./
else
  echo "npx が見つからないため ESLint をスキップしました"
fi

Python 系ならRuffかBlackが定番です。
Ruffは ruff format を持っていて、まとまったコードベースでも処理待ちのストレスが少ない場面が多いです。

if command -v ruff >/dev/null 2>&1; then
  ruff format .
else
  echo "ruff が見つからないため整形をスキップしました"
fi

if command -v black >/dev/null 2>&1; then
  black .
else
  echo "black が見つからないため整形をスキップしました"
fi

自動整形 Hook を入れてみると、『Prettier』を手で回す回数がほぼゼロになりました。
しかも差分の形が揃うので、レビューではレイアウトの揺れではなく変更の意図だけを見ればよくなります。
『Prettier』は npx prettier --write . のように素直な CLI を持っていて、ESLintも --fix を噛ませられるので、Hook に乗せたときの収まりがいい構成です。

テンプレ3: 危険コマンドのブロック

ここは事故防止に直結するテンプレートです。
イベントは、コマンド実行前やツール実行前に割り込めるものを UI で選びます。
どのイベントで中断できるかは仕様に依存するため、実際に止められるかどうかは /hooks のヘルプで確認しながら決める前提です。
設計としては「危険パターンを検知したら終了コードを変えて止める」「誤検知時だけ明示的に逃がす」の 2 段構えが扱いやすいのが利点です。

シェルコマンド文字列を受け取れる前提なら、たとえば次のように rm -rf / や fork bomb の典型パターンを弾けます。

cmd="${HOOK_INPUT:-}" # サンプル変数。実際はイベント仕様に合わせてください。

if [ "${ALLOW_DANGEROUS:-0}" = "1" ]; then echo "dangerous command bypassed by ALLOW_DANGEROUS=1" exit 0 fi

# $CLAUDE_HOOK_INPUT のような具体的な変数名やペイロード名は # 実際の Hook イベントスキーマに依存します。
運用では公式ドキュメントに従って # フィールド名や JSON パスを読み替えてください。
case "$cmd" in

"rm -rf /"|"rm -rf ~"|":(){ :|:& };:"|":(){:|:&};:")

echo "Blocked dangerous command: $cmd" exit 1 ;; "--force") echo "dangerous-looking command allowed by --force" exit 0 ;; *) exit 0 ;; esac

入力変数名は選ぶイベントの仕様に合わせて読み替える必要がありますが、骨格はこのまま流用できます。
誤検知時の逃げ道として ALLOW_DANGEROUS=1 の環境変数か --force を先に用意しておくと、運用で詰まりません。
筆者はこの逃げ道を最初から設計に入れておくほうで、止める仕組みの安心感と、必要時に進められる余地の両方が残ります。
危険コマンド検知は強く締めたくなりますが、バイパス手段を後付けにすると、現場では「怖いから Hook を無効化する」に流れがちでした。

cmd="${HOOK_INPUT:-}"

if [ "${ALLOW_DANGEROUS:-0}" = "1" ]; then cmd="${HOOK_INPUT:-}" # サンプル変数。
実際はイベント仕様に合わせてください。

if [ "${ALLOW_DANGEROUS:-0}" = "1" ]; then exit 0 fi

# 受け渡し形式は Hook の仕様に従って読み替えてください。公式ドキュメントのイベントスキーマを参照して運用してください。 case "$cmd" in

"rm -rf "|"dd if="|"mkfs."|"shutdown -h now"|"reboot")

echo "Blocked potentially destructive command: $cmd" exit 1 ;; *) exit 0 ;; esac まずはファイルの存在を見て、冒頭だけ表示するテンプレートです。

if [ -f CLAUDE.md ]; then
  echo "=** CLAUDE.md **="
  sed -n '1,40p' CLAUDE.md
elif [ -f CONTRIBUTING.md ]; then
  echo "=** CONTRIBUTING.md **="
  sed -n '1,40p' CONTRIBUTING.md
else
  echo "ルールファイルは見つかりませんでした"
fi

短い運用ルールを固定文として注入する方法もあります。たとえば「テスト必須」「コミットメッセージ規約」「生成物の直接編集禁止」だけを毎回出す形です。

echo "このプロジェクトの作業ルール:"
echo "- 変更後はテストを実行する"
echo "- コミットメッセージは規約に従う"
echo "- 自動生成ファイルを直接編集しない"

CLAUDE.mdは、リポジトリルートに置いてプロジェクト固有の判断基準を書く慣習が定着しています。
Claude Codeのベストプラクティスでも、その種の恒久コンテキストを整理しておく発想が中心です（hooks でワークフローを自動化する - Claude Code DocsHook で冒頭に要点を見せるようにしておくと、長い文書を毎回読み直さなくても、作業の軸だけをすぐ思い出せます）。

テンプレ5: 文脈注入

セッション開始時には、ルールだけでなく「今なにが残っているか」も出しておくと会話の立ち上がりが速くなります。
ここでは今日の作業文脈をターミナルから拾って、最初にまとめて表示します。
イベントはセッション開始時を選びます。

いちばん扱いやすいのは Git の状態です。

if command -v git >/dev/null 2>&1; then
  echo "=** git status -sb **="
  git status -sb
else
  echo "git が見つかりませんでした"
fi

GitHub Issues まで見たいなら、『gh』が入っている環境では未処理 Issue をその場で出せます。
未導入なら静かにスキップする分岐にしておくと、環境差で止まりません。
GitHub Issues をその場で確認したい場合は、gh がインストールされている環境であれば未処理 Issue を一覧表示できます。
未導入の環境では静かにスキップする分岐にしておくと、環境差で処理が止まりません。

if command -v gh >/dev/null 2>&1; then
  echo "=** open issues **="
  gh issue list
else
  echo "gh が無いため issue 一覧はスキップしました"
fi

両方をまとめると、セッション冒頭で「ブランチの差分」「未追跡ファイル」「Issue の残件」が一度に見えます。

if command -v git >/dev/null 2>&1; then
  echo "=** git status -sb **="
  git status -sb
fi

if command -v gh >/dev/null 2>&1; then
  echo "=** open issues **="
  gh issue list
fi

この種の文脈注入は派手ではありませんが、毎回ゼロから状況説明する時間を削ってくれます。
特に途中作業の多い日ほど、冒頭で git status -sb が出るだけで会話の前提が揃いますし、『gh』の issue list が並ぶと「今日はどれを片づけるか」まで自然に焦点が定まります。
ルール強制テンプレートと組み合わせると、「このプロジェクトでの作法」と「いま残っている仕事」を同時に渡せるので、Hook が単なる自動実行ではなく、作業の入口そのものになります。

GitHub CLI のクイック スタート - GitHub ドキュメント

docs.github.com

自動化シナリオの設計方法

設計フレーム

Claude CodeのHooksを長く運用するなら、その場で思いついたコマンドを足していくより、ひとつのシナリオとして設計したほうが崩れません。
考え方はRPAやMAのシナリオ設計とほぼ同じで、起点があり、条件があり、実行があり、その結果に応じて次の処理が分かれます。
開発者向けのローカル自動化であっても、設計単位で見ると分離しておくのが基本です。
具体的には「いつ始まるか」「何を見て判断するか」「何を実行するか」「失敗したらどう扱うか」を分けます。
SalesforceのMAシナリオ解説でも、顧客行動を起点に条件とアクションを積み重ねる構造が中心になっていますが、Hook でもその発想をそのまま持ち込めます（『MAのシナリオ設計とは？作り方のポイントと事例・雛形』）。

実務では、まずトリガーを決めます。
たとえばセッション開始時に文脈注入をするのか、コマンド実行前に危険操作を止めるのか、編集後に整形や検証を走らせるのかで、同じコマンドでも置き場所が変わります。
次に条件です。
対象ファイルが存在するか、OS が macOS か Linux か、gh や prettier が入っているか、特定ディレクトリ配下だけに限定するかといった判定を先に書きます。
そのうえでアクションを置きます。
実行コマンドは npx prettier --write .、npx eslint --fix ./、ruff check --fix、black .、gh issue list のように具体化できますが、実行の前に条件が並んでいるだけで副作用の範囲を絞れます。

私自身、運用を見直したときに「条件分岐を先に書く」形へ揃えてから、Hook が余計な場面で暴れることが減りました。
とくに依存コマンドの有無を最初に見るだけで、未導入の端末で処理全体が止まる事故が減り、保守の手間が軽くなりました。
command -v gh >/dev/null 2>&1 や command -v notify-send >/dev/null 2>&1 のような一行は地味ですが、後から効いてきます。

その次に分岐を設計します。
分岐は成功か失敗かだけでは足りません。
ユーザー選択で通知だけ出すのか、自動修正まで進むのか、あるいは危険コマンドをブロックして終了するのかまで書き分けます。
たとえば整形系の Hook なら、成功時は静かに通過、失敗時は終了コードを返してメッセージを出す、依存コマンドがなければスキップして警告だけ残す、という3分岐のほうが運用に乗ります。
RPA の設計書でも、正常フローだけを描くと現場で止まりやすく、条件分岐と例外の明示がないと保守側が読めません。
Hook も同じで、短いシェルでも「フロー図が頭に浮かぶ状態」にしておくと再利用できます。

例外処理も最初から部品として入れておくと安定します。
失敗したら即終了だけでなく、リトライするのか、スキップするのか、通知だけ飛ばすのか、ロールバックするのかを先に決めます。
たとえば通知であれば、macOS では osascript、Linux では notify-send、Windows ではBurntToastや PowerShell のトースト通知 API といった実装に分かれます。
どれか一つが無ければ何も起きないという設計より、通知不能なら標準出力に落とす設計のほうが扱いやすい場面が多くあります。
シナリオの主目的が「作業を止めること」なのか「補助情報を出すこと」なのかで、失敗時の扱いは変えるべきです。

高頻度で発火する Hook では、負荷の見積もりも設計項目です。
保存や編集のたびに走る整形・検証は、単発では短く見えても、積み重なると作業テンポに影響します。
BizRobo!系の RPA 現場では、実処理量の2〜3倍を丸1日流して耐久を見る考え方が知られていますが、Hook でも発想は同じです。
開発中によく起きるイベント頻度を想定し、その倍の回数で連続実行したときにログが詰まらないか、テンポが崩れないか、同じファイルを何度も触っても結果が壊れないかを見ると、場当たり設定から一段上がれます。

テストと例外設計

Hook の設計で抜けやすいのは、動くかどうかだけ見て終わることです。
実際には、正常系より再実行や失敗系のほうが運用では効きます。
テスト観点は最低でも、1回だけの正常実行、連続実行、失敗時の終了コード、依存コマンド未導入時の動作、ログ粒度の5つに分けて考えると抜けが減ります。

正常系では、狙ったトリガーで一度だけ走り、期待したアクションが実行され、成功判定が取れるかを確認します。
整形 Hook なら対象ファイルが整形されるか、検証 Hook なら eslint や ruff check が通るか、通知 Hook なら指定の文言が表示されるかです。
この段階で見たいのは「動いた」ではなく、「成功を何で判定するか」です。
終了コードが 0 なのか、標準出力に特定文字列を出すのか、生成ファイルの有無で見るのかを先に決めておくと、後の分岐が書きやすくなります。

連続実行では、再入可能性を見ます。
同じ Hook が短時間に連続して発火したとき、二重通知にならないか、整形済みファイルに再度整形をかけても不要差分が出ないか、一時ファイルが積み上がらないかを見ます。
たとえば『Prettier』の --write やBlackのフォーマットは、整形後に再実行しても結果が安定する設計なので、この性質を前提に Hook に組み込みやすい部類です。
逆に、ログへ追記するタイプのアクションや外部 API を叩く処理は、同じイベントが重なると影響が見えやすいので、重複実行の抑制が必要になることがあります。

失敗系では、終了コードが 0 以外のときに何を返すかを確認します。
ここを曖昧にすると、失敗しているのに次工程へ進んだり、単なる補助 Hook が全体を止めたりします。
整形や lint のように品質ゲートとして使うものは停止寄り、通知や文脈注入のように補助として使うものはスキップ寄り、という線引きが妥当です。
RPA でも MA でも、例外を「業務停止級」と「記録だけ残して継続」に分けて扱いますが、Hook でも同じ整理で迷いが減ります。

依存コマンド未導入時の動きも、最初から仕様にしておくと強いです。
たとえば gh が無ければ Issue 一覧は出さない、notify-send が無ければ標準出力へメッセージを出す、prettier が無ければ echo "prettier not found" で警告して抜ける、という形です。
ここを例外扱いにするのか、通常分岐として扱うのかで設計の読みやすさが変わります。
私の手元では、未導入を「異常」とみなすより「条件不成立」と置いたほうが、後から読む人が意図を掴みやすくなりました。

ログ出力の粒度にも目を向けたいところです。
普段は静かに通過し、失敗時だけ理由を出すのか、毎回「何を判定して何をスキップしたか」まで出すのかで、使い勝手が変わります。
日常運用では冗長なログは邪魔になりがちですが、設計直後の立ち上げ期は判定理由が見えたほうが詰まりを潰せます。
そこで、通常時は最小限、失敗時は原因がわかる行を残す、という二層構成にすると収まりがいいです。
たとえば「gh が無いため issue 一覧はスキップしました」の一行があるだけで、無言停止との区別がつきます。

設計テンプレ（表）を埋める

Hook を再利用可能な形にするなら、頭の中だけで設計せず、表に落とすのが有効です。
RPA のシナリオ設計書でも、ステップ分解と例外欄を明示しただけで保守性が上がります。
Hook でも列を固定すると、思いつき実装から抜け出せます。
最低限ほしい列は、トリガー、条件、アクション、成功判定、失敗時、ロールバック、ログ・通知、備考です。

この表を埋めると、どこに条件分岐を置くか、例外処理を停止にするか継続にするか、ログを誰向けに出すかが自然に見えてきます。
通知、整形、検証のような代表的な用途でも、トリガーと失敗時の扱いは同じではありません。
そこを揃えずに設定だけ増やすと、あとから Hook 同士が干渉します。
反対に、表の列を毎回固定しておけば、別の自動化にも横展開できます。
WebhookでもRPAでもMAでも、WHEN・IF・THEN に例外と記録を加えた設計が土台になりますが、Claude Codeの Hook はその考え方をシェルレベルまで小さくしたものだと捉えると、設計の軸がぶれません。

Hooks と Webhook / RPA / MA シナリオの違い

比較表：Hooks / Webhook / RPA / MA

名前が似ていても、起点と動く場所が違います。
Claude CodeのHooksはローカルの CLI 作業に割り込ませる自動化で、Webhookは外部サービスから HTTP で飛んでくる通知です。
RPAは業務手順そのものをロボット化する発想で、MAシナリオは顧客行動を起点に施策を流す設計です。
Atlassianの Jira Automation でよく見る WHEN / IF / THEN や、Microsoftの Azure Automation で Webhook から Runbook を起動する構成を見ると、似た言葉でも担当範囲がまったく違うことが見えてきます。
Claude Code 。

ここで混同しやすいのが、HooksとWebhookの名前の近さです。
Hooksは「Claude の中で起きたイベントに対して、手元のマシンで何を実行するか」を決める仕組みです。
一方でWebhookは「外のサービスで起きたイベントを、HTTP でどこに送るか」を決めます。
たとえば Jira Automation なら、WHEN で課題更新を検知し、IF で条件を絞り、THEN で Webhook を送る、という流れになります。
Azure Automation の Webhook はその通知を受けて Runbook を起動する役です。
つまり Webhook は外部起動の入口で、Hooks はローカル作業の差し込み口です。

実務では、まず Hooks でローカル開発の摩擦を減らし、外部連携が必要になったら Webhook や RPA を組み合わせる流れにすると設計が散らかりません。
最初から外部オーケストレーションまで広げると、通知ひとつ入れたいだけでも構成が重くなります。
反対に、手元の整形や通知を全部 Webhook 的に考えると、ローカルで完結する処理まで遠回りになります。

補足として、React Hooksは別物です。
Reactでは state や effect を扱う UI 開発用 API を Hooks と呼びますが、これはClaude Codeの自動化機能とは分類が違います。
Reactの Hooks は React 16.8 で導入された仕組みで、この記事で扱っている「CLI イベントにコマンドを差し込む Hook」とは目的も実行場所も一致しません。
名前だけで同じ箱に入れないほうが理解が早まります。

どれをいつ使うか

最短で 1 つ設定するなら、Claude Code側で /hooks を開き、まずは Notification hook を 1 本だけ足すのがいちばん手堅いです。
通知は副作用が小さく、整形やブロック系より失敗時の影響範囲も狭いからです。
設定画面で Hook を追加し、イベントに通知したいタイミングを選び、実行コマンドに OS ごとの通知コマンドを入れます。
macOS なら osascript -e 'display notification \"Claude Code task finished\" with title \"Claude Code\"'、Linux なら notify-send \"Claude Code\" \"Claude Code task finished\"。
Windows ではBurntToastの New-BurntToastNotification を使う流れがありますが、最初の 1 本は macOS か Linux の標準系コマンドのほうが詰まりにくい設計です。

設定を保存すると、選んだイベントが発火したタイミングでそのコマンドが実行されます。
たとえば処理完了やセッション節目に紐づけていれば、ターミナルを見ていない間でもデスクトップ通知が上がります。
確認場所は二つあります。
ひとつは OS の通知センターで、実際に通知が出たかを見る場所です。
もうひとつはClaude Code側の Hook 実行結果で、コマンドが通ったか、終了コードがどうだったかを追えます。
通知が出ないのに Hook 自体は走っている、という切り分けがここでできます。

このあと何を選ぶかは、起点がどこにあるかで決めると迷いません。
ローカルでコード編集のたびに『Prettier』やESLintやRuffを回したいなら Hooks です。
GitHub の Issue 一覧を gh issue list で出すのも Hooks の守備範囲です。
外部サービスで発生したイベントを受けて別システムを動かすなら Webhook に寄ります。
請求書作成や基幹画面への転記のように、複数画面をまたぐ定型作業を置き換えるなら RPA の出番です。
メール配信やスコア条件で施策を分けるなら MA シナリオが中心になります。

判断に迷ったときは、「その自動化は手元のターミナルで完結するか」を先に見ます。
完結するなら Hooks、外から HTTP で起動されるなら Webhook、業務手順の置き換えなら RPA、顧客接点の分岐設計なら MA、という並びです。
こう切り分けると、最初の 1 本をどこに置くべきかが見えます。
今回の導入なら、/hooks から Notification hook を追加し、通知が出るところまで通すだけで十分に価値があります。
そこから整形、検証、外部連携へと段階的に広げるほうが、構成の意図を保ったまま育てられます。

失敗しやすいポイントとベストプラクティス

曖昧な判定とHookの相性

Hook を増やしていくと、最初にぶつかるのが「その処理は機械的に決め切れるか」という壁です。
ここで無理をすると、deterministic な Hook に人間の判断を押し込む形になり、運用が急に不安定になります。
たとえばファイル拡張子で対象を絞って『Prettier』やESLintを走らせる、危険語句に一致したら実行を止める、といった処理は条件が明確なので Hook と噛み合います。
反対に、「この変更は本当に危険か」「このコマンドは今の文脈なら許してよいか」のように意図や背景を読む必要がある判定は、固定ルールだけで扱うと誤検知か見逃しのどちらかに寄りやすくなります。

Claude Code Docsの英語版にある 『Automate workflows with hooks』 でも、Hook には deterministic なものだけでなく prompt-based / agent-based hook という考え方があります。
判断材料が文脈依存で、単純なパターンマッチでは足りない処理なら、最初から prompt-based / agent-based hook に寄せたほうが設計の筋が通ります。
禁止コマンドの完全遮断は deterministic に置きます。
例外承認や意図確認は prompt-based に逃がすという分担にすれば、ルールを増やしすぎて保守が困難になる事態を避けられます。

この線引きは、実際に運用してみると体感で見えてきます。
たとえば通知 Hook でも、「すべてのイベントで通知する」とするとすぐにノイズ疲れが出ます。
私の手元では、通知を増やしすぎた時点で通知センターを見る習慣そのものが薄れました。
そこで長時間処理だけに絞ると、通知が来たときの意味がはっきりし、作業の切り替えも自然になりました。
Hook は入れられるから入れるのではなく、反応したときに利用者が次の行動を決められる粒度まで絞るほうが機能します。

曖昧さが残る処理では、例外ケースを最初から定義しておくのも効きます。
依存コマンド未導入、オフライン、権限不足のような場面で毎回失敗終了に倒すと、補助的な Hook が本体作業の邪魔になります。
この種のケースは「スキップ + 警告」に寄せると、止めるべき処理と流してよい処理の境目がはっきりします。
たとえば gh issue list のような文脈注入系や、osascript、notify-send による通知系は止めずに流す設計のほうが実務に馴染みます。

運用トラブルの回避策

失敗しやすいのは、便利そうな Hook を短期間で何本も足してしまうパターンです。
通知、整形、lint、ブロック、外部連携を同時に入れると、どこで遅くなったのか、どの Hook が差分を作ったのか、どの条件で止まったのかが見えなくなります。
RPA の設計で例外処理と負荷テストを先に考えるのと同じで、Hook も「正常時に何を出し、失敗時に何を残し、スキップ時にどう見せるか」を揃えておかないと、後から追えません。

ログは成功、失敗、スキップの 3 種が判別できる形に統一しておくと、トラブル時の切り分けが速くなります。
標準出力や標準エラーに出すプレフィックスを固定しておけば、後で集計するときも扱いやすくなります。
たとえば [hook:notify][skip]、[hook:format][ok]、[hook:guard][fail] のように揃えるだけでも、無言で終わったのか、意図的に飛ばしたのか、実際に落ちたのかが混ざりません。
Hook の本数が増えるほど、この整列が効いてきます。

ブロック系 Hook には、誤検知したときの逃げ道も必要です。
危険コマンド検知で一時的に作業を進めたい場面は現実にあります。
そのとき環境変数やフラグで一時バイパスできる設計にしておくと、緊急対応で設定ファイルを書き換えるような荒い回避をせずに済みます。
ただし、ここは監査ログを必ず残す前提です。
誰が、どの条件で、何を迂回したかが追えないバイパスは、ルールより先に信頼を壊します。

ブロック系は、本番に入れる前のテスト方法でも差が出ます。
私が効果を感じたのは、「本当に止まるか」と「誤検知で止まらないか」をペアで試すやり方でした。
禁止したい文字列を含むコマンドで確実に止まり、近いが問題ないコマンドでは通る、という両面を揃えて見ないと、実運用で片側だけ破綻します。
止めるテストだけでは安心材料が半分しかなく、通すテストだけでも同じです。
ブロック Hook は通行止めの看板ではなくゲートなので、閉まる場面と開く場面の両方を確認しておくと事故が減ります。

段階導入の進め方

導入順にも定石があります。
いきなりブロックや複雑な分岐から始めるより、影響範囲の狭いイベントから積み上げたほうが、Hook の挙動とチームの相性を見極めやすくなります。
最初の一歩は通知、その次に整形、そのあとで検証やルール強制という順番が収まりやすいのが利点です。
通知は副作用が小さく、整形は結果が目で追え、検証やブロックは作業を止めるだけの根拠が必要になるからです。

段階導入では、対象も絞ったほうがよいです。
たとえば整形なら最初からリポジトリ全体にかけるのではなく、.js や .ts に対する『Prettier』、Python ファイルに対するRuffやBlackのように範囲を明示すると、差分の出方が読めます。
Ruffは一括整形で待ち時間が短く、数千ファイル規模では体感差がそのまま作業テンポに出るので、Python 側の導入ではこの軽さが利点になります。
一方で、整形ルールの切り替えを複数ツールで同時に進めると、差分の責任範囲が曖昧になります。
導入時は「どのイベントで」「どのファイルに」「どのツールを」走らせるかを固定したほうが混乱が少なくなります。

段階導入では、対象も絞ったほうがよいです。
たとえば整形は最初からリポジトリ全体にかけるのではなく、.js や .ts に対する『Prettier』、Python ファイルに対するRuffやBlackのように範囲を明示すると、差分の出方が読めます。

この順番で育てると、「便利そうだから追加した Hook」が減り、「作業のどこを整えたいか」から逆算した Hook だけが残ります。
結果として、過剰自動化で速度が落ちる、誰も設定を触れない、誤検知で作業が止まる、といった典型的な失敗を避けやすくなります。
導入の速さより、1 本ごとに挙動を説明できる状態を保つことが、保守不能な Hook 群を作らない近道です。

テンプレートを自分用にカスタマイズするチェックリスト

チェックリスト

テンプレートをそのまま置くだけでは、別のプロジェクトで意図どおりに動かないことがあります。
移植時に見るべきポイントは、Hook がどのイベントで走るか、成功をどう判定するか、失敗したときに止めるのか流すのか、そしてチーム全体で同じ前提を共有できるかです。
ここが曖昧なまま本数だけ増やすと、便利な自動化ではなく、理由の見えない副作用の集まりになります。
Claude Code Docsの 『hooks でワークフローを自動化する』 に沿って考えると、Hook はイベント起点の小さな自動化として扱うのが筋がよく、1 本ごとに責務を言葉で説明できる状態を保てます。

自分用に調整するときは、まず対象イベントを決めます。
通知ならセッション開始時、整形や lint なら編集後、危険コマンドの遮断なら実行前というように、起点と処理内容を一致させます。
ここがずれると、たとえば『Prettier』やESLintが想定外のタイミングで走って差分を増やしたり、ブロック系 Hook が遅すぎて止める意味を失ったりします。
『gh』で未処理 Issue を並べる文脈注入は開始時に置くと自然ですが、保存のたびに走らせるとノイズになります。
イベント選定は便利さではなく、作業の流れにどこで差し込むと副作用が最小になるかで決めるとまとまります。

期待結果も先に固定しておくとぶれません。
成功時に通知が 1 回出ればよいのか、差分がなくなるまで整形されればよいのか、[hook:format][ok] のようなログが 1 行残れば十分なのかを定義します。
整形系なら再実行して差分が出ない状態、通知系なら終了コードが 0 で標準出力にも実行方法が残る状態、文脈注入系なら一覧取得に成功して処理全体は止めない状態、といった具合です。
『Prettier』なら npx prettier --write .、ESLintなら npx eslint --ext .js,.jsx,.ts,.tsx --fix ./ のようにコマンド自体は明快なので、成功条件を「何が起きたら完了とみなすか」に寄せて書いておくとレビューでも迷いません。

失敗時の動作は、中断・スキップ・警告のみの三択に寄せて整理すると運用が安定します。
危険コマンドの検知は中断、通知や Issue 表示はスキップ、補助情報の取得失敗は警告だけ、という切り分けです。
加えて、終了コードの意味も決めておくと後で追いやすくなります。
たとえば 0 は成功、1 は処理を止める失敗、2 は依存コマンド未導入なので意図的にスキップ、といった割り当てです。
終了コードの方針がないと、未導入なのに失敗扱いになって作業全体が止まり、導入初期の反発を招きます。

依存コマンドの有無は、毎回インストール前提で書かないほうが破綻しません。
command -v gh、command -v notify-send、command -v osascript のような存在確認を先に入れ、未導入ならスキップしてログだけ残す構成にすると、導入途中のチームでも止まりません。
なお、Ruff の高速性については開発者側のベンチマークで大きな差が報告されています（開発者ベンチマークで >30x の主張がある例）。
ただし実際の差はファイル数や環境、I/O、ツールのオプション等で変動します。
移行前には自分のプロジェクトでベンチマークや差分確認を行うことを推奨します。

権限とセキュリティは、テンプレートで最も個性が出るところです。
明確な禁止パターンだけでなく、ワイルドカード付き削除や強制 push、環境変数上書きなども列挙し、例外許可の条件と監査ログの要件も合わせて定義しておくと運用が安定します。

ロギングは、標準出力だけで足りるのか、ファイルにも残すのか、外部収集に送るのかを分けて考えると整理できます。
ローカル作業の補助なら標準出力に 1 行、ブロック系や例外バイパスはファイルにも残す、チームで監査したいものだけ外部収集対象にする、といった粒度が現実的です。
すべてを詳細ログにすると読まれなくなり、逆に何も残さないと再現できません。
再入可能性の確認もここに含めておくとよく、同じ Hook を連続発火させても差分が増えないか、短時間に複数回走っても壊れないか、誤検知のテストケースを再現できるかをテンプレート側に明文化すると、後から足した Hook も同じ基準で見られます。
なお、Ruff の高速性については開発者側のベンチマークで大きな差が報告されています（開発者ベンチマークで >30x とする例があります）。
ただし、この数値はファイル数、I/O、CPU、キャッシュ、ツールのバージョンや実行オプション等で大きく変動します。
Ruff に切り替える場合は、移行前に自分のプロジェクトでベンチマークと整形差分の確認を行うことを推奨します。

チェックリストは「設定項目の一覧」ではなく「運用時に揉める論点の一覧」にすると効きます。イベント、成功判定、失敗時の扱い、依存不足時の分岐、OS ごとの差分が埋まっていれば、テンプレートを別案件へ持っていっても崩れにくくなります。

チームへの展開と運用ルール

個人用に育てたテンプレートをチームへ広げるときは、保管場所と更新手順を先に決めておくと迷いません。
実運用では、共通ルールはリポジトリルートのCLAUDE.mdに置き、Hook の具体設定やサンプルコマンドは同じリポジトリ内で管理する形が収まりやすいのが利点です。
CLAUDE.mdは Claude がセッション開始時に参照する慣習があるので、どの Hook を採用し、どの OS で何を使い、未導入時にどう振る舞うかを書く場所として相性があります。
通知は macOS なら osascript、Linux なら notify-send、Windows ならBurntToastまたは PowerShell のトースト通知といった具合です。
整形は JavaScript 系なら『Prettier』、Python 系ならRuffまたはBlack、GitHub 連携は『gh』というように、採用ツール名まで明示しておくと認識が割れません。

更新手順も暗黙知にしないほうが運用が続きます。
新しい Hook を追加するときは、まず個人ブランチで単体テストを行い、連続発火時の安定性と再入可能性を確認し、その後に PR でチェックリストを埋める、という順番にするとレビューが流れ作業になりません。
とくに整形系は、導入時にベースブランチで一度差分を固めてから運用へ入れたほうが、機能変更と整形差分が混ざらず追いやすくなります。
Python でRuffへ切り替える場合も、互換性のズレをゼロとは扱わず、先に全体整形を固定してから Hook を有効にするほうが事故が少なくなります。

チーム展開では、誰が更新権限を持つかもルールに含めます。
全員が自由に Hook を足せる状態だと、似た用途の自動化が重複し、同じイベントに複数の整形や検証がぶら下がりがちです。
そこで、共通 Hook は少人数で管理し、個人用 Hook はローカル専用として切り分けると整理できます。
チーム共通に載せる条件は、対象イベントが明確であること、失敗時の扱いが定義されていること、未導入時に作業を止めないこと、ログの粒度が決まっていること、というように基準化すると判断しやすくなります。
ここでも PR テンプレートに同じ観点を含めておくと、レビュー速度が落ちません。

運用ルールとしては、ログの置き場と見方も揃えておくと効きます。
普段は標準出力の短いメッセージだけにして、ブロックやバイパスが絡む処理だけはファイルへ残す、と決めておくと、日常のノイズを抑えながら必要なときだけ掘れます。
外部収集まで持っていくのは、監査が必要なコマンドブロックや例外許可の記録に限定したほうが現実的です。
日々の通知や整形ログまで集めると、重要な失敗が埋もれます。

検証ルールも文書化しておくと、Hook が増えても破綻しません。
見るポイントは、同じ入力に対して毎回同じ結果になるか、短時間に連続で発火しても二重実行や差分の増殖が起きないか、誤検知ケースを再現テストとして残せるかです。
これは RPA のシナリオ設計で例外系を先に洗うのと似ていて、RPAのシナリオとは？作成手順や簡単な作り方のコツを具体例を交えて解説 のような設計論でも、条件分岐と例外処理を先に詰める発想が基本になっています。
Hook も同じで、正常系の動作確認だけでは運用で足りません。
止める、流す、スキップする、その三つが想定どおりに出るかまで見ておくと、テンプレートがプロジェクト固有の道具として定着します。

まとめと次のアクション

本記事の要点

Claude CodeのHooksは、決まったイベントを起点にローカルの開発フローへ自動処理を差し込める点が強みです。
まず効くのは、作業の区切りを知らせる通知、保存後の整形、実行前の検証やブロックの3系統でした。
実際に通知から整形まで入れると、手作業のうっかりが目に見えて減り、レビュー前の整形忘れも消えました。
ローカルの開発摩擦を減らすならHooks、SaaS連携ならWebhook、業務全体の自動化ならRPAやMAという切り分けで考えると迷いません。

次にやること（補足）