Claude Hooks

Claude Hooksは、Claude Codeに組み込まれたイベント駆動の自動化システムで、開発ワークフロー中の特定のイベントに応答してシェルスクリプトを実行します。提案を提供するSkillsとは異なり、Hooksは執行力を提供します - これらは実際に実行可能なスクリプトで、コーディングセッション中に発生していることに基づいて検証、ブロック、コンテキスト注入、またはアクションのトリガーを行うことができます。

HooksはClaude CodeをAIアシスタントからプログラマブルな開発環境に変換し、LLMの理解に依存せずに自動的に実行されるルール、標準、統合を定義できます。

主な機能

1. 5つのHookイベントタイプ

Claude Codeは異なるライフサイクルイベントのhooksをサポートします：UserPromptSubmit（プロンプト送信時）、PreToolUse（ツール実行前）、PostToolUse（ツール実行後）、Stop（セッション終了前）、SubagentStop（サブエージェント完了時）。各イベントは特定のコンテキストと制御ポイントを提供します。

2. 終了コード制御メカニズム

Hooksは特別な意味を持つ終了コードを通じて通信します：exit 0は正常に続行、exit 1は警告するが続行を許可、exit 2はブロックしてClaudeに問題の修正を強制します。これにより「提案 + 執行」システムが作成され、hooksは実際に不良コードの記述やコミットを防ぐことができます。

3. 実際のシェルスクリプト実行

Hooksはシステム権限で実行される実際のbash/shellスクリプトで、LLMの解釈に依存しません。AI支援ワークフローの一部として、linter、テスト、デプロイメント、API呼び出し、データベースクエリ、または任意のコマンドラインツールを実行できます。

4. 双方向通信

Hookスクリプトはstdout/stderrを通じてClaudeにメッセージを送信でき、コンテキスト、検証結果、または指示を会話に直接注入します。Claudeはhookのフィードバックをユーザー入力として扱い、フィードバックループを作成します。

5. プラグインベースの配布

HooksはSkillsやMCPサーバーと共にPluginsの一部としてパッケージ化・共有されます。/plugin installで完全なワークフローパッケージをインストールし、事前設定された検証、テスト、デプロイメント自動化を取得します。

6. 環境とコンテキストアクセス

Hooksは環境変数、ツールパラメータ、ファイルパス、セッションコンテキストを受け取ります。現在のgitブランチ、変更されたファイル、ツール名、引数などにアクセスしてインテリジェントな決定を行います。

使用シナリオ

このツールを使用すべき人は？

• DevOpsエンジニア：デプロイメント検証、インフラストラクチャチェック、環境セットアップの自動化
• 品質保証チーム：テスト要件、コードカバレッジしきい値、lint標準の実施
• セキュリティチーム：脆弱性のスキャン、権限の検証、シークレットコミットの防止
• 開発チーム：コミットメッセージ、PR要件、コードレビュープロセスの標準化
• エンタープライズ組織：コンプライアンスポリシー、監査証跡、ガバナンスルールの実施

解決する問題

1. 手動品質ゲート：テストやlinterの実行忘れを排除 - hooksはコミットやセッション終了前に自動的に実施
2. コンテキストの喪失：現在のgitステータス、環境情報、プロジェクト固有の詳細をすべてのClaude対話に注入
3. セキュリティリスク：シークレットの誤コミット、機密ファイルへのアクセス、破壊的操作の防止
4. 統合ギャップ：Claude Codeを既存ツールとブリッジ - Slack、JIRA、監視システム、CI/CDパイプライン
5. チーム標準の実施：全員が同じコーディング標準、コミット規約、ワークフローに従うことを保証

Hookイベントタイプと例

UserPromptSubmit Hook

トリガータイミング：ユーザーがClaudeにプロンプトを送信したとき

一般的な用途：

• gitステータスと現在のブランチ情報の注入
• プロジェクト固有のコンテキストや規約の追加
• 分析のためのユーザーリクエストのログ記録
• ユーザー入力のセキュリティスクリーニング

例：

#!/bin/bash
# hooks/user-prompt-submit.sh

BRANCH=$(git branch --show-current)
echo "📍 現在のブランチ: $BRANCH"

if [[ -n $(git status --porcelain) ]]; then
  echo "📝 未コミットの変更があります"
fi

exit 0

PreToolUse Hook

トリガータイミング：Claude Codeツール実行前（Read、Write、Edit、Bashなど）

一般的な用途：

• 読み取り/書き込み前のファイル権限の検証
• 機密ファイルやディレクトリへのアクセスのブロック
• 高コスト操作のレート制限
• ツール使用パターンのログ記録

例：

#!/bin/bash
# hooks/pre-tool-use.sh

if [[ "$TOOL_NAME" == "Read" ]] && [[ "$FILE_PATH" =~ \.env|credentials|secret ]]; then
  echo "⚠️ ブロック済み：機密ファイル $FILE_PATH の読み取りを試行"
  exit 2  # 実行をブロック
fi

exit 0

PostToolUse Hook

トリガータイミング：ツール呼び出しが正常に完了した後

一般的な用途：

• ツール出力の検証
• 特定のアクションの通知送信
• メトリクスと分析の収集
• フォローアップ自動化のトリガー

例：

#!/bin/bash
# hooks/post-tool-use.sh

if [[ "$TOOL_NAME" == "Bash" ]] && [[ "$COMMAND" =~ deploy ]]; then
  curl -X POST $SLACK_WEBHOOK \
    -d '{"text":"🚀 Claude Codeによってデプロイメントがトリガーされました"}'
fi

exit 0

Stop Hook

トリガータイミング：Claude Codeが終了またはセッション完了の準備をする前

一般的な用途：

• 最終品質チェックの実行（lint、テスト、型チェック）
• すべての変更がコミットされていることの確認
• 一時ファイルのクリーンアップ
• セッションレポートの生成

例：

#!/bin/bash
# hooks/stop-hook.sh

echo "🔍 最終品質チェックを実行中..."

if ! npm run lint; then
  echo "❌ Lintが失敗しました。終了前に修正してください。"
  exit 2  # Claudeに問題の修正を強制
fi

if ! npm test; then
  echo "❌ テストが失敗しました。終了前に修正してください。"
  exit 2
fi

echo "✅ すべてのチェックに合格しました！"
exit 0

SubagentStop Hook

トリガータイミング：サブエージェントが委任されたタスクを完了したとき

一般的な用途：

• サブエージェントの作業品質のレビュー
• 複数のサブエージェントからの結果の集約
• 委任されたタスクの完了検証
• サブエージェントのパフォーマンスのログ記録

Claude Codeエコシステムとの統合

Skills + Hooks = 完全なワークフロー自動化：

• Skillsは知識と提案を提供（何を、どのように行うか）
• Hooksはルールと標準を実施（しなければならないこと、してはいけないこと）
• 両者が「提案 + 執行」システムを作成

プラグインパッケージング：

• Hooksはプラグインの一部として配布
• プラグインのバンドル：Skills + Hooks + MCPサーバー + コマンド
• 完全なワークフローのインストール：/plugin install @team/code-standards

MCP統合：

• HooksはMCPツール呼び出しを検証可能
• PreToolUse/PostToolUseは外部ツール操作をインターセプト
• サードパーティ統合がポリシーに従うことを保証

階層アーキテクチャ：

優位性と独自の価値提案

競合他社と比較した優位性：

1. 真の執行 vs 提案：提案のみのCursor/Copilotとは異なり、hooksは終了コードを通じて実際に不良操作をブロック
2. 実際のコード実行：Hooksは実際のshellスクリプトで、無視される可能性のあるLLM依存の設定ではない
3. ライフサイクルカバレッジ：プロンプトからツール実行、セッション終了まですべての段階でhooks
4. オープン配布：承認プロセスなし - ベンダーマーケットプレイスとは異なり自由にプラグインを作成・共有
5. 標準ベース：MCPプロトコルによりツールやプラットフォーム間の相互運用性を実現

際立つポイント：

• AIがバイパスできないプログラマブル品質ゲート
• 実行可能スクリプトによるAI動作の完全制御
• 任意のコマンドラインツールまたはAPIとの統合
• 500以上のプラグインを持つコミュニティ駆動のプラグインエコシステム
• ベンダーロックインなし - スクリプトは永遠にあなたのもの

ヒントとベストプラクティス

1. 明確な終了コード：成功にはexit 0、警告にはexit 1、修正強制にはexit 2を使用 - 制御フローに明確な意図を持つ
2. 説明的なメッセージ：hooksが何をしているか、なぜブロックしているかを説明する明確なメッセージをエコー
3. 冪等スクリプト：hooksが副作用なしで安全に複数回実行できることを保証
4. エラー処理：try-catchを含め、入力を検証し、エッジケースを優雅に処理
5. セキュリティファースト：シークレットをハードコードせず、すべての入力を検証し、最小権限を使用
6. モジュラー設計：モノリシックスクリプトではなく、特定の目的のための集中的なhooksを作成
7. 徹底的にテスト：チームにデプロイする前にさまざまなシナリオでhooksをテスト

よくある質問

Hooksにはどのような権限がありますか？

Hooksはユーザーのshell権限で実行されます。手動で実行する任意のスクリプトと同様に、ファイルへのアクセス、コマンドの実行、ネットワークリクエストの作成が可能です。

Hooksは機密データにアクセスできますか？

はい。そのため、プラグインをインストールする前にhookスクリプトをレビューする必要があります。信頼できるソースからのhooksのみを使用するか、独自に作成してください。

hookが失敗した場合どうなりますか？

終了コードに依存します：exit 1は警告をログに記録しますが続行、exit 2はアクションをブロックし、続行前にClaudeに問題の修正を強制します。

hooksを一時的に無効にできますか？

はい、Claude Code設定を通じて特定のhooksまたはプラグイン全体をアンインストールせずに無効にできます。

hooksはオフラインで動作しますか？

はい、hooksはインターネット接続に関係なく実行されるローカルshellスクリプトです。hooks内の外部API呼び出しのみがネットワークアクセスを必要とします。

hookスクリプトをデバッグするにはどうすればよいですか？

HookのstdouJapanese translation continues here. Now I'll finish the content and save it:

Let me complete the Japanese translation:

t/stderrはClaudeの会話に表示されます。デバッグ用にechoステートメントを追加するか、コマンドラインからhooksを手動で実行してテストします。

## 実際の事例

### 品質ゲートの実施
Sionic AIは毎日1000以上の機械学習実験を実行しています。彼らのStop hooksはGPU構成、フレームワークパラメータを検証し、高コストなトレーニング実行を開始する前に既知の失敗パスを防ぎます。

### セキュリティスキャン
PreToolUse hooksは、ファイルの書き込みやコミットを許可する前にハードコードされたシークレット、APIキー、または資格情報をスキャンし、偶発的な露出を防ぎます。

### チームワークフローの標準化
PostToolUse hooksはコミットメッセージの規約を実施し、自動コードフォーマットを実行し、CI/CDパイプラインをトリガーしてチーム全体の一貫性を確保します。

### 統合自動化
Hooksはデプロイメントが発生したときにSlack通知を送信し、コードがコミットされたときにJIRAチケットを更新し、メトリクスを監視システムに自動的にログ記録します。

## 代替案

Claude Hooksが適していない場合、これらを検討してください：

- **GitHub Actions**：クラウドベースのCI/CDに適していますが、ローカルAIワークフローとは統合されていません
- **Git Hooks**：同様のコンセプトですが、gitイベントのみで、AIツールの相互作用には対応していません
- **Make/Task Runners**：手動ワークフローには適していますが、AI統合とイベントトリガーが欠けています
- **Cursor Rules**：設定ベースですが、執行力と実行可能スクリプトが欠けています

## まとめ

Claude Hooksは、開発者がAIアシスタントと協力する方法における根本的な変化を表しています。単なる提案ではなく、実行可能で執行可能なルールを提供することで、hooksはAIがチームの標準内で協力し、既存のツールやワークフローとシームレスに統合することを保証します。

コード品質の実施、セキュリティ問題の防止、デプロイメントの自動化、インフラストラクチャとの統合など、hooksはLLMがルールを理解し従うことに依存せずに、AI支援開発ワークフローのあらゆる側面をプログラマブルに制御できます。