你是来找一份bug 报告模板的——字段、标题、能直接粘进 Jira 或表单的东西。它就在下面,拿走。但一份好的软件 bug 报告模板得回答标准字段从不回答的那个问题:这玩意儿当初到底应该怎样? Jira 里的工单、表单里的记录,都是一座孤岛——它描述哪里坏了,却和当初定义「什么才算对」的那条 spec 或决策彻底脱节。Draftlize 给你同样的八个字段,并把最后一个变成一条真链接:bug 卡片直接指向它违反的 spec,修复它的 agent 在写下第一行代码之前,先读到原始意图。
这就是整份 bug 报告模板。Jira 工单、Linear issue、bug 报告表单里照搬即可。下一节讲的是:当最后一个字段不再是一段随手写的备注、而变成一条指向被破坏 spec 的链接时,会发生什么。
一句话:模块、坏掉的行为、触发条件。「结账——用了优惠券后,总价没算上按量折扣。」一个不用打开工单就能分诊的标题。
构建/版本、操作系统、浏览器、设备,以及账号或数据状态。一半的「无法复现」都卡在这里——bug 是真的,只是少了你忘记写下来的那个环境。
编号、从已知初始状态出发、带上确切输入。如果一个陌生人没法照着走到那个故障,这份报告就没写完。这一栏决定了 bug 是被修掉、还是被打回。
本该发生什么——最好附上这么说的那条 spec 或决策。多数模板在这儿就含糊带过了。「对」不是一种看法,它当初是在某处被定义过的。把那个地方指出来。
实际发生了什么:错误的输出、报错、堆栈、截图。具体、可观测,而不是「就是坏了」。这一栏和「预期表现」之间的落差,就是这个 bug。
阻断、严重、次要、轻微——再加上影响:谁会撞上、多频繁、有没有绕过办法。严重程度是 agent 或人排队列的依据;老实地估。
截图、录屏、日志、HAR 文件、出错的请求体。这些证据把「我觉得它坏了」变成一个别人能据以动手的、可复现的事实。
这个 bug 所违背的那条 spec、需求或产品决策。在表单里,这是一条你粘上就忘的死链接。它定义了「修好」到底意味着什么——也正是这整页要讲的那一栏。
模板就这些。下面讲:一张和 spec 断了线的工单,为什么只是半份 bug 报告——以及我们怎么解决。
这些字段是好的——所以每个 bug 报告表单大体都长这样。但它们记下的是哪里错了,从不记什么才是对。「预期表现」是报告者记忆里那条规则的样子,而记忆往往不等于规则。真正定义了「对」的那条 spec,在另一个工具里——如果它还活着的话。
接手 bug 的人——无论是开发者还是 AI agent——只对着报告里的症状打补丁。他们从没看见当初设定这一行为的那个决策,于是把它「修」成了违反另一条规则的样子,你便又发了第二个 bug 去撤销第一个。
你改了一条定价或流程决策。某处还躺着一批照着旧行为提的 bug——它们要么已经过时,要么「预期」已经指错了方向。没有任何东西把这条 spec 和那些工单连起来,于是它们在 backlog 里烂掉,直到有人在一个早已不存在的 bug 上浪费掉一下午。
在 Draftlize,bug 报告不是一张搁浅的工单,而是一张带着那八个字段的结构化卡片,而「关联 spec 或决策」是一条指向它所破坏 spec 或决策卡片的真链接。bug 与它所违背的意图,只隔一次点击,同处一张结构化的图谱里。
Claude Code 或 Cursor 通过 MCP,在碰代码之前先打开关联的 spec 和决策。它朝着当初真正被定义的行为去修——而不是报告者那半段记忆——于是补丁是在还原意图,而不是在猜。
因为这条链接是真的、不是粘上去的 URL,改一条 spec 会把所有照着它提的 bug 标记出来——就像构建系统让一个改动文件下游的一切失效那样。一个「预期」刚刚发生位移的 bug,会被浮出来,而不是悄无声息地搁浅在 backlog 里。
bug,是「实际发生了什么」与「本该发生什么」之间的距离。一份略去后半句的报告,只是半个 bug。留下这八个字段。把最后一个,接到它所破坏的那条 spec 上。
一份好的 bug 报告，写清「实际发生了什么」与「本该发生什么」之间的距离：清楚的复现步骤、实际结果、预期结果、环境、严重级别，以及一条连到它所违反 spec 或决策的链接。「预期结果」正是多数报告漏掉的那一半——少了它，一个 bug 只描述了一半。
标题、复现步骤、实际结果、预期结果、环境或版本、严重级别或优先级、截图或日志，以及相关 spec 或决策。复现步骤和预期结果挑大梁：它们把「它坏了」变成工程师（或 agent）不用来回追问就能动手的东西。
bug 是产品和它自己 spec 之间的缝——它没做到它被定义要做的事。功能请求则要产品做一件它从没被规定过的新事。一个恢复既定行为，一个新增意图。用同一种方式登记它们，会把一条值得保持清晰的界线弄糊。
相关 spec 字段是一条真链接，于是一个 bug 离它所违反的行为只有一步，编码 agent 在动手修之前会先读那个意图。改动 spec，凡是针对旧行为提的 bug 都标成 stale——一张过时的工单会被浮出来，而不是烂在 backlog 里。
把上面的模板拿走,或者开一个项目,让每个 bug 都连到它违反的那条 spec——这样修复它的 agent 能读到原始意图,而一条被改动的 spec,也绝不会留下一个过时的 bug。
注册送 $5,免费开始