株式会社BlueAI 代表取締役CEO / ソフトウェアエンジニア / プロダクトエンジニア / Google Cloud Architect / 元AIスタートアップ(Doorkel)
Claude Code Hooks の使い方｜イベント駆動でワークフローを自動化する
「Claude Code がファイルを保存したあとに自動で lint をかけたい」「危険なコマンドを実行する前にブロックしたい」「タスク完了時に Slack に通知を飛ばしたい」――こうした要望に応えるのが Claude Code Hooks です。
Claude Code Hooks は、Claude Code の動作中に発生する特定のイベントにフックして、任意のシェルコマンドを自動実行する仕組みです。ファイル保存後のフォーマット、コミット前のテスト実行、危険な操作のブロックなど、開発ワークフローの自動化を Claude Code のレベルで実現できます。
本記事では、Hooks の基本概念からトリガーイベントの種類、設定方法、実用的なユースケース、そしてセキュリティ上の注意点までを網羅的に解説します。この記事を読み終えるころには、自分のプロジェクトに最適な Hooks を設計・運用できるようになっているはずです。
Claude Code の基本的な設定方法については、以下の記事を参考にしてください。
Hooks とは何か
Hooks は、Claude Code のイベント駆動型の拡張機能です。Claude Code が特定のアクションを実行する「前」や「後」に、あらかじめ定義しておいたシェルコマンドを自動で実行します。
たとえば、Claude Code がファイルを書き込んだ直後に prettier を走らせたり、rm コマンドを実行しようとしたときにブロックしたりといったことが可能です。これにより、人間が手動で行っていた確認作業やフォーマット作業を自動化し、ミスを防げます。
Hooks の主な特徴は以下の通りです。
- イベント駆動: Claude Code の特定のアクションに連動して自動実行される
- シェルコマンドベース: 実行するのは通常のシェルコマンドなので、既存のツールチェーンをそのまま活用できる
- 条件付き実行: ツール名やファイルパターンに基づいて、実行条件を細かく制御できる
- ブロッキング対応: 特定の操作を中断・禁止することも可能
Skills がタスクに対する「手順書」だとすれば、Hooks は「自動監視システム」です。Skills はユーザーが明示的に呼び出しますが、Hooks は条件が揃えば自動的に発火します。
トリガーイベントの種類
Claude Code Hooks では、以下のイベントをトリガーとして利用できます。それぞれのイベントがどのタイミングで発火するかを理解することが、効果的な Hooks 設計の第一歩です。
PreToolUse
ツールが実行される直前に発火するイベントです。ツールの実行を事前にチェックし、必要に応じてブロックできます。
主な用途は以下の通りです。
- 危険なコマンドの実行を防止する
- 特定のファイルへの書き込みを制限する
- 実行前にログを記録する
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"command": "bash /path/to/check-dangerous-commands.sh"
}
]
}
}
PreToolUse のフックコマンドがゼロ以外の終了コードを返すと、そのツールの実行はブロックされます。これにより「ホワイトリスト方式」や「ブラックリスト方式」のアクセス制御が実現できます。
PostToolUse
ツールが実行された直後に発火するイベントです。ツールの実行結果を受けて後処理を行う場合に使います。
主な用途は以下の通りです。
- ファイル保存後に lint/format を自動実行する
- テスト結果をログに記録する
- 変更内容を外部システムに通知する
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "npx prettier --write $CLAUDE_FILE_PATH"
}
]
}
}
PostToolUse は最も使用頻度が高いトリガーです。ファイルの書き込みや編集のあとに自動でフォーマットをかけるパターンは、ほぼすべてのプロジェクトで役立ちます。
Notification
Claude Code がユーザーへの通知を発行するタイミングで発火します。長時間のタスクが完了したときや、ユーザーの入力を待っているときなどに利用できます。
{
"hooks": {
"Notification": [
{
"command": "bash /path/to/send-slack-notification.sh"
}
]
}
}
Notification フックは、リモートで Claude Code を動かしている場合や、バックグラウンドタスクの完了を検知したい場合に特に便利です。
Stop
Claude Code がタスクを完了して停止するタイミングで発火するイベントです。
{
"hooks": {
"Stop": [
{
"command": "bash /path/to/on-task-complete.sh"
}
]
}
}
Stop フックは、タスクの最終結果を外部に連携したり、後片付けの処理を行ったりする用途に適しています。CI/CD パイプラインとの連携や、ログの集約などに活用できます。
SubAgentStop
サブエージェントがタスクを完了したタイミングで発火します。Claude Code がサブエージェントを使って並列処理を行う場合に、個々のサブタスクの完了をキャッチできます。
設定方法
Hooks は .claude/settings.json に定義します。プロジェクトルートの設定ファイルに書くことで、チーム全体で同じ Hooks を共有できます。
基本的な設定構造
{
"hooks": {
"PreToolUse": [
{
"matcher": "ツール名のパターン",
"command": "実行するシェルコマンド"
}
],
"PostToolUse": [
{
"matcher": "ツール名のパターン",
"command": "実行するシェルコマンド"
}
],
"Notification": [
{
"command": "実行するシェルコマンド"
}
],
"Stop": [
{
"command": "実行するシェルコマンド"
}
]
}
}
Hook の構成要素
各 Hook は以下の 2 つの要素で構成されます。
matcher（マッチャー）
実行条件を指定するパターンです。ツール名に対する正規表現パターンで、対象となるツールを絞り込みます。
"Bash"— Bash ツールのみにマッチ"Write|Edit"— Write または Edit ツールにマッチ".*"— すべてのツールにマッチ- 省略した場合 — すべてのイベントにマッチ（Notification, Stop など）
command（コマンド）
イベント発火時に実行するシェルコマンドです。通常のシェルスクリプトと同じように記述します。
コマンド内では、以下の環境変数が利用できます。
| 環境変数 | 説明 |
|---|---|
$CLAUDE_TOOL_NAME | 実行されるツールの名前 |
$CLAUDE_TOOL_INPUT | ツールへの入力（JSON 文字列） |
$CLAUDE_FILE_PATH | 対象ファイルのパス（該当する場合） |
$CLAUDE_SESSION_ID | 現在のセッション ID |
設定ファイルの配置場所
Hooks の設定はスコープに応じて異なるファイルに記述します。
| 配置場所 | スコープ | Git 管理 |
|---|---|---|
~/.claude/settings.json | 全プロジェクト共通 | しない |
.claude/settings.json | プロジェクト全体 | する |
個人的な Hooks（自分専用の通知設定など）はグローバルの設定ファイルに、チームで共有すべき Hooks（lint/format の自動実行など）はプロジェクトの設定ファイルに書くのがベストプラクティスです。
実用的なユースケース
ここからは、実際の開発現場で役立つ Hooks の具体例を紹介します。
1. ファイル保存後に自動 lint/format
最も基本的かつ効果の高いユースケースです。Claude Code がファイルを書き込んだり編集したりしたあとに、自動でフォーマッターを実行します。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}
]
}
}
ポイントは 2>/dev/null || true で、フォーマッターが対象外のファイル（画像ファイルなど）に対して実行された場合にエラーで Hook チェーン全体が止まるのを防いでいます。
ESLint と組み合わせる場合は、以下のように設定します。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null; npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null; exit 0"
}
]
}
}
2. git commit 前の自動テスト実行
Claude Code が git commit を実行しようとしたときに、事前にテストを走らせて失敗時にはコミットをブロックします。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"command": "bash -c 'INPUT=$(echo $CLAUDE_TOOL_INPUT | jq -r .command 2>/dev/null); if echo \"$INPUT\" | grep -q \"git commit\"; then npm test || exit 1; fi'"
}
]
}
}
この Hook は、CLAUDE_TOOL_INPUT の内容を解析して git commit が含まれている場合にのみテストを実行します。テストが失敗すると終了コード 1 が返され、コミットがブロックされます。
3. 特定ファイル変更時のビルド自動実行
設定ファイルやスキーマファイルなど、変更時にビルドの再実行が必要なファイルを監視します。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "bash -c 'if echo \"$CLAUDE_FILE_PATH\" | grep -qE \"\\.(proto|graphql|sql)$\"; then make generate; fi'"
}
]
}
}
OpenAPI スキーマや Protocol Buffers の定義ファイルが変更されたときにコード生成を自動実行するなど、プロジェクト固有のビルドパイプラインを Hook に組み込めます。
4. 危険な操作の自動ブロック
rm -rf やデータベースの DROP 文など、取り返しのつかない操作を事前にブロックします。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"command": "bash -c 'INPUT=$(echo $CLAUDE_TOOL_INPUT | jq -r .command 2>/dev/null); if echo \"$INPUT\" | grep -qE \"rm\\s+-rf\\s+/|DROP\\s+TABLE|DROP\\s+DATABASE|truncate\\s+\"; then echo \"BLOCKED: Dangerous command detected\" >&2; exit 1; fi'"
}
]
}
}
このパターンは、CI 環境や本番に近い環境で Claude Code を使う場合に特に重要です。意図しないデータ削除や環境破壊を未然に防ぎます。
セキュリティ対策の詳細については、以下の記事も参照してください。
5. Slack/Teams への通知連携
Claude Code がタスクを完了したとき、またはユーザーの入力を待っているときに、外部のチャットツールに通知を送ります。
{
"hooks": {
"Notification": [
{
"command": "curl -s -X POST -H 'Content-Type: application/json' -d '{\"text\": \"Claude Code: タスクが完了しました\"}' $SLACK_WEBHOOK_URL"
}
]
}
}
より高度な通知を行う場合は、専用のスクリプトファイルを用意します。
#!/bin/bash
# .claude/hooks/notify-slack.sh
WEBHOOK_URL="${SLACK_WEBHOOK_URL}"
if [ -z "$WEBHOOK_URL" ]; then
exit 0
fi
MESSAGE="Claude Code notification: Session $CLAUDE_SESSION_ID"
curl -s -X POST \
-H 'Content-Type: application/json' \
-d "{\"text\": \"$MESSAGE\"}" \
"$WEBHOOK_URL"
通知スクリプトをファイルに分離することで、メンテナンス性が向上し、複雑なロジックも記述しやすくなります。
Hooks と Skills の違いと使い分け
Hooks と Skills はどちらも Claude Code の拡張機能ですが、その性質は大きく異なります。
| 特徴 | Hooks | Skills |
|---|---|---|
| 実行トリガー | 自動（イベント駆動） | 手動（スラッシュコマンド） |
| 定義場所 | settings.json | .claude/skills/*.md |
| 記述形式 | JSON + シェルコマンド | Markdown |
| 主な用途 | 自動化・ガードレール | タスクの手順書 |
| 実行タイミング | ツール実行の前後 | ユーザーが明示的に呼び出し |
使い分けの指針
- 「常に自動で実行してほしいこと」は Hooks — フォーマット、lint、危険操作のブロック
- 「必要なときに呼び出したいこと」は Skills — コードレビュー、デプロイ、コンポーネント生成
具体的には、以下のように分担するのが効果的です。
- Hooks で「書いたコードを常に整える」（PostToolUse でフォーマット）
- Skills で「レビューの手順を標準化する」（
/reviewで呼び出し） - Hooks で「危険操作を常に防ぐ」（PreToolUse でブロック）
- Skills で「デプロイ前チェックを実行する」（
/deployで呼び出し）
両者を組み合わせることで、Claude Code のワークフローを多層的に制御できます。Skills について詳しくは以下の記事を参照してください。
デバッグ方法とトラブルシューティング
Hooks がうまく動作しない場合の確認ポイントと対処法を紹介します。
Hook が発火しない場合
1. matcher パターンの確認
最も多い原因は、matcher のパターンが対象ツールにマッチしていないことです。ツール名は大文字小文字を区別するため、正確に記述する必要があります。
// NG: 小文字では一致しない
{ "matcher": "bash", "command": "..." }
// OK: ツール名は大文字始まり
{ "matcher": "Bash", "command": "..." }
2. 設定ファイルの JSON 構文エラー
settings.json に構文エラーがあると、Hooks 全体が読み込まれません。JSON バリデーターで構文を確認してください。
cat .claude/settings.json | jq .
3. コマンドのパスが解決できない
Hook のコマンドは Claude Code のワーキングディレクトリから実行されます。相対パスを使う場合は、プロジェクトルートからの相対パスになることに注意してください。絶対パスを使うのが確実です。
Hook がエラーで失敗する場合
1. 環境変数の確認
Hook コマンド内で参照する環境変数が正しくセットされているか確認します。デバッグ用に一時的にログ出力を追加すると原因を特定しやすくなります。
{
"matcher": "Write",
"command": "echo \"DEBUG: TOOL=$CLAUDE_TOOL_NAME FILE=$CLAUDE_FILE_PATH\" >> /tmp/claude-hooks.log"
}
2. コマンドの権限
外部スクリプトを実行する場合は、実行権限が付与されていることを確認してください。
chmod +x .claude/hooks/my-hook.sh
3. 終了コードの意図しない伝播
PostToolUse で実行するコマンドが非ゼロの終了コードを返すと、予期しない動作を引き起こす可能性があります。必要に応じて || true を付与してエラーを無視してください。
デバッグ用 Hook パターン
開発中は、すべてのイベントをログに出力する Hook を設定しておくと、動作の理解に役立ちます。
{
"hooks": {
"PreToolUse": [
{
"matcher": ".*",
"command": "echo \"[PRE] $(date '+%H:%M:%S') $CLAUDE_TOOL_NAME\" >> /tmp/claude-hooks.log"
}
],
"PostToolUse": [
{
"matcher": ".*",
"command": "echo \"[POST] $(date '+%H:%M:%S') $CLAUDE_TOOL_NAME\" >> /tmp/claude-hooks.log"
}
]
}
}
ログファイルを tail -f /tmp/claude-hooks.log で監視することで、Hook の発火タイミングをリアルタイムで確認できます。
セキュリティの注意点
Hooks は強力な機能である一方、誤った設定はセキュリティリスクを生むこともあります。以下の点に注意してください。
信頼できるコマンドのみを実行する
Hooks で実行するコマンドは、プロジェクトのコードと同等の権限で動作します。外部から取得したスクリプトを無検証で Hook に設定しないでください。
// NG: 外部 URL のスクリプトを直接実行
{ "command": "curl -s https://example.com/hook.sh | bash" }
// OK: プロジェクト内のバージョン管理されたスクリプト
{ "command": "bash .claude/hooks/verified-hook.sh" }
環境変数に機密情報を含めない
settings.json は Git で管理されるファイルです。Webhook URL や API キーなどの機密情報を直接書き込まないでください。環境変数から参照する形にします。
// NG: Webhook URL を直接記述
{ "command": "curl -X POST https://hooks.slack.com/services/xxx/yyy/zzz" }
// OK: 環境変数から参照
{ "command": "curl -X POST $SLACK_WEBHOOK_URL" }
PreToolUse でのブロックは慎重に
PreToolUse で過度に厳しいブロックルールを設定すると、Claude Code の正常な動作まで妨げてしまう可能性があります。まずはログ出力のみの Hook で動作を確認し、段階的にブロックルールを追加していくアプローチが安全です。
チーム共有時のレビュー
プロジェクトの .claude/settings.json に Hook を追加する場合は、通常のコードレビューと同様にチームメンバーのレビューを受けてください。Hook は開発者全員の環境に影響するため、意図しない副作用がないかを複数の目で確認することが重要です。
まとめ
本記事では、Claude Code Hooks の基本概念からトリガーイベントの種類、設定方法、実用的なユースケース、デバッグ手法、セキュリティの注意点までを解説しました。ポイントを振り返ります。
- Hooks はイベント駆動の拡張機能: ツール実行の前後や通知タイミングに自動でシェルコマンドを実行する
- 4 つのトリガーイベント: PreToolUse（実行前）、PostToolUse（実行後）、Notification（通知時）、Stop（完了時）を使い分ける
- matcher + command で構成: ツール名のパターンマッチと実行コマンドのシンプルな組み合わせ
- PreToolUse はガードレール: 危険な操作のブロックや事前チェックに活用する
- PostToolUse は自動化の要: ファイル保存後のフォーマットやビルドの自動実行に最適
- Skills との使い分け: 常時自動実行は Hooks、手動呼び出しは Skills
Hooks を適切に設定することで、Claude Code は「指示されたことを実行するツール」から「プロジェクトのルールに従って自律的に品質を保つパートナー」へと進化します。まずはファイル保存後の自動フォーマットなど、小さな Hook から導入を始めてみてください。
Hooks やスラッシュコマンドの設定方法をハンズオンで学びたい方は、以下のレッスンも参考にしてください。
