缺陷描述写得含糊，常见后果是开发反复追问、缺陷被退回，甚至按“无法复现”关闭后问题再次出现。把一条缺陷写完整，可以按四段组织：复现步骤写清前置条件、操作和观察点；期望结果注明依据来源；实际结果写具体现象与影响范围；再附上环境信息和日志证据。写完后用“他人能否照步骤复现、能否据此判断对错”自检一遍。
要点总览（TL;DR）
- 缺陷描述按六类字段组织：标题、复现步骤、期望结果、实际结果、环境信息、日志证据，每类字段回答一个固定问题，缺一项就会留下需要追问的空档。
- 复现步骤写到“没接触过该功能的人照着做能走到异常出现”的颗粒度：前置条件写清账号角色、数据状态与配置项，操作一步一个动作并编号，在异常首次出现的那一步标注观察点，末尾写明复现频率。
- 期望结果注明依据来源（需求条目、设计稿、接口约定或业务规则），实际结果写具体现象、报错原文、界面位置与影响范围，二者逐条对应；原因推测单独标注，不混进现象描述。
- 环境信息覆盖版本、设备或浏览器、操作系统、账号角色与相关配置；日志与截图按可打开、可定位、已脱敏附写，证据暂缺时标注待补充内容与补齐时间。
- 提交前用三项自检：他人能否照步骤复现、期望结果是否有依据、附件能否打开并定位到观察点；缺少复现步骤或期望依据时评审退回补充。
一条完整缺陷描述包含哪些字段
缺陷描述的作用是让没有参与发现过程的人，仅凭记录就能重现问题并判断对错。它由六类字段组成，每类字段回答一个固定问题，缺一项就会留下需要追问的空档。
| 字段 | 回答的问题 | 写作要点 |
|---|---|---|
| 标题 | 什么对象出了什么现象 | 一句话点明模块、操作与异常表现，便于检索和去重 |
| 复现步骤 | 怎么触发 | 前置条件加编号操作，关键步骤标观察点 |
| 期望结果 | 应该怎样 | 写明依据来源与具体表现 |
| 实际结果 | 实际怎样 | 写现象、报错文本、界面位置与出现频率 |
| 环境信息 | 在什么条件下出现 | 版本、设备、系统、账号角色、相关配置 |
| 日志证据 | 有什么可验证的材料 | 截图、日志关键行、请求响应，注明时点 |
字段之间存在对应关系：复现步骤中的每个观察点，都应在实际结果里有对应的现象记录；期望结果与实际结果成对出现，逐条对照，评审人才能判断这是缺陷还是需求变更。标题、步骤、期望、实际构成缺陷的主干，环境与证据是支撑主干可验证的附件。字段分工清楚后，填写时就不会把原因分析、修复建议混进现象描述里。
复现步骤怎么写：前置条件、操作与观察点
复现步骤的颗粒度标准是：一个没接触过该功能的人照着做，能走到出现异常的那一步。达到这个标准，步骤需要拆成前置条件、编号操作和观察点三部分。
前置条件写清状态起点
前置条件描述操作开始前系统应处于什么状态，通常包括：使用哪个账号及角色权限、需要预先准备哪些数据及其状态（如“已提交未审核的订单”）、涉及哪些配置项及其取值（如“消息通知开关为开启”）。前置条件写得越具体，复现时因环境差异导致的偏差越少。
操作一步一个动作
操作按编号逐步写，每步只包含一个动作，避免把“打开页面、填写表单并提交”合并成一句。合并描述会让读者无法判断异常出现在哪一步。推荐格式如下：
- 使用测试账号 A（角色：项目管理员）登录系统；
- 进入“缺陷列表”页面，点击“新建缺陷”；
- 在标题栏输入 200 个字符，点击“保存”；观察点：页面提示“保存成功”，但列表未出现新记录；
- 刷新页面，再次查看列表。
观察点标注在异常首次出现的那一步，说明看到了什么，而不是只写“出现异常”。如果异常在后续步骤才显现，观察点就放在显现的那一步。
写明复现频率
步骤末尾补充复现情况：稳定复现、偶现（约几次出现一次）、仅在特定条件下出现。偶现问题要说明已尝试的次数和触发条件，方便开发判断排查方向。频率信息也影响后续的严重程度判断，但严重程度如何定级属于另一套规则，这里只负责把事实写清。
期望结果与实际结果怎么写清
期望结果回答“按什么标准判断这是错的”，实际结果回答“看到的是什么”。两者都写具体，评审才能快速判断是否为缺陷。
期望结果注明依据来源
期望结果不能只写“应该正常保存”，要写清依据来自哪里：需求条目的编号与原文、设计稿的页面与状态、接口文档的字段约定、业务规则说明。例如：“依据需求 REQ-1024，标题超过 100 字符时应提示‘标题过长’并阻止保存。”有依据来源，期望结果就从个人判断变成可核对的约定；依据本身有争议时，问题会回到需求澄清，而不是停留在缺陷记录里反复争论。
实际结果写可观察的现象
实际结果要写具体现象、报错原文、界面位置和影响范围。把“保存有问题”改成“点击保存后页面提示‘保存成功’，刷新后列表无新增记录，控制台报错 XXX”，信息量完全不同。避免使用“不正常”“有问题”“失效”这类无法核对的词。出现频率和影响范围（如“影响所有项目管理员账号”）也写在这里。
逐条对应，推测单独标注
期望与实际按条目一一对应，形成对照：期望 A 对应实际 A，期望 B 对应实际 B。这样评审时能逐条判断哪一条不满足。现象描述与原因推测分开写，推测放在单独段落并标注“推测”，例如“推测与标题长度校验未生效有关，待确认”。推测可以帮助排查，但不能混进现象描述，否则后来的人会把猜测当成事实。
环境信息与日志证据怎么附
同样的操作在不同环境下结果可能不同，证据决定了缺陷能否被验证。环境信息与日志证据按“可打开、可定位、已脱敏”三条要求附写。
环境信息包含的项
- 产品版本号或构建号，以及所在环境（开发、测试、预发、生产）；
- 设备型号、浏览器及版本，或客户端系统版本；
- 操作系统版本；
- 账号角色与权限范围；
- 与问题相关的配置项及取值，如开关状态、参数设置。
日志与截图的采集要求
截图要包含异常出现的完整界面，标出异常位置，并记录操作时间点，便于在日志中定位。日志截取异常前后一段时间的相关行，保留时间戳、请求标识和错误码，不要只贴一行报错。涉及账号、手机号、身份证号、业务数据的内容做脱敏处理，替换为占位符并说明替换规则。
附件命名与待补充标注
附件按“缺陷标题关键词_内容类型_时间”命名，如“标题保存失败_控制台日志_0315”，正文中引用附件时说明它对应哪个观察点。证据暂时拿不到时，在对应字段标注“待补充：需要 XX 日志”，并说明由谁在什么时间前补齐，避免缺陷带着空白证据进入处理环节。
角色分工与提交前自检
缺陷描述质量由提交、评审、处理三方共同保证，各方的职责边界清楚，退回和补充才有依据。
| 角色 | 职责 | 交付物 |
|---|---|---|
| 提交人（测试或业务人员） | 按字段填写完整，附上环境与证据，提交前完成自检 | 字段齐全、证据可打开的缺陷记录 |
| 评审人或模块负责人 | 核对期望结果的依据是否成立、复现步骤是否可照做，判断是否为缺陷 | 评审结论：接受、退回补充或转需求澄清 |
| 开发 | 按步骤复现；信息不足时提出具体补充请求，说明缺哪一项 | 补充请求清单或修复记录 |
开发遇到无法复现时，应指出卡在哪一步、缺少什么信息，由提交人补充后继续处理；直接关闭会让问题失去跟踪。提交前的自检按三项执行：他人能否照步骤复现；期望结果是否有明确依据；附件能否正常打开并定位到对应观察点。三项都通过再提交。
缺陷记录通常承载在缺陷管理工作项中，字段填写、附件上传和评审流转在同一处完成。ONES Project 支持缺陷跟踪管理，与 TestCase 数据互通，可一键提 Bug 至对应项目或迭代，并统计缺陷状态分布；ONES TestCase 中未通过的用例可快速创建缺陷任务，缺陷任务在测试与研发团队间流转。把上述字段规范落到这类工作项里，提交人按模板填写，评审人在同一记录上核对依据并退回补充，缺陷从提交到修复的过程就有据可查。
示例：一条缺陷从模糊描述改写成完整记录
以下为演示情景，用一条虚构缺陷展示改写过程。
改写前的模糊描述
标题：“保存有问题”。描述：“新建缺陷时保存不正常，麻烦看下。”这条记录没有操作路径、没有判断依据、没有环境和证据，开发只能追问或凭经验猜测。
按字段改写后的完整记录
- 标题：缺陷列表新建记录时标题超过 100 字符仍提示保存成功，刷新后记录丢失
- 前置条件：测试账号 A（项目管理员角色）；项目 P 下已有 10 条缺陷记录；标题长度校验配置为默认值。
- 复现步骤：1）登录后进入项目 P 的缺陷列表；2）点击“新建缺陷”；3）标题输入 120 个字符，其余字段填默认值，点击“保存”，观察点：提示“保存成功”；4）刷新列表，观察点：无新增记录。
- 复现频率：稳定复现，连续 3 次均出现。
- 期望结果：依据需求 REQ-1024，标题超过 100 字符时应提示“标题过长”并阻止保存。
- 实际结果：提示“保存成功”，刷新后列表无新增记录，影响所有项目管理员账号。
- 环境信息：测试环境，版本号 V2.3.1；Chrome 浏览器；账号角色为项目管理员。
- 证据：保存成功提示截图、刷新后列表截图、控制台日志（已脱敏），附件名“标题超长保存_截图与日志_0315”。
改写理由与可迁移规律
改写做了四件事：把“保存有问题”拆成可执行的四步操作并标出两个观察点；把期望结果挂到需求条目上，使对错有依据；把实际结果写成可观察的提示文本与列表状态；补上环境与证据，使问题可验证。这套做法可以迁移到其他缺陷类型：界面类问题重点写界面位置与截图，接口类问题重点写请求参数、响应内容与日志，数据类问题重点写数据状态与前后对比。字段结构不变，变的只是每类字段里填什么。
完成检查：缺陷描述是否写完整
提交和评审时，用下表逐项判断，全部通过才算写完整。
| 检查项 | 通过标准 | 判断方式 |
|---|---|---|
| 复现步骤可照做 | 前置条件、编号操作、观察点齐全，未参与的人能走到异常出现 | 请他人按步骤操作一遍 |
| 期望结果有依据 | 注明需求条目、设计稿、接口约定或业务规则 | 核对依据来源是否存在且适用 |
| 实际结果具体 | 有现象、报错文本、界面位置、频率与影响范围 | 检查是否出现“不正常”等笼统词 |
| 环境信息齐全 | 版本、设备或浏览器、系统、账号角色、相关配置均已填写 | 对照环境清单逐项核对 |
| 证据可打开可定位 | 附件能打开，命名规范，正文引用对应观察点，敏感信息已脱敏 | 实际打开附件确认 |
其中两项作为阻断项：缺少复现步骤，或期望结果没有依据来源时，评审应退回补充，不进入处理环节。其余项缺失可在处理过程中补充，但需在记录中标注待补充内容和补齐时间。按这张表执行，缺陷描述的质量标准就从个人习惯变成团队可核对的提交与评审依据。
常见问题
偶现缺陷的复现步骤怎么写，才能让开发愿意继续排查？
偶现缺陷的步骤写法与稳定复现一致，额外补充三样信息：已尝试的次数（如“连续操作 20 次出现 3 次”）、触发时的特殊条件（如并发操作、网络切换、特定数据量）、以及每次出现时的共同点。步骤中把观察点标在异常显现的位置，实际结果里写清每次出现的表现是否一致。
如果暂时找不到规律，在记录中明确写“规律待补充”，并说明下一步计划采集哪些日志或监控数据。这样开发拿到的是可继续排查的线索，而不是一句“偶尔出问题”。
期望结果的依据本身有争议时，缺陷应该怎么处理？
期望结果的依据来自需求条目、设计稿、接口约定或业务规则。当提交人与开发对依据的理解不一致时，这条记录的性质就从缺陷变成了需求澄清：评审人应核对依据来源是否存在、是否适用于当前版本，把争议点写进评审结论，转给需求负责人确认。
处理方式是在缺陷记录上标注“转需求澄清”并附上争议的具体条目，而不是让双方在缺陷评论里反复争论。澄清结论确定后，再回到缺陷记录判断是否需要继续修复。
日志和截图涉及用户隐私数据，附件应该怎么处理？
附写证据前先做脱敏：账号、手机号、身份证号、业务数据替换为占位符，并在正文说明替换规则，方便他人对照原始日志定位。截图只保留异常相关的界面区域，避免带出无关的用户信息。
日志截取异常前后一段时间的相关行，保留时间戳、请求标识和错误码。如果脱敏后信息不足以定位问题，可在记录中说明需要哪类原始数据，由有权限的人员在受控环境下查看，不把敏感原文直接贴进缺陷描述。
开发按步骤复现不出来，可以直接关闭缺陷吗？
不建议直接关闭。开发无法复现时，应指出卡在哪一步、缺少什么信息，向提交人提出具体补充请求，例如“第 3 步的配置项取值是多少”“需要该时段的完整日志”。提交人补充后继续处理，问题保持跟踪状态。
直接关闭会让问题失去跟踪，后续再次出现时又要从头排查。如果确认是环境差异导致，也应在记录中写明差异点，作为后续同类问题的参考。
团队刚推行这套写法，怎样让字段规范真正落地而不是停留在文档里？
落地可以从三处入手：把字段结构做成缺陷提交模板，提交人按模板填写；在评审环节按完成检查表逐项核对，缺少复现步骤或期望依据时退回补充；定期回看被退回的记录，找出最常缺的字段，针对性提醒。
缺陷记录通常承载在缺陷管理工作项中，字段填写、附件上传与评审流转在同一处完成。ONES Project 支持缺陷跟踪管理，与 TestCase 数据互通，可一键提 Bug 至对应项目或迭代，并统计缺陷状态分布；ONES TestCase 中未通过的用例可快速创建缺陷任务，缺陷任务在测试与研发团队间流转。把字段规范落到这类工作项里，提交与评审就有统一的载体。
