Claude Code hooks とは？──「このタイミングで必ず実行」の使い方

こんな方に読んでほしい

• CLAUDE.md / settings.json は使い始めたが、hooks はまだ手を出せていない方
• 「コードを編集したら毎回フォーマッターを手で走らせている」方
• 「Claude にお願いしても、たまにやってくれない作業」を確実に自動化したい方

【注意点】
– この記事は Claude Code（デスクトップアプリ版 / CLI）が対象です。
– hooks は任意のシェルコマンドを自動実行する機能です。安全に関わる注意点を後半にまとめています。設定する前に必ず目を通してください。

前回の記事「CLAUDE.md と settings.json の使い分け」の最後で、settings.json の設定項目のひとつとして hooks に少しだけ触れました。

CLAUDE.md と settings.json の使い分け──Claudeに制約を持たせる2つの方法

こんな方に読んでほしいClaude Code を使い始めて、毎回同じ指示を出していることに気づいた方「Claude に好き勝手なコマンドを実行させたくない」と感じている方CLAUDE.md と settings.json の違いがよくわから…

middle-se-learn.com

2026.05.31

hooks は少し上級向けの機能ですが、「コード変更後に自動でフォーマッターを走らせる」といった使い方ができます。

このとき、よくわからないと感じた方も多いと思います。
この記事では、その hooks を解説します。仕組みの説明から、コピペで試せる設定例、そして「最初の一歩」まで順を追って紹介します。

hooks とは何か

一言でいうと、hooks は Claude Code の特定のイベントのタイミングで、自動的にシェルコマンドを実行する仕組みです。

たとえば「Claude がファイルを編集した直後に、自動でフォーマッターを走らせる」「危険なコマンドを実行しようとした直前に、それをブロックする」といったことができます。

ポイント

hooks を理解するうえで大切なのは、実行するのは Claude（AI）ではなく、Claude Code の実行環境だということです。

前回の記事で、CLAUDE.md と settings.json の違いをこう整理しました。

• CLAUDE.md は Claude への「お願い」。高い確率で従ってくれるが、保証はない。
• settings.json の permissions は権限の制限。技術的に強制される。

hooks はこの2つとはまた別の性質を持っています。「指定したイベントが起きたら、Claude の判断を介さず必ずコマンドが実行されます。」

「お願いベースだと、たまにやってくれない」という作業こそ、hooks の出番です。AI の気まぐれに左右されず、決められたタイミングで決められた処理が確実に走ります。

動きのイメージ

hooks の動きを図にすると、こんな流れです。

ユーザー操作 / Claudeの動作
        ↓
［イベント発火］ ← 例: ファイルを編集した直後
        ↓
hook（自分で決めたコマンド）が自動実行
        ↓
例： prettier でフォーマット / 危険コマンドをブロック / 通知を出す

「あるタイミングをきっかけに、自分で決めたコマンドが自動的に実行される」──これが hooks の仕組みになります。

どんなタイミングで動かせるのか

hooks を設定できる「タイミング（イベント）」は、実は20種類以上あります。ただ、いきなり全部を覚える必要はありません。まずは次の5つだけ押さえておけば十分です。

ここで「ツール」とは、Claude がファイルを編集する（Edit / Write）、コマンドを実行する（Bash）といったClaude の操作の単位だと思ってください。

表のいちばん右、「処理を止められる？」の列がポイントで、PreToolUse のような「〜する前」のイベントは、その操作自体をブロックできます。一方 PostToolUse（〜した後）は、すでに起きたことに反応するだけなので止められません。

他にも、Claude が応答を終えたとき（Stop）、サブエージェントが終わったとき（SubagentStop）、コンテキストが圧縮される前（PreCompact）など、細かいイベントがあります。慣れてきたら公式ドキュメントで探してみてください。

設定の書き方

hooks は、 settings.json の中に書きます。

どこに置くか（おさらい）

settings.json には置き場所が3つあり、より具体的な場所が優先されます。

~/.claude/settings.json        ← 全プロジェクト共通（自分用）
.claude/settings.json          ← プロジェクト共通（チームで共有）
.claude/settings.local.json    ← 自分だけの設定（.gitignore推奨）

最初に試すときは、自分専用の ~/.claude/settings.json に書くのがおすすめです。

基本の構造

hooks の設定は、次のような形をしています。最初は少しごちゃっと見えますが、分解すれば単純です。

{
  "hooks": {
    "イベント名": [
      {
        "matcher": "対象を絞る条件",
        "hooks": [
          {
            "type": "command",
            "command": "実行したいシェルコマンド"
          }
        ]
      }
    ]
  }
}

各部分の意味は以下の通りです。

• イベント名： 上記で紹介したPostToolUse などを入れます。「いつ動かすか」です。
• matcher： どのツールに反応するかを絞る条件です。たとえば Edit|Write なら編集系の操作、Bash ならコマンド実行に反応します。省略すると、そのイベントのすべてに反応します。
• type： 実行方式です。シェルコマンドを動かすなら "command" を指定します。
• command： 実際に走らせたいコマンドです。ここに自分のやりたい処理を書きます。

「いつ（イベント名）・何に対して（matcher）・何を実行するか（command）」の3点セットで作成するようになります。

設定例

実際に使える設定例を3つ紹介します。それぞれ「目的 → 設定 → 何が起きるか」の順で見ていきましょう。

例① ファイルを編集したら自動でフォーマット

hooks のいちばんの定番がこれです。コードを修正してもらった後に、prettierやeslintなどのフォーマッターを実行して整形してもらいます。

目的： Claude がコードを編集するたびに、Prettier で自動的に整形してほしい。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

何が起きるか： Claude がファイルを編集（Edit / Write）するたびに、その編集対象ファイルに自動で Prettier がかかります。「整形して」とお願いしなくても、毎回きれいに整います。

少し補足すると、hook には「どのファイルを編集したか」といった情報が JSON 形式で渡されます。上のコマンドの jq -r '.tool_input.file_path' は、その情報から「編集されたファイルのパス」を取り出している部分です。取り出したパスを prettier --write に渡して整形しているわけです。ここは「そういうものか」とだけ理解しておけば大丈夫です。

例② 危険なコマンドをブロックする

次は「〜する前」のイベント、PreToolUse を使った例です。

目的： rm -rf のような破壊的なコマンドは、実行される前に止めたい。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '破壊的なコマンドをブロックしました' >&2; exit 2"
          }
        ]
      }
    ]
  }
}

ポイント： PreToolUse の hook で終了コード 2 を返すと、その操作をブロックできます。exit 2 の部分がそれです。また >&2（標準エラー出力）に書いたメッセージは、ブロック理由として Claude に伝わります。

⚠️ この例はあくまで説明用に単純化しています。 このまま使うと、すべての Bash コマンドがブロックされてしまいます。実際には「rm のときだけ止める」よう条件を加えるか、前回紹介した permissions の deny ルールと組み合わせるのが現実的です。「危険な操作を実行前に止められる」という仕組みの感覚をつかむための例として見てください。

例③ Claude が入力待ちになったら通知する

最後は便利系の例です。Notification イベントを使います（macOS 向け）。

目的： 長い作業を任せている間、Claude が確認待ちになったらすぐ気づきたい。

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

何が起きるか： Claude が通知を出すタイミング（権限の確認待ちなど）で、Mac の通知センターにメッセージが表示されます。席を外していても、Claude が止まったことに気づけます。

この例では matcher を省略しているので、すべての通知に反応します。

知っておきたい注意点

hooks は強力な機能ですが、そのぶん注意点もあります。設定する前に、ここは必ず読んでおいてください。

① 任意のシェルコマンドを、確認なしで実行する

hooks に書いたコマンドは、あなたへの確認なしに自動で実行されます。これは便利な反面、ファイルの削除やデータの外部送信といった操作も書けてしまう、ということです。

特に、他人が作った settings.json や、ネットで拾ったプロジェクトの hooks を、中身を読まずに使うのは危険です。 何が実行されるのか、必ず自分の目で確認してから使いましょう。

② スクリプトは絶対パスで指定する

hook から自作のスクリプトを呼び出す場合は、相対パスではなく絶対パスで指定しす。

"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/my-script.sh"

$CLAUDE_PROJECT_DIR はプロジェクトのルートを指す変数です。相対パスで書くと、意図しない場所で実行されてしまうリスクがあります。

③ hooks は「最後の安全装置」ではない

hooks はあくまで自動化の仕組みです。「絶対に守らせたい禁止事項」は、前回紹介した settings.json の permissions: deny と組み合わせて二重に守るのが安心です。

⚠️ hooks は強力ですが、設定を間違えると毎回エラーが出たり、意図せず処理が止まったりします。まずは自分用（~/.claude/settings.json）に1つだけ入れて、動きを確かめながら進めるのがおすすめです。

最初の一歩

「何から始めれば？」と思われたら、害がなくて効果が目に見える「例①の自動フォーマット」がおすすめです。

次の3ステップで試してみてください。

1. ~/.claude/settings.json を開く（なければ新規作成。またはClaudeに作ってもらいます）
2. 例①の hooks ブロックを貼り付けて保存する
3. Claude にJavaScriptコードを1回編集してもらう → 保存後に自動で整形されれば成功です

下記のようにhooksが実行されたログが表示されれば成功です。

※settings.jsonをセッション途中で新規作成すると、hooksが実行されないことがあります。
　その場合は、Claudeを再起動すると実行されるようになります。

まとめ

hooks は使い方が難しいと思われるかもしれませんが、まずは気軽に試して「自動で動く」便利さを体感してみてください。