quality-workflow

质量工作流

验证关卡规范

义务：quality-and-verification。

• 在内部迭代中使用有针对性、范围明确的验证（聚焦构建、特定测试筛选条件）；仅在结束工作或最终提交前运行完整测试套件，作为最终关卡。
• 耗时较长的关卡（提交前验证、完整测试套件、CI）用于最终确认，而非内部迭代调试。重新运行完整关卡前，先用最小复现（单个失败测试、有针对性的构建、隔离命令）验证每个假设。
• 依赖升级或环境变更后测试失败时，先在变更前的状态（之前的 SHA／升级前的基准）复现问题，再判断是否由变更导致。

测试覆盖方法

• 测试 MUST 覆盖成功、失败、边界、无效输入和关键状态转换（适用时，包括首次运行／冷启动与后续运行的行为）。适用时，测试 MUST 包含具有代表性的并发、重试和恢复场景。
• 对于非简单变更，Agent MUST 在选择测试前列出变更涉及的外部可见契约范围。以变更的文档、规范、CLI 帮助、API 描述、UI 控件、文件格式和面向用户的消息作为该范围的事实依据。
• Agent MUST 构建一个小型范围矩阵（范围项 × 状态／结果），并直接覆盖风险最高的组合。Agent MUST NOT 将一个通过的正常路径检查视为相邻文档化入口也能正常工作的证据。
• 对于确定性输出文件，Agent MUST 使用完整内容快照测试或黄金测试。
• Agent MUST 优先让非确定性故障变得可复现，而不是添加休眠或重试。Agent MUST NOT 掩盖不稳定性。
• 对于时序、顺序或竞态问题，Agent MUST 优先使用确定性同步机制（事件、带版本的状态、确认／握手），而不是固定休眠。
• 对于集成边界（网络、数据库、外部服务、UI 流程），Agent MUST 添加集成、E2E 或契约测试来验证该边界。Agent MUST NOT 仅依赖单元测试覆盖集成问题。
• 对于非简单变更，Agent MUST 创建一个小型测试矩阵（场景 × 输入 × 状态），并 MUST 覆盖风险最高的组合。必须记录有意保留的测试缺口。

反馈循环与根本原因

• Agent MUST 将发现和修复问题所需的时间视为质量属性，并 MUST 通过自动化和可观测性缩短反馈循环，而不是依赖人工 QA。
• 对于任何缺陷修复或事故补救，Agent MUST 简要分类根本原因：
  1. 实现错误。
  2. 设计缺陷。
  3. 需求含糊或错误。
• Agent MUST 在同一变更集中向上游反馈根本原因：添加或强化测试／检查／告警，更新规范和验收标准，并在适用时更新设计文档或 ADR。
• 如果故障本应更早被发现，Agent MUST 在最早的可靠环节添加关卡（lint、类型检查、测试、CI 必需检查、运行时告警或健康检查）。跳过此项需要获得用户明确批准。
• Agent MUST 在 PR 描述或问题评论中记录预防机制（什么能防止问题再次发生）。如果没有具体改进反馈循环，Agent MUST NOT 报告“已修复”。

验证证据流程

AC→证据映射格式

• Agent MUST 明确维护 AC -> evidence (tests/commands/manual steps) 映射。
• 当更改新增或修改命令、标志、端点、视图或状态等用户可见界面时，Agent SHOULD 并行维护 changed surface item -> direct evidence 映射。
• 为减少冗长，MAY 采用紧凑的逐项形式呈现映射（每个 AC 一行，包含证据和结果）。
• 对于非代码更改，Agent MUST 运行相关验证子集，并 MUST 说明为何不需要运行完整测试套件。
• 如果无法运行所需检查，Agent MUST 停止并请求明确批准，以便继续进行部分验证。Agent MUST 提供精确的手动验证计划。

最终交付回复格式

• 对于每项会改变状态的任务，Agent MUST 在内部明确维护 AC -> evidence 映射。
• 在面向用户的常规最终回复中，Agent MUST 默认简要总结结果、验证情况和剩余风险。
• 仅当用户要求，或更高优先级规则要求分别展示特定路径的证据时，Agent MUST 展开说明 Goal/Verification、AC -> evidence 或精确命令列表。

CI 和提交钩子设置

有关 CI 和提交钩子不变量，请参阅规则模块 quality-and-verification 和 lint-format-static。本节介绍设置流程。

• 如果获准，Agent MUST 配置所需的默认分支检查；否则，Agent MUST 报告限制。
• Agent MUST NOT 依赖仅运行冒烟测试或仅按计划运行的门禁。
• 如果尚未安装钩子，Agent MUST 在本次会话的首次提交前安装钩子。如果无法安装，Agent MUST 在每次提交前手动运行完整验证。
• 验证脚本 MUST 强制检查锁文件完整性（检测清单与锁文件之间的偏差）。

环境限制

• 如果环境限制执行（网络、数据库、沙箱），Agent MUST 运行可用的测试子集、记录跳过的覆盖范围，并 MUST 确保 CI 覆盖其余部分。
• 对于面向用户的工具和 GUI，除自动化测试外，Agent MUST 执行端到端手动验证。如果手动测试发现问题，Agent MUST 先添加失败测试，再进行修复。
• 对于 CLI 和 API 更改，直接契约检查 MUST 覆盖可发现性入口，例如帮助、用法、版本、架构或其他等效的文档化入口（如果这些入口属于交付契约的一部分）。
• 如果所需测试难以执行，Agent MUST 记录这一缺口、提供手动验证计划，并 MUST 获得明确批准。

测试实践

• 启发式等待 MUST 要求基于条件的逻辑、明确的截止时间、诊断信息和请求者的明确批准。
• 日志 MUST 精简并包含诊断上下文。日志 MUST NOT 包含机密或个人数据。Agent MUST 在最终补丁前移除调试用埋点。