前回の学習編で、Hooks は「決まったタイミングで、AIの判断を待たず必ず動く仕組み」だと整理しました。言葉だけでは手応えがないので、今回は実際に1つ仕込んでみます。題材は定番の「ファイルを編集したら、自動でチェックを走らせる」。ポイントは、設定ファイルを自分で開かず、すべて Claude Code に言葉で頼んで進めることです。

ひとことで言うと：「編集したら自動でチェックして」と言葉で頼むだけで、settings.json にフックが書き込まれた。ただし最初は動かず、原因は「①設定の反映に再起動が要る」「②matcher が実際のツール名と合っていない」の2つ。確実に動くからこそ、対象と中身は具体的に伝えるのがコツ。

このシリーズ（全13回＋番外編・拡張編）

  1. 基礎 ― 全体像と拡張機能の地図
  2. Skills（学習編）― 繰り返す手順を覚えさせる
  3. Skills（実践編）― 作って、つまずいて、直す
  4. Subagents（学習編）― 作業を別の文脈に切り出す
  5. Subagents（実践編）― 温泉宿を調べて比較する
  6. Hooks（学習編）― 特定のタイミングで自動実行する
  7. Hooks（実践編）― 編集したら自動でチェックを走らせる（この記事）
  8. MCP（学習編）― 外部サービスへの接続口
  9. MCP（実践編）― Google ドライブ連携でつまずいた話
  10. Plugin（学習編）― 作った部品をひとつの箱にまとめる
  11. Plugin（実践編）― 便利設定を箱に詰めて配る
  12. Marketplace（学習編）― 箱を並べて配る
  13. Marketplace（実践編）― お店に公開し、取り込む
  14. 番外編 ― 拡張機能の選び方チートシート
  15. 拡張編① Agent Teams（学習編）― 複数のAIをチームで動かす
  16. 拡張編② Agent Teams（実践編）― 3人チームで多角的にレビューする

作りたいもの ― 「書いたら、勝手に確認」

ゴールはシンプルです。Claude がファイルを書き込んだ直後に、決めておいたチェック（ここでは「変更されたファイルの一覧を出して、簡単な確認メッセージを表示する」程度の軽いもの）を毎回自動で走らせる。お願いし忘れても抜けない——これが Hooks の値打ちでした。

まずは“読むだけ・表示するだけ”から。 いきなり整形やテストのような重い処理を仕込むと、うまくいかないときに切り分けづらくなります。最初は「メッセージを出すだけ」「変更点を一覧するだけ」の無害なフックで、仕組みが動くことを確かめるのが安全です。

STEP1｜「フックを設定して」と言葉で頼む

設定は settings.json というファイルに書きますが、自分で開く必要はありません。Claude Code 本人に、やりたいことを具体的に伝えて頼むだけです。実際に打った指示はこれです。

ファイルを編集したら自動でチェックを走らせるフックを設定したいです。 プロジェクトの .claude/settings.json に、PostToolUse フックを追加してください。 ・対象（matcher）は Write と Edit ・実行する処理は、変更が入ったことを知らせる簡単なメッセージ表示でOK 既存の設定は壊さないように。追加できたら中身を見せてください。

こう頼むと、Claude が設定ファイルを開いて、次のような内容を書き加えてくれます。「どのイベントで・何に反応して・何をするか」という、学習編で見た3点セットがそのまま形になっています。

{ "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "echo '✅ ファイルを更新しました' " } ] } ] } }

難しい文法を覚えていなくても、やりたいことを日本語で伝えれば、正しい書式に翻訳して書き込んでくれる。これが「ターミナルを開かずに完結する」ということです。

STEP2｜動かしてみる（そして、動かない）

さっそく試します。Claude に適当なファイルを1つ作らせて、フックが反応するかを見ます。

> テスト用に memo.txt を作って、一行だけ書いてください。

ところが、ファイルはできたのにあの確認メッセージが出ません。学習編で「条件に合えば毎回必ず動く」と書いたはずなのに、うんともすんとも言わない。ここから切り分けが始まります。

つまずきの原因 ― 2つあった

原因1：設定を足しただけでは反映されない

フックの設定は、セッションの途中で書き換えても、その場では読み直されないことがあります。学習編で扱った Skills と同じで、いったん Claude Code を終了して立ち上げ直すと、新しい settings.json が読み込まれます。再起動して試すと、今度はファイル作成のあとに ✅ ファイルを更新しました が出るようになりました。

原因2：matcher が実際のツール名と合っていない

もう一つ引っかかったのが matcher です。フックは「どのツールに反応するか」をツール名で指定しますが、ここをあいまいに頼むと、実際とは違う名前で書かれてしまうことがあります。たとえば「保存したら」というニュアンスだけで頼むと、ファイル書き込みのツール名（Write / Edit）とずれて、いつまでも発火しません。

直し方も、やはり言葉で頼むだけです。

さっきのフックが反応しません。 ファイルの新規作成と編集の両方で発火するように、 matcher を Write と Edit の両方に直してください。

すると Claude が matcher を "Write|Edit" に修正してくれました。「何に反応してほしいか」を具体的に伝える——これが、確実に動くフックを作る一番のコツでした。

教訓：フックは“確実に動く”からこそ、対象と中身は具体的に。 Skills は多少あいまいでも空気を読んでくれますが、Hooks は機械的なルールです。「いつ・何に・何をするか」がぼんやりしていると、動かないか意図しない場面で動くかのどちらかになります。頼むときは具体的に、そして最初は無害な処理で試すのが安全です。

うまくいかないときの確認手順

  1. まず再起動を疑う。 設定を足した直後は反映されていないことがあります。Claude Code を開き直してから試します。
  2. matcher を見直す。 「思った場面で発火しない」ときは、対象のツール名がずれている可能性大。「ファイル編集で動かして」と具体的に直してもらいます。
  3. 処理を単純化して切り分ける。 重い処理が失敗しているのか、フック自体が発火していないのかを分けるため、まず「メッセージを出すだけ」に落として動作を確認します。
  4. 設定ファイルの場所を確認する。 プロジェクト用（.claude/settings.json）と自分の全体用（~/.claude/settings.json）があります。「いまのプロジェクトにだけ効かせたい」のか「常に効かせたい」のかを伝えて、置き場所を選んでもらいます。

仕組みが動いたら ― 実用フックに育てる

無害なフックで仕組みを確認できたら、あとは中身を入れ替えるだけです。これも言葉で頼めます。たとえば、

  • 「コードを書き換えたら、自動で整形（フォーマッタ）を走らせて」
  • 「危ないコマンドを実行しようとしたら、その前に止めて確認して」
  • 「作業が終わったら、変更したファイルの一覧をまとめて」

いずれも「いつ・何に反応して・何をするか」を具体的に伝えれば、Claude が settings.json に落とし込んでくれます。整形・チェック・ガードレールのように「抜けると事故になる」処理ほど、お願いベースではなくフックに寄せておくと安心です。

まとめ ― 言葉で頼み、具体的に伝える

  • フックの設定は ターミナルを開かず「こういうフックを設定して」と頼むだけ。Claude が settings.json に書き込む。
  • 足した直後は反映されないことがある。まず再起動を疑う。
  • 発火しないときは matcher（反応する対象）がずれていることが多い。対象を具体的に伝えて直す。
  • 最初は無害な処理で仕組みを確認し、動いてから整形・チェックなどの実用フックに育てる。

次回からは、ここまで作ってきた部品（Skills・Subagents・Hooks・MCP）をまとめて配る仕組みへ進みます。まずは Plugin（学習編） で「箱に詰める」考え方を押さえます。