Claude Code を1〜2か月使って、hook / MCP / skill / sub-agent のいずれかを自分で設定したのに「設定したはずなのに発動しない」事象に遭遇している中級ユーザー向け
hook / MCP / skill / sub-agent の設定が「無言で発動しない」事象に当たって、/context・/memory・/hooks・/mcp・/doctor の静的確認系では原因が絞れなかった時に叩く。コマンドを叩いた後で対象事象をもう一度再現してから「ログ読んで」と頼むのが基本動線。最初から全部ログが欲しいなら /debug ではなく claude --debug で起動し直す。MCP だけ追いたい時は claude --debug mcp、hook の評価ログを細かく追いたい時は claude --debug hooks を使い分ける。
Claude Code に同梱されている診断用 skill のひとつで、「設定はしたのに動いていない」事象を解きほぐすために使います。具体的には、セッションの中で取れていなかった内部ログをこの瞬間から有効化して、そのログと settings.json の中身を Claude に読ませて原因を当てさせる、という流れを1コマンドで開始します。
主に hook / MCP / skill / sub-agent あたりを設定したのに沈黙して発動しない時の、最終手前の一手です。
噛み砕くと
イメージとしては、家電が動かない時に修理屋を呼ぶ感覚に近いです。/debug を叩くと、Claude がこのセッションの中で「内蔵カメラを回す」モードに入ります。録画が始まるのはコマンドを叩いた瞬間からで、それ以前の挙動は残っていません。
だから先に状況を1行説明して、もう一度問題を再現させて、そのうえで「読んで」と頼む流れになります。
大事な前提：このコマンドは「事象を再現できる状態」じゃないと意味が薄い
通常起動した Claude Code は、内部の詳細ログを取っていません。/debug を叩いた瞬間からログ取得が始まるので、叩く前に1回起きた事象はもう記録に残っていない、と思った方が正確です。
なので診断したい現象を、コマンドを叩いた後でもう一度起こせる状態を作ってから入る、というのが基本動線です。逆に最初から全部のログが欲しい場合は、起動時に claude --debug を渡してセッション全体を debug モードで立ち上げる方が確実です。
「PR を出す前に lint を自動で走らせる hook が発動しない」を例に、実際の手順を見る
ここでは、Edit ツールが走る前に lint を1回挟みたくて PreToolUse hook を settings.json に書いたのに、何度ファイルを編集しても hook が呼ばれない、という設定済みユーザーがよく踏むシーンを追います。
ステップ1: まず先に静的な確認系で詰めるところまで詰める
いきなり /debug に行くと、Claude が読むログが薄くて分析範囲が広がります。先に下記の確認系を一通り当てて、それでも原因が見えない時の最後の一手が /debug という順番です。
| 叩くコマンド | 何が見える | 使う場面 |
|---|---|---|
/context |
今 Claude に渡っている全部。system prompt、memory、skills、MCP、messages | 「私の指示が伝わってない気がする」最初の入口 |
/memory |
読み込まれた CLAUDE.md / rules / 自動メモ |
CLAUDE.md の内容が無視されている時 |
/skills |
利用可能な skill 一覧 | 特定の skill が発動しない時 |
/hooks |
登録済み hook 一覧と matcher の中身 | hook が発動しない時。matcher 誤記の検知も含む |
/mcp |
接続中の MCP サーバー一覧 | MCP のツールが Claude 側に出てこない時 |
/doctor |
設定ファイル全般の検証。schema エラーやインストール健全性 | 上記で見つからない、設定ファイルそのものが怪しい時 |
/debug [issue] |
セッションのデバッグログ有効化と Claude による分析 | 上の単体確認系で原因が絞れなかった時の「次の一手」 |
今回は /hooks で hook 自体は登録されていることは確認できた、/doctor でも schema エラーは出なかった、という前提で進めます。
ステップ2: 状況を1行で説明しながらコマンドを叩く
診断の焦点を絞るために、何が起きているかを [description] 部分に書きます。空でも叩けますが、書くか書かないかで Claude の分析範囲が桁違いに変わります。
/debug pretooluse hook for edit never firesこれでこのセッションのデバッグログ取得が ON になります。Claude 側からは「了解、ログ取得を開始しました。再現してください」のような応答が返ります。
ステップ3: 事象を再現する
診断モードに入った後で、対象の操作を1回やります。ここでは Claude にファイル編集を頼みます。
適当な .py ファイルの末尾に空行を1つ足してくださいClaude が Edit ツールを呼びます。ここで本来なら PreToolUse hook が走って lint コマンドが先に動くはずですが、今回は何も走らずに編集だけ完了します。これで「hook が呼ばれなかった」というログが debug ログに残ります。
ステップ4: Claude に分析させる
診断材料が揃ったので、続けて Claude にお願いします。
いま編集した時の hook 評価ログを読んで、なぜ PreToolUse hook が発動しなかったか原因を特定してくださいClaude は debug ログと settings.json の場所を辿って読み、判定結果を返します。今回のシーンでは「settings.json の matcher が edit|write と小文字で書かれているけど、Claude Code がツール名と突き合わせる時の表記は Edit / Write と先頭大文字なので、matcher にヒットせず hook がスキップされていた」のような形で当ててきます。
ステップ5: 修正案を当てて再現確認する
Claude の指摘に従って settings.json の matcher を "Edit|Write" に直して保存します。同じセッションのまま、もう一度 Edit を伴う操作を頼んで、今度は lint が先に走ることを確認します。debug ログにも matcher にヒットして PreToolUse が評価された痕跡が残るので、対策が効いたかどうかをログレベルで裏付けできます。
ステップ6: 必要なら起動側に切り替える
初心者がやりがちな勘違いとして、「セッション中盤の /debug で過去ログも遡って読める」と思ってしまうケースがあります。debug ログはコマンドを叩いた瞬間から先しか取られないので、起動時から全部欲しい場合は素直にいったん Claude Code を終了して、次のように起動し直します。
claude --debugMCP まわりだけ追いたい時は、対象を絞った起動コマンドが使えます。hook の評価ログを起動直後から細かく追いたい時も、同じ形式で hooks 専用モードを指定できます。
claude --debug mcp
claude --debug hooksつまり /debug は何をしてくれるのか
- やってくれる: そのセッションのデバッグログを今この瞬間から有効化し、ログと
settings.jsonの内容を Claude に読ませて、どこで詰まっているかの仮説と修正案を返す - やってくれない: コマンドを叩く前に起きた事象のログを遡って復元することはしない。起動時から取りたいなら
claude --debug側 - 意味が薄い場面: 事象を再現する手段がない時、たとえば一度しか起きなかったクラッシュなど。MCP まわりだけ追いたい時は
claude --debug mcpで起動した方がstderrまで取れて早い。hook の評価ログを細かく追いたい時もclaude --debug hooksで起動する手がある
使いどころ3シナリオ（具体題材で再現）
シナリオ1: settings.json に書いた PreToolUse hook が無言で発動しないとき
上の実演そのものです。/hooks で登録は見える、/doctor で schema は通る、なのに走らない、というケース。matcher の大文字小文字違いや、command 側のファイル場所の書き間違いを debug ログから当てさせます。「Edit を頼んでも lint が走らない」現象を、診断モードで Edit をもう一度再現してログを取って、その場で Claude に原因を読ませる、の3手で詰まる原因にたどり着けます。
シナリオ2: 自作の sub-agent を呼んだのに想定とまったく違う返事が来るとき
「料理ブログ用の食材表記チェック sub-agent」を作って /agents で呼んだのに、なぜか毎回「食材リストの確認はしません」と返してくる、というケース。/debug sub-agent ingredient-checker returns wrong reply でログ取得を開始して、もう一度呼ばせます。Claude が .claude/agents/ 配下の md ファイルの読み込み結果と評価された system prompt を突き合わせて、「実は別ファイルが優先されている」「指示の途中に YAML の閉じ忘れがあって system prompt が途切れている」みたいな原因を返してきます。
シナリオ3: MCP サーバーは接続済みなのにツール一覧が空のとき
家計簿アプリの開発で SQLite 用の MCP サーバーをつないだのに、/mcp 上は connected と出ているのに、ツール一覧が0個。この場面では /debug 単体では弱いです。MCP サーバーの stderr 出力はセッション中の /debug では取れないので、いったん終了して claude --debug mcp で立ち上げ直して、サーバーの起動エラーを直接見る方が早いです。先に /mcp の Reconnect を試して、それでも0件のままなら起動側に切り替える、というのが公式の推奨手順です。
初心者が踏みやすい落とし穴
- コマンドを叩く前のログは取れていない。通常起動の Claude Code はデバッグログが off で、
/debugを叩いた瞬間からしか記録されない。叩く前に1回だけ起きた事象は、もう材料として残っていない - 叩いてすぐ「直して」と頼むと空ログを読むだけになる。診断したい事象を、コマンドを叩いた後でもう一度起こしてから分析を頼む、という順番が必要
/doctorと混同しがち。/doctorは設定ファイルの schema 検証とインストール健全性確認の静的チェック、/debugは実際の挙動ログを取って分析する動的チェック。役割が違うので両方使う場面がある- MCP サーバーの stderr はセッション中の
/debugでは取れない。MCP の起動失敗を追う時はclaude --debug mcpで立ち上げ直す方が早い。同様に hook の評価ログを細かく追いたい時はclaude --debug hooksという形式もある。公式 docs の hooks セクションが「Start a session withclaude --debug hooksand trigger the tool call. The debug log records each event, which matchers were checked」と明示している [description]を端折ると分析範囲が広がりすぎる。任意とはいえ「hook が発動しない」と1行書くか書かないかで Claude の絞り込み精度が大きく変わる。/debug pretooluse hook for edit never firesのように具体的に書いた方が、ログから該当箇所を絞って読んでくれる- セッションを跨ぐと debug 設定はリセットされる。次のセッションでも詳細ログが欲しい場合は再度叩くか、起動時に
claude --debugを渡す
書き方
/debug [description]やってみるとこうなる
入力
/debug pretooluse hook for edit never fires出力例
了解、このセッションのデバッグログ取得を開始しました。問題の事象（PreToolUse hook が Edit ツールに対して発動しない件）を再現してください。再現後、ログを読んで matcher・command・条件分岐のどこで弾かれているかを特定します。このページに出てきた言葉
- skill
- Claude Code に同梱されている「特定用途向けの事前指示書」。<code>/debug</code> もこの形式で配布されている bundled skill のひとつ
- hook
- <code>settings.json</code> に書いておく、特定のタイミング（例: Edit ツール実行直前）で自動的に走る仕掛け
- matcher
- hook で「どのツールに対して発動するか」を絞る条件文字列。例: <code>"Edit|Write"</code> と書くと Edit ツールと Write ツールの直前に hook が走る
- MCP
- 外部ツールを Claude Code から呼べるようにする仕組み。Model Context Protocol の略
- settings.json
- Claude Code の設定をまとめて書いておくファイル。ユーザー単位とプロジェクト単位の2か所がある
- debug ログ
- Claude Code が内部で何をやっているか（どの設定を読んだ、どの hook を評価した、どの skill を判定した等）を細かく書き出したテキストの流れ
- stderr
- プログラムがエラー時に出力する文字列の流れ。通常出力 stdout とは別の経路で出てくる
- PreToolUse hook
- Claude Code が何かツールを呼ぶ直前に割り込ませる種類の hook。lint・型チェック・危険コマンドのブロックなどに使う