From ea9bc41e4c9e4457499f933780d5b1ac75232db2 Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Wed, 3 Jun 2026 17:43:07 +0800 Subject: [PATCH] =?UTF-8?q?refactor(prompts):=20=E7=A7=BB=E9=99=A4=20apply?= =?UTF-8?q?-review=20=E4=B8=AD=E6=89=80=E6=9C=89=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E5=9B=9E=E5=86=99=E6=AD=A5=E9=AA=A4=EF=BC=8C=E9=80=82=E9=85=8D?= =?UTF-8?q?=20fast-drive=20=E5=8D=95=E5=90=91=E5=B7=A5=E4=BD=9C=E6=B5=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/prompts/prompt-apply-review.md | 87 ++++++++++++----------------- 1 file changed, 35 insertions(+), 52 deletions(-) diff --git a/docs/prompts/prompt-apply-review.md b/docs/prompts/prompt-apply-review.md index bb2955c..208b6d1 100644 --- a/docs/prompts/prompt-apply-review.md +++ b/docs/prompts/prompt-apply-review.md @@ -1,17 +1,17 @@ -审查 OpenSpec apply 完成后以及后续手动修补后的实际变更，判断实际产物、验证结果和变更文档是否与 `design.md` 事实来源一致，识别偏离、漏记和可优化点，并将确认后的实际变更同步回变更文档，按以下流程执行。 +审查 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 阶段，不在此提示词范围内 +- 禁止同步或修改 `openspec/specs/` 下的主规范，该操作属于 archive 阶段，不在此提示词范围内 - 优先使用当前会话中的执行说明、验证结论、手动修补记录和已生成的变更文档；仅在无法明确 change、`schemaName`、改动范围或修补来源时，再用提问工具或 OpenSpec 命令补充定位 - 不要因为实际产物已经存在就自动以实际产物为准；先判断差异属于“design 要求未完成”、“验证后新增修补”、“合理落地细化”还是“意外偏离/回归” -- 每批实际产物或文档修改执行前用提问工具获得用户确认 +- 每批实际产物修改执行前用提问工具获得用户确认 - 删除/重写前用提问工具获得用户确认；若存在 git 仓库，不创建 `.bak` 备份文件，改用当前 `git status` / `git diff` 作为回退依据；仅在无版本控制或用户明确要求时，才将备份放到代码目录外的用户确认路径 -- 若修改实际产物涉及新行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，同步更新验证材料、相关变更文档和必要的文档/沟通材料 +- 若修改实际产物涉及新行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，同步更新验证材料 ## 1. 收集 @@ -66,21 +66,20 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts； 按以下优先级检查： -| 优先级 | 维度 | 检查点 | -| ------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 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 是否仍保留模板注释、空表格行或占位任务文本 | +| 优先级 | 维度 | 检查点 | +| ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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` +- 实际变更因验证暴露问题、手动修补或合理落地细化而新增/变更 → 需确认是否需要补充验证 - 实际变更与 `design.md` 不一致，且无法判断应以哪边为准 → 列入待确认清单 -- `tasks.md` 状态与实际完成情况或验证结果不一致 → 修正任务状态或补充任务 +- `tasks.md` 状态与实际完成情况或验证结果不一致 → 列入任务状态问题清单 不要把以下情况直接视为合理修补： @@ -91,14 +90,13 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts； 重点识别： -- `design.md` 要求但未落地的结果、流程、内容、场景、异常处理、文档/沟通更新或验证步骤 -- 实际变更偏离“目标 / 非目标”“执行约束”“决策”或“执行计划”的地方 -- apply 完成后新增的修补、边界处理、接口调整、行为变化、流程变化或内容变化未同步到 `design.md` -- “影响范围”与实际改动范围不一致，导致新会话无法复盘真实影响面 -- “验证计划”中要求的验证、质量检查、审阅、批准、沟通检查或人工检查未执行或未记录 -- `tasks.md` 标记完成，但实际产物、验证、文档或沟通未闭环 +- `design.md` 要求但未落地的结果、流程、内容、场景、异常处理或验证步骤 +- 实际变更偏离"目标 / 非目标""执行约束""决策"或"执行计划"的地方 +- apply 完成后新增的修补、边界处理、接口调整、行为变化、流程变化或内容变化 +- "影响范围"与实际改动范围不一致，导致新会话无法复盘真实影响面 +- "验证计划"中要求的验证、质量检查、审阅、批准、沟通检查或人工检查未执行或未记录 +- `tasks.md` 标记完成，但实际产物或验证未闭环 - `design.md` 或 `tasks.md` 仍保留 `` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容 -- 必要的文档/沟通材料未同步影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果的变更 - 实际产物存在明显的重复、复杂度过高、表达不清、责任不明、风险处理薄弱、验证质量不足等问题 - `fast-drive` change 中仍错误依赖 `proposal.md`、`specs/*.md`、`Capabilities` 或 `Modified Capabilities` 的内容 @@ -107,13 +105,12 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts； 1. **问题总览表**：问题类型 × 涉及文件数 2. **实际变更与修补清单**：本次已落地的主要变更、后续修补和验证结论；若缺少验证结果，对未验证部分单独标记 3. **Design 偏离清单**：实际变更未完成、完成不充分或偏离 `design.md` 的内容 -4. **需回写文档清单**：实际产物和验证中已确认、但 `design.md`、`tasks.md` 或相关文档/沟通材料未体现的变更、修补或约束变化 -5. **方向待确认清单**：实际变更与 `design.md` 不一致，且无法判断应以哪边为准的事项 -6. **任务状态问题清单**：未真正完成、状态错误或需补充的新任务 -7. **验证问题清单**：缺失覆盖、掩盖错误、验证不足或修补后未回归验证的问题 -8. **质量/优化清单**：可优化的实际产物问题和建议 -9. **Schema 差异清单**：实际 schema 与默认 `fast-drive` 不同时，列出因此跳过或改按实际 artifacts 审查的内容 -10. **逐项分析**：每个问题说明位置、问题、影响、建议和建议修复方向 +4. **方向待确认清单**：实际变更与 `design.md` 不一致，且无法判断应以哪边为准的事项 +5. **任务状态问题清单**：未真正完成、状态错误或需补充的新任务 +6. **验证问题清单**：缺失覆盖、掩盖错误、验证不足或修补后未回归验证的问题 +7. **质量/优化清单**：可优化的实际产物问题和建议 +8. **Schema 差异清单**：实际 schema 与默认 `fast-drive` 不同时，列出因此跳过或改按实际 artifacts 审查的内容 +9. **逐项分析**：每个问题说明位置、问题、影响、建议和建议修复方向 若所有清单均为空，输出“审查通过，未发现问题”，跳至步骤 5。 @@ -124,11 +121,9 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts； 再整理完整修复方案，按类别列出： - 实际工作或验证补充：补完成、补异常处理、补回归验证、修复被弱化或绕过的验证 -- Design 回写：同步 `design.md` 中遗漏或过时的需求、执行约束、影响范围、决策、执行计划、验证计划、风险或待解决问题 - 任务状态修正：修正已完成/未完成状态，补充 apply 后新增但已完成的修补任务或验证任务 -- 文档/沟通同步：同步行为、流程、接口、内容、数据、配置、责任边界或用户可见结果变化 - 质量优化：在不改变目标结果的前提下优化结构、表达、一致性、可维护性或移交质量 -- Schema 兼容处理：若实际 schema 不是 `fast-drive`，按实际存在的 artifacts 说明额外文档同步项 +- Schema 兼容处理：若实际 schema 不是 `fast-drive`，按实际存在的 artifacts 说明需关注的差异项 对每个拟修改的文件说明： @@ -142,38 +137,26 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts； ## 4. 执行 -逐项执行已确认的实际产物、验证和文档修复。 +逐项执行已确认的实际产物和验证修复。 若涉及删除或重写： -- 存在 git 仓库时，先记录当前 `git status` / `git diff`，不要在实际产物、文档或代码目录创建 `.bak` 文件 +- 存在 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 偏离清单” 是否已清空或已标注保留原因 -- “需回写文档清单” 是否已清空 -- “方向待确认清单” 是否已清空或已记录用户决策 -- “任务状态问题清单” 和 “验证问题清单” 是否已清空或已标注残留原因 -- “质量/优化清单” 中哪些已处理，哪些有意延期 -- 必要的文档/沟通材料是否已按影响范围同步 -- 所有模板注释、空表格行和占位文本是否已清空或替换为有效内容 +- "Design 偏离清单" 是否已清空或已标注保留原因 +- "方向待确认清单" 是否已清空或已记录用户决策 +- "任务状态问题清单" 和 "验证问题清单" 是否已清空或已标注残留原因 +- "质量/优化清单" 中哪些已处理，哪些有意延期 ## 5. 收尾 -列出所有修改的文件、回退依据、验证命令或检查结果、文档同步摘要和剩余风险；若实际创建了备份，再列出备份文件。 +列出所有修改的文件、回退依据、验证命令或检查结果和剩余风险；若实际创建了备份，再列出备份文件。 若本次因缺少验证结果、修补记录或上下文而降级执行，或有问题因信息不足暂未处理，单独说明。