缺陷管理文档编写最常见的失效，不是没人写，而是三份文档各写各的：Bug 单里只有截图，复盘记录停在“加强测试”，质量周报又把数量抄一遍。文档都在，却没有回答同一个问题——这条 Bug 暴露了哪段流程的缺口，下一次用什么证据证明它被补上。
缺陷报告记录单条事实，复盘记录解释一类问题，质量周报呈现一个周期的风险变化。三者共用字段和口径，才构成一套可用的文档体系。
一、先分清三份文档的边界
边界不清，最先出现的是重复劳动：报告里写根因，复盘里重述步骤，周报里再列一遍 Bug 清单。
| 文档 | 回答的问题 | 完成标准 |
|---|---|---|
| Bug 报告 | 发生了什么，如何复现 | 接手人能独立复现 |
| 复盘记录 | 为什么发生，哪段流程失效 | 根因可验证，行动项可验收 |
| 质量周报 | 本周质量变好还是变差 | 结论能支持排期和发布 |
三份文档共用模块、版本、严重程度、发现阶段、根因分类五个字段。 字段不统一，周报只能数总数。
二、缺陷报告（Bug 报告）怎么写：让接手人不必追问
Bug 报告是交接凭证。 判断标准很直接：开发、测试或产品任意一方拿到它，能否独立复现并做出处理判断。
标题写“场景+异常结果”
“登录有问题”“页面报错”等于让接手人重新排查一遍。可用的写法是“【订单提交】优惠券金额为 0 时点击提交，页面提示 500 且订单未生成”。标题带模块、触发条件和异常结果，便于检索与去重。
核心字段一张表
一张表覆盖交接所需的核心信息。
| 字段 | 写什么 | 判断标准 |
|---|---|---|
| 环境与版本 | 产品、项目、影响版本、设备、账号、数据条件 | 能区分测试与线上 |
| 复现步骤 | 最短路径、频率、前置条件 | 他人照做能复现 |
| 实际与期望 | 客观现象；引用需求或设计稿 | 不写“好像”，不凭偏好 |
| 影响与分级 | 用户、业务、数据、资金；严重程度看后果，优先级看处理顺序 | 同类问题用同一标准 |
| 证据与关联 | 截图、日志、请求 ID；关联需求、用例、版本 | 能支持定位和回溯 |
字段不是越多越好。新增字段前先回答：填完它，谁会据此改变动作？答不上来就设为选填。
复现步骤要能照着走
- 普通账号进入订单确认页。
- 选择满 100 减 20 的优惠券，金额为 100 元。
- 提交后提示“系统异常”，订单列表无记录。
频率：10 次操作出现 7 次，线上账号同样可复现。步骤只保留触发问题所需的最少动作；偶发问题写清频率和样本量，不能只写“偶尔”。
严重程度与优先级分开
严重程度看后果，优先级看什么时候处理。 只影响内部报表的 P2 问题，如果卡住月底结算，优先级可以升高；尚未发布、没有数据风险的 P1 问题，处理顺序可以后移。混成一个等级，团队最后只能靠会议重新排序。
一条记录只描述一个 Bug；根因写在备注里；关闭前补齐解决版本和验证结果。在禅道 Bug 管理流程中，提 Bug 可填写项目、模块、影响版本、类型、标题、严重程度、优先级和重现步骤；解决时记录方案与版本，验证通过后关闭。
三、复盘记录怎么写：从“谁的锅”转到“哪条链路失效”
复盘不是把 Bug 报告再讲一遍，而是解释现有流程为什么没有更早拦住它。
什么情况值得复盘
线上 P1/P2、影响资金或数据安全、逃逸 Bug、同一模块反复出现的问题、跨团队交接断点，值得单独复盘。普通体验问题合并进周报即可。
六段结构
复盘记录按六段写，避免写成事件经过。
| 段落 | 写什么 |
|---|---|
| 事实时间线 | 发生、发现、止损、修复、验证时间 |
| 影响 | 用户范围、业务中断、数据后果 |
| 根因 | 触发、放大、未及时发现的因素 |
| 处置 | 临时止损、永久修复、回滚条件 |
| 行动项 | 动作、负责人、截止、验收证据 |
| 复发监控 | 用例、监控指标、评审检查项 |
六段里最容易空的是根因和验收。根因要对应到流程、设计或工具，验收要能说清用什么证据判断完成。
5 Whys 不要把根因写成“开发粗心”
以重复下单为例：为什么重复创建？重试被当成新请求。为什么没识别？接口没有幂等键。为什么没有幂等设计？评审清单没有并发与重试项。为什么清单缺失？模板没有维护人。根因是评审缺少幂等检查项、模板无人维护。行动项是新增检查项、指定维护人，下个迭代试用，以评审记录和压测用例验收。
5 Whys 不是必须问满五次。追到可行动的系统或流程原因就可以停；多因素问题用鱼骨图或故障树，不要硬凑单链因果。
行动项要能被验收
“加强测试”“提高意识”不是行动项。可验收的写法包含四件事：改哪个检查项、谁负责、何时完成、用什么证据判断完成。行动项进入任务系统，并在下一期周报显示状态。
无指责不等于不追事实。记录当时已知什么、谁做了什么决定、风险如何被接受，但不把根因归到个人性格。
四、质量周报怎么写：用少量指标解释变化
周报不是 Bug 清单的复制，也不是数字排行榜。它回答三件事：本周质量趋势如何，风险集中在哪里，下周准备做什么。
先定口径，再算数字
指标先定口径，再谈变化。
| 指标 | 公式 | 回答的问题 |
|---|---|---|
| 缺陷密度 | Bug 数 / 规模 | 模块质量浓度 |
| 缺陷逃逸率 | 上线后 Bug 数 /（测试 + 上线后）×100% | 测试漏检程度 |
| 缺陷重开率 | 重开数 / 已修复数 | 修复与验收质量 |
| 修复及时率 | 时限内解决数 / 应解决数 | 响应效率 |
| 遗留 Bug 占比 | 上线未关闭数 / 全部 Bug 数 | 发布风险 |
这些是常见口径，不是行业统一标准。固定公式、统计窗口和数据来源，至少连续 4 到 8 周后再做趋势比较。
一页周报的五段
- 结论：本周风险上升、下降或持平，用一句话说明依据。
- 数字：新增、解决、遗留 Bug 数，按严重程度拆分。
- 风险：前三个风险模块或版本，写清影响、处置、风险接受人。
- 趋势：与上周或上个迭代对比，说明是真实变化还是口径变化。
- 行动：下周动作、负责人、完成时间、验收证据。
指标要组合看
指标要组合看，单看一个数字容易把“记录变少”误判成“质量变好”。 Bug 总数下降，同时逃逸率和重开率上升，可能是记录变少或修复变糙。缺陷密度上升，但早期评审发现比例也上升，可能是检测能力增强。周报要给解释。
示例
示例数据：本周新增 Bug 42 个，较上周增加 12%；P1/P2 共 8 个，集中在支付与权限模块。上线后逃逸 3 个，均为重试导致的重复提交，已触发复盘。当前遗留 P2 两个，均有绕行方案，风险接受人为项目负责人。下周完成幂等检查项评审。
这段示例没有把“新增增加”直接写成“质量下降”，而是把数字、风险、行动放在一起。
五、把三份文档接成一套闭环
三份文档不是三个模板，而是一条数据的三种视图。Bug 报告提供事实，复盘记录解释原因，周报汇总趋势。复盘产出的行动项进入下周周报，周报暴露的高频问题再触发复盘。
缺陷管理文档编写不是把三份模板发给团队，而是让同一套字段在三个粒度上复用。
节奏可以这样定：新 Bug 在每天固定时间或每个工作日做一次分诊，确认是否成立、谁处理、何时处理；周报按自然周或迭代固定发布；复盘按事件触发，不追求每单都复盘。多产品线组织按产品、项目、版本分层统计，避免总数掩盖局部风险。
角色写进制度：提交者保证可复现，开发确认根因和方案，测试验证并关闭，质量负责人维护口径，项目或产品负责人接受残余风险。没有人对口径负责，周报很快会变成各说各话。
工具上，禅道把需求、任务、用例和 Bug 放在同一条研发链路里，用例执行失败可以转 Bug，修复后回归关闭；Bug 列表和测试单结果可作为周报底稿。据《2025 年软件测试行业现状调查报告》，禅道连续 11 年获得常用测试管理工具第一名。工具解决数据留存与关联，文档怎么写、口径怎么定，仍由团队约定。
六、常见问题
Bug 关闭后还能改严重程度吗？ 可以，但要保留理由和时间；已进周报的历史数据不回改，修正时在下一期注明口径调整。
周报按自然周还是迭代统计？ 选一个主口径，另一个放附录；混用会让两个周期无法比较。
缺陷报告让问题可复现，复盘记录让原因可解释，质量周报让风险可比较。把字段、口径和行动项统一起来，缺陷管理文档编写才不只是交文档，而是在为下一次发布决策留下证据。
文章标题 ：缺陷管理文档编写：缺陷报告、复盘记录与质量周报的写法 ，发布者 ：项目管理研究院
