Claude Code の hooks でできること

2026/5/23

Claude Code の hooks（フック） は、「特定のタイミングで、自動的に決まったコマンドを実行する」仕組みです。設定ファイル settings.json に書いておくと、ツールの実行前後やセッションの開始時などに、自分で用意したスクリプトが走ります。

ポイントは、これを実行するのが Claude 本体ではなく、ハーネス（Claude Code の実行環境） だということ。「今後、ファイルを編集したら必ずフォーマッタをかける」のような 毎回確実に 起きてほしい自動化は、お願いベースの CLAUDE.md やメモリでは保証できません。ハーネスが機械的に実行する hooks だからこそ実現できます。

この記事では、hooks で何ができるのかを、個人開発者が実際に使いたくなる例を中心に整理します。対象は Claude Code v2.1.148 時点。組み込みスキルやスラッシュコマンドの一覧は別記事（組み込みスキル 10 個／スラッシュコマンド 30 個）に、毎回読まれる指示書 CLAUDE.md との使い分けはCLAUDE.md には何を書くべきかにまとめています。

フックが動くタイミング

hooks は「イベント」に紐づきます。主なものは次のとおりです。

イベント	発火するタイミング	実行を止められるか
`SessionStart`	セッションの開始・再開時	×
`UserPromptSubmit`	あなたがプロンプトを送信した時	○
`PreToolUse`	Claude がツールを実行する直前	○
`PostToolUse`	ツールが成功した後	×
`Stop`	Claude が応答を終えた時	○
`Notification`	通知が発生した時	×

このほか、ツール失敗時（PostToolUseFailure）やサブエージェントの開始・終了（SubagentStart / SubagentStop）などのイベントもあります。「実行を止められる」イベント（PreToolUse など）では、フックから操作をブロックできます（後述）。

設定の最小形

hooks は settings.json の hooks キーに書きます。「Bash ツールを使う直前に、あるスクリプトを走らせる」なら、最小形はこうです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/check.sh" }
        ]
      }
    ]
  }
}

matcher … 対象のツール名。"Bash" のような完全一致、"Edit|Write" のように | 区切り、"*"（または省略）で全ツールが対象になります。
command … 実行するスクリプト。${CLAUDE_PROJECT_DIR} でプロジェクトのルートを参照できます。スクリプトには、どのツールがどんな引数で呼ばれたかが、JSON で渡されます。

settings.json を直接編集するのが不安なら、Claude Code に「〜したらフックで〜して」と頼めば、組み込みスキルの /update-config が設定を書いてくれます。

個人開発者の実用例

1. 危険なコマンドをブロックする

PreToolUse で Bash を対象にし、渡されたコマンドを検査します。rm -rf のような危険な操作だったら、フックを失敗させて実行を止める。AI に任せきりにする前の、安全網になります。

2. 編集のあとに自動でフォーマットする

PostToolUse で Edit|Write を対象にし、prettier や linter を走らせます。Claude が書いたコードのスタイルが、毎回自動でそろいます。

3. 作業の完了を通知する

Stop（応答完了時）でデスクトップ通知や音を鳴らします。Claude に長い作業を任せて別のことをしている間でも、終わったタイミングが分かります。

4. コミット前にチェックを走らせる

PreToolUse で Bash を見張り、git commit を検知したら lint やテストを実行。失敗したらコミットを止めます。壊れたコードが履歴に入るのを防げます。

5. セッション開始時にセットアップする

SessionStart で、環境変数の確認や依存関係のチェックを自動実行。毎回のセッションを、整った状態から始められます。

ブロックの仕組み（止めたいとき）

「フックで操作を止めたい」ときは、スクリプトの 終了コード が鍵になります。

終了コード 0 … 成功。問題なし、そのまま進む
終了コード 2 … ブロック。操作を止め、エラー出力（stderr）の内容を Claude に伝える
それ以外 … エラー扱いだが、操作自体は止めない

つまり「危険なら止める」フックは、検査して問題があれば exit 2 を返すスクリプトを書けば成立します。難しい仕掛けは要りません。

まとめ

hooks は、「お願い」ではなく「仕組み」で動く自動化です。CLAUDE.md が Claude に読んでもらう指示書 なのに対して、hooks は ハーネスが機械的に実行する処理。だから「毎回、必ず」が要るところに使います。

まずは実用例 1（危険なコマンドのブロック）か 2（編集後の自動フォーマット）あたりから、settings.json に 1 つ足してみるのが、いちばん体感しやすい入り口です。

サブエージェントごとにフックを仕掛けることもできます。サブエージェントの仕組みは、別記事 Claude Code のサブエージェントの使い方にまとめています。

#Claude Code#開発ツール#リファレンス