Claude CodeのHooks入門
CLAUDE.mdに「編集したら必ずチェックを実行して」と書いたのに、AIがときどき忘れる——そんな経験はありませんか？
それ、あなたの書き方が悪いのではありません。仕組みの限界です。そして、その限界を超えるための公式機能が「Hooks（フック）」です。
公式ドキュメントの説明が本質を突いています。
CLAUDE.mdの指示は「お願い（advisory）」。フックは「必ず実行される（deterministic）」
つまりフックとは、AIの作業の決まったタイミングで、100%自動実行される仕掛けのことです。
📌 本記事は2026年8月時点の公式ドキュメントに基づきます。
結論：フック＝「AIへのお願い」を「システムの強制」に変える
| 知りたいこと | 答え |
|---|---|
| 何ができる？ | ファイル編集のたびにチェック実行、危険な操作のブロック、完了時の自動検査など |
| CLAUDE.mdとの違い | CLAUDE.mdは守られないことがある。フックは必ず動く |
| 設定場所 | .claude/settings.json（プロジェクト用）等 |
| むずかしい？ | 設定ファイルはJSON形式。ただし公式は「AIに書かせろ」と推奨（後述） |
| 確認方法 | /hooks コマンドで設定済み一覧を表示 |
具体的に何が仕込めるのか
代表的なタイミング（イベント）を、初心者に必要な5つに絞って紹介します。
| タイミング | 名前 | 使用例 |
|---|---|---|
| ツール実行の直前 | PreToolUse | 「特定フォルダへの書き込みをブロック」 |
| ツール実行の直後 | PostToolUse | 「ファイル編集のたびに自動整形を実行」 |
| 指示を送った瞬間 | UserPromptSubmit | 「毎回、現在時刻や環境情報を添える」 |
| AIの応答が終わる時 | Stop | 「検査に合格するまで作業を終わらせない」 |
| セッション開始時 | SessionStart | 「作業前に環境をセットアップ」 |
補足：正確には、公式ドキュメントには30以上のイベントが定義されています。日本語の解説記事では「8種類」と書かれていることが多いのですが、これは古い情報です。まずは上の5つで十分です。
いちばん強力な使い方：「合格するまで終われない」ゲート
公式ベストプラクティスが推奨する、フックの真骨頂がこれです。
Stopフック（応答終了時）に検査スクリプトを仕込むと、検査が通らない限りAIは作業を終了できず、自動でやり直しを続けます。
「テスト通った？」「確認した？」と人間が聞いて回る代わりに、システムが門番をするわけです。AIの「できました（できてない）」問題への、最も確実な対策です。
公式の注記：無限ループ防止のため、8回連続でブロックされると強制的に終了します。
この「AIに証拠を出させる」思想の全体像は「公式ベストプラクティス日本語版」で解説しています。
設定の仕組み（読める程度でOK）
フックは .claude/settings.json などの設定ファイルに書きます。構造はこうなっています。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npm run lint"
}
]
}
]
}
}
日本語に訳すと：「編集か書き込みツールが使われた直後（PostToolUse＋matcher）に、npm run lint を実行して」。
設定ファイルの置き場所で適用範囲が変わります。
| 場所 | 効く範囲 |
|---|---|
~/.claude/settings.json |
自分の全プロジェクト |
.claude/settings.json |
そのプロジェクト（チーム共有可） |
.claude/settings.local.json |
そのプロジェクトの自分だけ |
公式の裏ワザ：「フックはAIに書かせる」
「JSONを書くのは無理…」という方に朗報です。公式ドキュメント自身が、フックの作成をClaude Codeに頼むことを推奨しています。
実際に公式が例示しているプロンプトの日本語版がこちら。
ファイルを編集するたびにeslintを自動実行するフックを設定して
migrationsフォルダへの書き込みをブロックするフックを書いて
AIが設定ファイルを書き、あなたは内容を確認して承認するだけ。「自動化の仕組みづくり」まで自動化できるのがClaude Codeの面白いところです。
ブロックの仕組み（少しだけ技術の話）
コマンド型フックは「終了コード」で挙動が決まります。
| 終了コード | 意味 |
|---|---|
| 0 | 合格。そのまま進む |
| 2 | 不合格。動作をブロックし、理由をAIに伝える |
| その他 | 警告だけ出して進む |
「2を返せばブロックできる」——これだけ覚えておけば、AIにフックを書かせるときも意図を正確に伝えられます。
よくある質問
Q1. フックが増えると危なくないですか？
フックは強力なぶん、間違った設定も必ず実行されます。まずは「整形を走らせる」など壊れても困らないものから始めて、ブロック系は慣れてから導入するのがおすすめです。
Q2. 一時的に全部止めたいときは？
設定に "disableAllHooks": true を書けば一括無効化できます。挙動がおかしいときの切り分けにも使えます。
Q3. 今どんなフックが動いているか確認するには？
/hooks コマンドで、設定済みフックの一覧を確認できます。
Q4. デスクトップアプリでも動きますか？
はい。公式ドキュメントに、ターミナル・IDE拡張・デスクトップアプリ・Web版すべてで動作すると明記されています。
まとめ
- フックは「お願い」ではなく「強制」。決まったタイミングで必ず実行される
- 初心者はまず5イベント（実行前・実行後・送信時・終了時・開始時）だけ覚えればOK
- 最強の使い方はStopフックの合格ゲート——検査に通るまでAIは終われない
- 設定はAIに書かせるのが公式推奨。日本語で頼むだけ
- まずは「編集のたびに整形」のような安全なものから
CLAUDE.mdが「しつけ」なら、フックは「柵」です。任せる範囲が広がるほど、柵の価値は上がります。
