Claude Code: Hooks システム
最終更新:2026-08-31
Hooks により、Claude Code の主要なポイントにカスタムロジックを挿入できます — 修正前の自動バックアップ、コミット前の自動テスト、エラー時の自動ロールバック。
💡 ヒント: Hooks は Claude Code のライフサイクルにおける「インターセプター」です — 特定のイベント発生時にカスタムスクリプトを実行し、自動化ワークフローを実装します。
📋 前提条件: 第17章 - 出力スタイル
1. 学ぶ内容
- フックのライフサイクルとイベントタイプ
- 内蔵およびカスタムフック
- フックの設定方法
- 実践的シナリオ
- フックのデバッグとトラブルシューティング
2. フックのライフサイクル
(1) イベントタイプ
| イベント | トリガーのタイミング | 一般的な用途 |
|---|---|---|
| before:prompt | ユーザー入力の処理前 | 入力の前処理 |
| before:tool:write | ファイル書き込み前 | 自動バックアップ |
| after:tool:write | ファイル書き込み後 | 自動フォーマット |
| before:tool:bash | コマンド実行前 | セキュリティチェック |
| after:tool:bash | コマンド実行後 | 結果の後処理 |
| after:response | レスポンス生成後 | 通知の送信 |
(2) フックコンテキスト
各フックはイベント名、タイムスタンプ、ファイルパス、コマンド、コンテンツ、セッション ID を含むコンテキストオブジェクトを受け取ります。
▶ 例1:フックトリガーフロー
TEXT
📖 参照専用
> Modify src/auth/jwt.ts
トリガーされたフック:
1. [before:tool:write] → jwt.ts を自動バックアップ
2. [ファイル書き込み完了]
3. [after:tool:write] → ESLint --fix を実行
4. [before:tool:bash] → コマンドの安全性をチェック
5. [実行: npm test]
6. [after:tool:bash] → テスト結果を解析
7. [after:response] → Slack 通知を送信
3. フックの設定
(1) グローバルフック設定
JSON
// ~/.claude/hooks.json
{
"hooks": {
"before:tool:write": [
{
"name": "auto-backup",
"command": "cp ${filePath} ${filePath}.bak",
"enabled": true
}
],
"after:tool:write": [
{
"name": "auto-format",
"command": "npx prettier --write ${filePath}",
"enabled": true
}
]
}
}
(2) プロジェクトレベルのフック
JSON
// .claude/hooks.json
{
"hooks": {
"before:tool:write": [
{
"name": "protect-config",
"condition": "filePath.endsWith('.env')",
"command": "echo 'Config file modification blocked' && exit 1",
"enabled": true
}
]
}
}
4. 実践的シナリオ
▶ 例2:自動バックアップフック
JSON
{
"hooks": {
"before:tool:write": [
{
"name": "git-backup",
"command": "git stash push -m 'auto-backup-before-claude' -- ${filePath} 2>/dev/null || true",
"enabled": true
}
]
}
}
▶ 例3:セキュリティ監査フック
JSON
{
"hooks": {
"before:tool:bash": [
{
"name": "block-dangerous-commands",
"condition": "command.includes('rm -rf') || command.includes('DROP TABLE')",
"command": "echo '⚠️ Dangerous command blocked' && exit 1",
"enabled": true
}
]
}
}
▶ 例4:自動テストフック
JSON
{
"hooks": {
"after:tool:write": [
{
"name": "auto-test",
"condition": "filePath.includes('src/') && filePath.endsWith('.ts')",
"command": "npm test 2>&1 | tail -5",
"enabled": true
}
]
}
}
5. フックのデバッグ
BASH
# フックデバッグを有効化
export CLAUDE_HOOK_DEBUG=1
# フック実行ログを確認
cat ~/.claude/hooks.log
# すべてのフックを一時的に無効化
claude --no-hooks
よくある問題
| 問題 | 原因 | 解決策 |
|---|---|---|
| フックがトリガーされない | enabled: false | 設定を確認 |
| フックエラー | コマンドのパス問題 | 絶対パスを使用 |
| フックが遅い | スクリプトの実行時間 | 非同期化またはロジックを簡素化 |
| ループトリガー | フックが別のフックをトリガー | 条件を追加して回避 |
6. 総合例:完全なフックソリューション
JSON
{
"hooks": {
"before:tool:write": [
{
"name": "auto-backup",
"command": "cp ${filePath} /tmp/claude-backup/$(basename ${filePath}).$(date +%s)",
"enabled": true
},
{
"name": "protect-env",
"condition": "filePath.endsWith('.env')",
"command": "echo '❌ Env file modification blocked' && exit 1",
"enabled": true
}
],
"after:tool:write": [
{
"name": "format",
"command": "npx prettier --write ${filePath} 2>/dev/null; npx eslint --fix ${filePath} 2>/dev/null; true",
"enabled": true,
"files": ["src/**/*.ts"]
}
],
"before:tool:bash": [
{
"name": "block-dangerous",
"condition": "command.match(/rm -rf|DROP|npm publish/)",
"command": "echo '⛔ Dangerous command blocked' && exit 1",
"enabled": true
}
]
}
}
❓ よくある質問
Q フックは Claude Code を遅くしますか?
A はい。各フックはコマンドを実行します。遅いフックは体験に明らかな影響を与えます。フックスクリプトは1秒以内に保ってください。
Q フックの失敗は操作をブロックしますか?
A 失敗した before フック(exit 1)は操作をブロックします。after フックの失敗は完了済みの操作に影響しません。
Q フックは Claude Code の出力を変更できますか?
A いいえ。フックは副作用(バックアップ、フォーマット、通知)のみを実行し、返される内容は変更しません。
Q フックと Plugin の違いは?
A フックは軽量なイベントレスポンス(コマンド実行)です。プラグインは完全な機能拡張(ツールの登録、動作の変更)です。シンプルなニーズにはフック、複雑なニーズにはプラグイン。
📖 まとめ
- フックは Claude Code のライフサイクルの主要ポイントでカスタムロジックをトリガー
- コアイベント:before/after:tool:write/read/bash
- 自動バックアップ、セキュリティ監査、自動フォーマットが最も一般的なシナリオ
- before フックの失敗は操作をブロック、after フックの失敗はブロックしない
- フックは高速に保つ(1秒以内)
📝 練習問題
- 基本 (⭐): after:tool:write フックを設定し、ファイル修正時に Prettier を自動実行させてください。
- 応用 (⭐⭐):
rm -rfとnpm publishをブロックするセキュリティフックを設定してください。 - 高度 (⭐⭐⭐): バックアップ、フォーマット、セキュリティチェック、通知をカバーする完全なフックソリューションを設計してください。