はじめてのHook教科書

まず、日常語としての「hook(フック)」の意味から始めましょう。コートを掛ける壁の金具、魚を釣る針、カーテンを吊るす金具――どれも共通しているのは「何かが引っかかったら、それに連動して別のことが起きる」という性質です。カーテンフックに布を引っ掛ければ、布は勝手に吊り下がった状態になります。

Claude Codeの「Hook」も、考え方はまったく同じです。「何か特定の出来事が起きたときに、それに引っかけて、あなたが用意した処理を自動的に走らせる仕組み」――これがHookの正体です。

🎫 中心となる比喩:駅の自動改札

この教科書では、この後もずっと「駅の改札」を例に使っていきます。まずはその土台を作りましょう。

左:むかしの改札(お願いベース) / 右:今の自動改札(機械が必ず確認)

昔ながらの改札は、駅員さんが目視で切符を確認していました。これは「ちゃんと確認してくださいね」というお願いに支えられた仕組みです。駅員さんは基本的にちゃんと仕事をしてくれますが、混雑していたり、他のことに気を取られていたりすると、うっかり見落としてしまうこともあり得ます。

一方、今の自動改札機は違います。ICカードをタッチすれば、駅員さんの気分にも忙しさにも関係なく、機械が必ずチェックしてくれます。これがHookの本質です。

「優秀な駅員さんがいるなら、それで十分では?」と思うかもしれません。ここで、よくある「あるある」を考えてみましょう。

これは、事実としてAnthropic自身も認めていることです。Claude Codeの記憶の仕組み(CLAUDE.mdや自動メモリー)は、会話のたびに読み込まれますが、Claudeはそれらを「必ず実行する強制設定」ではなく「参考にする文脈」として扱います。つまり、CLAUDE.mdにどれだけ丁寧に書いても、それは最終的にはAIの判断を経由するのです。

もし「これだけは絶対に、例外なく起きてほしい」ということがあるなら、AIの判断を経由しない仕組みが必要です。それがHookです。Anthropic自身のドキュメントでも、そのような「絶対に起きてほしいこと」にはHookを使うべきだと述べられています。

比較表でもう一段深く整理

ここからは、実際にHookがどんな「部品」でできているかを、ゆっくり分解していきます。難しく見えても、部品ひとつひとつはシンプルです。

① どこに書くのか

Hookの設定は、JSON形式のファイルに書きます。置き場所は3種類あり、「誰に対して有効にしたいか」で使い分けます。

② JSONの構造を分解する

Hookの設定は、入れ子になった箱のようなものです。外側から順番に見ていきましょう。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "実行したいコマンド" }
        ]
      }
    ]
  }
}

• "hooks" ―― 「ここからHookの設定ですよ」という一番外側の箱
• "PostToolUse" ―― いつ動くか(イベント名)。「改札の、どのタイミングのゲートか」にあたります
• "matcher" ―― 誰に対して動くか。「PASMOの人だけ対象にする改札」のような絞り込みです
• "type": "command" ―― どんな方法で処理するか。一番よく使うのは、シェルコマンドをそのまま実行するcommandタイプです
• "command" ―― 実際に駅員(コンピューター)が行う処理そのもの

③ 結果はどう伝わるのか(終了コード)

コマンドを実行した結果、Hookは「終了コード」という数字でClaude Codeに結果を伝えます。ここだけ、しっかり覚えておきましょう。

Claude Codeには、Hookを引っ掛けられる「タイミング(イベント)」が30種類ほど用意されています。全部を一度に覚える必要はまったくありません。ここでは、実務でよく使う順に、少しずつ紹介していきます。

🎫 PreToolUse ―― 改札を「通る前」

Claudeが何か操作(ファイルの編集、コマンドの実行など)をしようとする、まさに直前のタイミングです。ここでHookが「ダメ」と判断すれば(終了コード2)、その操作は実際に実行される前に止められます。改札で言えば、不正乗車をしようとした人を、ゲートの前でしっかり止めるイメージです。危険なコマンドのブロックや、秘密ファイルへのアクセス防止など、「絶対にさせたくないこと」はここで止めます。

🎫 PostToolUse ―― 改札を「通った後」

操作が終わった直後のタイミングです。ここが初心者がいちばん誤解しやすいポイントなのですが、この時点ではもう改札を通過してしまっているので、その操作自体を取り消すことはできません。ただし、「実は問題があった」とClaudeに即座に伝えることはできます。ファイル保存後の自動フォーマットや、DESIGN.mdの検証など、「やったことをチェックして知らせる」用途で使います。

その他の代表的なイベント(まずは名前だけ知っておく)

• SessionStartClaude Codeとの会話が始まった瞬間。駅が開店するタイミングです
• UserPromptSubmitあなたが指示を送った瞬間。利用者が改札に近づいてきたタイミングです
• StopClaudeが「作業完了」と判断した瞬間。その日の営業を終えるタイミングです
• NotificationClaude Codeが何かを知らせようとする瞬間。駅内アナウンスのイメージです

matcherは、「どの操作の時だけ、このHookを動かすか」を絞り込むフィルターです。改札で言えば「PASMOの人だけ」「定期券の人だけ」のように、特定の条件の人だけをチェック対象にするイメージです。

ここからは、実際の設定例を「レシピ」としてまとめました。まずは動かしてみて、感覚をつかむのが一番の近道です。

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

#!/bin/bash
# stdinからツールの入力(JSON)を受け取り、コマンド内容を確認する
INPUT=$(cat)
if echo "$INPUT" | grep -q "rm -rf"; then
  echo "危険なコマンドのため、実行をブロックしました。" >&2
  exit 2
fi
exit 0

#!/bin/bash
INPUT=$(cat)
if echo "$INPUT" | grep -q "\.env"; then
  echo ".envファイルへのアクセスは許可されていません。" >&2
  exit 2
fi
exit 0

#!/bin/bash
npx @google/design.md lint DESIGN.md
if [ $? -ne 0 ]; then
  echo "DESIGN.mdの検証エラーです。色やコントラスト比を見直してください。" >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" } ] }
    ]
  }
}

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "git log --oneline -10" } ] }
    ]
  }
}

ここまで読んで「自分で書くのは大変そう」と感じたなら、朗報があります。実は、自分でJSONやスクリプトを書かなくても大丈夫です。

1. Claude Codeに、日本語でお願いする。「ファイルを保存したら自動でPrettierを走らせるHookを書いて」のように頼むだけで、設定ファイルとスクリプトを一緒に作ってくれます。
2. まずは1つだけ試す。この章で紹介したレシピの中から、いちばん自分に必要そうなものを1つだけ選んで試してみましょう。
3. /hooksで確認する。ターミナルで/hooksと入力すれば、今どんなHookが設定されているか、一覧で確認できます。
4. 少しずつ育てる。慣れてきたら、他のレシピも1つずつ足していきましょう。