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 フックは軽量なイベントレスポンス(コマンド実行)です。プラグインは完全な機能拡張(ツールの登録、動作の変更)です。シンプルなニーズにはフック、複雑なニーズにはプラグイン。

📖 まとめ


📝 練習問題

  1. 基本 (⭐): after:tool:write フックを設定し、ファイル修正時に Prettier を自動実行させてください。
  2. 応用 (⭐⭐): rm -rfnpm publish をブロックするセキュリティフックを設定してください。
  3. 高度 (⭐⭐⭐): バックアップ、フォーマット、セキュリティチェック、通知をカバーする完全なフックソリューションを設計してください。
Web-Tutorial.com

Web-Tutorial 技術チーム

複数の開発者によって共同維持されているプログラミングチュートリアルプラットフォーム。各チュートリアルは専門分野の開発者が執筆・レビューしています。正確で信頼性の高いコンテンツを目指しています — 問題を見つけた場合はお知らせください。

100%