Claude Code Hooks活用ガイド｜自動化を100%確実にする方法

📚 この記事は「Claude Code 完全攻略シリーズ」の Episode 11 です。

Claude Codeは強力なAIコーディングアシスタントですが、プロンプトで指示した内容が100%実行される保証はありません。「ファイル保存後にフォーマッタを実行して」と毎回伝えても、AIが忘れることはあります。

そこで登場するのがHooks機能です。Hooksは決定論的な自動化を実現する仕組みで、特定のイベントに対してシェルコマンドを自動実行します。プロンプト指示のような「お願い」ではなく、「確実に実行される」仕組みです。

本記事では、Claude Code Hooksの基本概念から実践的な活用例まで、SES現場で即使えるテクニックを解説します。

Claude Code Hooksとは？プロンプト指示との違い

Claude Code Hooksの仕組み：イベント発生→条件マッチ→シェルコマンド自動実行

決定論的な自動化が最大の特徴

従来のClaude Codeでの自動化は、CLAUDE.mdやプロンプトに「〇〇してください」と書く方式でした。これはAIへの「お願い」であり、実行されない可能性があります。

一方、Hooksはイベント駆動型のシェルコマンド実行です。

項目	プロンプト指示	Hooks
実行確実性	不確実（AIが判断）	100%確実
実行タイミング	AIの判断に依存	イベント発生時に自動
実行内容	自然言語で記述	シェルコマンド
カスタマイズ性	柔軟だが不安定	固定だが信頼性高

SES現場では確実に守るべきルール（フォーマット、セキュリティ、ログ記録）にHooksを使い、柔軟な判断が必要な作業にはプロンプト指示を使うのがベストプラクティスです。

Hooksの3つのタイプ

Claude Code Hooksには以下の3タイプがあります。

Command Hooks — シェルコマンドを直接実行（最も一般的）
Prompt Hooks — AIに追加のプロンプトを注入
Agent Hooks — 別のエージェントプロセスを起動

本記事ではCommand Hooksを中心に解説しますが、Prompt HooksとAgent Hooksも実用的なシーンがあります。

Hooksが対応する17種類のイベント

Hooksは以下のイベントに対して設定できます。

PreToolUse / PostToolUse

最もよく使われるイベントペアです。

PreToolUse — ツール実行前に発火。コマンドのブロックや条件チェックに使用
PostToolUse — ツール実行後に発火。フォーマッタ実行やログ記録に使用

対応するツール名の例：

Write — ファイル書き込み
Edit — ファイル編集
Bash — シェルコマンド実行
Read — ファイル読み取り

Notification / Stop

Notification — Claude Codeが通知を送るタイミングで発火。カスタム通知に活用
Stop — セッション終了時に発火。クリーンアップ処理に使用

その他、SessionStart、SessionResume、PreCompact、PostCompactなどのイベントも用意されています。

Hooksの設定方法

/hooksコマンドでの対話的設定

最も簡単な方法は、Claude Code内で/hooksコマンドを実行することです。

> /hooks

対話的なUIが表示され、イベントの選択、マッチ条件の設定、実行コマンドの入力をステップバイステップで行えます。

JSON設定ファイルの直接編集

より詳細な制御には、.claude/settings.jsonを直接編集します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "prettier --write \"$CLAUDE_FILE_PATH\"",
        "description": "ファイル変更後に自動フォーマット"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "echo \"$CLAUDE_FILE_PATH\" | grep -q '\\.env' && exit 1 || exit 0",
        "description": ".envファイルへの変更をブロック"
      }
    ]
  }
}

グローバル/プロジェクト/ローカルの使い分け

Hooksの設定は3つのスコープで管理できます。

スコープ	設定ファイル	用途
グローバル	`~/.claude/settings.json`	全プロジェクト共通ルール
プロジェクト	`.claude/settings.json`	リポジトリ固有ルール
ローカル	`.claude/settings.local.json`	個人設定（Git管理外）

SES現場では、プロジェクトスコープをチームで共有し、ローカルスコープで個人の好みを上書きするのが効率的です。

実践的なHooks活用例5選

ファイル編集後の自動フォーマット

最も一般的な活用例です。Claude Codeがファイルを書き換えた後、自動的にPrettierやESLintを実行します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "ext=\"${CLAUDE_FILE_PATH##*.}\"; case $ext in js|ts|jsx|tsx|json|css) npx prettier --write \"$CLAUDE_FILE_PATH\" ;; py) black \"$CLAUDE_FILE_PATH\" ;; esac",
        "description": "拡張子に応じたフォーマッタ実行"
      }
    ]
  }
}

これにより、Claude Codeが生成するコードは常にプロジェクトのフォーマットルールに準拠します。

機密ファイルへの変更ブロック

SES現場では、触ってはいけないファイル（.env、secrets/、本番設定ファイルなど）があります。PreToolUseフックで変更を事前にブロックできます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "echo \"$CLAUDE_FILE_PATH\" | grep -qE '\\.(env|pem|key)$|secrets/' && echo 'BLOCKED: 機密ファイルへの変更は禁止されています' >&2 && exit 1 || exit 0",
        "description": "機密ファイルの変更を禁止"
      }
    ]
  }
}

exit 1を返すとツール実行がキャンセルされ、Claude Codeに「ブロックされた」旨が通知されます。

コマンド実行ログの自動記録

誰がどのコマンドを実行したかを記録することは、SES現場での監査対応に重要です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "command": "echo \"$(date +%Y-%m-%dT%H:%M:%S) | $CLAUDE_TOOL_INPUT\" >> .claude/audit-log.txt",
        "description": "Bashコマンド実行ログを記録"
      }
    ]
  }
}

通知のカスタマイズ

長時間のタスク完了時に、デスクトップ通知やSlack通知を送ることができます。

{
  "hooks": {
    "Notification": [
      {
        "command": "osascript -e 'display notification \"$CLAUDE_NOTIFICATION\" with title \"Claude Code\"'",
        "description": "macOSデスクトップ通知"
      }
    ]
  }
}

Toolの実行許可/拒否制御

特定のツールの使用自体を制限できます。例えば、rm -rfを含むBashコマンドをブロックする場合：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf' && echo 'BLOCKED: rm -rf は禁止です。trash コマンドを使ってください' >&2 && exit 1 || exit 0",
        "description": "rm -rfの使用を禁止"
      }
    ]
  }
}

チーム開発でのHooks運用

Git管理によるルール共有

.claude/settings.jsonをGitリポジトリに含めることで、チーム全体でHooksルールを共有できます。

# .gitignore に以下を追加（ローカル設定は除外）
.claude/settings.local.json
# プロジェクト設定は含める
!.claude/settings.json

新しいメンバーがリポジトリをクローンした時点で、チームのHooksルールが自動適用されます。SES案件で新たに参画するエンジニアにも、統一されたルールが即座に適用される利点があります。

セキュリティ上の注意点

Hooksはシェルコマンドを実行するため、以下の点に注意が必要です。

信頼できないリポジトリのHooksに注意 — クローンしたリポジトリの.claude/settings.jsonに悪意あるHooksが仕込まれている可能性があります
環境変数の漏洩に注意 — Hooksコマンド内で$PATH以外の環境変数を使う場合、ログに残る可能性があります
実行権限の最小化 — Hooksで実行するコマンドは、必要最低限の権限で実行されるよう設計してください

デバッグとトラブルシューティング

Hooksが期待通りに動作しない場合のデバッグ方法です。

ログ出力を有効化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "echo \"[DEBUG] File written: $CLAUDE_FILE_PATH\" >> /tmp/claude-hooks.log && prettier --write \"$CLAUDE_FILE_PATH\"",
        "description": "デバッグログ付きフォーマット"
      }
    ]
  }
}

よくあるトラブル

症状	原因	解決策
Hookが発火しない	matcherのパターン不一致	ツール名を正確に指定（大文字小文字注意）
コマンドがエラー	パスが通っていない	フルパスでコマンドを指定
意図せずブロック	exit 1の条件が広すぎる	grep条件を絞り込む

まとめ

Claude Code Hooksは、AIの柔軟性と自動化の確実性を両立させる重要な機能です。

プロンプト指示は柔軟だが不確実、Hooksは固定だが100%確実
PostToolUseでフォーマット自動化、PreToolUseで機密ファイル保護が定番
チーム開発では.claude/settings.jsonをGit管理して統一ルールを共有
SES現場では監査ログ、セキュリティ保護、フォーマット統一が特に重要

Hooksを活用することで、Claude Codeの利便性を最大化しながら、プロジェクトの品質とセキュリティを守ることができます。

Claude Code 完全攻略シリーズの他の記事もチェック：

Claude Code入門ガイド — 基本的な使い方
Claude Code CI/CD統合 — CI/CDパイプラインとの連携
Claude Codeセキュリティガイド — セキュリティ対策
Claude Codeチーム開発 — チームでの活用法