Claude Codeで曖昧な不具合を再現可能な報告に変えるバグレポートテンプレート

Claude Code のデバッグは、依頼文の時点で成功率が決まる

バグ修正を頼むときに「動きません」だけを渡すと、Claude Code は推測で走り始めます。良いバグレポートは、症状、再現手順、期待結果、実際の結果、制約、検証方法を短くそろえます。

この記事は 初回タスク実行ガイド の次に使うテンプレートです。セッションを翌日に渡すなら handoff テンプレート も一緒に使ってください。

コピペ用バグレポートテンプレート

目的:
- 直したい不具合:
- 直さないこと:

環境:
- OS / browser / runtime:
- branch:
- 関連コマンド:

再現手順:
1.
2.
3.

期待結果:
-

実際の結果:
-

ログまたはスクリーンショット:
-

制約:
- 触ってよいファイル:
- 触らないファイル:
- 外部サービスへ送信しない:

検証:
- 実行する build/test:
- 目視で確認する URL:

Claude Code への依頼:
まず原因候補を3つに絞り、最小修正案、触るファイル、検証手順を出してください。
承認するまで編集しないでください。

良い例

直したい不具合:
モバイル幅で pricing CTA が横にはみ出す。

再現手順:
1. /en/products/ を 390px 幅で開く
2. pricing card までスクロールする
3. CTA の右端が viewport を超える

検証:
npm.cmd run build
Playwright で 390px 幅のスクリーンショットを撮る

この粒度なら Claude Code は「どこを見て、何を壊してはいけないか」を理解できます。

悪い例

サイトが変です。いい感じに直して。

これは範囲、成功条件、制約がありません。モデルが優秀でも、確認不能な作業になります。

Claude Code に渡す前の確認

• 再現手順は3分以内で実行できるか
• 成功条件は1つ以上のコマンドかスクリーンショットで確認できるか
• 触らないファイルを明記したか
• 推測ではなくログや URL を含めたか

次に進むなら

よく使うコマンドは 無料 cheatsheet にまとめてください。バグ修正のプロンプトを型化したい場合は 50 Prompt Templates が近道です。チームで不具合対応の流れを整えるなら 導入相談 を見てください。

実務では原因調査と修正を分ける

バグ修正でよくある失敗は、原因が絞れていない状態で patch を作らせることです。まず再現、次に原因候補、最後に最小修正という順番を守ると、Claude Code の出力をレビューしやすくなります。

この bug report をもとに、まだ修正せずに調査だけしてください。
1. 再現できるか
2. 原因候補を3つ
3. もっとも可能性が高い箇所
4. 修正前に読むべきファイル
5. 最小修正で済むか、大きな設計変更が必要か

この段階で「再現できない」「ログが足りない」「触る範囲が広すぎる」と出たら、修正に進まないでください。良いバグレポートは、モデルに答えを急がせるものではなく、レビュー可能な調査順序を作るものです。