Claude CodeのHooks(フックス)とは？活用例や設定方法・使い方も解説

Claude Codeを使い始め、Hooks(フックス)という機能があることを知り、どんなものか気になっている人は多いですよね。

また、使おうにも設定方法がわからなかったり、エラーが出ても原因を特定しにくかったりと、扱い方がわからない人もいるはず。

そこでこの記事では活用例や設定方法も交え、Claude Code Hooksのの特徴を解説します。Hooksを使うべきなのか、といった疑問にもお答えするので、ぜひ参考にしてください。

Claude Codeの特徴をより詳しく知りたい人は、次の記事を参考にしてください。

Claude CodeのHooksとは？

Claude Code Hooksとは、特定のイベントが発生したタイミングでシェルコマンドを自動実行する仕組みです。たとえば「AIがツールを呼び出す前」「タスクが完了した後」など、決められたタイミングで任意のスクリプトを走らせられます。

ここからは次の2つのカスタムコマンドとCLAUDE.mdとの違いを解説します。

カスタムコマンドとの違い

カスタムコマンドは「ユーザーが手動で呼び出す」のに対し、Hooksは「イベントが起きたとき自動で動く」点が根本的な違いです。

カスタムコマンドは /deploy のようにチャット欄で打ち込んで実行するため、毎回人が操作する必要があります。一方Hooksは、ファイル保存やツール実行などのイベントに紐づいて自動で動作する設計になっています。

「毎回コマンドを打つのが面倒」「人手に頼らず確実に実行したい」という場面では、Hooksが適しています。

Claude Codeのコマンドについて詳しく知りたい人は、次の記事を参考にしてください。

CLAUDE.md(プロンプト指示)との違い

CLAUDE.mdはAIへの行動指針を文章で伝えるファイルです。あくまでAIへの「お願い」にとどまるため、必ずしも指示どおりに動くとは限りません。

一方Hooksは、AIの解釈を介さずシェルコマンドを直接実行します。「フォーマットを必ず実行したい」「ファイル保存前に検証を挟みたい」のように確実性が求められる処理はHooksで設定するのが最適です。

Claude Code Hooksの活用例

Hooksが使える場面は幅広く、日常的な開発作業のほとんどで自動化が可能です。ここからは次の4つの活用例を解説します。

タスク完了時に通知を送る・音で知らせる

長時間かかる処理を任せている間、画面を見続けなくて済むのがHooksの便利な点です。Stopイベントに通知コマンドを設定すれば、タスク完了と同時に音やポップアップで知らせてくれます。

Macの場合は osascript -e 'display notification "完了しました"' 、Windowsでは powershell -command "..." を使った通知が実現できます。作業中に別の仕事をしていても完了を見逃さずに済むのが大きなメリットです。

上記を含め、Claude Codeの通知方法をより詳しく知りたい人は、次の記事を参考にしてください。

コマンド実行前に安全チェックを挟む

PreToolUseイベントを使うと、AIがツールを実行する直前に検証スクリプトを挟めます。たとえば、本番環境への影響がある操作や、特定のディレクトリへの書き込みを検知したタイミングで処理を止められます。

スクリプトが終了コード 2 を返すとClaudeの実行がブロックされる仕組みです。ヒューマンエラーや意図しないファイル操作を防ぐ安全弁として活用でき、チーム開発での運用にも向いています。

ファイル変更時にフォーマットを自動実行

PostToolUseイベントと組み合わせると、AIがファイルを編集した直後にフォーマッターを自動実行できます。prettierやblackのようなツールを設定しておけば、コードスタイルが常に統一された状態を保てます。

レビュー時にスタイルの指摘が出るたびに手動修正する手間がなくなります。フォーマットを「忘れる」ことがなくなるため、チームのコードレビュー品質も安定します。

Git操作前後にカスタムスクリプトを走らせる

PreToolUseでgit commitやgit pushの前後にスクリプトを実行できます。コミット前にテストを走らせたり、プッシュ後にSlackへ通知を飛ばしたりと、開発フローへの組み込みが可能です。

従来はgit hooksで設定していたような処理を、Claude Codeの設定に統合して管理できます。設定を1か所にまとめられるため、チームへの共有も容易になります。

Claude CodeのHooksは活用すべき？

結論として、繰り返し発生する定型処理がある開発者にはHooksの活用を強くおすすめします。

理由は、Hooksによって「AIが作業したあとの確認・整形・通知」を自動化できるからです。手動対応が必要だった後処理を省けるため、1日の作業量が多いほど恩恵が大きくなります。

ただし、設定が不要なケースもあります。シンプルな用途でClaudeを使うだけなら、Hooksの設定コストが見合わない場合があります。次の基準を参考にしてください。

Anthropicの公式ドキュメントでも「Hooksはユーザーが決定論的な制御を持てる仕組み」として位置づけられており、AIの不確実な動作を補完する手段として推奨されています。

Claude Code Hooksの設定方法

Hooksの設定はsettings.jsonへの記述で完結します。ここからは次の6つの設定手順を解説します。

settings.jsonへの記述手順

設定ファイルは2か所のどちらかに配置します。

記述の基本構造は次のとおりです。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"完了\" with title \"Claude\"'"
          }
        ]
      }
    ]
  }
}

使えるイベント名はPreToolUse・PostToolUse・Notification・Stop・SubAgentStopなどです。公式ドキュメントで最新のイベント一覧を確認することをおすすめします。

matcherの役割と指定方法

matcherは「どのツール呼び出しに反応するか」を絞り込む設定項目です。指定しない場合はすべてのツール実行に反応します。

たとえばBashツールにのみ反応させたい場合は次のように記述します。

{
  "matcher": "Bash",
  "hooks": [
    {
      "type": "command",
      "command": "echo 'Bashが実行されます'"
    }
  ]
}

正規表現も使えるため、特定のファイル操作だけに絞ることもできます。Write|Editのように複数ツールをまとめて指定することも可能です。

通知の設定手順(Mac/Windows)

Macでの通知設定はosascriptを使います。

"command": "osascript -e 'display notification \"タスク完了\" with title \"Claude Code\"'"

Windowsでの通知設定はPowerShellを使います。

"command": "powershell -command \"[System.Windows.Forms.MessageBox]::Show('完了しました')\""

通知音だけでよければ、Macではafplay /System/Library/Sounds/Glass.aiffのように既存の音声ファイルを指定できます。どちらの設定もStopイベントに紐づけるのが基本的な使い方です。

複数のHooksを同時に設定する方法

1つのイベントに複数のHooksを設定したい場合は、配列に並べて記述します。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '完了1'"
          },
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}

配列内の上から順に実行されます。処理の順序に意味がある場合は、先に動かしたいコマンドを上に書くことを意識してください。

他PCとHooksの設定を共有する方法

チームで同じHooks設定を使いたい場合は、プロジェクトルートの.claude/settings.jsonにHooksを記述します。このファイルをGitリポジトリに含めると、git pullするだけでチーム全員が同じ設定を使えます。

ユーザー固有の設定（個人の通知音など）は~/.claude/settings.jsonに分けて管理するとすっきりします。プロジェクト共通の処理はプロジェクト側、個人設定はユーザー側と使い分けるのがおすすめです。

設定が反映されないときの確認項目

設定を書いてもHooksが動かない場合は、次の項目を確認してください。

JSONのバリデーションにはjqコマンドが有効です。cat settings.json | jq .を実行して出力が正常に返れば、JSON自体に問題はありません。

上記を含め、Claude Codeのおすすめ設定を詳しく知りたい人は、次の記事を参考にしてください。

Claude Code Hooksが動かない時の対処法

Hooksが期待どおりに動かない場合、大半は設定ミスかコマンドのパス問題です。エラーの原因を特定する順番を理解しておくと、解決が速くなります。

ここからは次の2つの対処法を解説します。

よくあるエラーパターンと解決策

よく起こるエラーと対処法は次のとおりです。

実行コマンドはターミナルで単体動作を確認してからsettings.jsonに書き込むと、切り分けが楽になります。

デバッグ時に確認すべきログの見方

Claude Codeはデバッグ用のログ出力を--debugフラグで確認できます。起動時に次のコマンドを使います。

claude --debug

ログには、Hooksの呼び出し履歴が記録されます。コマンドの終了コードやエラーメッセージも確認できます。

Hooksのスクリプト内でstderrに出力した内容は、Claudeのレスポンスに表示されます。デバッグ用にecho "実行確認" >&2を一時的に追加すると、Hooksが呼び出されているかどうかを確かめられます。

終了コード1はエラーとしてログに残りますが、処理は継続されます。終了コード2はClaude側の処理をブロックするため、意図しないブロックが発生していないかも合わせて確認してください。

まとめ

Claude Code Hooksは、決められたイベントをトリガーにシェルコマンドを自動実行する機能です。通知・安全チェック・フォーマット・Git連携など、日常の開発作業を自動化できます。

設定はsettings.jsonへの記述で完結し、プロジェクト共有もGit管理で対応可能です。イベント名はPreToolUse・PostToolUse・Stop・SubAgentStopなど、大文字小文字まで正確に記述する必要があります。

動かない場合は--debugフラグとターミナルでの単体実行確認が最速の解決策です。繰り返し発生する後処理や確実に実行したい安全チェックがある開発者は、ぜひHooksの設定を試してみてください。