Claude Code Hooks：自動化ワークフローの実践的な構築方法

Claude Code Hooksは、AIによるコーディング作業に「人間の意図」を精密に織り込むための仕組みです。ツールの実行前後にカスタムスクリプトを差し込むことで、コード品質の自動チェックやログ記録、通知送信といった繰り返し作業を大幅に効率化できます。

Claude Code Hooksとは何か

Claude Code Hooksとは、Claude Codeがツールを実行する際に、特定のタイミングでシェルコマンドやスクリプトを自動実行できる仕組みです。従来は「AIが作業する → 人間が確認する → 次のステップへ」という流れでしたが、Hooksを使えば「AIが作業する → 自動検証・通知 → 次のステップへ」という洗練されたワークフローを実現できます。

Hooksが特に威力を発揮する場面をいくつか挙げてみましょう。

コードの自動品質チェック: AIがファイルを編集するたびにLinterやFormatterを走らせ、問題があれば即座に検知できます。

変更履歴の自動記録: どのファイルがいつ編集されたかをログに残すことで、デバッグや監査が容易になります。

外部サービスへの通知: Slackやメールと連携し、重要な作業完了を自動で関係者に知らせることができます。

セキュリティチェック: センシティブなファイルへのアクセスを検知し、必要に応じてブロックすることも可能です。

Hooksの設定ファイル

Hooksの設定は ~/.claude/settings.json（グローバル設定）またはプロジェクトルートの .claude/settings.json（プロジェクト固有設定）に記述します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '🔧 Bashツール実行前: $CLAUDE_TOOL_INPUT' >> /tmp/claude-hooks.log"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && npx eslint --fix $CLAUDE_TOOL_INPUT_FILE_PATH 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

設定はJSON形式で記述し、フックタイプごとに matcher（対象ツール名）と実行する command を指定します。

4つのフックタイプを理解する

Claude Code Hooksには現在、4つのタイミングでスクリプトを実行できます。それぞれの特性を把握することが、効果的な活用の第一歩です。

PreToolUse：ツール実行前に動く

PreToolUse フックは、Claude Codeがツールを呼び出す直前に実行されます。最大の特徴は「ツールの実行を阻止する（blocking）」かどうかを選択できる点です。

スクリプトの終了コードが 0 であれば通常通りツールが実行され、0以外 の場合はツールの実行が阻止されます。これにより、危険なコマンドの自動検知やアクセス制御が実現できます。

#!/bin/bash
# 本番環境への直接デプロイを防ぐPreToolUseスクリプト例
TOOL_INPUT="$CLAUDE_TOOL_INPUT"
if echo "$TOOL_INPUT" | grep -q "production" && echo "$TOOL_INPUT" | grep -q "deploy"; then
  echo "⚠️  本番環境へのデプロイはレビューが必要です"
  exit 1  # ツール実行をブロック
fi
exit 0  # 通常通り実行

PostToolUse：ツール実行後に動く

PostToolUse フックは、ツールの実行が完了した直後に動きます。ツール実行の結果を受け取れるため、後処理や検証に最適です。

Editツール実行後に自動でフォーマットをかける使い方が特に人気です。

#!/bin/bash
# Editツール後に自動でPrettierを実行するスクリプト例
FILE="$CLAUDE_TOOL_INPUT_FILE_PATH"
if [[ "$FILE" =~ \.(js|ts|jsx|tsx|json|css)$ ]]; then
  npx prettier --write "$FILE" 2>/dev/null
  echo "✅ $FILE をフォーマットしました"
fi

Stop：Claude Codeが作業を終了するとき

Stop フックは、Claude Codeがセッションを終了する際に一度だけ実行されます。作業完了の通知や、最終的なサマリーの生成に活用できます。

#!/bin/bash
# 作業完了をSlackに通知するスクリプト例
SESSION_ID="$CLAUDE_SESSION_ID"
curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  -d "{\"text\":\"✅ Claude Code セッション完了 (ID: ${SESSION_ID})\"}"

Notification：通知イベント

Notification フックは、Claude Codeが何かを通知しようとするタイミングで実行されます。例えばユーザーの入力待ち状態になったときなどに活用でき、長い処理の途中経過を外部に伝えるのに便利です。

環境変数で渡される情報

Hooksスクリプト内では、実行コンテキストに関する情報が環境変数として自動的に設定されます。主要なものを把握しておきましょう。

環境変数	内容
`CLAUDE_TOOL_NAME`	実行されるツールの名前（例: `Bash`, `Edit`）
`CLAUDE_TOOL_INPUT`	ツールへの入力内容（JSON形式）
`CLAUDE_TOOL_INPUT_FILE_PATH`	Editツール使用時のファイルパス
`CLAUDE_PROJECT_DIR`	現在のプロジェクトのルートディレクトリ
`CLAUDE_SESSION_ID`	セッションの識別子
`CLAUDE_HOOK_EVENT_NAME`	発火したフックタイプの名前

これらを組み合わせることで、ツールの種類やファイルパスに応じた柔軟な処理が可能になります。

matcherでフックの適用範囲を制御する

matcher フィールドでは、どのツールに対してフックを適用するかを指定します。完全一致のほか、正規表現も使用できます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/auto-lint.sh"
          }
        ]
      }
    ]
  }
}

上記の例では、Edit と Write の両方のツールが実行された後にLintスクリプトを実行します。matcher を空文字列にすると、すべてのツールが対象になります。

実践レシピ集

レシピ1：TypeScriptファイルの自動型チェック

#!/bin/bash
# auto-typecheck.sh
FILE="$CLAUDE_TOOL_INPUT_FILE_PATH"
if [[ "$FILE" =~ \.tsx?$ ]]; then
  PROJECT_DIR="$CLAUDE_PROJECT_DIR"
  cd "$PROJECT_DIR"
  npx tsc --noEmit --skipLibCheck 2>&1 | head -20
fi

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "/path/to/auto-typecheck.sh" }]
      }
    ]
  }
}

レシピ2：セキュアなシークレット検出

機密情報（APIキー、パスワード等）がコードに混入するのを防ぐ設定です。

#!/bin/bash
# secret-detector.sh
FILE="$CLAUDE_TOOL_INPUT_FILE_PATH"
PATTERNS="(API_KEY|SECRET|PASSWORD|TOKEN|PRIVATE_KEY)\s*=\s*['\"][^'\"]{8,}"
 
if [ -f "$FILE" ] && grep -qE "$PATTERNS" "$FILE"; then
  echo "🚨 機密情報の可能性があるパターンを検知しました: $FILE"
  grep -nE "$PATTERNS" "$FILE" | head -5
  exit 1  # 上書きをブロック
fi
exit 0

レシピ3：作業ログの自動記録

#!/bin/bash
# activity-logger.sh
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
TOOL="$CLAUDE_TOOL_NAME"
FILE="${CLAUDE_TOOL_INPUT_FILE_PATH:-N/A}"
LOG_FILE="$HOME/.claude/activity.log"
 
echo "[$TIMESTAMP] $TOOL → $FILE" >> "$LOG_FILE"

このスクリプトをPostToolUseに設定することで、Claude Codeのすべての作業が ~/.claude/activity.log に自動記録されます。

レシピ4：テストの自動実行

#!/bin/bash
# auto-test.sh
FILE="$CLAUDE_TOOL_INPUT_FILE_PATH"
PROJECT_DIR="$CLAUDE_PROJECT_DIR"
 
# テストファイルが変更されたらすぐにテストを実行
if [[ "$FILE" =~ \.(test|spec)\.(js|ts)$ ]]; then
  cd "$PROJECT_DIR"
  npx jest "$FILE" --passWithNoTests 2>&1 | tail -10
fi

Hooksを安全に運用するポイント

Hooksはシェルコマンドをそのまま実行するため、設定を誤ると意図しない動作が起きる可能性もあります。安全に運用するための注意点を整理しておきましょう。

スクリプトのエラーハンドリング: set -e を使い過ぎると、細かいエラーでHooksが止まります。意図的にエラーを許容したい場合は || true を活用しましょう。

実行権限の確認: スクリプトファイルには chmod +x で実行権限が必要です。設定後に動作しない場合はまず権限を確認してください。

デバッグにはログを活用: echo "デバッグ情報" >> /tmp/hooks-debug.log のようにログを書き出しながら開発すると、問題の特定が容易になります。

冪等性（べきとうせい）を意識する: 同じHooksが複数回実行されても問題ないよう設計する点が肝心です。特にファイル生成や状態変更を伴う処理では注意が必要です。

全体を振り返って：Hooksで「賢い開発環境」を作ろう

Claude Code Hooksは、一度設定してしまえば毎回の作業を着実に支援してくれる、非常に実用的な機能です。最初は小さなログ記録から試してみて、徐々に自動フォーマットやセキュリティチェックへと拡張していくのがおすすめです。

「AIが作業する → 自動で品質が担保される → 人間は本質的な判断に集中できる」という循環を実現できたとき、開発体験は大きく向上するはずです。ぜひ、自分のプロジェクトに合ったHooks設定を育てていただければと思います。

🌟 プレミアム会員限定のコンテンツもあります

Claude Labでは、今回ご紹介したHooks活用術のさらに深い内容をプレミアム記事として公開しています。

MCPサーバーとHooksの組み合わせ：外部APIと連携した高度なワークフロー構築
チーム開発でのHooks共有ベストプラクティス：組織全体でHooksを標準化する方法
Claude Code + CI/CDパイプライン統合：GitHubActionsとの実践的な連携レシピ

プレミアム会員（月額¥280〜）になると、これらの深掘り記事すべてにアクセスできます。Claude AIを日々の開発に活かしたい方に、心からおすすめしています。