AIに主導権を渡さない！Claude Code Hooks 完全ガイドと自動化チュートリアル

✨ AIに主導権を渡さない！Claude Code Hooks 完全ガイドと自動化チュートリアル

最近、ターミナルでClaude Codeを使っている方が増えているのではないでしょうか。新機能の開発、バグの追跡、複雑なコードの整理など、AIアシスタントとして素晴らしい働きを見せてくれます。

しかし、私たち開発者は知っています。大規模言語モデル（LLM）の本質は「確率的」であることです。コードを書き終えた後に「テストを実行してね」とか「フォーマットを忘れないでね」と指示しても、AIがそれを忘れたり、セッション間で一貫性を欠いたりする可能性があります。

エンジニアリングの世界で私たちが最も求めるのは、**確実性（Deterministic control）**です。

まさにこの問題に応えるためにClaude Code Hooksが登場しました。これは、プロンプトでの「お願い」を、毎回必ず実行される保証されたアクションに変える機能です。

Claude Code Hooksは、ユーザーが定義したShellコマンドであり、Claude Codeの動作の特定のタイミングで自動的にトリガーされます。これにより、AIの「確率的な理解」に頼るのではなく、信頼性の高い「確実なシステム」を構築できるようになります。

Claude Code Hooksは、AIによるコーディングのパラダイムを、単なるアシスタントから、開発ワークフローの強制力を持つパートナーへと進化させるための鍵となる機能なのです。

I. Claude Code Hooksの仕組みと主要なイベント

Claude Code Hooksの設定は、プロジェクトディレクトリ内の .claude/settings.json ファイル、またはユーザー設定内の ~/.claude/settings.json ファイルにJSON形式で保存されます。この設定ファイル内で、Claude Codeのライフサイクルでリスニングしたい「イベント」を定義します。

Hookイベント名	実行されるタイミング	Claude Code Hooksの主な用途
PreToolUse	Claude Codeがツール（ファイルの書き込み、Bashコマンドの実行など）を実行する前。	セキュリティと検証： 危険なコマンド（rm -rfなど）のブロック、機密ファイルへのアクセス防止、またはツールの入力パラメータの変更。
PostToolUse	ツールが正常に完了した後。	品質保証： コードの自動フォーマット（prettierやgofmtなど）の実行、テストスイートの実行、操作の監査ログ記録。
Notification	Claude Codeが通知を送信するとき。	カスタム通知： ユーザーの入力が必要な場合や、長時間タスクが完了した場合に、デスクトップやSlackにカスタムアラートを送信。
Stop	メインのAIエージェントが応答全体を終了するとき。	ワークフローの継続： セッションの作業サマリーの作成や、変更の自動Gitコミットなど、最終アクションをトリガーする。
UserPromptSubmit	ユーザーがプロンプトを送信したが、AIがそれを処理する前。	コンテキスト注入： プロンプトに現在のGitブランチ情報などの追加コンテキストを自動的に付与、またはプロンプトの内容のセキュリティ検証。

これらのClaude Code Hooksイベントを組み合わせることで、開発標準を強制し、信頼性の高い自動化を実現できます。

II. Claude Code Hooks 使用チュートリアル：実行コマンドのログ記録

それでは、最も簡単な例である「実行されたすべてのShellコマンドをログに記録する」Claude Code Hooksを設定する手順を見ていきましょう。

1. 前提条件の準備

このチュートリアルでは、Claude Code HooksがJSON形式でデータを標準入力（stdin）として渡すため、コマンドラインでJSONを処理するためのツール jq が必要です。

2. Hooks設定の開始

Claude Codeのターミナルで、特殊なスラッシュコマンド /hooks を実行します。

次に、フックイベントとして PreToolUse を選択します。このイベントはツールが実行される前にトリガーされるため、ログ記録に最適です。

3. マッチャーの追加

+ Add new matcher… を選択します。 入力フィールドに Bash と入力し、Enterを押します。これにより、このClaude Code HooksはBashツールの呼び出しに対してのみ実行されるようになります。

💡 ヒント： 全てのツールをマッチさせたい場合は * を使用するか、空のままにします。

4. Hookコマンドの追加

+ Add new hook… を選択し、次のログ記録コマンドを入力します。このコマンドは、jqを使用してJSON入力から実行コマンドと説明を抽出し、指定されたファイルに追記します。

jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

5. 設定の保存

ストレージの場所を選択します。今回はホームディレクトリにログを記録するため、ユーザー設定（User settings）を選択します。これにより、このClaude Code Hooksは全てのプロジェクトに適用されます。

Escキーを押してREPLに戻ると、Claude Code Hooksが登録され、アクティブになります。

6. Hooksの検証とテスト

1. /hooks コマンドを再度実行するか、~/.claude/settings.json ファイルを確認して、設定が登録されていることを検証します。
2. Claude Codeにファイル一覧表示のような簡単なコマンド（例：ls）を実行するよう要求します。
3. ログファイルの内容を確認します: cat ~/.claude/bash-command-log.txt。

以下のようなエントリーが表示されれば、最初のClaude Code Hooksの設定は成功です。

ls - Lists files and directories

III. Claude Code Hooksの高度な活用シナリオ

基本的なClaude Code Hooksの使い方をマスターしたら、次は開発ワークフローを自動化するさらに強力な活用法を探りましょう。

1. 自動コードフォーマットとLinting（PostToolUse）

AIがコードを生成した後、Claude Code Hooksを使用してコード規約を強制します。

• 実装方法： PostToolUse イベントを設定し、Edit|Write などのファイル操作ツールにマッチさせます。その後、npx prettier --write や black などのフォーマッタを実行するコマンドを定義します。

2. 危険な操作のブロック（PreToolUse）

PreToolUse Claude Code Hooksは、ツール実行前に介入できるため、セキュリティの番人として機能します。

• 実装方法： PreToolUse 鉤子を設定し、Claude Codeが実行しようとしているコマンドやファイルパスを検証するスクリプトを実行します。例えば、ファイルパスに機密ファイル（.env、secrets.yml）やGitディレクトリ（.git/）が含まれていないかチェックし、検出した場合は終了コード 2 を返すことで、ツールの実行を阻止できます。

3. 継続的なテストと品質チェック（PostToolUse）

AIが導入した新しいコードが既存の機能を壊していないことを確認するために、Claude Code Hooksを利用します。

• 実装方法： PostToolUse 鉤子を設定し、ファイルが変更された後に pytest や npm test などのテストスイートを自動的に実行します。時間がかかるテストの場合は、エージェントループをブロックしないよう、バックグラウンドで実行するように設定することも可能です。

IV. セキュリティとベストプラクティス

警告： Claude Code Hooksは、ユーザーの現在の環境の権限（credentials）を使用してShellコマンドを自動実行するため、悪意のある、あるいは不完全なClaude Code Hooksはデータ損失やシステムへの損害を引き起こす可能性があります。

安全にClaude Code Hooksを使用するために、以下の点に留意してください：

• 入力の検証とサニタイズ： stdinから受け取るJSONデータは決して盲目的に信頼せず、常に検証すること。
• Shell変数の引用： コマンドインジェクションを防ぐため、Shellスクリプト内で変数を参照する際は必ず "$VAR" のように引用符を使用すること。
• パスのトラバーサル阻止： ファイルパスに .. のような親ディレクトリへの移動を示すシーケンスが含まれていないかチェックすること。
• 実行速度の維持： Claude Code Hooksは同期的に実行されるため、エージェントループをブロックします。理想的な実行時間は100ミリ秒未満です。時間がかかる操作は非同期で実行することを検討してください。
• 無限ループの防止： Stop 鉤子などでAIの継続を強制する場合、入力JSONの stop_hook_active フィールドを確認し、無限に継続しないようにロジックを組む必要があります。