Claude Code Bug Report 模板：把模糊问题变成可复现修复

只告诉 Claude Code “页面坏了”或“测试挂了”，它只能猜。猜出来的补丁可能看起来合理，却常常缺少根因、验证命令和 reviewer 需要的上下文。高质量 bug report 的作用，是把模糊抱怨变成可以复现、可以测试、可以交接的修复任务。

这篇文章给你一套适合 Claude Code 的实用模板：症状、期望结果、实际结果、最小复现、日志、环境、失败测试、约束和 PR 交接。建议先读第一次任务 runbook，深入排查时接着看调试技巧，修复后再用PR 质量检查收尾。

官方资料可以放在手边：Claude Code CLI reference、commands reference、common workflows、GitHub Actions guide。它们能帮助你区分 --verbose、/debug、/feedback、PR 自动化等场景。

一份可用报告必须包含什么

项目	写什么	Claude Code 能判断什么
症状	哪个页面、命令、route 或 API 出问题	调查入口
期望结果	正确的业务规则或 UI 规则	“修好”的定义
实际结果	错误文本、状态码、错位、错误输出	事实而不是猜测
最小复现	几分钟内能失败的最短路径	如何验证假设
环境	OS、runtime、浏览器、branch、env 名称	本地与 CI 差异
证据	日志、截图、stack trace、失败测试	修复前后的证明
约束	可以改和不该改的文件	防止大范围重构
交接	根因、验证、风险、后续任务	缩短 review 时间

最常见的错误是没有写“期望结果”。“把错误消掉”不是需求。API 应该返回空数组、400、用户提示，还是重试？先把规则写成一句可以验证的话。

可复制的 bug report 模板

把下面内容保存为 bug-report.md，填完后再交给 Claude Code。

# Bug report for Claude Code

## Goal
- 要修的 bug:
- 想要的结果:
- 不在本次范围内:

## Environment
- OS:
- Node / package manager:
- Browser / device:
- Branch:
- 相关 env 名称，不写值:

## Symptom
- 发生位置:
- 影响谁:
- 频率: 每次 / 偶发 / 不清楚

## Expected behavior
-

## Actual behavior
-

## Minimum reproduction
1.
2.
3.

## Evidence
- Error message:
- Logs:
- Screenshot:
- Failing command:

## Recent changes
- PR / commit:
- 可能相关的文件:

## Constraints
- 可以修改的范围:
- 不要修改:
- 不要粘贴 secrets 或客户数据:

## Request to Claude Code
1. 不要立刻改代码
2. 先列出 3 个最可能原因
3. 给出能否定每个原因的最小检查
4. 先创建最小复现或失败测试
5. 用最小有效 diff 修复
6. 汇报验证命令和剩余风险

这份模板适合内部 ticket、支持交接和 PR 评论。重点不是文档形式，而是先告诉 Claude Code 什么才算修好。

用脚本收集上下文

手动收集信息时，常会漏掉 branch、Node 版本或当前 diff。下面的 Node 脚本没有第三方依赖，会收集基本信息并遮盖明显 secret。

// 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

脚本输出是证据，不是安全审计。真实 API key、客户信息、生产日志全文不要贴进 Claude Code。

用例1：移动端 CTA 溢出

差的报告：

手机页面坏了。

好的报告：

Symptom:
  390px 宽度打开 /zh/products/ 时，pricing CTA 右侧超出屏幕。

Expected behavior:
  两个 CTA 垂直排列，不出现横向滚动。

Minimum reproduction:
  1. Chrome DevTools 设置宽度 390px
  2. 打开 /zh/products/
  3. 滚动到 pricing 区块

Evidence:
  document.documentElement.scrollWidth 为 412
  已附截图

Constraints:
  不改商品链接和文案，只检查布局 CSS。

这样 Claude Code 就能检查宽度、gap、按钮文案和父容器。涉及变现页面时，还要验证 products 和 training 的路径没有被修坏。

用例2：结账 API 返回 500

API bug 需要请求内容、期望响应、实际错误和相关配置名。

Symptom:
  POST /api/checkout 只有 plan=pro 时返回 500。

Expected behavior:
  返回 200 和支付 URL。若配置缺失，应给出明确配置错误。

Actual behavior:
  TypeError: Cannot read properties of undefined (reading 'prices')

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

Environment:
  使用 STRIPE_SECRET_KEY 和 PRICE_PRO_ID，不粘贴值。

Constraints:
  不增加真实支付请求。先检查配置加载和输入校验。

让 Claude Code 先比较三个假设：配置加载、请求校验、价格映射。最小复现能在本地跑通时，失败测试通常可以放在 handler 或 config module。

用例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"]);
  });
});

提示词要明确：“先让这个测试失败，再修复实现，不依赖本地时区。” 常见陷阱是只改 UI 日期显示，却没有修正统计边界。

给 Claude Code 的调查提示词

Read bug-report.md and bug-context.json.

Process:
1. Do not edit yet
2. Separate facts from guesses
3. Rank the top three root-cause hypotheses
4. Propose the smallest check that could disprove each one
5. Create a minimum reproduction or failing test first
6. After approval, make the smallest useful fix

Done means:
- The expected/actual gap is explained
- A failing test or reproduction command remains
- Verification commands are reported
- The PR handoff includes root cause, fix, risk, and follow-up

官方 common workflows 也强调：给 Claude 错误、复现命令、步骤，以及问题是稳定还是偶发。/debug 用来诊断 Claude Code 会话，/feedback 或 /bug 用来反馈 Claude Code 产品本身，不要和你自己应用的 bug report 混在一起。

PR 交接模板

## 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:

这和会话 handoff 模板以及测试策略配合很好。使用 Claude Code GitHub Actions 的团队，也可以把 issue 评论和 CI 失败提示统一成同一结构。

常见陷阱

不要把无关 bug 塞进同一份报告。登录、结账、布局问题应该拆开复现。

不要粘贴完整日志。只贴错误附近约二十行、request ID 和复现命令。

边界值、数据映射、API 契约、权限判断类 bug，尽量不要在没有失败测试的情况下结束。

不要让 Claude Code “到处看看”。小复现比大范围授权更有用。

不要省略 PR 交接。Reviewer 需要根因、证据和剩余风险。

把变现路径也纳入验证

在 ClaudeCodeLab 这样的内容站里，bug fix 可能影响 CTA、产品卡、免费 PDF 表单、Gumroad 链接或咨询入口。只要修改了文章布局或商品路径，就要把这些路径纳入验证范围。

个人使用时，可以先把免费清单改成自己的仓库模板。需要可复用提示词、review gate 和设置材料时，看产品页。团队要统一 bug report、Claude Code 权限、PR review 和 CI 交接流程时，可以从培训与咨询开始。

实操结果

实际试下来，包含复现步骤、期望结果、失败测试和 PR 交接的报告，比一句“帮我修一下”更容易得到小 diff，也更少被 reviewer 追问。提升最大的一步，是让 Claude Code 在编辑前先列出三个假设。错误假设被快速排除后，整个会话会从“猜补丁”变成“有证据的调试”。