审查 OpenSpec apply 完成后以及后续手动修补后的实际变更,判断实际产物和验证结果是否与 `design.md` 事实来源一致,识别偏离、漏记和可优化点,按以下流程执行。 ## 约束 - 先审查再修复;未经用户确认,不修改实际产物 - 默认按 `fast-drive` workflow 审查;识别 change 后先确认 `schemaName`;若实际 schema 不同,说明差异,仅对实际存在的 artifacts 做审查 - 在 `fast-drive` workflow 下,核心 artifacts 是 `design.md` 和 `tasks.md`;不要要求存在 `proposal.md` 或 `specs/*.md` - 在 `fast-drive` workflow 下,`design.md` 是范围、需求、决策、执行约束、执行方向和验证预期的事实来源,`tasks.md` 是 apply 进度和验证闭环的跟踪文件 - 禁止同步或修改 `openspec/specs/` 下的主规范,该操作属于 archive 阶段,不在此提示词范围内 - 优先使用当前会话中的执行说明、验证结论、手动修补记录和已生成的变更文档;仅在无法明确 change、`schemaName`、改动范围或修补来源时,再用提问工具或 OpenSpec 命令补充定位 - 不要因为实际产物已经存在就自动以实际产物为准;先判断差异属于“design 要求未完成”、“验证后新增修补”、“合理落地细化”还是“意外偏离/回归” - 每批实际产物修改执行前用提问工具获得用户确认 - 删除/重写前用提问工具获得用户确认;若存在 git 仓库,不创建 `.bak` 备份文件,改用当前 `git status` / `git diff` 作为回退依据;仅在无版本控制或用户明确要求时,才将备份放到代码目录外的用户确认路径 - 若修改实际产物涉及新行为、流程、接口、内容、数据、配置、责任边界或用户可见结果,同步更新验证材料 ## 1. 收集 读取约束: - 直接使用 Read 工具并行读取文件,禁止使用 subagent/Task 工具做文件读取和内容转发 - 不原样输出文件内容,仅在步骤 2 输出审查结论 分步收集: a) 先并行读取核心入口和配置,确定范围: - 本次 change 的 `design.md` - 本次 change 的 `tasks.md` - workflow context/configuration,例如存在时读取 `openspec/config.yaml` - 若可定位到 schema,读取对应 schema;`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml` b) 从 `design.md` 的实际章节提取审查基准。`fast-drive` 默认中文章节包括: - `背景` - `讨论记录` - `需求` - `目标 / 非目标` - `执行约束` - `影响范围` - `决策` - `执行计划` - `验证计划` - `风险 / 权衡` - `待解决问题` c) 从 `tasks.md` 提取任务状态、已完成项、未完成项、验证任务和文档/沟通任务;重点记录所有已标记完成的 `- [x]` 或等价完成状态。 d) 获取实际改动范围:若在版本控制工作区中,优先使用 `git diff --name-only`、`git diff --name-only --cached`;若工作区已干净或不适用版本控制,再结合 `design.md`、`tasks.md`、验证记录和执行记录反推。 e) 并行读取实际改动范围、“影响范围”“执行计划”“验证计划”涉及的实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料。 f) 收集当前会话中与本次变更相关的执行说明、apply 过程中的偏离、验证失败、手动修补原因、验证命令或检查结果、待确认事项。 g) 若实际 schema 不是 `fast-drive`,只读取实际存在的 artifacts;若存在 `proposal.md`、`specs/*.md`,再按该 schema 的要求补充读取和审查。 若当前上下文无法明确 change 或文档路径: - 先用提问工具让用户确认 change 名称或文档范围 - 仍无法确认时,再执行 `openspec status --change "{name}" --json` 和 `openspec instructions apply --change "{name}" --json` 辅助定位 若已明确 change,但尚未确认 `schemaName`,先读取 change 元数据或执行 `openspec status --change "{name}" --json` 确认。 若缺少验证结果或手动修补记录,明确说明本次无法可靠判断部分差异的来源,仅能基于实际产物与文档现状审查。 ## 2. 分析 按以下优先级检查: | 优先级 | 维度 | 检查点 | | ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | P0 | 实际变更与验证结论 | 当前实际产物的真实状态是什么;apply 后是否有手动改动或验证后修补;验证是否证明这些变更有效;若缺少验证结果,标记相关结论为“未验证”;检查是否存在回归、未覆盖场景或被掩盖的问题 | | P1 | `design.md` 一致性 | 实际变更是否符合“需求”“目标 / 非目标”“执行约束”“决策”“执行计划”和“验证计划”;“待解决问题”是否已明确区分 blocking / non-blocking 或写出“无”;是否违反被明确否决的方案、用户偏好或约束 | | P2 | `tasks.md` 真实性 | 已完成任务是否真的完成并完成必要验证;未完成任务是否仍然必要;apply 或手动修补是否引入了需要补充的新任务或验证任务 | | P3 | 质量与可维护性 | 实际产物的结构、清晰度、一致性、可维护性、风险处理、移交质量、验证质量、与现有模式的一致性是否存在明显问题或可优化点 | | P4 | Schema 兼容性 | 对实际存在的 artifacts 检查是否符合其 schema;若不是 `fast-drive`,仅按实际 artifacts 检查,不凭空要求 `fast-drive` 专属结构;最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 | 分析时区分四类差异: - `design.md` 要求已明确,但实际变更未完成或完成不充分 → 需补充实际工作或验证 - 实际变更因验证暴露问题、手动修补或合理落地细化而新增/变更 → 需确认是否需要补充验证 - 实际变更与 `design.md` 不一致,且无法判断应以哪边为准 → 列入待确认清单 - `tasks.md` 状态与实际完成情况或验证结果不一致 → 列入任务状态问题清单 不要把以下情况直接视为合理修补: - 通过跳过、弱化或绕过验证来声称变更完成 - 为了贴合当前实际产物而降低已确认的需求、验收标准或执行约束 - 未经过讨论和验证就扩大功能、流程、内容或责任范围 - 违反“执行约束”、被拒绝方案或“待解决问题”中尚未解决的 blocker 重点识别: - `design.md` 要求但未落地的结果、流程、内容、场景、异常处理或验证步骤 - 实际变更偏离"目标 / 非目标""执行约束""决策"或"执行计划"的地方 - apply 完成后新增的修补、边界处理、接口调整、行为变化、流程变化或内容变化 - "影响范围"与实际改动范围不一致,导致新会话无法复盘真实影响面 - "验证计划"中要求的验证、质量检查、审阅、批准、沟通检查或人工检查未执行或未记录 - `tasks.md` 标记完成,但实际产物或验证未闭环 - `design.md` 或 `tasks.md` 仍保留 `` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容 - 实际产物存在明显的重复、复杂度过高、表达不清、责任不明、风险处理薄弱、验证质量不足等问题 - `fast-drive` change 中仍错误依赖 `proposal.md`、`specs/*.md`、`Capabilities` 或 `Modified Capabilities` 的内容 输出审查结果: 1. **问题总览表**:问题类型 × 涉及文件数 2. **实际变更与修补清单**:本次已落地的主要变更、后续修补和验证结论;若缺少验证结果,对未验证部分单独标记 3. **Design 偏离清单**:实际变更未完成、完成不充分或偏离 `design.md` 的内容 4. **方向待确认清单**:实际变更与 `design.md` 不一致,且无法判断应以哪边为准的事项 5. **任务状态问题清单**:未真正完成、状态错误或需补充的新任务 6. **验证问题清单**:缺失覆盖、掩盖错误、验证不足或修补后未回归验证的问题 7. **质量/优化清单**:可优化的实际产物问题和建议 8. **Schema 差异清单**:实际 schema 与默认 `fast-drive` 不同时,列出因此跳过或改按实际 artifacts 审查的内容 9. **逐项分析**:每个问题说明位置、问题、影响、建议和建议修复方向 若所有清单均为空,输出“审查通过,未发现问题”,跳至步骤 5。 ## 3. 计划(用户确认) 先针对“方向待确认清单”用提问工具逐项向用户确认。 再整理完整修复方案,按类别列出: - 实际工作或验证补充:补完成、补异常处理、补回归验证、修复被弱化或绕过的验证 - 任务状态修正:修正已完成/未完成状态,补充 apply 后新增但已完成的修补任务或验证任务 - 质量优化:在不改变目标结果的前提下优化结构、表达、一致性、可维护性或移交质量 - Schema 兼容处理:若实际 schema 不是 `fast-drive`,按实际存在的 artifacts 说明需关注的差异项 对每个拟修改的文件说明: - 修改内容 - 修改原因 - 预期影响 - 验证方式 - 若存在分支方案,分别说明适用前提 用提问工具展示完整修复方案,获得用户确认后执行。 ## 4. 执行 逐项执行已确认的实际产物和验证修复。 若涉及删除或重写: - 存在 git 仓库时,先记录当前 `git status` / `git diff`,不要在实际产物或代码目录创建 `.bak` 文件 - 不存在版本控制,或用户明确要求备份时,先用提问工具确认代码目录外的备份路径,再执行修改 若修改了实际产物或验证材料: - 运行或执行相关验证;若修补影响范围较大,再补充执行受影响的回归验证 执行后重新读取所有被修改的实际产物和验证材料,并复核: - "Design 偏离清单" 是否已清空或已标注保留原因 - "方向待确认清单" 是否已清空或已记录用户决策 - "任务状态问题清单" 和 "验证问题清单" 是否已清空或已标注残留原因 - "质量/优化清单" 中哪些已处理,哪些有意延期 ## 5. 收尾 列出所有修改的文件、回退依据、验证命令或检查结果和剩余风险;若实际创建了备份,再列出备份文件。 若本次因缺少验证结果、修补记录或上下文而降级执行,或有问题因信息不足暂未处理,单独说明。