🤖 Claude Code フック（Hooks）
Claude Codeを使い始めると、多くの人が次のような疑問にぶつかります。「Claude.mdにルールを書いたのに、時々守られない」実はこれはClaude Codeの仕様によるものであり、バグではありません。Claude CodeのHooks（フック）機能について、Claude.mdとの違いを含めて分かりやすく解説します。
📌 Claude.mdとフックの根本的な違い
まず最も重要なポイントです。
| 項目 | Claude.md | Hooks |
|---|---|---|
| 動作方式 | 確率論的 | 決定論的 |
| AIの判断 | 必要 | 不要 |
| 実行保証 | なし | あり |
| 柔軟性 | 高い | 低い |
| 用途 | ルール・指示 | 自動処理 |
Claude.mdは「お願い」
例えばClaude.mdに次のような内容を書いたとします。
ファイル編集後は npm format を実行してください
期待としては、
ファイル編集→フォーマット実行
しかし実際には、
ファイル編集→終了
となる場合があります。
なぜ実行されないのか？
Claude.mdに書いた内容は、AIへの指示（プロンプト）だからです。
Claudeは常に、「今何をするのが最も適切か？」を判断しながら動いています。
そのため、
- コンテキストが長くなった
- 他の指示が優先された
- ユーザーが途中で停止した
- 別の文脈が強くなった
といった場合、Claude.mdに書かれた内容を実行しないことがあります。
🎲 Claude.mdは確率論的
ClaudeなどのLLMは本質的に次に最も確率が高い行動を選択しています。
つまり、必ず実行ではなく、実行する可能性が高いという仕組みです。
これを確率論的（Probabilistic）と呼びます。
🔒 Hooksは決定論的
一方でHooksは違います。HooksはClaudeの判断に依存しません。
設定した条件に一致した場合、必ず実行されます。
例えば
ファイル編集後→npm format実行
というフックを設定した場合、
Claudeが忘れても、Claudeが判断を変えても、必ず実行されます。
🎯 Claude.mdとHooksの使い分け
Claude.mdが向いているもの
コーディングルール
TypeScriptで実装する
命名規則
変数名はcamelCaseを使用する
設計方針
SOLID原則に従う
こういったAIの判断が必要なものはClaude.md向きです。
Hooksが向いているもの
自動フォーマット
prettier
自動テスト
npm test
通知
作業完了通知
ロギング
履歴保存
危険操作のブロック
rm -rf
などです。
📌 Hooksでよく使う4つのイベント
Claude Codeには約10種類のイベントがあります。
しかし最初は次の4つだけ覚えれば十分です。
① PreToolUse
ツール実行前
Claudeがツールを使う直前に発火します。
ファイル編集→PreToolUse→実行
用途
危険操作の防止
例えば rm -rf のような削除コマンドを検出したら、実行を止めることができます。
特定フォルダ保護
/home/userや Desktop 配下の重要フォルダを守ることも可能です。
特徴
フックが exit 2 を返すと、Claudeの処理を中断できます。
② PostToolUse
ツール実行後
Claudeがツールを実行した後に発火します。
ファイル編集→編集完了→PostToolUse
用途
自動フォーマット
prettier
ESLint
eslint
テスト実行
npm test
ドキュメント生成
README更新
など。
最も利用頻度が高い
Claude.mdでは実行漏れが発生しますが、Hooksなら100%実行されます。
③ Stop
タスク完了時
Claudeが作業を終えて 次の指示待ち状態になった時に発火します。
用途
デスクトップ通知
作業完了
音を鳴らす
ピロン♪
ログ保存
実行履歴記録
長時間処理と相性が良い
AIに数十分作業させる場合、完了を見逃さないためによく使われます。
④ SessionStart
セッション開始時
Claude Code起動時に発火します。
Claude起動→SessionStart
用途
npm install
npm install
Docker起動
docker compose up
環境初期化
初期セットアップ
毎回行う作業を自動化できる
開発開始前に毎回やる処理をHooks化できます。
⚙️ Hooks設定の基本構造
設定は通常
settings.json
に記述します。
概念的には次のようになります。
{
"hooks": {
"PostToolUse": {
...
}
}
}
🔍 Matcherとは？
イベントだけではなく、どのツールに対して発火するかも指定できます。
これをMatcherと呼びます。
全ツール対象
"*"または ""
Bash実行時のみ
"Bash"
ファイル編集時のみ
"Write" "Edit"
例
Write→Hook発火→フォーマット実行
⚠️ サブエージェントでは発火しない
注意点があります。
例えば
Sub Agent→ファイル編集した場合、
通常の Write／Edit フックは発火しません。
この場合は SubagentStop イベントを使用する必要があります。
その他のイベント一覧
| イベント | 用途 |
|---|---|
| PermissionRequest | 許可確認時 |
| Notification | 通知送信時 |
| UserPromptSubmit | ユーザー入力時 |
| SubagentStop | サブエージェント終了時 |
| PreCompact | コンパクト前 |
| SessionEnd | セッション終了時 |