# 提示词：排查 bug（复现、定位、修复、验证）

> 把排查拆成复现、定位、修复、验证四步，要求先写出会失败的测试再动手，并限制猜测次数，避免智能体靠压制报错来交差。

## 适用场景

线上或本地出现了报错、结果不对、偶发失败。最糟糕的求助方式是只发一句「登录有 bug，帮我修」。智能体会猜一个原因、改几行、告诉你好了，而你并不知道它到底有没有真的修好。

这份提示词的核心是两点：一是必须先有可重复的复现（最好是一条会失败的测试）；二是修复之后必须由同一条复现来证明问题消失。

## 模板

```text
问题现象：【一句话描述，包括预期行为和实际行为】
复现步骤或命令：【可以直接运行的命令；如果不知道，请写「不确定」】
错误信息 / 日志：
【粘贴完整报错和堆栈，不要截断】
我怀疑的位置（可选）：【文件或模块】
最近的变化（可选）：【最近的提交、升级的依赖、改过的配置】

请按以下四步处理，每一步完成后用两三句话汇报，再进入下一步：

第 1 步，复现。
运行复现命令，确认你看到的错误与我描述的一致。如果无法复现，停下来告诉我缺少什么信息，
不要凭空改代码。

第 2 步，定位。
提出至多 3 个假设，按可能性排序，并说明每个假设会导致什么可观察的现象。
通过读代码、加临时日志、缩小输入范围等方式逐个验证，找到根本原因后再继续。
结论要写明：出错的文件和位置、触发条件、为什么会这样。

第 3 步，修复。
先写一个会失败的测试，它精确地复现这个 bug，运行并确认它确实失败。
然后修改代码让它通过。要求：
- 修复根本原因，不要用 try/catch 吞掉错误、不要改断言、不要跳过测试来让它变绿。
- 改动尽量小，不顺手重构。

第 4 步，验证。
运行新测试和相关的已有测试，贴出真实输出。再确认没有残留的临时日志或调试代码。
最后给出：原因总结、改动清单、没有验证到的风险。

如果同一个思路连续失败两次，停下来告诉我你学到了什么，再换思路，不要反复微调。
```

## 怎么用 / 怎么改

- 报错信息一定要完整粘贴。堆栈里的文件名和行号是智能体最有用的线索。日志太长时，用管道把输出交给它：`cat error.log | claude -p "解释这个错误"`，这是 Claude Code 命令行的用法，其他工具照此思路传入即可。
- 偶发问题要补充频率和环境，比如「大约每 20 次失败 1 次，只在 CI 上出现」，并让它在第 2 步考虑竞态、时间、外部依赖。
- 前端问题可以附上截图（拖入或粘贴图片），并写清楚预期的样子。
- 已知 bug 位置时，把第 2 步删掉，直接从写失败测试开始。
- 想看修复建议而不改代码，把第 3 步改成「给出两到三种修复方案和取舍，等我选择」。

## 常见问题或注意事项

- **它把测试改成能过的样子。** 在第 3 步强调「不要修改已有断言」，评审时单独看测试文件的 diff。
- **复现不了，它仍然信心满满地改了。** 第 1 步的「停下来」要写在最前面，并明确禁止修改文件。
- **纠正超过两次仍然没好。** 上下文里已经堆满失败的尝试，效果会变差。官方的建议是清空上下文，带着已经学到的信息重写一个更具体的提示词再开始。
- **修好了但不知道为什么。** 要求它在汇报里写「为什么这个修复有效」，说不清就是没理解根因。