🪝

Claude Code Hooks で開発ワークフローの自動化

に公開
2026/01/25

はじめに

Claude Code を使っている開発者の皆さん、Hooks(フック)という機能をご存知でしょうか?

Hooks は、Claude Code のライフサイクルイベントに応じて、自動的にシェルコマンドやスクリプトを実行する機能です。コードの編集後に自動でフォーマットを実行したり、テスト結果に基づいて通知を送ったり、セキュリティチェックを自動化したりできます。

従来のプロンプト指示では難しかった「再現性の高い、決定論的な処理」を、コードベースで確実に実行できるのが大きな特徴です。

この記事では、以下の内容を解説します:

  • Claude Code Hooks の概要と仕組み
  • 設定方法(JSON ファイルとコマンドによる設定)
  • 実践的な活用例
  • ベストプラクティスとセキュリティ対策

Claude Code をより強力な開発ツールとして使いたい方は、ぜひ参考にしてください。

Claude Code Hooks とは?

Claude Code Hooks は、Claude Code における特定のライフサイクルイベントのタイミングで、あらかじめ指定したコマンドやスクリプトを自動実行する拡張機能です。

主な特徴

  • イベント駆動型: ツールの実行前後、セッション開始・終了時など、特定のタイミングで自動実行
  • 決定論的な制御: LLM の「判断」に依存せず、確実にコマンドを実行
  • 柔軟な設定: JSON 設定ファイルまたはコマンドで簡単に設定可能
  • 開発効率の向上: 手動作業を自動化し、作業漏れやミスを防止

Hooks のイベントタイプ

Claude Code Hooks は、様々なライフサイクルイベントに対応しています。

基本的なイベント

イベント 発火タイミング 主な用途
PreToolUse ツール実行前 権限制御、編集ブロック、事前検証
PostToolUse ツール実行後 自動フォーマット、テスト実行、ログ記録
Notification 通知送信時 外部サービスへの通知、カスタム通知
Stop セッション・応答終了時 クリーンアップ、レポート生成
SubagentStop サブエージェント終了時 並列プロセス管理、複数タスク管理

上級者向けイベント

  • UserPromptSubmit: ユーザーがプロンプトを送信した時
  • PreCompact: コンテキストの圧縮前
  • SessionStart: セッション開始時

設定方法

Hooks の設定方法は 2 つあります:JSON 設定ファイルとコマンドによる対話的な設定です。

方法 1: JSON 設定ファイル

プロジェクトルートに .claude/settings.json を作成します。

基本構造

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

設定項目の説明

  • EventName: イベントタイプ(PostToolUse、PreToolUse など)
  • matcher: 対象となるツール名のパターン(文字列、正規表現、ワイルドカード * に対応)
  • type: 実行タイプ(command でシェルコマンド、prompt で LLM 評価)
  • command: 実行するコマンド

具体例:編集後の自動フォーマット

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run format"
          }
        ]
      }
    ]
  }
}

この設定により、Edit、Write、MultiEdit のいずれかのツールが実行された後、自動的に npm run format が実行されます。

複数のフックを設定

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint"
          },
          {
            "type": "command",
            "command": "npm test"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Session completed' >> session.log"
          }
        ]
      }
    ]
  }
}

方法 2: コマンドによる対話的な設定

Claude Code のチャット欄で /hooks コマンドを実行すると、対話的な設定ウィザードが開始されます。

設定手順

  1. チャットに /hooks と入力
  2. 対話形式で設定が開始される
  3. イベントタイプを選択(例:PostToolUse)
  4. マッチャーを選択または入力(例:Edit)
  5. 実行するコマンドを入力(例:npm run format)
  6. 保存

設定の反映

設定を変更したら、Claude Code を再起動することで反映されます。

実践的な活用例

1. 自動コードフォーマット

コード編集後に自動的にフォーマッターを実行します。

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write ."
          }
        ]
      }
    ]
  }
}

Python プロジェクトの場合:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "black ."
          }
        ]
      }
    ]
  }
}

2. 自動テスト実行

コード変更後に自動的にテストを実行し、問題を早期発見します。

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --bail"
          }
        ]
      }
    ]
  }
}

3. 重要ファイルの編集制御

本番環境の設定ファイルなど、重要なファイルの編集を制限します。

.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/check-safe-edit.sh"
          }
        ]
      }
    ]
  }
}

check-safe-edit.sh の例:

scripts/check-safe-edit.sh
#!/bin/bash

# 編集禁止ファイルのリスト
FORBIDDEN_FILES=("config/production.yml" "secrets.env")

for file in "${FORBIDDEN_FILES[@]}"; do
  if git diff --name-only | grep -q "$file"; then
    echo "Error: Cannot edit production file: $file"
    exit 1
  fi
done

exit 0

4. 作業完了通知

セッション終了時にデスクトップ通知を送ります。

.claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'セッションが完了しました'"
          }
        ]
      }
    ]
  }
}

macOS の場合:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"セッションが完了しました\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

5. Git コミット自動化

作業完了時に自動的に Git コミットを作成します。

.claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/auto-commit.sh"
          }
        ]
      }
    ]
  }
}

auto-commit.sh の例:

scripts/auto-commit.sh
#!/bin/bash

# 変更があるかチェック
if [[ -n $(git status -s) ]]; then
  git add .
  git commit -m "Auto-commit: Claude Code session completed at $(date)"
  echo "Changes committed successfully"
else
  echo "No changes to commit"
fi

6. リンティングとフォーマットの組み合わせ

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run format"
          }
        ]
      }
    ]
  }
}

ベストプラクティス

1. コマンドはスクリプト化する

長いコマンドは外部スクリプトとして管理しましょう。

// ❌ 悪い例:長いワンライナー
{
  "command": "if [ -f package.json ]; then npm run lint && npm run format && npm test; fi"
}

// ✅ 良い例:スクリプト化
{
  "command": "./scripts/post-edit-check.sh"
}

2. 適切なイベントを選択

  • PostToolUse: コード編集後の処理(フォーマット、テスト)
  • PreToolUse: 編集前の検証(権限チェック、バリデーション)
  • Stop: セッション終了時のクリーンアップ

3. エラーハンドリングを含める

スクリプトには適切なエラーハンドリングを実装しましょう。

scripts/post-edit-check.sh
#!/bin/bash

set -e  # エラー時に即座に終了

# フォーマット
npm run format || {
  echo "Format failed"
  exit 1
}

# リント
npm run lint || {
  echo "Lint failed"
  exit 1
}

echo "All checks passed"
exit 0

4. タイムアウトを設定

長時間実行されるコマンドには、タイムアウトを設定します。

{
  "type": "command",
  "command": "npm test",
  "timeout": 30  // タイムアウト時間(秒)
}

5. ログを記録

デバッグのために、実行ログを記録しましょう。

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/post-edit.sh >> .claude/hooks.log 2>&1"
          }
        ]
      }
    ]
  }
}

セキュリティと注意点

セキュリティリスク

Hooks は フルユーザー権限 でコマンドを実行します。以下の点に注意してください:

  1. 信頼できるコマンドのみを設定

    • 任意のコマンド実行が可能なため、悪意のあるコードを実行するリスクがあります
    • 実行するスクリプトの内容を必ず確認してください
  2. 入力の検証

    • 外部入力を使用する場合は、適切にサニタイズしてください
    • シェルインジェクションのリスクに注意
  3. 機密情報の管理

    • 設定ファイルに機密情報(API キー、パスワード等)を直接記載しないでください
    • 環境変数や外部の設定管理ツールを使用しましょう

プロジェクト管理の注意点

  • .gitignore で管理: 機密情報を含む設定ファイルは .gitignore に追加
  • チーム共有時の配慮: チームメンバーの環境に合わせた設定を心がける
  • ドキュメント化: Hooks の設定と目的を README に記載

トラブルシューティング

Hooks が実行されない

原因と解決策:

  1. 設定ファイルの場所を確認

    • .claude/settings.json が正しい場所にあるか確認
    • プロジェクトルートからの相対パスを確認
  2. JSON の構文エラー

    • JSON の形式が正しいか確認
    • オンライン JSON バリデータで検証
  3. 設定の反映

    • claude --reload-config を実行
    • Claude Code を再起動

コマンドが失敗する

デバッグ方法:

  1. ログを確認

    tail -f .claude/hooks.log
    
  2. コマンドを手動実行

    • ターミナルで同じコマンドを実行して動作確認
    • 権限やパスの問題を特定
  3. エラー出力をファイルに保存

    {
      "command": "npm test 2>&1 | tee test-output.log"
    }
    

まとめ

Claude Code Hooks を使うことで、開発ワークフローを大幅に自動化できます。

重要なポイント

  • イベント駆動型の自動実行: ライフサイクルイベントに応じてコマンドを自動実行
  • 柔軟な設定: JSON ファイルまたはコマンドで簡単に設定可能
  • 豊富なイベントタイプ: PreToolUse、PostToolUse、Stop など、様々なタイミングで実行
  • セキュリティ意識: フルユーザー権限での実行に注意

次のステップ

  1. 簡単な Hooks から試す(編集後の自動フォーマット等)
  2. プロジェクトに合わせてカスタマイズ
  3. チーム内でベストプラクティスを共有
  4. Agent Skills と組み合わせて、さらに強力なワークフローを構築

Claude Code Hooks を活用して、効率的な開発体験を実現しましょう!

参考リンク

Discussion