Claude Code Hooks開発ガイド：完全実践マニュアル

2026年編集更新: 旧版にあったユーザー全体の遮断ルールと強制継続の例は廃止しました。現在の推奨は、ガイダンス優先、既定では Hooks なし、プロジェクトによる明示的なオプトインです。

Claude Code Hooks はイベント駆動の自動化です。特定のライフサイクルイベントで、小さく決定的な処理を必ず実行する必要がある場合に役立ちます。Agent に仕事の進め方を伝えるための第一選択ではありません。

最も軽い仕組みから選ぶ

ニーズ	優先する仕組み
プロジェクトの方針や意図を伝える	CLAUDE.md のガイダンス
再利用できる手順をまとめる	必要なときに選択する Skill
明確な境界で検証する	通常のコマンド、タスク、CI
ライフサイクルイベントを自動観測する	小さなオプトイン Hook
ツールへのアクセスを制御する	CLI のネイティブ権限と組織ポリシー

既定のインストールは 有効な Hooks がゼロでも、agents、skills、session ワークフローをすべて提供できます。自動インターセプターが少ないほど、遅延、予期しない拒否、デバッグの複雑さを減らせます。

Guidance-first の Hook 契約

Hook を追加する前に、次の5点を明記します。

1. イベント: 自動化を必要とする正確なイベント。
2. 効果: Hook が行う、境界の明確な1つの副作用。
3. スコープ: オプトインし、設定を所有するプロジェクト。
4. 失敗時の動作: 任意の便利機能が Session を停止不能にしないこと。
5. 削除手順: ツールキット全体を削除せずに無効化できること。

「関連テストを優先する」「差分を要約する」「公開前に確認する」といった内容はガイダンスのままにします。助言をインターセプトに変えても、能力ではなく摩擦が増えることがほとんどです。

オプトインに向く Hooks

良い候補は、決定的、高速、可視で、簡単に取り外せます。

• 操作完了後に短いローカル監査記録を追加する。
• 明示的なプロジェクトイベント後に生成済みメタデータを更新する。
• Session 開始時に短いプロジェクト案内を表示する。
• 長時間タスクの完了後に通知する。

1つの Hook は1つの処理だけを行い、出力を制限し、できる限りネットワークに依存せず、有効化状態をプロジェクト設定で明確にします。

既定でインストールしないパターン

• すべてのプロジェクトへコピーされるユーザー全体の Hook バンドル。
• Shell やファイル操作を広く拒否する事前インターセプト。
• Claude や subagent に継続を強制する停止イベント処理。
• ユーザーから見えない自動テスト、lint、commit、deploy のゲート。
• prompt、ソースコード、資格情報を取得する長時間スクリプト。

これらは正常な CLI を停止しているように見せ、ネイティブ権限、CI、明示的なワークフロー Skills と役割が重複します。

実際に有効な設定を監査する

プロジェクトの Hook ディレクトリが空でも、Hooks が動作していないとは限りません。環境に適用されるすべての設定レイヤーを確認します。

• 組織管理設定
• ユーザー設定
• プロジェクト設定
• commit しないローカルプロジェクト設定
• Claude 資産を読み込む可能性がある拡張機能や互換 CLI 統合

各登録について、イベント、コマンド、スコープ、timeout、データアクセス、操作を変更または拒否できるかを記録します。スクリプトが存在しない登録や目的不明の自動化を削除し、利用者が価値を説明できるものだけを残します。

作業を妨げずに検証する

使い捨てプロジェクトで、1回に1つのオプトイン Hook だけを試します。

• Hook を無効にしても通常の Session が動く。
• 失敗が見え、回復できる。
• 遅延に上限がある。
• 秘密や非公開ソースを出力しない。
• 偶発的な継続ループを作らない。

現在のイベント schema とライフサイクルはセッション15：Hooksシステムを参照してください。Hooks なしを既定にしたマルチ CLI 環境は Director Mode Lite を利用できます。