Claude Codeバグ報告テンプレート: 曖昧な不具合を再現できる修正依頼に変える

Claude Codeに「画面が壊れています」「テストが落ちます」とだけ渡すと、もっともありそうな修正に飛びつきます。早いように見えて、実際には原因の切り分け、検証コマンド、レビュー説明が不足し、同じバグを別の形で戻しやすくなります。

よいバグ報告は、モデルへの作文ではありません。人間の開発者にもClaude Codeにも同じように読める、再現可能な作業指示です。症状、期待結果、実際の結果、最小再現、ログ、環境、触ってよい範囲、最後に作るべき失敗テストまでそろえると、Claude Codeは「推測で直す」状態から「事実を確認して直す」状態に変わります。

この記事は、初回タスク実行ガイドの次に使うデバッグ用テンプレートです。深い調査はClaude Codeデバッグ技術へ、修正後のレビューはPR品質チェックへつなげてください。公式情報としては、Claude CodeのCLIリファレンス、コマンド一覧、よくあるワークフロー、GitHub Actions連携を確認しておくと、--verbose、/debug、/feedback、PR連携の使い分けが明確になります。

バグ報告に必ず入れる項目

Claude Code向けのバグ報告は、長文である必要はありません。ただし、次の情報は省かないでください。

項目	書く内容	Claude Codeが判断できること
症状	何が、どの画面・コマンド・APIで起きたか	調査対象の入口
期待結果	本来どう動くべきか	修正の成功条件
実際の結果	エラー文、HTTPステータス、崩れ方	事実と推測の分離
再現手順	3分以内に再現できる最小手順	原因候補の検証方法
環境	OS、Node、ブラウザ、ブランチ、設定	ローカル差分の影響
証拠	ログ、スクリーンショット、失敗テスト	修正前後の比較
制約	触ってよいファイル、触らないファイル	余計なリファクタの防止
引き継ぎ	PR本文に書く根本原因、検証、残リスク	レビュー時間の短縮

初心者が一番つまずくのは「期待結果」を書かないことです。「エラーを消す」だけでは、空配列を返すのか、400を返すのか、UIに警告を出すのか判断できません。期待結果は、仕様書のように完璧でなくても構いません。「モバイル幅ではCTAが縦に並び、横スクロールが出ない」のように、目で確認できる一文にします。

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

次のテンプレートをbug-report.mdとして保存し、空欄を埋めてからClaude Codeに渡してください。

# Bug report for Claude Code

## 目的
- 直したい不具合:
- 今回のゴール:
- 今回はやらないこと:

## 環境
- OS:
- Node / package manager:
- Browser / device:
- Branch:
- 関連するenv名（値は書かない）:

## 症状
- どこで起きるか:
- 誰が見る問題か:
- 発生頻度: 毎回 / ときどき / 不明

## 期待結果
-

## 実際の結果
-

## 最小再現手順
1.
2.
3.

## 証拠
- エラーメッセージ:
- ログ:
- スクリーンショット:
- 失敗しているコマンド:

## 最近の変更
- PR / commit:
- 変更された可能性が高いファイル:

## 制約
- 触ってよい範囲:
- 触らない範囲:
- 秘密情報や顧客データは貼らない:

## Claude Codeへの依頼
1. すぐ修正せず、原因候補を3つ挙げる
2. それぞれの候補を否定できる最小の確認手順を出す
3. 最小再現または失敗テストを先に作る
4. 最小差分で修正する
5. 実行した検証コマンドと残リスクを報告する

このテンプレートは、社内チケットにもPRコメントにも使えます。重要なのは、Claude Codeに「どのファイルを編集するか」より先に「何をもって直ったとみなすか」を渡すことです。

再現情報を集めるスクリプト

手作業で環境情報を集めると、ブランチ名、Nodeバージョン、直近差分を抜かしがちです。以下のスクリプトはNode.jsだけで動き、秘密情報らしい値をマスクしながら、Claude Codeへ渡す文脈をまとめます。

// scripts/collect-bug-context.mjs
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";
import { platform, release } from "node:os";
import { cwd } from "node:process";

function run(command, args) {
  try {
    return execFileSync(command, args, {
      cwd: cwd(),
      encoding: "utf8",
      stdio: ["ignore", "pipe", "pipe"],
    }).trim();
  } catch (error) {
    return `(failed: ${command} ${args.join(" ")})`;
  }
}

function maskSecrets(text) {
  return text
    .replace(/(api[_-]?key|token|secret|password)=([^\\s]+)/gi, "$1=***")
    .replace(/Bearer\\s+[A-Za-z0-9._-]+/g, "Bearer ***");
}

function readPackageScripts() {
  if (!existsSync("package.json")) return "package.json not found";
  const pkg = JSON.parse(readFileSync("package.json", "utf8"));
  return JSON.stringify(pkg.scripts ?? {}, null, 2);
}

const report = {
  generatedAt: new Date().toISOString(),
  cwd: cwd(),
  os: `${platform()} ${release()}`,
  node: process.version,
  branch: run("git", ["branch", "--show-current"]),
  status: run("git", ["status", "--short"]),
  lastCommit: run("git", ["log", "-1", "--oneline"]),
  diffStat: run("git", ["diff", "--stat"]),
  packageScripts: readPackageScripts(),
};

console.log(maskSecrets(JSON.stringify(report, null, 2)));

使い方は次の通りです。

mkdir -p scripts
# 上のコードを scripts/collect-bug-context.mjs に保存
node scripts/collect-bug-context.mjs > bug-context.json

この出力をそのまま貼るだけでも、Claude Codeは「今どのブランチで、どの差分があり、どの検証コマンドが存在するか」を把握しやすくなります。ただし、マスク処理は保険です。APIキー、顧客データ、本番ログの全文は貼らず、必要な行だけに絞ってください。

ユースケース1: モバイルでCTAがはみ出す

悪い報告は「スマホ表示が崩れています」です。これでは、画面幅、URL、崩れた要素、期待する並びが分かりません。

よい報告は次のようになります。

症状:
  /products/ を390px幅で開くと、pricing CTAの右端が画面外にはみ出す。

期待結果:
  2つのCTAは縦に並び、横スクロールは出ない。

最小再現:
  1. Chrome DevToolsで幅390pxにする
  2. /products/ を開く
  3. pricing sectionまでスクロールする

証拠:
  document.documentElement.scrollWidth が 412
  スクリーンショットあり

制約:
  商品リンクと文言は変えない。CSSとレイアウトだけ確認する。

ここまで書くと、Claude CodeはCSSの幅、gap、ボタン文言、親コンテナを確認できます。修正後は、PC幅だけでなく390pxと768pxでも確認するように頼みます。広告や商品導線のあるページでは、CTAが直ったかだけでなく、productsページやtrainingページへの導線が残っているかも検証対象にします。

ユースケース2: APIが500を返す

APIの不具合では、HTTPステータスとログの一部だけでは足りません。入力ペイロード、期待レスポンス、最近変えた設定、環境変数名が必要です。

症状:
  POST /api/checkout が plan=pro のときだけ500を返す。

期待結果:
  200と決済URLを返す。設定不足なら500ではなく設定エラーとして検知したい。

実際の結果:
  TypeError: Cannot read properties of undefined (reading 'prices')

最小再現:
  curl -X POST http://localhost:3000/api/checkout \
    -H "content-type: application/json" \
    -d '{"plan":"pro"}'

環境:
  STRIPE_SECRET_KEY と PRICE_PRO_ID を使う。値は貼らない。

制約:
  決済プロバイダの実通信は増やさない。まず設定読み込みと入力検証を確認する。

このケースでは「直してください」ではなく「先に設定読み込み、入力検証、価格IDマッピングの3候補を比較してください」と依頼します。Claude Codeがすぐ外部サービスの呼び出し部分を変え始めたら止めます。最小再現がローカルのcurlで済むなら、失敗テストもAPIハンドラか設定モジュールの単体テストで作れます。

ユースケース3: 日付境界でテストが落ちる

タイムゾーンや月末のバグは、スクリーンショットより失敗テストの方が強い証拠になります。

import { describe, expect, it } from "vitest";
import { exportMonthlyOrderIds } from "../src/export-orders";

describe("exportMonthlyOrderIds", () => {
  it("includes March orders and excludes April 1 UTC", () => {
    const orders = [
      { id: "mar-start", createdAt: "2026-03-01T00:00:00.000Z" },
      { id: "mar-end", createdAt: "2026-03-31T23:59:59.999Z" },
      { id: "apr-start", createdAt: "2026-04-01T00:00:00.000Z" },
    ];

    expect(exportMonthlyOrderIds(orders, "2026-03")).toEqual(["mar-start", "mar-end"]);
  });
});

Claude Codeには「このテストを先に失敗させ、ローカルタイムゾーンに依存しない実装に直してください」と頼みます。ここでの落とし穴は、UIの日付表示だけを直して、集計ロジックの境界を放置することです。失敗テストがあれば、修正後のPRでレビュー担当者も根本原因を追いやすくなります。

最小再現を作る順番

最小再現とは、バグを起こすために必要な条件だけを残した小さな実験です。初心者は「本番と同じ状態を全部再現しないと意味がない」と考えがちですが、実務では逆です。不要な画面、不要なデータ、不要な外部通信を外すほど、Claude Codeは原因候補を狭めやすくなります。

最初に決めるのは、どの層で再現するかです。UIだけで起きるならブラウザ幅、DOM、CSSを見ます。APIで起きるならcurlやハンドラの単体テストに落とします。日付、金額、権限のように純粋なロジックで起きるなら、関数の入力と出力だけに切り出します。この切り分けをしないまま全体のE2Eだけを渡すと、Claude Codeはネットワーク、認証、表示、状態管理を同時に疑うため、差分が大きくなります。

次に、外部サービスを一度外します。決済、メール、検索、LLM APIなどは、実通信ではなく固定レスポンスに置き換えます。これは「ごまかす」ためではありません。バグが自分のコードにあるのか、外部レスポンスの変化にあるのかを分けるためです。外部サービスそのものが原因候補なら、最後に統合テストや手動確認で戻します。

三つ目に、入力データを削ります。100件の注文データでしか再現しないように見えるバグでも、本当に必要なのは「月末の1件」と「翌月1日の1件」だけかもしれません。空文字、null、境界値、タイムゾーン、権限なしユーザーのような条件を残し、それ以外は削ります。この作業をClaude Codeに頼む場合は「最小再現に必要なデータだけ残し、削った条件を列挙してください」と依頼すると、後でレビューしやすくなります。

最後に、失敗を固定します。自動テストが作れるなら先に失敗させます。作れない場合でも、再現コマンド、画面幅、入力値、期待結果を固定します。「たまに起きる」バグは、時計、乱数、キャッシュ、リトライ、並列実行のどれかが関係することが多いです。Claude Codeに「不安定さを隠す修正ではなく、なぜ不安定に見えるのかを説明してから直してください」と伝えると、待ち時間を増やすだけの修正を避けやすくなります。

初心者向けの書き方ルール

バグ報告は丁寧な文章より、曖昧さの少なさが大切です。「おかしい」「変」「うまくいかない」は、症状として弱い言葉です。「390pxで横スクロールが出る」「POSTが500を返す」「3月31日の注文がCSVに含まれない」のように、観測できる形で書きます。

専門用語を使う場合は、初出で言い換えます。たとえばminimum reproductionは「最小再現」、regression testは「同じバグを戻さないためのテスト」、handoffは「次の担当者が迷わない引き継ぎ」と書きます。Claude Codeには英語の用語も通じますが、チームの人間が読むPRでは日本語の補足が効きます。

また、秘密情報を貼らないルールは必ず明記します。APIキー、Cookie、顧客メールアドレス、決済IDの全文は不要です。必要なのは「どの環境変数名を使っているか」「どのリクエストID周辺で失敗したか」「どの入力条件で再現したか」です。証拠を増やすほど良いのではなく、安全に共有できる証拠だけを残します。

Claude Codeの出力をレビューする観点

Claude Codeが修正案を出したら、すぐに採用せず、バグ報告の項目に戻って照合します。期待結果に対して本当に直ったか、実際の結果が消えた理由を説明できるか、失敗テストが成功に変わったか、制約外のファイルを触っていないかを確認します。ここで「ビルドが通ったからOK」にすると、仕様を満たしていない修正を見逃します。

レビューでは、差分の大きさも見ます。原因が入力検証1箇所なのに、UI、API、型定義、文言、設定ファイルが一気に変わっているなら、Claude Codeに「根本原因に必要な変更だけに縮めてください」と戻します。逆に、修正が小さすぎて失敗テストやPR説明がない場合は、「同じバグを防ぐ証拠を追加してください」と頼みます。

PRに渡す前には、読者をレビュー担当者に置き換えて確認します。その人は、このバグがなぜ起きたかを知りません。再現手順、根本原因、検証コマンド、残リスクがPR本文にそろっていれば、レビューはコードの妥当性に集中できます。そろっていなければ、レビューは調査のやり直しになります。

Claude Codeへ渡す実行プロンプト

バグ報告を埋めたら、次のプロンプトで調査から始めます。

このbug-report.mdとbug-context.jsonを読んでください。

進め方:
1. まだ編集しない
2. 事実と推測を分ける
3. 原因候補を可能性順に3つ出す
4. 各候補を否定できる最小確認を提案する
5. 最小再現または失敗テストを先に作る
6. 承認後に最小差分で修正する

完了条件:
- 期待結果と実際の結果の差が説明されている
- 失敗テストまたは再現コマンドが残っている
- 実行した検証コマンドが報告されている
- PR本文に貼れる根本原因、修正内容、残リスクがある

公式のよくあるワークフローでも、エラー、再現コマンド、再現手順、一貫して起きるかどうかを伝える重要性が示されています。/debugはClaude Code自体のセッションログ調査に役立ち、/feedbackまたは/bugはClaude Code製品へのフィードバックです。自分のアプリのバグ報告と、Claude Code本体の不具合報告は混ぜないようにしてください。

PR引き継ぎテンプレート

修正できたら、次の形でPR本文に残します。セッションhandoffテンプレートと同じ考え方で、次に読む人の調査時間を減らします。

## Root cause
-

## Fix
-

## Regression coverage
- Added failing test:
- Manual reproduction checked:

## Verification
- [ ] npm test
- [ ] npm run typecheck
- [ ] npm run build
- [ ] mobile / desktop visual check if UI changed

## Risk
-

## Claude Code notes
- Hypotheses rejected:
- Files intentionally not touched:
- Follow-up issue:

Claude CodeにPR作成まで任せる場合でも、この構成を先に渡すと説明が薄くなりにくいです。GitHub連携を使うチームは、公式のClaude Code GitHub Actionsを確認し、CI失敗時にClaudeへ何を渡すかをこのテンプレートに合わせると運用しやすくなります。

よくある落とし穴

1つ目は、複数のバグを1つの報告に詰め込むことです。ログイン、決済、レイアウトを同時に頼むと、Claude Codeは広い差分を作りがちです。1報告1症状に分けます。

2つ目は、ログを貼りすぎることです。全文ログはコンテキストを圧迫し、秘密情報のリスクもあります。エラー周辺の20行、リクエストID、再現コマンドに絞ります。

3つ目は、失敗テストなしで修正を終えることです。すべてのバグに自動テストが必要とは限りませんが、境界値、データ変換、API契約、権限判定はテスト化しやすい領域です。テスト戦略と合わせて読むと、どこまで自動化するか判断しやすくなります。

4つ目は、Claude Codeに「全部見て直して」と頼むことです。初心者ほど範囲を広げると安心しますが、実務では逆です。最小再現を作り、原因候補を捨て、狭い差分にします。

5つ目は、PR引き継ぎを省くことです。修正した本人とClaude Codeは経緯を知っていますが、レビュー担当者は知りません。根本原因、検証、残リスクがないPRは、後からもう一度調査されます。

収益導線も検証対象に入れる

ClaudeCodeLabのような記事サイトでは、バグ修正は本文だけの問題ではありません。CTAボタン、無料PDF、Gumroad商品、productsとtrainingへの導線が壊れると、記事の価値が収益につながりません。特にデバッグ記事の読者は、今まさに困っているため、実用テンプレートから教材や相談へ進む導線が自然である必要があります。

個人で使うなら、まず無料チェックリストを自分のリポジトリ用に調整してください。繰り返し使うプロンプト、レビュー観点、CI向けの報告文まで整えたい場合はproductsを確認してください。チームで「バグ報告、Claude Codeの権限、PRレビュー、CI失敗時の引き継ぎ」を標準化したい場合は、trainingで実プロジェクトに合わせた導入設計を相談できます。

実際に試した結果

実際に試した結果、曖昧な「直して」だけの依頼よりも、再現手順、期待結果、失敗テスト、PR引き継ぎを先に渡した依頼の方が、Claude Codeの差分は小さく、レビューで聞かれる質問も減りました。とくに効果が大きかったのは、最初に3つの原因候補を出させることです。外れた仮説を早く捨てられるため、修正そのものより前の調査品質が上がります。公開前には、この記事のテンプレートを使って本文、コードブロック、内部リンク、公式リンク、CTAを再確認してください。