メインコンテンツまでスキップ

発話から skill 起動まで

ここから、1 つのバグを題材に /debug の流れを追います。このガイドを通して使う題材はこれです。

今回のバグ

ユーザー取得関数 fetchUser が、対象が見つからないとき undefined を返してしまい、呼び出し側がクラッシュする。「ときどき画面が真っ白になる」と報告が来た。

開発者がこう打ち込みます。

fetchUser が空配列のとき undefined を返してクラッシュする。直して

この一言が送信された瞬間から、ハーネスが動き始めます。

まず UserPromptSubmit hook が走る​

発話がモデルへ届く前に、UserPromptSubmit イベントの hook が必ず実行されます。この環境では promote-ultracode.sh と surface-salvage-on-resume.sh の 2 本が登録されています（登録は settings.json、詳細は hooks の仕組み）。後者はレート上限などで中断したセッションの再開時に、保存済みの調査結果へ気づける案内を 1 回だけ注入する hook なので、今回の発話では何もしません。

主役は promote-ultracode.sh（🔧 自作）です。この hook は、発話に「複数ファイル横断」「大規模リファクタ」「網羅的に」といった重いタスクを示す複合句が含まれるかを調べます。含まれていれば「ultracode（高出力 + ワークフロー化）に切り替えては？」という案内をコンテキストに差し込みます。重いタスクをそのまま単発で受けてしまい、ワークフロー化し損ねる失敗が繰り返されたため、発話の段階で誘導する仕掛けになりました。

promote-ultracode.sh（抜粋）
ULTRACODE_TRIGGER='複数ファイル|横断的|...|大規模(リファクタ|変更|改修|移行|刷新)|...'

if ! echo "$PROMPT" | grep -qiE "$ULTRACODE_TRIGGER"; then
  # 重いタスクのトリガー語なし → 注入せず通過
  exit 0
fi

今回の「1 つの関数を直して」という発話は単発タスクなので、トリガーには当たりません。hook は何もせず通過します。これは Guides と Sensors でいう Computational Guide（行動の前に、決定的に走って方向づける仕掛け）の一例です。当たらなければ静かに見送るのも仕事のうちです。

次に skill が選ばれる​

発話がモデルに届くと、「これはどの skill の出番か」が判断されます。/debug の起動口は 2 つあります。

  • 発話トリガー:「バグ」「エラー」「動かない」「失敗した」といった語を含む発話
  • 明示呼び出し: /debug と直接打つ

skill のフロントマターにある description は、skill 一覧としてあらかじめモデルに見えています。今回は「クラッシュする。直して」なので、これを根拠にデバッグ依頼として /debug が選ばれます。skill の発話トリガー機構と SKILL.md の仕様（allowed-tools / effort などのフィールド）は Claude Code 標準（📦）で、/debug の手順そのものは筆者の自作（🔧）です。

~/.claude/skills/debug/SKILL.md（フロントマター）
name: debug
description: バグ・エラー・テスト失敗の原因調査と修正 (Investigate→Fix→Verify を最大 3 反復で自律解決)。...
allowed-tools: Read, Grep, Glob, Bash, Write, Edit, WebSearch, mcp__context7__..., mcp__sequential-thinking__...
effort: max

ここで効いている要素が 2 つあります。

  • allowed-tools: この skill の作業中、列挙したツールを許可プロンプトなしで使えるようにする指定（ツールの利用範囲を制限する機構ではなく、制限する側は disallowed-tools）。/debug は調査だけでなく修正までこなすため Write / Edit を列挙している。規範として読み取り専用に徹する /review との違いがここに表れる
  • effort: max: 思考量を要する複数仮説の検証に備え、skill が active な間は session の effort 設定を上書きして最大値（low / medium / high / xhigh の上）で実行する

そして起動が決まると SKILL.md の本文がロードされ、そのまま作業手順になります。/debug の場合は「Investigate（調査）→ Fix（修正）→ Verify（検証）を最大 3 回まで反復する」という構造化されたワークフローです。

SKILL.md の workflow（抜粋）
1. Step 0 (MCP 起動): sequential-thinking 強制使用 + context7
2. Step 0.5 (Spec-First): Spec drift が root cause か確認
3. エラー分類 (型/ロジック/環境/並行性) → 起点絞り込み
4. 仮説立案 (スコア × コスト で優先度付け、並列検証禁止)
5. 検証 → 真因特定 → 修正案 → Verify (pass 1)
6. 反復 (新仮説、最大 3 pass)

ここまでの流れ​

/debug skill と debugger subagent の使い分け

今回は、いま開いている環境でそのまま直す /debug skill を使います。大量のコードを別コンテキストへ隔離してじっくり調べたいなら、debugger subagent に委任します。名前は似ていますが、/debug が即時対応、debugger が隔離調査という役割分担です。

この章のまとめ

要点は次のとおりです。

  • 発話はモデルへ届く前に UserPromptSubmit hook が必ず通る（当たらなければ静かに通過）
  • skill は発話トリガー or /名前 で選ばれ、SKILL.md のフロントマターと本文が「作業の制約と手順」になる
  • effort: max で推論がブーストされ、allowed-tools で許可プロンプトなしに使えるツールが決まる

次は MCP の on-demand ロード で、/debug の最初の一手「Step 0」を見ます。