用 AI 编程修 Bug，最怕一句话开场：“这个功能坏了，你帮我看看。”Cursor、Claude Code、Codex 当然可以读代码、跑测试、查日志，但如果你不给复现路径，它很容易在错误方向上花时间：先猜组件，再猜接口，再猜缓存，最后改了一堆却没有真正解决问题。
Bug 复现报告的价值，是把“我感觉不对”变成“在什么环境、做了哪些动作、出现什么结果、期望应该怎样”。对 AI 编程工具来说，这类信息比一大段情绪化描述更有用。它能直接缩小搜索范围，也能让修复后的验收更明确。
这篇属于 AI编程工具专题 和 老达AI实践专题 的实操补充。如果你已经看过 AI编程调试怎么做，本文重点讲调试前最关键的一步：先把问题复现清楚。
为什么 AI 修 Bug 更需要复现报告
人类同事听到“页面打不开”，通常会继续追问：哪个页面、哪个账号、什么浏览器、什么时候开始、有没有报错。AI 也需要这些信息，只是它不会总在第一时间问全。
如果复现报告缺失，AI 容易出现三个问题。
- 误判范围：明明是接口返回字段变化，却先去改前端样式。
- 过度修改：为了“保险”，把相关组件和校验逻辑都重构一遍。
- 验收模糊：修完以后只说“看起来好了”，但没有重新跑复现路径。
所以我建议把 Bug 复现报告当成 AI 编程任务的入口材料。它不需要写得很长，但必须让工具知道从哪里下手。
一份合格复现报告包含什么
最小可用版本可以包含六块内容。
- 问题标题：一句话说清现象，例如“文章页移动端目录按钮点击无响应”。
- 影响范围：哪个页面、哪个角色、哪个设备或哪类数据受影响。
- 复现步骤：按 1、2、3 写出具体操作，不要只写结论。
- 实际结果：看到的错误、空白、异常提示、接口状态码或日志。
- 期望结果：正确情况下应该发生什么。
- 补充材料：截图、控制台日志、请求参数、最近改动、相关链接。
这六块足够让 Cursor、Claude Code、Codex 开始有效工作。更复杂的线上问题，可以再加用户 ID、时间范围、版本号、环境变量差异和回滚记录。
复现步骤要写成可执行动作
很多人写复现步骤，只写“打开文章页，目录坏了”。这对 AI 不够友好。更好的写法是把动作拆到可以被执行和验证。
复现步骤：
1. 打开移动端视口，访问任意文章页，例如 /tools/7602.html。
2. 滚动到正文第二屏。
3. 点击右下角目录按钮。
4. 观察目录面板是否展开。
实际结果：
按钮有点击态，但目录面板没有出现，控制台无明显报错。
期望结果：
点击后目录面板展开，再次点击或点击遮罩后关闭。这类描述会把 AI 的注意力直接引到移动端视口、目录按钮、点击事件和面板状态，而不是让它从整站页面结构里盲猜。
如果你正在用 AI编程提示词模板，可以把复现步骤作为任务说明的固定模块，让每次排错都有同样入口。
环境信息不要省略
AI 修 Bug 时，经常需要判断“只在某个环境出现”还是“所有环境都出现”。所以复现报告里要写清环境。
- 本地、测试环境、生产环境分别是否可复现。
- 浏览器、系统、设备或 Node/PHP/Python 版本。
- 登录状态、用户角色、权限差异。
- 最近一次部署、插件更新、依赖升级或配置改动。
例如 WordPress 站点的问题，至少要说明是前台页面、后台编辑器、REST API 还是主题模板。AI 编程工具看到环境信息后，才知道该查主题、插件、接口、缓存，还是服务器配置。
日志和截图要“少而准”
给 AI 日志不是越多越好。整屏复制 500 行日志，反而会稀释重点。更好的做法是截取和错误时间点最接近的部分，并标明来源。
日志来源：浏览器控制台
时间：2026-06-12 10:31 左右
关键报错：
TypeError: Cannot read properties of null (reading 'addEventListener')
相关文件：
/assets/js/toc.js:42截图也一样，不要只给一张整页长图。最好同时给“出错位置截图”和“期望状态截图”。如果是接口问题，再补 Network 面板里的请求 URL、状态码、响应摘要。
这和 AI编程验收清单 的思路一致：证据要能支撑判断，而不是只负责证明“我确实遇到了问题”。
尽量做最小复现，不要一上来丢整个项目
如果问题比较复杂，最小复现能显著提高 AI 的判断质量。最小复现不是重新做一个完整项目，而是把触发 Bug 的条件压缩到最小。
- 前端问题：保留一个组件、一组 props、一个交互动作。
- 接口问题：保留一个请求、必要参数、关键响应字段。
- 数据问题：保留一条异常记录和一条正常记录做对比。
- 样式问题：保留触发布局错位的容器、断点和内容长度。
如果最小复现能稳定触发问题，AI 就不需要在大量无关上下文里找线索。等它定位原因后，再回到真实项目里做修复。
让 AI 先复述判断，再改代码
拿到复现报告后，不要马上让 AI 修改。先让它复述问题和排查计划。
请先根据复现报告判断最可能的三类原因，说明你会优先检查哪些文件、命令或日志。不要先改代码，先给出排查路径。
这一步能减少误改。如果 AI 的判断明显偏离，比如你给的是移动端交互问题，它却准备先改数据库结构，就可以及时拉回来。
涉及线上站点、支付、权限、用户数据时，还要结合 AI编程安全审查，先确认修复方案不会引入更大的风险。
修复后必须重新跑复现路径
Bug 修复的验收，不能只看测试通过。最直接的验收，是按原复现步骤重新执行一遍。
- 原复现路径是否不再触发问题。
- 相邻路径是否仍然正常，例如桌面端和移动端都能用。
- 日志里是否没有新增错误。
- 如果加了测试，测试是否覆盖了这次问题。
- 如果不能加自动测试，是否记录了人工检查步骤。
这一步可以和 AI编程版本管理 配合：一个修复对应一个清晰提交，提交信息里写明复现路径和验收结果。后面同类问题再出现，也能快速回查。
可以直接复用的 Bug 复现模板
Bug 标题：
影响范围：
- 页面/功能：
- 环境：
- 用户角色：
复现步骤：
1.
2.
3.
实际结果：
期望结果：
关键证据：
- 截图：
- 日志：
- 请求/响应：
最近改动：
请先做：
1. 复述问题；
2. 给出排查计划；
3. 标出可能涉及的文件；
4. 未确认前不要扩大修改范围。这个模板适合贴给 Cursor、Claude Code、Codex。它比“帮我修一下”多花两分钟，但通常能省下后面半小时的无效排查。
老达点评
AI 编程让修 Bug 的速度变快了，但它没有取消问题描述这件事。相反，越是让 AI 直接动代码，越需要把复现路径、证据和验收标准写清楚。
我的经验是：好的 Bug 复现报告，不是给 AI 增加负担，而是在帮它少猜。你把问题描述得越像一条可执行任务，Cursor、Claude Code、Codex 就越容易从“到处看看”变成“沿着证据定位”。这也是个人项目和小团队最值得养成的 AI 编程基本功。
