Hooksとは

モノ美

HooksってClaude Codeにお願いするのと何が違うの？

ラボ太

大きな違いは「確実性」だよ。プロンプトでお願いしても忘れることがあるけど、Hooksに設定すれば100%実行されるんだ。

Hooksは、Claude Codeのライフサイクルの特定のタイミングで、シェルコマンドを自動実行する仕組み。ファイル編集後の自動フォーマット、コミット前のセキュリティチェック、通知のカスタマイズなど、開発ワークフローの自動化に活用できる。

プロンプトでの指示は「お願い」であり、AIが忘れたり無視したりする可能性がある。一方、Hooksは「強制実行」であり、設定されたコマンドが確実に実行される。

他の上級機能については上級者ガイドを参照してほしい。

イベント一覧

モノ美

どんなタイミングでHooksを実行できるの？

ラボ太

主に4つのタイミングがあるよ。ツール実行の前後、通知時、セッション開始時だね。

Hooksが対応している主なイベントは以下の通り。

イベント	発火タイミング	主な用途
PreToolUse	ツール実行前	操作のブロック、バリデーション
PostToolUse	ツール実行後	フォーマット、リント、ログ記録
Notification	通知送信時	通知方法のカスタマイズ
SessionStart	セッション開始時	コンテキスト注入、環境チェック
Stop	応答完了時	作業サマリーの生成、後処理

PreToolUseの特徴

PreToolUseは唯一「操作をブロックできる」イベント。Hookが非ゼロの終了コードを返すと、そのツール操作がキャンセルされる。セキュリティ上重要なファイルへの書き込みを防ぐといった用途に使える。

PostToolUseの特徴

PostToolUseは最もよく使われるイベント。ファイル編集後の自動フォーマット、テスト実行、リント実行などに活用される。

設定方法

モノ美

設定ファイルはどこに書くの？

ラボ太

settings.jsonに記述するよ。プロジェクト共有用と個人用で配置場所が違うんだ。

配置場所	適用範囲
.claude/settings.json	プロジェクト共有
~/.claude/settings.json	全プロジェクト共通（個人用）

基本的な構造


{
  "hooks": {
    "イベント名": [
      {
        "matcher": "対象ツール名（正規表現）",
        "command": "実行するコマンド"
      }
    ]
  }
}

matcherでイベントの対象を絞り込み、commandに実行するシェルコマンドを指定する。matcherを省略すると、そのイベントのすべての操作が対象になる。

実践例1：自動フォーマット

モノ美

一番よく使われる設定って何？

ラボ太

ファイル編集後の自動フォーマットだね。Claude Codeが書いたコードを自動的に整形してくれるよ。

Prettier（JavaScript/TypeScript）


{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Black（Python）


{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "black $CLAUDE_FILE_PATH 2>/dev/null; isort $CLAUDE_FILE_PATH 2>/dev/null"
      }
    ]
  }
}

環境変数 $CLAUDE_FILE_PATH には、操作対象のファイルパスが自動的にセットされる。

実践例2：セキュリティチェック

モノ美

機密情報を間違ってコミットしちゃうのを防げるの？

ラボ太

PreToolUseを使えば、危険な操作をブロックできるよ。

APIキーの漏洩を防ぐ


{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "! grep -qE '(AKIA[0-9A-Z]{16}|sk-[a-zA-Z0-9]{48})' $CLAUDE_FILE_PATH"
      }
    ]
  }
}

この設定では、AWSアクセスキーやOpenAI APIキーのパターンがファイルに含まれている場合、書き込みがブロックされる。

特定ファイルへの書き込みを禁止


{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo $CLAUDE_FILE_PATH | grep -qvE '(\\.env|\\.secret|credentials)'"
      }
    ]
  }
}

.envファイルや認証情報ファイルへの書き込みを自動的にブロックする。

実践例3：リント実行

ESLint（PostToolUse）


{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ]
  }
}

|| true を付けることで、リントエラーがあってもHook自体は成功扱いになる。Claude Codeの操作が中断されない。

実践例4：通知のカスタマイズ

モノ美

長い処理が終わったら通知してもらえないの？

ラボ太

Notificationイベントを使えば、好きな方法で通知を受け取れるよ。

macOSの通知センターに通知


{
  "hooks": {
    "Notification": [
      {
        "command": "osascript -e 'display notification \"$CLAUDE_NOTIFICATION\" with title \"Claude Code\"'"
      }
    ]
  }
}

Windowsのトースト通知


{
  "hooks": {
    "Notification": [
      {
        "command": "powershell -Command \"[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null; $xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent(0); $xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode('$CLAUDE_NOTIFICATION')); [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Claude Code').Show([Windows.UI.Notifications.ToastNotification]::new($xml))\""
      }
    ]
  }
}

実践例5：セッション開始時のコンテキスト注入

環境情報の自動取得


{
  "hooks": {
    "SessionStart": [
      {
        "command": "echo \"Current branch: $(git branch --show-current), Node: $(node -v), Python: $(python --version 2>&1)\""
      }
    ]
  }
}

セッション開始時に現在のブランチやランタイムのバージョンを自動的にClaude Codeに伝える。

複数Hookの組み合わせ

ラボ太

複数のHookを組み合わせると、かなり強力なワークフローが作れるよ。


{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo $CLAUDE_FILE_PATH | grep -qvE '\\.env'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
      },
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ],
    "Stop": [
      {
        "command": "echo \"Session completed at $(date)\" >> .claude/session-log.txt"
      }
    ]
  }
}

この設定では、.envへの書き込みをブロック、編集後に自動フォーマットとリント、セッション終了時にログ記録を行う。

注意点

Hookのコマンドが失敗（非ゼロ終了）した場合、PreToolUseでは操作がブロックされる
PostToolUseでは操作後に実行されるため、ブロックではなくエラー通知になる
重いコマンドをHookに設定すると、Claude Codeの操作速度が低下する
環境変数（$CLAUDE_FILE_PATHなど）はイベントによって利用可能なものが異なる

モノ美

最初はどのHookから始めるのがいいかな？

ラボ太

まずはPostToolUseの自動フォーマットから始めるのがおすすめだよ。効果が分かりやすいし、設定もシンプルだからね。

まとめ

Hooksは、Claude Codeの操作に「確実に実行される自動化」を追加する強力な機能。主なポイントは以下の通り。

PreToolUseで危険な操作をブロック
PostToolUseで自動フォーマット・リントを実行
Notificationで通知方法をカスタマイズ
SessionStartで環境情報を自動注入
複数のHookを組み合わせて堅牢なワークフローを構築

まずは自動フォーマットから導入して、徐々にセキュリティチェックや通知を追加していくのが良いだろう。

Claude Code Hooks完全ガイド｜開発ワークフローを自動化する仕組みと実践例