Claude Codeのhooksを3つの設定だけで動かす、最初の自動化ガイド

【PR】この記事はAmazonアソシエイトのリンクを含みます。Amazonのアソシエイトとして、mononofu26は適格販売により収入を得ています。

はじめに

Claude Codeでファイルを編集するたびに、フォーマッターを手で走らせていないでしょうか。あるいは、AIが実行しようとしているコマンドの内容を、毎回自分の目で確認していないでしょうか。

Claude Codeには「hooks（フック）」という機能があり、決まったタイミングでシェルコマンドを自動的に実行できます。Claude自身が「このコマンドを実行しよう」と判断して呼び出すツール呼び出しとは違い、hooksはイベントが起きた瞬間に、設定ファイルに書かれたとおり必ず実行される点が特徴です。AIの判断に依存しないぶん、同じ処理を毎回確実に走らせたい場面に向いています。

この記事では、hooksを初めて使う人向けに、最小限の3つの組み合わせだけを使って自動化を始める手順をまとめます。全部の機能を覚える必要はなく、まずこの3つを動かしてみることで、hooksが何をしてくれる機能なのかが具体的につかめます。

hooksとは何か

Claude Codeのhooksは、Claude Codeのライフサイクルの特定のタイミング（イベント）で、あらかじめ登録したコマンドを実行する機能です。設定は次の3階層の構造になっています。

1. イベント名 — いつ発火するか（例: PostToolUse、PreToolUse、Notification）

2. matcher（マッチャー） — どのツール呼び出しに反応するか（例: \"Write\"、\"Edit|Write\"）

3. hooks配列 — 実際に実行するコマンド

設定ファイルは ~/.claude/settings.json（全プロジェクト共通のユーザー設定）、.claude/settings.json（プロジェクト共通の設定でgit管理してよい）、.claude/settings.local.json（自分だけのローカル設定）のいずれかに書きます。同じイベントが複数のファイルで定義されている場合はローカル設定が優先されるため、試行中の設定はまずローカルファイルに書くのが安全です。

matcherの書き方には3種類あります。

• 完全一致（\"Write\" はWriteツールだけに反応する）

• パイプでの複数指定（\"Edit|Write\" はEditまたはWriteに反応する）

• 正規表現（\"Notebook.*\" のようにツール名の前方一致でまとめて指定する）

matcherを省略するか空文字にすると、そのイベントに該当するすべてのケースで発火します。

hooksが受け取る入力情報

hooksのコマンドは、実行されるときに標準入力（stdin）からJSON形式のデータを受け取ります。シェルスクリプトの中で jq などを使ってこの値を読み取れば、どのツールが呼ばれたか、どのファイルに対する操作かを判断できます。

代表的なフィールドは次のとおりです。

• session_id — 現在のセッションを識別する値

• cwd — Claude Codeを起動したディレクトリ

• hook_event_name — どのイベントで発火したか（PreToolUse・PostToolUseなど）

• tool_name — 呼ばれたツールの名前（Write・Edit・Bashなど）

• tool_input — ツールに渡されたパラメータ（ファイルパスやコマンド本体など）

PostToolUseではこれに加えて tool_response も渡され、ツールの実行結果を見てから処理を分岐させることもできます。環境変数だけで済む単純な用途なら気にする必要はありませんが、条件分岐を作りたくなったら、まずこのJSONの中身を jq . などでそのまま覗いてみると、何が使えるかが一目で分かります。

Claude Code hooksの設定方法：最初に試す3つの組み合わせ

hooksには多くのイベント種類がありますが、最初から全部を理解する必要はありません。まずは次の3つだけで、日々の作業の手間が減る自動化を体験できます。

1. PostToolUseで自動フォーマットを走らせる

PostToolUseは、ツール（Write・Editなど）が実際に実行された直後に発火するイベントです。ファイルを編集した直後にフォーマッターを走らせたいときに使います。

{
  \"hooks\": {
    \"PostToolUse\": [
      {
        \"matcher\": \"Edit|Write\",
        \"hooks\": [
          {
            \"type\": \"command\",
            \"command\": \"prettier --write \\\"$CLAUDE_FILE_PATH\\\"\"
          }
        ]
      }
    ]
  }
}

matcherに \"Edit|Write\" と書くと、Edit・Writeどちらのツールが呼ばれたときにも発火します。コマンドの中で使える環境変数はツールの種類によって変わるため、実際に使う前に自分の環境でどの変数にファイルパスが入るかを確認しておくと安心です。

2. PreToolUseで望まない操作を止める

PreToolUseは、Claudeがツールのパラメータを組み立てた後、実際にツールを実行する前に発火します。ここでコマンドの内容を調べ、望まない操作であれば実行前に止められます。

一度実行されてから対処するPostToolUseとの大きな違いは、ここで止めれば実際には何も起きていない状態を保てることです。たとえば、特定のディレクトリへの書き込みや、再帰的な削除コマンドを実行前にチェックする使い方が代表的です。

PreToolUseのhookが「ブロックする」と判断した場合、その内容がClaudeに伝わり、Claudeは別の方法を考え直します。承認・拒否・保留のいずれかを返せる設計になっているため、常に全部を拒否するのではなく、特定の条件のときだけ止める、という細かい制御ができます。

3. Notificationで入力待ちに気づく

Claude Codeがユーザーの入力を待っている状態になったときに発火するイベントです。長い作業を別の画面で行っている間、Claude Codeの画面を見ていなくても、デスクトップ通知や音で「入力待ちです」と気づけるようにできます。

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

Notificationイベントはmatcherを持たないケースが多く、登録しておけば該当するすべてのタイミングで発火します。macOSならosascript、他のOSなら対応する通知コマンドに置き換えて使います。

終了コードの基本だけ覚える

hooksのコマンドが何を返すかによって、Claude Codeの動きが変わります。最初に覚えておきたいのは次の2つだけです。

• 終了コード0 — 正常終了。処理を続ける

• 終了コード2 — ブロックするエラー。標準エラー出力（stderr）の内容がClaudeに渡され、Claudeはその内容を踏まえて動き直す

終了コード1など、0でも2でもないコードは、Claude Codeからは単なる非ブロッキングのエラーとして扱われ、処理は止まりません。「止めたいのに止まらない」という最初のつまずきは、たいていこの終了コードの選び間違いが原因です。

動作を確認する最短の方法

設定を書いた直後は、本当に発火しているかを確かめたくなります。いちばん手早いのは claude --debug でClaude Codeを起動する方法です。デバッグモードでは、どのイベントでどのhookが呼ばれ、終了コードが何だったかがターミナルに流れるため、設定ファイルの構文は合っているのに発火しない、といった状態と、構文自体が間違っている状態を区別できます。

また、Claude Codeのセッション内で /hooks というスラッシュコマンドを使うと、現在登録されているhooksの一覧を確認できます。設定ファイルを編集した直後は、変更がそのセッションに反映されていない場合があるため、一覧に表示されているかどうかも合わせて確認すると、設定ファイルの書き間違いと反映待ちの切り分けがしやすくなります。

設定ファイルの置き場所の使い分け

hooksを試すときは、まず .claude/settings.local.json に書くのがおすすめです。このファイルは個人の実験用であり、チームの設定ファイル（.claude/settings.json）に影響を与えません。動作を確認できたら、チームで共有したい設定だけを .claude/settings.json に移す、という順番で進めると、設定ミスがチーム全体に広がるリスクを避けられます。

~/.claude/settings.json はユーザー単位のグローバル設定です。どのプロジェクトでも使いたい通知系の設定（先述のNotificationの例など）は、プロジェクトをまたいで使うことが多いため、ここに置くと管理がシンプルになります。

はじめて設定するときに迷いやすい点

• matcherを書き忘れるとどうなるか: 省略すれば該当イベントの全ケースに発火します。意図せず全部に反応してしまうことがあるため、最初は対象を絞ったmatcherを明示するほうが事故を防ぎやすいです。

• 複数のhooksを同じイベントに並べたらどうなるか: 配列に複数の設定を並べれば、該当する条件に一致したものがそれぞれ実行されます。1つのイベントに役割の違う処理を混在させると、どの設定が何をしているか分かりにくくなるため、最初は1イベント1目的で始めるのが見通しをよくするコツです。

• コマンドが遅いとClaude Codeの応答も遅くなるか: hooksのコマンドの実行が終わるまで、Claude Codeは次の処理に進みません。重い処理を仕込むと、作業全体の待ち時間が延びる点は意識しておく必要があります。

• 設定ファイルを編集したら、すぐに反映されるか: 編集した内容がその場のセッションに反映されているとは限りません。/hooks で一覧を確認し、反映されていなければ新しいセッションを開始し直すのが確実です。

おわりに

hooksは「AIに毎回同じことを頼む」作業を、設定ファイル1つに任せる仕組みです。最初から複雑な自動化を目指さず、まずはPostToolUseでの自動フォーマット、PreToolUseでの望まない操作のチェック、Notificationでの入力待ち通知という3つだけを試してみると、hooksが何をしてくれる機能なのかが具体的に分かります。

慣れてきたら、SessionStartやUserPromptSubmitなど他のイベントも使えるようになり、設定できる範囲がぐっと広がります。まずは手元の設定ファイルに、小さな1つのhookを書いてみることから始めてみてください。

あわせて読みたい

• AI初心者がCodexで月5万円を稼ぐ方法

• 2026年、ガンプラはAIで\"設計\"できる——配色・改造・バックストーリーまで試した全記録

• 【導入編①】カメラの前で「録画開始」と言うだけ。Claude CodeとOBSをつないだら、Vtuber配信が\"勝手に進む環境\"が手に入った話