Claude Code Bug Report 模板：把模糊报错变成可复现的修复输入

Claude Code 调试是否成功，常常取决于你给它的 bug report

如果只写“坏了”，Claude Code 只能猜。好的 bug report 会同时给出症状、再现步骤、期望结果、实际结果、限制和验证方法。

这篇文章适合接在 第一次任务运行手册 后使用。如果需要把上下文交给下一次会话，也请配合 handoff 模板。

可复制的 bug report 模板

目标:
- 要修的 bug:
- 不做的事:

环境:
- OS / browser / runtime:
- branch:
- 相关命令:

再现步骤:
1.
2.
3.

期望结果:
-

实际结果:
-

日志或截图:
-

限制:
- 可以修改的文件:
- 不要修改的文件:
- 不要发送到外部服务:

验证:
- 要运行的 build/test:
- 要目视确认的 URL:

给 Claude Code 的请求:
先把原因缩小到3个候选，写出最小修复方案、会修改的文件和验证步骤。
在我批准前不要编辑。

好例子

要修的 bug:
移动端宽度下 pricing CTA 横向溢出。

再现步骤:
1. 用 390px 宽度打开 /en/products/
2. 滚动到 pricing card
3. CTA 右边超出 viewport

验证:
npm.cmd run build
用 Playwright 截 390px 的图

坏例子

网站有点怪，帮我修好。

这个请求没有范围、成功条件和限制。即使模型很强，也很难稳定交付。

发送前检查

• 再现步骤能在3分钟内完成吗
• 成功条件能用命令或截图确认吗
• 写清楚不能碰的文件了吗
• 是否包含日志、URL 或截图

下一步

常用命令请放进 免费 cheatsheet。如果想把调试 prompt 固定成模板，可以看 50 Prompt Templates。团队流程需要整理时，请看 导入咨询。

实务中要把调查和修复分开

调试时最常见的失败，是原因还没缩小就让 Claude Code 写 patch。更稳定的顺序是：先复现，再列原因候选，最后做最小修复。这样每一步都可以 review。

基于这个 bug report，请先只调查，不要修复。
1. 是否可以复现
2. 3 个原因候选
3. 最可能的代码区域
4. 修复前应该阅读的文件
5. 是否能用最小修改解决，还是需要设计调整

如果这一步得到“无法复现”“日志不足”“范围太大”，就不要进入修复。好的 bug report 不是催模型给答案，而是让调查顺序变得可验证。