「直して」だけだと、なぜうまくいかないのか
Claude Code にバグ調査を頼むとき、つい このエラー直して とログを貼って終わりにしてしまいがちだ。これでもそれっぽい修正は返ってくるが、こういう頼み方には構造的な弱点がある。
- 再現条件が共有されていないので、Claude が「たぶんこういうケースだろう」と推測で直す
- 直った確認手段がないので、直ったかどうかが分からないまま会話が進む
- 表面のエラーメッセージだけ消して、根本原因が残る
人間の優秀なエンジニアにバグ調査を頼むときも、いきなり「直して」とは言わない。再現手順を渡し、仮説を立てさせ、検証してから最小限の修正を入れる。Claude Code に対しても同じで、頼み方を体系的にするだけで調査の質が安定しやすくなる（効果は対象コードやログの量によって変わる）。
この記事では、その「頼み方の型」をプロンプト例つきで整理する。
全体の型：再現 → 仮説 → 検証 → 最小修正
まず指示の骨格を1つのプロンプトとして渡してしまうのがおすすめだ。
次のバグを調査してほしい。いきなり修正コードは書かないで、次の順で進めて：
1. 再現：このバグが起きる条件を、入力・状態・手順として言語化する
2. 仮説：原因の候補を複数挙げ、それぞれの根拠（コードの該当箇所）を示す
3. 検証：仮説を切り分けるために、どこを確認すれば良いか述べる
4. 最小修正：原因を1つに絞れたら、影響範囲が最小の修正案を出す
各ステップが終わったら一度止まって、私の確認を待って。
ポイントは 「いきなり修正コードを書かないで」 と明示することと、ステップごとに止めさせること。Claude Code は放っておくと一気に修正まで走ることがあるので、調査フェーズと修正フェーズを分けるよう言葉で区切る。
ログの渡し方：全文よりも「文脈つき」で
ログは雑に貼るより、何のログか・いつ取れたものかを添えると切り分けが速くなりやすい。
悪い例：エラーメッセージ1行だけ貼る。
良い例：
再現したときのスタックトレース全文（先頭から末尾まで）はこれ：
```
TypeError: Cannot read properties of undefined (reading 'id')
at formatUser (src/user/format.ts:42)
at ...
```
このときの入力は user = null だった。
直前のログでは fetchUser が 200 を返しているのに本体が空だった。
```
スタックトレースは省略せず先頭から末尾まで渡す。途中を省くと、Claude がフレームを推測で補完してしまうことがある。長くてコンテキストを圧迫する場合は、関係しそうな範囲を自分で切り出すより、このログをファイルに保存したので読んで とログファイルのパスを渡し、Claude 自身に読ませる方が扱いやすい。
debug.log にエラー時のログを出力した。読んで、エラーに関係する行だけ抜き出して原因の手がかりを挙げて。
Claude Code はワークスペース内のファイルを直接読めるので、長いログはファイル渡しが扱いやすい。
再現手順を言語化させる
「再現できないバグは直せない」のは AI でも同じだ。再現条件が曖昧なときは、まず Claude に再現手順を文章化させる。
このバグの再現手順を、私が手で再現できるレベルまで具体化して。
- 必要な前提状態（DB・環境変数・ログイン状態など）
- 操作の手順
- 期待される結果と、実際に起きる結果
不明な前提があれば、推測せず質問して。
不明な前提があれば質問して を入れておくと、勝手に前提を決めつけて進むのを抑えやすい。返ってきた再現手順を自分で一度試し、「ここまでは再現する／しない」を Claude にフィードバックすると、仮説を絞り込みやすくなる。
原因に踏み込ませるプロンプト
表面のエラーを消すだけの修正を避けるには、「なぜそうなるか」を言わせる。
このエラーの根本原因を特定して。
- 「なぜ user が undefined になるのか」を、コードを辿って説明して
- 症状（エラーメッセージ）への対症療法ではなく、原因そのものを指して
- 原因が複数あり得るなら、どれが今回のケースか切り分ける方法も
対症療法ではなく原因を と明示するのが効きやすい。例えば「user?.id にすればエラーは消えるが、それは本当に null が来るのが正しいのか？」まで踏み込ませると、fetchUser が空ボディを返すのがそもそもおかしい のような上流の原因にたどり着きやすくなる。
テストで固定してから直す
ここが個人的にいちばん効いていると感じる手順だ。直す前に、バグを再現する失敗テストを先に書かせる。
修正する前に、このバグを再現する失敗テストを1つ書いて。
- 今は失敗する（赤になる）ことを確認して
- そのテスト名・内容を見せて
- 確認できたら止まって。修正はその後で。
テストが赤になるのを確認してから修正に進むと、
- バグが本当に再現できている証拠になる
- 修正後に同じテストが緑になれば、直った証拠になる
- 将来の再発（リグレッション）も検知しやすくなる
修正フェーズはこう続ける。
さっきの失敗テストが通るように、最小限の修正を入れて。
- 既存の他のテストを壊していないか、テスト全体を実行して確認して
- 関係ない箇所のリファクタは今回はしないで
最小限 関係ないリファクタはしない と縛ると、調査のついでにあちこち書き換えられて差分が膨らむのを防ぎやすい。テスト実行も Claude Code に任せられるので、テストを実行して結果を見せて まで含めて頼むと、修正と検証が1往復で回しやすい。
修正案は「適用前にレビュー」する
最後に、修正を適用させる前に差分の意図を説明させる。
適用する前に、変更する差分とその理由を説明して。
- どのファイルの何を、なぜ変えるのか
- この修正で再現テストが通る理由
- 副作用が出そうな箇所はあるか
差分の意図を言語化させると、こちらも妥当性を判断しやすいし、Claude が「とりあえず通ったから OK」で進むのを防ぎやすい。納得できたら OK、適用して で進める。
まとめ：頼み方をテンプレ化しておく
バグ調査は、毎回ゼロから指示を考えるより型を1つ持っておくと楽になる。要点はこれだけだ。
- いきなり修正させない（調査と修正を分ける）
- ログは全文＋文脈、長ければファイルで渡す
- 再現手順を言語化させ、自分でも再現する
- 対症療法でなく根本原因を言わせる
- 失敗テストで固定してから、最小修正する
- 適用前に差分の意図をレビューする
この型をプロジェクトの CLAUDE.md に「バグ調査の進め方」として書いておくと、毎回貼らなくても Claude Code が踏襲してくれて運用しやすい。
こうした「Claude Code への頼み方」を再利用できる形にしたものを、無料の GitHub リポジトリ claude-code-skills-starter で4つの Claude Code スキルとして公開しています。Claude Code の実践的な使い方は X @k___n___t_1125 でも発信中です。