[Claude Code #11] フック：依頼ではなく仕組みで自動化する

CLAUDE.mdに「編集後は必ずフォーマッターを実行して」と書いても、AIが忘れることがあります。指示はあくまで依頼だからです。

必ず起きなければならないことは、依頼ではなく仕組みにする必要があります。Claude Codeでは、その仕組みがフックです。

フックはユーザーが定義するシェルコマンドです。Claude Codeの動作中、特定のタイミングで自動実行され、モデルが何を選んでも決定的に適用されます。

Claude Code 第10回までのコマンドが手動で仕掛けるものだったとすれば、フックは自動で仕掛けられる装置です。

5分で最初のフックを作る

フックはsettings.jsonのhooksブロックに記述します。Claudeが入力を待っているときにmacOS通知を表示する例を見てみましょう。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"入力が必要です\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

保存して/hooksと入力すると、登録済みフックの一覧が表示されます。この画面は読み取り専用なので、settings.jsonを直接編集するか、Claudeに依頼します。

どのタイミングで仕掛けられるのか

公式フックガイドを基準に、よく使うイベントは次のとおりです。

• SessionStart：セッションの開始時・再開時
• UserPromptSubmit：プロンプト送信直後、Claudeが処理する前
• PreToolUse：ツール呼び出し直前。呼び出しをブロック可能
• PostToolUse：ツール呼び出しが成功した直後
• Stop：Claudeのターン終了時
• Notification：Claudeが入力を待っているとき

matcherで対象を絞り込みます。"matcher": "Edit|Write"と書けば、ファイル編集ツールを使うときだけフックが動作します。

代表的な3つの活用例

編集後の自動フォーマット。PostToolUseにEdit|Writematcherを設定してprettierを実行します。AIがどのファイルを編集しても、フォーマットが強制されます。

保護ファイルのブロック。PreToolUseフックで特定のパスを検査し、終了コード2で終了したらその編集をブロックします。任意の失敗コードではなく、必ず2でなければなりません。CLAUDE.mdの指示とは違い、モデルが忘れても突破されません。

完了時の通知。先ほどのNotificationの例のように、ターミナルを見続ける必要はありません。

判断が必要ならpromptフック

シェルスクリプトでは判定しにくい条件もあります。「依頼した作業はすべて終わったか？」のようなものです。

この場合はtype: "prompt"フックを使います。シェルコマンドの代わりに判断基準を書いておくと、デフォルトのHaikuモデルがyes/noで判定します。

Stopイベントにpromptフックを設定すると、「終わっていなければ作業を続けて」になります。実際、第6回で扱った/goalはこの構造をセッション限定のラッパーにしたものです。

フックはシェルをそのまま実行する

強力であるぶん、リスクもあります。自分の権限で任意のシェルコマンドが自動実行される仕組みだからです。

プロジェクトのsettings.jsonにあるフックでは、リポジトリを信頼するか確認されます。他人のリポジトリを開くときは、この確認を軽く扱わないでください。

フックコマンド内の変数は引用符で囲み、検証なしに外部入力を実行しないという基本も守る必要があります。

まとめ

フックは「必ず起きなければならないこと」をモデルの記憶力から切り離し、システムに任せる仕組みです。

まずはフォーマッターの強制、保護ファイルのブロック、完了通知から始めましょう。判断が必要な条件はpromptフックへ拡張できます。

次回は、一定間隔でプロンプトを繰り返し実行する/loopを扱います。フックがイベントの自動化なら、/loopは時間の自動化です。

出典と確認基準

• Claude Code公式ドキュメント — Automate actions with hooks（Anthropic、2026-08-14確認）
• Claude Code公式ドキュメント — Hooks reference（Anthropic、2026-08-14確認）

あわせて読みたい

Claude Codeシリーズ

• 前回：[Claude Code #2] /plan 計画モード：変更前に設計を合意する
• 前回：[Claude Code #1] /init、CLAUDE.mdの自動生成から始める

関連トピック

• [エージェント設計 #1] ハーネスエンジニアリングとは？プロンプトの次に来るもの