Claude Code hooks 実運用ガイド｜セッション開始時の文脈注入とコマンド透過書き換え
hooksは、Claude Codeのライフサイクルの特定イベントに合わせて任意のコマンドを自動実行する仕組みです。Radineerでは、セッション開始時の社内文脈の自動注入や、開発コマンドのトークン最適化プロキシ経由への透過書き換えに使っています。本ガイドでは設定の置き場所から落とし穴までを実装者目線でまとめます。
Radineer 編集部 ・ 自社の Claude Code 本番運用に基づく解説（2026 年 5 月時点）
Claude Code hooksとは、セッション開始やツール実行といった特定のイベントが起きたときに、あらかじめ設定したコマンドを自動で走らせる仕組みです。これにより「毎回手で貼っていた文脈の投入」や「コマンドの書き換え」といった定型作業を、ユーザーの操作なしに自動化できます。
hooksとは何か
hooksは、Claude Codeの動作の節目(イベント)に紐づけて任意のシェルコマンドを実行する設定です。Claude本体の判断に任せるのではなく、ハーネス(CLI)側が決まったタイミングで確実にコマンドを発火させる点が特徴です。
そのため「セッションを始めたら必ず最新の社内ルールを読み込ませる」「特定のコマンドを必ず別コマンドに置き換える」といった、再現性が要る自動化に向いています。Claudeに毎回お願いするのではなく、仕組みとして固定できるのが利点です。
主要なhookイベントの早見表
hookはイベント単位で設定します。代表的なイベントと、どんな自動化に向くかを整理します。なお実際に利用できるイベント名や仕様は公式ドキュメントを参照してください。
| イベントの種類 | 発火タイミング | 向いている用途 |
|---|---|---|
| セッション開始時 | 新しいセッションを始めた直後 | 社内ルールや直近の文脈の自動注入 |
| ツール/コマンド実行前 | コマンドが実行される直前 | コマンドの透過リライト、実行内容のチェック |
| ツール/コマンド実行後 | コマンドが実行された直後 | 結果のロギング、後処理 |
| セッション終了/停止時 | 応答や作業が一区切りした時点 | 通知、後片付け、記録の保存 |
実例: セッション開始時に社内文脈を自動注入する
Radineerでは、セッション開始のhookで「直近の lessons.md(過去の失敗から学んだ運用ルール)」と「重要メモリ(feedback系のメモ)」を自動で文脈に読み込ませています。
これにより、毎回プロジェクトの前提や注意事項を手で貼り付ける必要がなくなり、セッションを始めた時点で必要な文脈がすでに入った状態になります。「同じ指摘を繰り返させない」「プロジェクト固有のお作法を毎回守らせる」運用が、人手を介さず安定します。
実例: コマンドの透過リライト
もう一つの実例が、開発コマンドをトークン最適化プロキシ経由に自動で書き換えるhookです。ユーザーは普段どおりコマンドを打つだけで、hookが裏側で実行コマンドを置き換えます。
ポイントは、ユーザー側の操作やオーバーヘッドがゼロであることです。コマンドのたびに「これはプロキシ経由で」と意識する必要がなく、透過的に最適化が効きます。手順を覚えてもらう運用は徹底が難しいため、hookで透過化してしまうほうが現場で破綻しません。
設定の置き場所と書き方
hookは settings.json に設定します。どのイベントで、どんなコマンドを実行するかを記述する形です。
運用上は、まず1イベント1目的で小さく始めることを勧めます。複数の処理を1つのhookに詰め込むと、問題が起きたときの切り分けが難しくなります。設定値や記法の正確な仕様は更新されることがあるため、必ず公式ドキュメントで最新の形式を確認してください。
落とし穴: 無限ループと権限
最大の注意点は、設定ミスによる処理のループや暴発です。たとえばコマンド実行をトリガーにするhookの中で、また同種のコマンドを呼んでしまうと連鎖が止まらなくなることがあります。発火条件は具体的に絞り、自分自身を再帰的に呼ばない設計にしてください。
もう一つは権限の扱いです。hookは設定したコマンドを自動実行するため、何が・どの権限で走るのかを把握しておく必要があります。導入時はまず安全側に倒し、ログを取りながら、想定どおりのコマンドだけが発火しているかを確認してから本運用に乗せるのが安全です。
よくある質問
hookはどこに設定しますか？
settings.json に設定します。どのイベントで、どんなコマンドを実行するかを記述します。設定の正確な記法やイベント名は更新されることがあるため、Anthropicの公式ドキュメントで最新の仕様を確認してください。
セッション開始時に毎回プロジェクトの前提を貼るのが面倒です。自動化できますか？
できます。Radineerではセッション開始のhookで、直近の運用ルール(lessons.md)と重要メモリを自動で文脈に注入しています。これにより、手で貼り付けなくてもセッション開始時点で必要な文脈が入った状態になります。
hookで処理が止まらなくなることはありますか？
あります。設定ミスでhookが連鎖的に発火し、ループや暴発につながることがあります。発火条件を具体的に絞り、hook内で自分自身を再帰的に呼ばないようにし、導入時はログを取りながら想定どおりの動作かを確認してください。
コマンドをいちいち書き換えるのは手間です。透過的にできますか？
できます。コマンド実行前のhookで、入力されたコマンドを別のコマンドに自動で書き換えられます。Radineerは開発コマンドをトークン最適化プロキシ経由に透過リライトしており、ユーザーは普段どおり打つだけで、追加の操作やオーバーヘッドはありません。