如何撰写一份好的 Bug 报告（供 AI 或开发者使用）

一份好的 Bug 报告，能让另一个人——无论是开发者还是 AI——看到你所看到的同样问题，而无需再向你提问。它需要一个具体的标题、复现问题的准确步骤、你预期的结果、实际发生的情况、逐字复制的任何错误信息，以及问题发生的位置：哪个页面、哪种浏览器、哪种设备、哪位用户。每份报告只写一个 Bug，如有帮助可附上截图。

大多数 Bug 理解起来比修复起来花的时间更长。一份清晰的报告能省去理解这一步。对于 AI 工具来说，这一点更加重要：AI 无法像人那样追问“‘结账很奇怪’是什么意思”，于是它只能猜测——而一次错误的猜测可能会弄坏其他东西。

模板

复制下面的内容并填写：

标题：[什么地方出了什么问题] —— 例如“预订表单拒绝晚上 6 点之后的时间”

复现步骤：
1. ...
2. ...
3. ...

预期：[应该发生什么]
实际：[实际发生了什么]

错误信息：[准确的文字，如有]
位置：[页面/URL、浏览器、设备、以哪位用户登录]
发生频率：[每次 / 有时 / 仅一次]
截图或录屏：[已附上]

本指南的其余部分会解释每个部分。

第一步：先尝试复现

在写报告之前，先尝试让 Bug 再次出现。这样你就能弄清楚哪些步骤是关键的，以及它是否每次都会发生。

• 从干净的状态开始：刷新页面，或退出后重新登录。
• 记下每一次点击和每一次输入。
• 尽量找到触发问题的 最短 路径。
• 尝试第二个浏览器或账号。如果只有某一位用户会遇到，这是一个很重要的线索。

更多相关内容，参见 如何调试 AI 构建的应用。

第二步：写一个具体的标题

标题应当说明什么地方出了什么问题，这样有人在浏览列表时就能知道这是哪个 Bug。

第三步：列出准确的步骤

给步骤编号。要具体：哪个页面、哪个按钮、输入了什么。

1. 以客户身份登录（测试账号：customer@example.com）。
2. 将“入门套件”加入购物车。
3. 输入折扣码 WELCOME10，然后点击 应用。
4. 点击 结账。

“试着用折扣码结账”这样的描述会漏掉许多关键细节：哪位用户、哪个商品、哪个折扣码、是否先应用了折扣码。

第四步：预期与实际

这是报告的核心。两者都要写，因为二者之间的差异就是 Bug 本身。

• 预期： 结账页面打开，并在总价中显示 10% 的折扣。
• 实际： 按钮转圈一秒钟，然后什么都没有发生。不使用折扣码时，结账正常。

如果没有“预期”，读者可能不知道这种行为是错误的。如果没有“实际”，他们就不知道该去看什么。

第五步：逐字复制错误信息

错误信息是找到原因最快的途径。请以文字形式逐字复制，不要改述。

在哪里找到它们：

• 屏幕上： 应用显示的任何提示信息。
• 浏览器控制台： 打开开发者工具（F12，或右键 → 检查），查看 Console（控制台） 标签中的红色行。
• 网络面板： 在开发者工具中找到失败的请求，记下它的 URL 和状态码（例如 POST /api/checkout → 500）。
• 服务器日志，如果你有访问权限。

类似 TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 这样的一行信息，往往能直接指向问题所在。

第六步：补充上下文

• 位置： 页面 URL、运行环境（预览、预发布或正式环境）。
• 用户： 哪位用户或角色——管理员、普通成员、未登录。
• 设备与浏览器： “iPhone 上的 Safari”与“Windows 上的 Chrome”可能差别很大。
• 数据： 记录中任何不寻常之处——超长文本、特殊字符、大量条目。
• 何时开始： “昨天修改折扣码之后”非常有价值。
• 发生频率： 每次都会发生，还是十次中偶尔出现一次。

第七步：展示问题

标出问题位置的截图，或一段简短的屏幕录制，可以消除歧义——对于布局类 Bug 尤其如此。如果你的 AI 工具支持图片，请附上一张。裁掉所有隐私内容，包括密钥和他人的数据。

为 AI 构建工具撰写 Bug 报告

同样的结构也可以作为提示词使用。有两点可以增加效果：

• 说明哪些内容不能改变，以免修复工作引入新的问题。
• 要求它验证修复结果，而不仅仅是编写修复代码。

以客户身份登录，购物车中有“入门套件”，并且已应用折扣码 WELCOME10，点击 结账 没有任何反应。预期：结账页面打开，总价减免 10%。实际：短暂的转圈，然后没有任何反应。网络面板显示 POST /api/checkout 返回了 500。不使用折扣码时结账正常。请找出原因并修复，同时不要改变没有折扣码的订单的价格计算方式。然后用百分比折扣码、固定金额折扣码以及不使用折扣码的情况分别检查结账流程。

如果你不确定原因，可以先要求诊断：

先不要修改代码。根据这份报告，可能的原因有哪些？每个原因分别需要什么来确认？

常见错误

• “它坏了。” 没有步骤、没有预期结果，无从下手。
• 一份报告里写了多个 Bug。 有些会被修复，有些会被遗漏。
• 错误信息经过改述。 “某个 undefined 的东西”掩盖了最有用的部分。
• 遗漏用户或角色。 很多 Bug 只影响管理员，或者只影响新用户。
• 只描述你想要的修复方式（“加一个空值检查”），而不是描述问题本身。
• 在截图或粘贴的日志中泄露机密信息。

检查清单

• 我已经复现了 Bug，并找到了最短的步骤。
• 标题说明了什么地方出了什么问题。
• 步骤有编号，并且具体明确。
• 预期与实际两者都已写明。
• 错误信息已逐字复制，并附上失败请求和状态码。
• 已包含页面、运行环境、用户、设备和浏览器。
• 我说明了发生频率和开始时间。
• 已附上截图或录屏，并移除了隐私信息。
• 每份报告只写一个 Bug。

向 Mythex 的智能体报告 Bug

在 Mythex 项目中，报告 就是 提示词。以下几个功能会有所帮助：

• 附上截图，可以是预览或错误页面的截图——每条消息最多 5 个文件。
• /fix 让智能体专注于修复 Bug；计划（Plan） 模式让它在编辑之前先进行调查。
• /test 让智能体在预览中复现流程，并报告它所看到的内容。
• 回退到此处 可以撤销一个让情况变得更糟的修复。

文档中的 用提示词调试 页面采用的也是同样的“步骤 / 预期 / 实际”结构。关于围绕它的修复与检查循环，参见 如何迭代改进 AI 构建的应用。

常见问题