claude-code-hooks-mastery は、Claude Code Hooks を学ぶためのプロジェクトです。
単にいくつかのスクリプトを並べただけではありません。Claude Code の hooks ライフサイクル、設定方法、スクリプトの書き方、よくある自動化シナリオをまとめて説明しています。Claude Code をより制御しやすく、よりエンジニアリング向けの助手として使いたい人にとって、読む価値のある資料です。
Claude Code は標準でもコードを読み、ファイルを編集し、コマンドを実行できます。しかし、特定のタイミングで権限を確認したり、危険な操作を止めたり、プロジェクト規約を注入したり、テストを実行したり、チームルールを思い出させたりしたい場合、チャット指示だけでは安定しません。Hooks の価値は、「毎回 AI に思い出させたいルール」を実行可能なワークフローに変えることです。
Hooks が解決する問題
Claude Code をしばらく使うと、よく次のような課題が出てきます。
- 新しい会話のたびに同じプロジェクトルールを説明する必要がある
- 実行してはいけないコマンドを実行しないか不安
- ファイル変更の前後で自動チェックしたい
- コミット前にフォーマット、テスト、セキュリティスキャンを走らせたい
- チーム規約を口頭の注意ではなく固定フローにしたい
- ツール呼び出しの前後でコンテキストを取得し、ログやブロックに使いたい
- 複雑なタスクでサブエージェントや専用スクリプトを起動したい
Hooks は、こうした「決まったタイミングでの自動動作」のためにあります。
Claude Code ワークフロー内のイベントフックとして考えるとわかりやすいです。セッション開始、ユーザーのプロンプト送信、モデルがツールを呼び出す直前、ツール呼び出し完了、エージェント終了直前などのタイミングで、設定したスクリプトを実行できます。
13 個の Hooks ライフサイクル
このプロジェクト README の重要な点の一つは、Claude Code の 13 個の hook イベントを体系的に整理していることです。
これらのイベントは、セッション開始からツール呼び出し、ユーザー入力からエージェント終了まで、複数の段階をカバーします。用途別には、おおまかに次のように分けられます。
- セッション起動関連：環境初期化、プロジェクトコンテキスト注入
- ユーザー入力関連：プロンプト確認、ルール補足、監査
- ツール呼び出し前関連：権限判断、コマンドブロック、安全チェック
- ツール呼び出し後関連：結果記録、フォーマット起動、検証実行
- タスク終了関連：要約、クリーンアップ、通知、状態保存
このライフサイクル設計により、すべてのルールを長いプロンプトに詰め込む必要がなくなります。
たとえば、権限制御はツール呼び出し前に行うべきです。フォーマットチェックはファイル変更後の方が自然です。プロジェクト規約の注入は、セッション開始時やユーザー入力後が向いています。正しい hook ポイントにルールを置く方が、すべてを system prompt に詰めるより信頼しやすくなります。
設定ファイルの場所
Claude Code の hooks は通常、設定ファイルで構成します。
よく使われる場所は次のとおりです。
- ユーザー単位の設定：
~/.claude/settings.json - プロジェクト単位の設定：
.claude/settings.json
ユーザー単位の設定は、一般的な安全ルール、コマンドブロック、ログパスなど、個人の好みに向いています。
プロジェクト単位の設定は、そのリポジトリに関するルールに向いています。たとえば、必ず実行するテスト、編集禁止のディレクトリ、生成ファイルの扱い、コミット前のチェックなどです。
チームで Claude Code を使うなら、プロジェクト単位の設定をリポジトリに置くのがおすすめです。そうすれば、各自が記憶で AI に注意するのではなく、全員が同じ AI 協作制約を持ってプロジェクトを開けます。
単一ファイルスクリプトが重要な理由
このプロジェクトでは UV の単一ファイルスクリプトが強調されています。
利点はデプロイが簡単なことです。1 つの Python ファイルで依存関係を宣言して実行できるため、1 つの hook のために複雑な環境を維持する必要がありません。多くの hook は小さな処理を 1 つ行うだけなので、この形式は適しています。
- コマンドの実行可否を確認する
- ファイルパスが安全か判断する
- プロジェクト規約を読み、Claude に返す
- 出力に機密情報が含まれていないか調べる
- 変更後にフォーマットやテストを実行する
- イベントをログに書く
Hook スクリプトは小さいほど保守しやすく、新しい複雑なシステムになりにくくなります。
どんな自動化ができるか
claude-code-hooks-mastery は多くの方向性を示しています。実務でよく使うのは次のようなものです。
1. 権限と安全制御
これは hooks の最も直接的な用途です。
Claude Code がコマンドを実行する前に、その内容をチェックできます。削除、リセット、クリア、上書きなどの高リスク操作が含まれている場合、実行を止めるか、人間の確認を求められます。
同様のルールはファイルパスにも使えます。
- 本番設定を変更しない
- 秘密鍵ファイルに書き込まない
- マイグレーションスクリプトを削除しない
- 指定ディレクトリに触れない
- 未承認のネットワークコマンドを実行しない
この保護をツール呼び出し前に置く方が、「危険な操作をしないで」とプロンプトに書くより確実です。
2. コンテキスト注入
多くのプロジェクトには固定された背景があります。
- 技術スタック
- コーディング規約
- テストコマンド
- ブランチ戦略
- ディレクトリ構造
- 禁止事項
- 生成ファイルの扱い
これらを毎回手動で Claude Code に伝えるのは面倒で、漏れやすいです。Hooks を使えば、セッション開始時やユーザーのプロンプト送信後に必要なコンテキストを自動注入できます。
これは Claude Code にプロジェクト単位の作業マニュアルを渡すようなものです。README や開発ドキュメントを置き換えるものではありませんが、AI がタスクを始める前に正しい状態へ入りやすくなります。
3. 変更後の検証
Claude Code がファイルを変更した後、hook で自動チェックを起動できます。
よくある処理は次のとおりです。
- フォーマットを実行する
- lint を実行する
- 単体テストを実行する
- 型エラーを確認する
- 生成ファイルをスキャンする
- Markdown や JSON の形式を検証する
これは低レベルなミスを減らすのに役立ちます。AI が複数ファイルを変更した場合、変更後に軽量な検証を走らせることで、問題を早めに見つけられます。
ただし、hook に重い処理をデフォルトで入れるのは向きません。ファイル変更のたびに完全なテストスイートを走らせると、体験が遅くなります。より実用的なのは、ファイル種別、ディレクトリ、タスクのリスクに応じてチェック範囲を選ぶことです。
4. チームルールの検証
チームに明確な約束があるなら、その一部を hooks に入れられます。
たとえば：
- コミットメッセージ形式
- コードスタイルルール
- 特定の生成ファイルを直接変更しない
- ドキュメントを同時に更新する
- API 変更ではテストも更新する
- 特定ディレクトリは指定ツールでのみ生成する
これにより Claude Code は、制約のない外部アシスタントではなく、チームワークフローの一部に近づきます。
もちろん、hooks は CI の代わりではありません。ローカルでの早めの注意や前置ブロックに向いています。最終検証は CI、review、テストシステムに任せるべきです。
5. サブエージェントと専用タスク
README ではサブエージェント関連の内容にも触れています。
この使い方は、複雑なタスクをより専門的なフローに分ける場合に向いています。たとえばメイン会話が要求を理解し、hook や設定が専用のチェック、監査、要約、ドキュメント整理タスクを起動します。
個人ユーザーにとって、最初にやる価値があるのは複雑なエージェント編成ではありません。まずは反復的で明確かつ低リスクな処理を hooks に任せることです。ルールが安定してから、より複雑な自動化を検討すれば十分です。
Statusline と出力スタイル
プロジェクトは statusline と出力スタイルも扱っています。
一見すると体験面の細部ですが、Claude Code を長期的に使う場合には重要です。Statusline は現在のコンテキスト、タスク状態、環境情報、ヒントを表示できます。出力スタイルは Claude Code の回答を自分の作業習慣に合わせやすくします。
毎日同じターミナルで AI と協作するなら、こうした細部は効率に影響します。良い状態表示は誤操作を減らし、現在の会話が正しいプロジェクト、正しいブランチ、正しい環境にいるかを素早く判断できます。
hooks を重くしすぎない
Hooks は強力ですが、何でも詰め込む場所ではありません。
良いルールは次のとおりです。
- 高頻度の処理は速くする
- 安全ブロックは明確にする
- 出力は短くする
- 失敗理由は読みやすくする
- スクリプトはできるだけ単一責務にする
- 重いチェックは明示コマンドや CI に任せる
毎回 10 秒以上かかる hook は、すぐに無効化したくなります。ブロックルールが曖昧な hook も、Claude Code とユーザーの両方にとって次に何をすべきか分かりにくくなります。
Hooks は、境界が明確な処理に最も向いています。許可または拒否、コンテキスト追加、ログ記録、軽量チェック、次の手順提示などです。
向いているユーザー
たまに Claude Code に小さなコード変更を頼むだけなら、hooks を深く学ぶ必要はまだないかもしれません。
しかし、次のような場合はこのプロジェクトを調べる価値があります。
- Claude Code を頻繁に使う
- AI に実際のプロジェクトコードをよく変更させる
- AI が危険なコマンドを実行しないか不安
- チーム規約を AI ワークフローに自動注入したい
- 変更後に自動チェックを走らせたい
- 繰り返しの注意を設定に変えたい
- より安定した AI コーディングフローを作っている
特に複数人で作業するプロジェクトでは、hooks の意味が大きくなります。チーム経験の一部をスクリプトとして残せるため、各メンバーがその場で AI に注意する必要が減ります。
利用時の注意
第一に、安全系 hook から始めることです。
複雑な自動化よりも、コマンドブロック、パス保護、機密ファイルチェックの方が実装しやすく、すぐにリスクを下げられます。
第二に、プロジェクト単位のルールは慎重にコミットすることです。
.claude/settings.json は、そのリポジトリを使う全員に影響します。コミット前に、通常開発を過度に制限しないこと、自分のマシンにしかないパスに依存しないことを確認した方がよいです。
第三に、hook の出力は簡潔にすることです。
Claude Code はその出力を消費します。長すぎるとコンテキストを汚し、曖昧すぎると次の行動を導けません。必要な判断と次の提案だけを返すのがよいです。
第四に、デバッグしやすく保つことです。
Hooks が増えると、問題は設定、スクリプト、権限、パス、依存関係、Claude Code 本体のどこからでも起こり得ます。明確なログを残すと、後の調査がずっと楽になります。
参考
最後に
Claude Code Hooks の価値は、「AI に毎回覚えていてほしいルール」を、実際に実行されるフローへ変えることです。
すでに Claude Code を実プロジェクトで使い始めているなら、hooks は「会話できるコーディング助手」から「制約を持つエンジニアリング協作者」へ進むための重要な一歩です。