180 lines
13 KiB
Markdown
180 lines
13 KiB
Markdown
审查 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/` 下的主规范；若实际 schema 包含 `specs/*.md`，也只允许修改本次 change 目录下实际存在的 spec artifacts，主规范同步属于 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 | 文档回写完整性 | 已落地的实际变更、验证后新增修补、边界处理、异常路径、验证结论、实际触达产物是否已同步回 `design.md` 和 `tasks.md`；若影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，再检查必要的文档/沟通材料是否同步 |
|
||
| P4 | 质量与可维护性 | 实际产物的结构、清晰度、一致性、可维护性、风险处理、移交质量、验证质量、与现有模式的一致性是否存在明显问题或可优化点 |
|
||
| P5 | Schema 兼容性 | 对实际存在的 artifacts 检查是否符合其 schema；若不是 `fast-drive`，仅按实际 artifacts 检查，不凭空要求 `fast-drive` 专属结构；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 |
|
||
|
||
分析时区分四类差异：
|
||
|
||
- `design.md` 要求已明确，但实际变更未完成或完成不充分 → 需补充实际工作或验证
|
||
- 实际变更因验证暴露问题、手动修补或合理落地细化而新增/变更 → 需回写 `design.md` 和/或 `tasks.md`
|
||
- 实际变更与 `design.md` 不一致，且无法判断应以哪边为准 → 列入待确认清单
|
||
- `tasks.md` 状态与实际完成情况或验证结果不一致 → 修正任务状态或补充任务
|
||
|
||
不要把以下情况直接视为合理修补：
|
||
|
||
- 通过跳过、弱化或绕过验证来声称变更完成
|
||
- 为了贴合当前实际产物而降低已确认的需求、验收标准或执行约束
|
||
- 未经过讨论和验证就扩大功能、流程、内容或责任范围
|
||
- 违反“执行约束”、被拒绝方案或“待解决问题”中尚未解决的 blocker
|
||
|
||
重点识别：
|
||
|
||
- `design.md` 要求但未落地的结果、流程、内容、场景、异常处理、文档/沟通更新或验证步骤
|
||
- 实际变更偏离“目标 / 非目标”“执行约束”“决策”或“执行计划”的地方
|
||
- apply 完成后新增的修补、边界处理、接口调整、行为变化、流程变化或内容变化未同步到 `design.md`
|
||
- “影响范围”与实际改动范围不一致，导致新会话无法复盘真实影响面
|
||
- “验证计划”中要求的验证、质量检查、审阅、批准、沟通检查或人工检查未执行或未记录
|
||
- `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`、`tasks.md` 或相关文档/沟通材料未体现的变更、修补或约束变化
|
||
5. **方向待确认清单**：实际变更与 `design.md` 不一致，且无法判断应以哪边为准的事项
|
||
6. **任务状态问题清单**：未真正完成、状态错误或需补充的新任务
|
||
7. **验证问题清单**：缺失覆盖、掩盖错误、验证不足或修补后未回归验证的问题
|
||
8. **质量/优化清单**：可优化的实际产物问题和建议
|
||
9. **Schema 差异清单**：实际 schema 与默认 `fast-drive` 不同时，列出因此跳过或改按实际 artifacts 审查的内容
|
||
10. **逐项分析**：每个问题说明位置、问题、影响、建议和建议修复方向
|
||
|
||
若所有清单均为空，输出“审查通过，未发现问题”，跳至步骤 5。
|
||
|
||
## 3. 计划（用户确认）
|
||
|
||
先针对“方向待确认清单”用提问工具逐项向用户确认。
|
||
|
||
再整理完整修复方案，按类别列出：
|
||
|
||
- 实际工作或验证补充：补完成、补异常处理、补回归验证、修复被弱化或绕过的验证
|
||
- Design 回写：同步 `design.md` 中遗漏或过时的需求、执行约束、影响范围、决策、执行计划、验证计划、风险或待解决问题
|
||
- 任务状态修正：修正已完成/未完成状态，补充 apply 后新增但已完成的修补任务或验证任务
|
||
- 文档/沟通同步：同步行为、流程、接口、内容、数据、配置、责任边界或用户可见结果变化
|
||
- 质量优化：在不改变目标结果的前提下优化结构、表达、一致性、可维护性或移交质量
|
||
- Schema 兼容处理：若实际 schema 不是 `fast-drive`，按实际存在的 artifacts 说明额外文档同步项
|
||
|
||
对每个拟修改的文件说明：
|
||
|
||
- 修改内容
|
||
- 修改原因
|
||
- 预期影响
|
||
- 验证方式
|
||
- 若存在分支方案，分别说明适用前提
|
||
|
||
用提问工具展示完整修复方案，获得用户确认后执行。
|
||
|
||
## 4. 执行
|
||
|
||
逐项执行已确认的实际产物、验证和文档修复。
|
||
|
||
若涉及删除或重写：
|
||
|
||
- 存在 git 仓库时，先记录当前 `git status` / `git diff`，不要在实际产物、文档或代码目录创建 `.bak` 文件
|
||
- 不存在版本控制，或用户明确要求备份时，先用提问工具确认代码目录外的备份路径，再执行修改
|
||
|
||
若修改了实际产物或验证材料：
|
||
|
||
- 同步更新相关变更文档；若影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，再同步必要的文档/沟通材料
|
||
- 运行或执行相关验证；若修补影响范围较大，再补充执行受影响的回归验证
|
||
|
||
若修改了文档：
|
||
|
||
- 在 `fast-drive` workflow 下，确认 `design.md` 仍是事实来源，`tasks.md` 仍从 `design.md` 派生
|
||
- 确认 `design.md` 的需求、执行约束、影响范围、决策、执行计划、验证计划、风险和待解决问题与实际变更一致
|
||
- 确认 `tasks.md` 每个完成任务都有对应实际产物和必要验证，新增修补已补充任务或记录在合适任务中
|
||
- 禁止将本次 change 内容同步到 `openspec/specs/`，该操作属于 archive 阶段
|
||
- 在 `fast-drive` workflow 下不创建 `proposal.md` 或 `specs/*.md`；若实际 schema 不是 `fast-drive`，则按实际 schema 的 required artifacts 创建或更新本次 change 目录下的 artifacts
|
||
|
||
执行后重新读取所有被修改的实际产物、验证材料和文档，并复核：
|
||
|
||
- “Design 偏离清单” 是否已清空或已标注保留原因
|
||
- “需回写文档清单” 是否已清空
|
||
- “方向待确认清单” 是否已清空或已记录用户决策
|
||
- “任务状态问题清单” 和 “验证问题清单” 是否已清空或已标注残留原因
|
||
- “质量/优化清单” 中哪些已处理，哪些有意延期
|
||
- 必要的文档/沟通材料是否已按影响范围同步
|
||
- 所有模板注释、空表格行和占位文本是否已清空或替换为有效内容
|
||
|
||
## 5. 收尾
|
||
|
||
列出所有修改的文件、回退依据、验证命令或检查结果、文档同步摘要和剩余风险；若实际创建了备份，再列出备份文件。
|
||
|
||
若本次因缺少验证结果、修补记录或上下文而降级执行，或有问题因信息不足暂未处理，单独说明。
|