lanyuanxiaoyao/Alfred
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: merge dev-openspec-optim into master

Browse Source
This commit is contained in:
兰缘小妖
2026-05-28 11:01:36 +08:00
parent 35ce2d1eda be4b85126b
commit cd1533328d
7 changed files with 195 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/development/README.md
View File

@@ -97,13 +97,6 @@
如果无需更新文档，必须在收尾说明中说明原因。详细规则见 [文档总览](../README.md)。 如果无需更新文档，必须在收尾说明中说明原因。详细规则见 [文档总览](../README.md)。
## OpenSpec 协作规则
- 本项目 OpenSpec 使用 fast-drive schema，变更文档只包含 design.md 和 tasks.md，不创建 proposal.md 或 specs/\*.md。
- design.md 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth。
- tasks.md 必须从 design.md 派生，一行一个 checkbox 任务。
- 实现阶段按 tasks.md 顺序执行，完成后立即标记任务状态。
## 事实来源 ## 事实来源
| 主题 | 事实来源 | | 主题 | 事实来源 |
@@ -114,4 +107,4 @@
## 更新触发条件 ## 更新触发条件
修改常用命令、质量门禁、全局工程规则、目录边界、OpenSpec 协作方式或开发文档索引时，必须更新本文档。 修改常用命令、质量门禁、全局工程规则、目录边界或开发文档索引时，必须更新本文档。

62
docs/prompts/prompt-apply-review.md
View File

@@ -1,11 +1,11 @@
审查 OpenSpec apply 完成后以及后续手动修补后的实际变更，判断实际产物、验证结果和变更文档是否与 `design.md` source of truth 一致，识别偏离、漏记和可优化点，并将确认后的实际变更同步回变更文档，按以下流程执行。 审查 OpenSpec apply 完成后以及后续手动修补后的实际变更，判断实际产物、验证结果和变更文档是否与 `design.md` 事实来源一致，识别偏离、漏记和可优化点，并将确认后的实际变更同步回变更文档，按以下流程执行。
## 约束 ## 约束
- 先审查再修复；未经用户确认，不修改实际产物或变更文档 - 先审查再修复；未经用户确认，不修改实际产物或变更文档
- 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查 - 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查
- 在 `fast-drive` workflow 下，核心 artifacts 是 `design.md` 和 `tasks.md`；不要要求存在 `proposal.md` 或 `specs/*.md` - 在 `fast-drive` workflow 下，核心 artifacts 是 `design.md` 和 `tasks.md`；不要要求存在 `proposal.md` 或 `specs/*.md`
- 在 `fast-drive` workflow 下，`design.md` 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth，`tasks.md` 是 apply 进度和验证闭环的 tracking 文件 - 在 `fast-drive` workflow 下，`design.md` 是范围、需求、决策、执行约束、执行方向和验证预期的事实来源，`tasks.md` 是 apply 进度和验证闭环的跟踪文件
- 禁止同步或修改 `openspec/specs/` 下的主规范；若实际 schema 包含 `specs/*.md`，也只允许修改本次 change 目录下实际存在的 spec artifacts，主规范同步属于 archive 阶段，不在此提示词范围内 - 禁止同步或修改 `openspec/specs/` 下的主规范；若实际 schema 包含 `specs/*.md`，也只允许修改本次 change 目录下实际存在的 spec artifacts，主规范同步属于 archive 阶段，不在此提示词范围内
- 优先使用当前会话中的执行说明、验证结论、手动修补记录和已生成的变更文档；仅在无法明确 change、`schemaName`、改动范围或修补来源时，再用提问工具或 OpenSpec 命令补充定位 - 优先使用当前会话中的执行说明、验证结论、手动修补记录和已生成的变更文档；仅在无法明确 change、`schemaName`、改动范围或修补来源时，再用提问工具或 OpenSpec 命令补充定位
- 不要因为实际产物已经存在就自动以实际产物为准；先判断差异属于“design 要求未完成”、“验证后新增修补”、“合理落地细化”还是“意外偏离/回归” - 不要因为实际产物已经存在就自动以实际产物为准；先判断差异属于“design 要求未完成”、“验证后新增修补”、“合理落地细化”还是“意外偏离/回归”
@@ -29,25 +29,25 @@ a) 先并行读取核心入口和配置，确定范围：
- workflow context/configuration，例如存在时读取 `openspec/config.yaml` - workflow context/configuration，例如存在时读取 `openspec/config.yaml`
- 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml` - 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml`
b) 从 `design.md` 提取审查基准： b) 从 `design.md` 的实际章节提取审查基准。`fast-drive` 默认中文章节包括：
- `Context` - `背景`
- `Discussion Notes` - `讨论记录`
- `Requirements` - `需求`
- `Goals / Non-Goals` - `目标 / 非目标`
- `Execution Guardrails` - `执行约束`
- `Affected Areas` - `影响范围`
- `Decisions` - `决策`
- `Execution Plan` - `执行计划`
- `Verification Plan` - `验证计划`
- `Risks / Trade-offs` - `风险 / 权衡`
- `Open Questions` - `待解决问题`
c) 从 `tasks.md` 提取任务状态、已完成项、未完成项、验证任务和文档/沟通任务；重点记录所有已标记完成的 `- [x]` 或等价完成状态。 c) 从 `tasks.md` 提取任务状态、已完成项、未完成项、验证任务和文档/沟通任务；重点记录所有已标记完成的 `- [x]` 或等价完成状态。
d) 获取实际改动范围：若在版本控制工作区中，优先使用 `git diff --name-only`、`git diff --name-only --cached`；若工作区已干净或不适用版本控制，再结合 `design.md`、`tasks.md`、验证记录和执行记录反推。 d) 获取实际改动范围：若在版本控制工作区中，优先使用 `git diff --name-only`、`git diff --name-only --cached`；若工作区已干净或不适用版本控制，再结合 `design.md`、`tasks.md`、验证记录和执行记录反推。
e) 并行读取实际改动范围、`Affected Areas`、`Execution Plan`、`Verification Plan` 涉及的实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料。 e) 并行读取实际改动范围、“影响范围”“执行计划”“验证计划”涉及的实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料。
f) 收集当前会话中与本次变更相关的执行说明、apply 过程中的偏离、验证失败、手动修补原因、验证命令或检查结果、待确认事项。 f) 收集当前会话中与本次变更相关的执行说明、apply 过程中的偏离、验证失败、手动修补原因、验证命令或检查结果、待确认事项。
@@ -66,14 +66,14 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；
按以下优先级检查： 按以下优先级检查：
| 优先级 | 维度 | 检查点 | | 优先级 | 维度 | 检查点 |
| ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| P0 | 实际变更与验证结论 | 当前实际产物的真实状态是什么；apply 后是否有手动改动或验证后修补；验证是否证明这些变更有效；若缺少验证结果，标记相关结论为“未验证”；检查是否存在回归、未覆盖场景或被掩盖的问题 | | P0 | 实际变更与验证结论 | 当前实际产物的真实状态是什么；apply 后是否有手动改动或验证后修补；验证是否证明这些变更有效；若缺少验证结果，标记相关结论为“未验证”；检查是否存在回归、未覆盖场景或被掩盖的问题 |
| P1 | `design.md` 一致性 | 实际变更是否符合 `Requirements`、`Goals / Non-Goals`、`Execution Guardrails`、`Decisions`、`Execution Plan` 和 `Verification Plan`；`Open Questions` 是否已明确区分 blocking / non-blocking 或写出 `None`；是否违反被明确否决的方案、用户偏好或约束 | | P1 | `design.md` 一致性 | 实际变更是否符合“需求”“目标 / 非目标”“执行约束”“决策”“执行计划”和“验证计划”；“待解决问题”是否已明确区分 blocking / non-blocking 或写出“无”；是否违反被明确否决的方案、用户偏好或约束 |
| P2 | `tasks.md` 真实性 | 已完成任务是否真的完成并完成必要验证；未完成任务是否仍然必要；apply 或手动修补是否引入了需要补充的新任务、验证任务或文档/沟通任务 | | P2 | `tasks.md` 真实性 | 已完成任务是否真的完成并完成必要验证；未完成任务是否仍然必要；apply 或手动修补是否引入了需要补充的新任务、验证任务或文档/沟通任务 |
| P3 | 文档回写完整性 | 已落地的实际变更、验证后新增修补、边界处理、异常路径、验证结论、实际触达产物是否已同步回 `design.md` 和 `tasks.md`；若影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，再检查必要的文档/沟通材料是否同步 | | P3 | 文档回写完整性 | 已落地的实际变更、验证后新增修补、边界处理、异常路径、验证结论、实际触达产物是否已同步回 `design.md` 和 `tasks.md`；若影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，再检查必要的文档/沟通材料是否同步 |
| P4 | 质量与可维护性 | 实际产物的结构、清晰度、一致性、可维护性、风险处理、移交质量、验证质量、与现有模式的一致性是否存在明显问题或可优化点 | | P4 | 质量与可维护性 | 实际产物的结构、清晰度、一致性、可维护性、风险处理、移交质量、验证质量、与现有模式的一致性是否存在明显问题或可优化点 |
| P5 | Schema 兼容性 | 对实际存在的 artifacts 检查是否符合其 schema；若不是 `fast-drive`，仅按实际 artifacts 检查，不凭空要求 `fast-drive` 专属结构；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 | | P5 | Schema 兼容性 | 对实际存在的 artifacts 检查是否符合其 schema；若不是 `fast-drive`，仅按实际 artifacts 检查，不凭空要求 `fast-drive` 专属结构；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 |
分析时区分四类差异： 分析时区分四类差异：
@@ -85,17 +85,17 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；
不要把以下情况直接视为合理修补： 不要把以下情况直接视为合理修补：
- 通过跳过、弱化或绕过验证来声称变更完成 - 通过跳过、弱化或绕过验证来声称变更完成
- 为了贴合当前实际产物而降低已确认的 requirement、acceptance criteria 或 guardrail - 为了贴合当前实际产物而降低已确认的需求、验收标准或执行约束
- 未经过讨论和验证就扩大功能、流程、内容或责任范围 - 未经过讨论和验证就扩大功能、流程、内容或责任范围
- 违反 `Execution Guardrails`、被拒绝方案或 `Open Questions` 中尚未解决的 blocker - 违反“执行约束”、被拒绝方案或“待解决问题”中尚未解决的 blocker
重点识别： 重点识别：
- `design.md` 要求但未落地的结果、流程、内容、场景、异常处理、文档/沟通更新或验证步骤 - `design.md` 要求但未落地的结果、流程、内容、场景、异常处理、文档/沟通更新或验证步骤
- 实际变更偏离 `Goals / Non-Goals`、`Execution Guardrails`、`Decisions` 或 `Execution Plan` 的地方 - 实际变更偏离“目标 / 非目标”“执行约束”“决策”或“执行计划”的地方
- apply 完成后新增的修补、边界处理、接口调整、行为变化、流程变化或内容变化未同步到 `design.md` - apply 完成后新增的修补、边界处理、接口调整、行为变化、流程变化或内容变化未同步到 `design.md`
- `Affected Areas` 与实际改动范围不一致，导致新会话无法复盘真实影响面 - “影响范围”与实际改动范围不一致，导致新会话无法复盘真实影响面
- `Verification Plan` 中要求的验证、质量检查、审阅、批准、沟通检查或 manual checks 未执行或未记录 - “验证计划”中要求的验证、质量检查、审阅、批准、沟通检查或人工检查未执行或未记录
- `tasks.md` 标记完成，但实际产物、验证、文档或沟通未闭环 - `tasks.md` 标记完成，但实际产物、验证、文档或沟通未闭环
- `design.md` 或 `tasks.md` 仍保留 `<!-- ... -->` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容 - `design.md` 或 `tasks.md` 仍保留 `<!-- ... -->` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容
- 必要的文档/沟通材料未同步影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果的变更 - 必要的文档/沟通材料未同步影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果的变更
@@ -124,7 +124,7 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；
再整理完整修复方案，按类别列出： 再整理完整修复方案，按类别列出：
- 实际工作或验证补充：补完成、补异常处理、补回归验证、修复被弱化或绕过的验证 - 实际工作或验证补充：补完成、补异常处理、补回归验证、修复被弱化或绕过的验证
- Design 回写：同步 `design.md` 中遗漏或过时的 requirements、guardrails、affected areas、decisions、execution plan、verification plan、risks 或 open questions - Design 回写：同步 `design.md` 中遗漏或过时的需求、执行约束、影响范围、决策、执行计划、验证计划、风险或待解决问题
- 任务状态修正：修正已完成/未完成状态，补充 apply 后新增但已完成的修补任务或验证任务 - 任务状态修正：修正已完成/未完成状态，补充 apply 后新增但已完成的修补任务或验证任务
- 文档/沟通同步：同步行为、流程、接口、内容、数据、配置、责任边界或用户可见结果变化 - 文档/沟通同步：同步行为、流程、接口、内容、数据、配置、责任边界或用户可见结果变化
- 质量优化：在不改变目标结果的前提下优化结构、表达、一致性、可维护性或移交质量 - 质量优化：在不改变目标结果的前提下优化结构、表达、一致性、可维护性或移交质量
@@ -156,8 +156,8 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；
若修改了文档： 若修改了文档：
- 在 `fast-drive` workflow 下，确认 `design.md` 仍是 source of truth，`tasks.md` 仍从 `design.md` 派生 - 在 `fast-drive` workflow 下，确认 `design.md` 仍是事实来源，`tasks.md` 仍从 `design.md` 派生
- 确认 `design.md` 的 requirements、guardrails、affected areas、decisions、execution plan、verification plan、risks 和 open questions 与实际变更一致 - 确认 `design.md` 的需求、执行约束、影响范围、决策、执行计划、验证计划、风险和待解决问题与实际变更一致
- 确认 `tasks.md` 每个完成任务都有对应实际产物和必要验证，新增修补已补充任务或记录在合适任务中 - 确认 `tasks.md` 每个完成任务都有对应实际产物和必要验证，新增修补已补充任务或记录在合适任务中
- 禁止将本次 change 内容同步到 `openspec/specs/`，该操作属于 archive 阶段 - 禁止将本次 change 内容同步到 `openspec/specs/`，该操作属于 archive 阶段
- 在 `fast-drive` workflow 下不创建 `proposal.md` 或 `specs/*.md`；若实际 schema 不是 `fast-drive`，则按实际 schema 的 required artifacts 创建或更新本次 change 目录下的 artifacts - 在 `fast-drive` workflow 下不创建 `proposal.md` 或 `specs/*.md`；若实际 schema 不是 `fast-drive`，则按实际 schema 的 required artifacts 创建或更新本次 change 目录下的 artifacts

48
docs/prompts/prompt-proposal-review.md
View File

@@ -5,7 +5,7 @@
- 仅修改本次变更文档，不修改实际产物 - 仅修改本次变更文档，不修改实际产物
- 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查 - 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查
- 在 `fast-drive` workflow 下，核心 artifacts 是 `design.md` 和 `tasks.md`；不要要求存在 `proposal.md` 或 `specs/*.md` - 在 `fast-drive` workflow 下，核心 artifacts 是 `design.md` 和 `tasks.md`；不要要求存在 `proposal.md` 或 `specs/*.md`
- 在 `fast-drive` workflow 下，`design.md` 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth，`tasks.md` 必须从 `design.md` 派生 - 在 `fast-drive` workflow 下，`design.md` 是范围、需求、决策、执行约束、执行方向和验证预期的事实来源，`tasks.md` 必须从 `design.md` 派生
- 优先使用当前会话中的讨论、explore/propose 阶段结论和已生成的变更文档；仅在无法明确 change、`schemaName` 或文档范围时，再用提问工具或 OpenSpec 命令补充定位 - 优先使用当前会话中的讨论、explore/propose 阶段结论和已生成的变更文档；仅在无法明确 change、`schemaName` 或文档范围时，再用提问工具或 OpenSpec 命令补充定位
- 每批文档修改建议执行前用提问工具获得用户确认 - 每批文档修改建议执行前用提问工具获得用户确认
- 删除/重写前用提问工具获得用户确认，并先备份原文件为 `{file}.bak.{timestamp}` - 删除/重写前用提问工具获得用户确认，并先备份原文件为 `{file}.bak.{timestamp}`
@@ -26,21 +26,21 @@ a) 先并行读取核心入口和配置，确定范围：
- workflow context/configuration，例如存在时读取 `openspec/config.yaml` - workflow context/configuration，例如存在时读取 `openspec/config.yaml`
- 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml` - 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml`
b) 从 `design.md` 提取审查基准： b) 从 `design.md` 的实际章节提取审查基准。`fast-drive` 默认中文章节包括：
- `Context` - `背景`
- `Discussion Notes` - `讨论记录`
- `Requirements` - `需求`
- `Goals / Non-Goals` - `目标 / 非目标`
- `Execution Guardrails` - `执行约束`
- `Affected Areas` - `影响范围`
- `Decisions` - `决策`
- `Execution Plan` - `执行计划`
- `Verification Plan` - `验证计划`
- `Risks / Trade-offs` - `风险 / 权衡`
- `Open Questions` - `待解决问题`
c) 基于 `Affected Areas`、`Execution Plan`、`Verification Plan`、讨论中提到的受影响范围，并行读取相关实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料，确认文档是否贴合当前实际状态。 c) 基于“影响范围”“执行计划”“验证计划”、讨论中提到的受影响范围，并行读取相关实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料，确认文档是否贴合当前实际状态。
d) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；若存在 `proposal.md`、`specs/*.md`，再按该 schema 的要求补充读取和审查。 d) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；若存在 `proposal.md`、`specs/*.md`，再按该 schema 的要求补充读取和审查。
@@ -57,13 +57,13 @@ d) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；
按以下优先级检查： 按以下优先级检查：
| 优先级 | 维度 | 检查点 | | 优先级 | 维度 | 检查点 |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| P0 | 讨论承接性 | 仅在存在讨论记录时检查：`design.md` 是否完整记录已确认的目标、非目标、用户偏好、约束、边界条件、风险、关键决策、被否决方案和待澄清事项；若无讨论记录，标记为“跳过” | | P0 | 讨论承接性 | 仅在存在讨论记录时检查：`design.md` 是否完整记录已确认的目标、非目标、用户偏好、约束、边界条件、风险、关键决策、被否决方案和待澄清事项；若无讨论记录，标记为“跳过” |
| P1 | `design.md` 自包含性 | `design.md` 是否足以让看不到前序对话的执行者继续工作；是否包含完整 required sections；`Open Questions` 是否明确区分 blocking / non-blocking 或写出 `None`；是否存在依赖未记录聊天上下文的隐含要求 | | P1 | `design.md` 自包含性 | `design.md` 是否足以让看不到前序对话的执行者继续工作；是否包含完整必需章节；“待解决问题”是否明确区分 blocking / non-blocking 或写出“无”；是否存在依赖未记录聊天上下文的隐含要求 |
| P2 | 当前状态真实性 | `design.md` 对当前实际产物、流程、接口、内容、数据、配置、依赖、责任边界、参考材料和验证入口的描述是否准确；是否把“计划变更”误写成“当前现状”；`Affected Areas` 是否遗漏真实受影响区域 | | P2 | 当前状态真实性 | `design.md` 对当前实际产物、流程、接口、内容、数据、配置、依赖、责任边界、参考材料和验证入口的描述是否准确；是否把“计划变更”误写成“当前现状”；“影响范围”是否遗漏真实受影响区域 |
| P3 | `tasks.md` 派生性 | `tasks.md` 是否从 `design.md` 派生；是否覆盖 requirements、guardrails、decisions、execution plan 和 verification plan；是否依赖 `proposal.md` 或 `specs/*.md` 中未写入 `design.md` 的内容 | | P3 | `tasks.md` 派生性 | `tasks.md` 是否从 `design.md` 派生；是否覆盖需求、执行约束、决策、执行计划和验证计划；是否依赖 `proposal.md` 或 `specs/*.md` 中未写入 `design.md` 的内容 |
| P4 | OpenSpec 合规性 | 对实际存在的 artifacts 检查是否遵循对应 schema 和 OpenSpec 术语；`tasks.md` 是否一行一个 `- [ ]` checkbox 任务、按 `##` numbered headings 分组、无无关的仓库/版本控制/发布操作任务；`design.md` 是否避免 task checkbox；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 | | P4 | OpenSpec 合规性 | 对实际存在的 artifacts 检查是否遵循对应 schema 和 OpenSpec 术语；`tasks.md` 是否一行一个 `- [ ]` checkbox 任务、按 `##` 编号标题分组、无无关的仓库/版本控制/发布操作任务；`design.md` 是否避免 task checkbox；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 |
分析时区分两类情况： 分析时区分两类情况：
@@ -73,9 +73,9 @@ d) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；
重点识别： 重点识别：
- 讨论中已确定但 `design.md` 未记录的内容 - 讨论中已确定但 `design.md` 未记录的内容
- `design.md` 中缺失或含糊的 requirements、acceptance criteria、guardrails、decisions、verification expectations - `design.md` 中缺失或含糊的需求、验收标准、执行约束、决策或验证预期
- `Open Questions` 未明确区分 blocking / non-blocking、与 `tasks.md` 冲突，或包含 apply 前必须解决的 blocker - “待解决问题”未明确区分 blocking / non-blocking、与 `tasks.md` 冲突，或包含 apply 前必须解决的 blocker
- `tasks.md` 未覆盖 `design.md` 的要求、约束、执行计划、验证计划或文档/沟通更新要求 - `tasks.md` 未覆盖 `design.md` 的需求、约束、执行计划、验证计划或文档/沟通更新要求
- `tasks.md` 标记了无法验证、跨行、过大、顺序错误或包含无关仓库/版本控制/发布操作的任务 - `tasks.md` 标记了无法验证、跨行、过大、顺序错误或包含无关仓库/版本控制/发布操作的任务
- 文档仍保留 `<!-- ... -->` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容 - 文档仍保留 `<!-- ... -->` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容
- 文档基于错误当前状态做出的设计或任务拆分 - 文档基于错误当前状态做出的设计或任务拆分

3
openspec/config.yaml
View File

@@ -2,7 +2,6 @@ schema: fast-drive
context: | context: |
- 使用中文（注释、文档、交流），面向中文开发者 - 使用中文（注释、文档、交流），面向中文开发者
- openspec文档的关键字按openspec规范使用，不要翻译为中文
- **优先阅读 docs/README.md** 获取文档路由、归属矩阵和影响分析规则 - **优先阅读 docs/README.md** 获取文档路由、归属矩阵和影响分析规则
- **其次阅读 docs/development/README.md** 获取开发规范、常用命令、质量门禁和全局规则 - **其次阅读 docs/development/README.md** 获取开发规范、常用命令、质量门禁和全局规则
- 文档文件名优先使用单个英文单词（usage.md、config.md、deploy.md、troubleshoot.md），目录上下文足以消歧时不在文件名重复限定词 - 文档文件名优先使用单个英文单词（usage.md、config.md、deploy.md、troubleshoot.md），目录上下文足以消歧时不在文件名重复限定词
@@ -29,8 +28,10 @@ context: |
rules: rules:
design: design:
- fast-drive的design.md章节标题和正文使用中文；仅OpenSpec术语、文件名、schema字段名、命令和代码符号保留英文
- 先前的讨论技术方案要尽可能体现在设计文档中，便于指导实现阶段不偏离已定的技术路线 - 先前的讨论技术方案要尽可能体现在设计文档中，便于指导实现阶段不偏离已定的技术路线
tasks: tasks:
- fast-drive的tasks.md分组标题、任务描述和验证说明使用中文；每个任务必须保留OpenSpec CLI可解析的单行checkbox格式
- 一行一个任务，严禁任务内容跨行 - 一行一个任务，严禁任务内容跨行
- 如果是代码存在更新必须 - 如果是代码存在更新必须
- 执行完整的测试、代码检查、格式检查等质量保障手段 - 执行完整的测试、代码检查、格式检查等质量保障手段

189
openspec/schemas/fast-drive/schema.yaml
View File

@@ -1,170 +1,139 @@
name: fast-drive name: fast-drive
version: 1 version: 1
description: Fast OpenSpec workflow - design -> tasks -> apply description: 快速 OpenSpec workflow - design -> tasks -> apply
artifacts: artifacts:
- id: design - id: design
generates: design.md generates: design.md
description: Self-contained solution brief and execution plan description: 自包含的方案说明和执行计划
template: design.md template: design.md
instruction: | instruction: |
Create design.md as the self-contained source of truth for what will 创建 design.md，作为本次变更“改什么、为什么改、如何执行”的自包含事实来源。
change, why it is changing, and how the work will be executed.
This workflow does not use proposal or specs artifacts. design.md MUST 本 workflow 不使用 proposal 或 specs artifacts。design.md MUST 保留前序探索和用户讨论中的重要结论，确保后续 apply 阶段即使经历上下文压缩或进入新会话，也能正确继续执行。
preserve the important outcomes from prior exploration and user
discussion so a later apply phase can proceed correctly even after
context compression or in a new session.
Write for someone who cannot see the earlier conversation. Keep simple 语言规则（强制）：
changes concise, but include enough detail to make execution
unambiguous. Add more detail when any apply:
- Cross-cutting change across multiple systems, teams, workstreams, or - fast-drive 的 design.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文
artifacts
- New dependency, integration, vendor, tool, policy, or external input - 最终 design.md 不得残留英文模板句子或英文占位内容，除非该英文是 OpenSpec 术语、文件名、schema 字段名、代码符号、命令或必要技术名词
- Significant information model, process model, data model, or ownership 面向看不到早期对话的人编写。简单变更保持精炼，但必须包含足够细节让执行无歧义。遇到以下情况时增加细节：
changes
- Security, privacy, compliance, performance, operational, or migration - 跨多个系统、团队、工作流或 artifacts 的横切变更
complexity
- Ambiguity that benefits from decisions before execution - 新增依赖、集成、供应商、工具、策略或外部输入
- Prior discussion settled non-obvious requirements, constraints, or - 重要的信息模型、流程模型、数据模型或归属关系变化
rejected alternatives
Required sections: - 涉及安全、隐私、合规、性能、运维或迁移复杂度
- **Context**: Problem, current state, relevant references, and the user - 执行前需要先做决策才能降低歧义
request that triggered this change
- **Discussion Notes**: Key points from exploration or prior discussion - 前序讨论已经确认非显而易见的需求、约束或被否决方案
that must not be lost. Include agreed conclusions, user preferences,
constraints, and important rejected ideas.
- **Requirements**: Expected outcomes, behavior/process/interface/content 必需章节（建议使用以下中文章节标题）：
changes, continuity expectations, and acceptance criteria.
- **Goals / Non-Goals**: What this change will achieve and what is - **背景**：问题、当前状态、相关参考资料，以及触发本次变更的用户请求
explicitly out of scope.
- **Execution Guardrails**: Must-follow constraints, forbidden approaches, - **讨论记录**：探索或前序讨论中必须保留的关键点，包括已确认结论、用户偏好、约束和重要的被否决方案
preserved behavior/processes, dependency limits, and project- or
workflow-specific boundaries.
- **Affected Areas**: Concrete artifacts, references, stakeholders, - **需求**：预期结果、行为/流程/接口/内容变化、连续性要求和验收标准
systems, workstreams, documents, configurations, assets, or handoffs that
are relevant to the change.
- **Decisions**: Key choices with rationale (why X over Y?). For each - **目标 / 非目标**：本次变更要达成的目标，以及明确不在范围内的内容
important decision, include alternatives considered and why they were not
chosen.
- **Execution Plan**: Main workstreams or artifacts to change, integration - **执行约束**：必须遵守的约束、禁止的做法、需保持的行为/流程、依赖限制，以及项目或 workflow 特有边界
or handoff points, sequencing, and any rollout notes.
- **Verification Plan**: Validation checks, reviews, approvals, - **影响范围**：与本次变更相关的具体 artifacts、参考资料、相关方、系统、工作流、文档、配置、资产或交接事项
acceptance checks, documentation checks, communication checks, and manual
checks needed to prove the change is complete.
- **Risks / Trade-offs**: Known limitations and things that could go - **决策**：关键选择及理由（为什么选 X 而不是 Y）。每个重要决策都要包含考虑过的替代方案，以及未选择它们的原因
wrong.
Format: [Risk] -> Mitigation
- **Open Questions**: Outstanding decisions, assumptions, or unknowns to - **执行计划**：主要工作流或待修改 artifacts、集成或交接点、执行顺序，以及必要的发布/落地说明
resolve before execution. Separate blocking questions that must pause
apply from non-blocking follow-ups. Use "None" if there are no open
questions.
Optional sections when relevant: - **验证计划**：用于证明变更完成所需的验证检查、审查、批准、验收检查、文档检查、沟通检查和人工检查
- **Migration / Rollout Plan**: Rollout steps, communication, ownership, - **风险 / 权衡**：已知限制和可能出错的事项
rollback, or continuity strategy. 格式：[风险] -> 缓解措施
Focus on preserving requirements, rationale, constraints, and approach. - **待解决问题**：执行前仍需解决的决策、假设或未知项。必须区分会阻塞 apply 的问题和非阻塞后续问题。没有未决问题时使用“无”
Avoid line-by-line or step-by-step details unless a detail is a deliberate
decision from the discussion.
Prefer durable summaries over chat transcripts. Use concrete artifact 可选章节（相关时添加，建议使用中文章节标题）：
names, data/information shapes, examples, stakeholders, ownership, and
edge cases when they affect execution.
Do not use task checkboxes in design.md; checkboxes belong only in - **迁移 / 发布计划**：发布步骤、沟通安排、归属、回滚或连续性策略
tasks.md.
Final design.md must not contain unresolved template comments, empty 聚焦保留需求、理由、约束和方案。除非某个细节是讨论中明确做出的决策，否则避免逐行或逐步骤展开。
table rows, or placeholder text.
If information is missing, state assumptions and open questions instead 优先写可长期使用的摘要，而不是聊天记录转写。当具体 artifact 名称、数据/信息形状、示例、相关方、归属和边界场景会影响执行时，必须写清楚。
of inventing hidden requirements. Do not rely on unstated chat context.
不要在 design.md 使用任务 checkbox；checkbox 只属于 tasks.md。
最终 design.md 不得包含未解决的模板注释、空表格行或占位文本。
如果信息缺失，写明假设和待解决问题，不要编造隐藏需求。不要依赖未写入文档的聊天上下文。
requires: [] requires: []
- id: tasks - id: tasks
generates: tasks.md generates: tasks.md
description: Trackable execution checklist derived from design.md description: 从 design.md 派生的可跟踪执行清单
template: tasks.md template: tasks.md
instruction: | instruction: |
Create tasks.md by breaking design.md into executable work. 创建 tasks.md，将 design.md 拆解为可执行工作项。
**IMPORTANT: Follow the template below exactly.** The apply phase parses **重要：必须遵守以下模板中的 checkbox 行格式。** apply 阶段会解析 checkbox 格式跟踪进度。未使用 `- [ ]` 的任务不会被跟踪。
checkbox format to track progress. Tasks not using `- [ ]` will not be
tracked.
Guidelines: 语言规则（强制）：
- Derive tasks from design.md. Do not depend on proposal.md or specs - fast-drive 的 tasks.md 使用中文分组标题和中文任务描述；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文
artifacts; any relevant prior discussion must already be captured in
design.md.
- Group related tasks under `##` numbered headings - 每个可跟踪任务必须保留 OpenSpec CLI 可解析的单行 checkbox 格式，例如 `- [ ] 1.1 任务描述` 或 `- [x] 1.1 已完成任务描述`
- Each task MUST be a single-line checkbox: `- [ ] X.Y Task description` - 最终 tasks.md 不得残留英文模板任务或英文占位内容，除非该英文是 OpenSpec 术语、文件名、schema 字段名、代码符号、命令或必要技术名词
- Tasks should be small enough to complete in one session 编写规则：
- Order tasks by dependency (what must be done first?) - 任务必须从 design.md 派生。不要依赖 proposal.md 或 specs artifacts；任何相关前序讨论都必须已经记录在 design.md 中
- Start with context review tasks when execution depends on guardrails, - 相关任务按 `##` 编号标题分组，分组标题使用中文
affected areas, or open questions
- Include validation tasks for checks, reviews, approvals, acceptance, - 每个任务 MUST 是单行 checkbox：`- [ ] X.Y 任务描述`
documentation, communication, and manual checks when required
- Do not include repository, version-control, or release operation tasks - 任务粒度应足够小，能在一个会话内完成
unless they are explicitly part of the change scope
- Final tasks.md must not contain unresolved template comments, empty - 按依赖顺序排序（先做必须先完成的事项）
table rows, or placeholder task text
Example: - 当执行依赖执行约束、影响范围或待解决问题时，从上下文审查任务开始
- 需要时包含验证任务，覆盖检查、审查、批准、验收、文档、沟通和人工检查
- 除非仓库、版本控制或发布操作明确属于本次变更范围，否则不要包含这类任务
- 最终 tasks.md 不得包含未解决的模板注释、空表格行或占位任务文本
示例：
``` ```
## 1. Context Review ## 1. 上下文审查
- [ ] 1.1 Read design.md and identify scope, requirements, decisions, guardrails, and open questions - [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题
- [ ] 1.2 Review relevant artifacts and references listed in Affected Areas - [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料
## 2. Execution ## 2. 执行
- [ ] 2.1 Execute first concrete work item from design.md - [ ] 2.1 执行 design.md 中的第一个具体工作项
- [ ] 2.2 Execute next concrete work item from design.md - [ ] 2.2 执行 design.md 中的下一个具体工作项
## 3. Validation ## 3. 验证
- [ ] 3.1 Run required validation from Verification Plan - [ ] 3.1 执行“验证计划”中要求的验证
- [ ] 3.2 Perform quality checks required by the project or workflow - [ ] 3.2 执行项目或 workflow 要求的质量检查
- [ ] 3.3 Perform required manual review or acceptance checks from Verification Plan - [ ] 3.3 执行“验证计划”中要求的人工审查或验收检查
## 4. Documentation / Communication ## 4. 文档 / 沟通
- [ ] 4.1 Update relevant documentation, runbooks, communication materials, or project references if behavior, process, interface, configuration, or usage changed - [ ] 4.1 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档、runbook、沟通材料或项目参考资料
``` ```
Reference design.md for scope, requirements, decisions, execution 以 design.md 中的范围、需求、决策、执行方向和验证预期为依据。
direction, and verification expectations.
Each task should be verifiable: it must be clear when the task is done. 每个任务都应可验证：必须能明确判断任务何时完成。
requires: requires:
- design - design
apply: apply:
@@ -173,9 +142,9 @@ apply:
- tasks - tasks
tracks: tasks.md tracks: tasks.md
instruction: | instruction: |
Read design.md first, then tasks.md. 先阅读 design.md，再阅读 tasks.md。
Also follow workflow context/configuration, such as openspec/config.yaml when available, and any relevant project or workflow documentation referenced by design.md. 同时遵守 workflow context/configuration，例如存在时读取 openspec/config.yaml，以及 design.md 引用的相关项目或 workflow 文档。
Treat design.md as the source of truth for scope, requirements, decisions, guardrails, execution direction, and verification expectations. 将 design.md 视为范围、需求、决策、执行约束、执行方向和验证预期的事实来源。
Work through pending tasks in dependency order and mark complete as you go. 按依赖顺序处理待办任务，并在完成后及时标记。
Mark a task complete only after its execution and required verification are done. 只有任务执行完成且必要验证完成后，才能标记任务完成。
Pause if tasks conflict with design.md, if design.md has blocking open questions, or if clarification is needed. 如果 tasks 与 design.md 冲突、design.md 存在阻塞性待解决问题，或需要澄清，必须暂停。

92
openspec/schemas/fast-drive/templates/design.md
View File

@@ -1,77 +1,77 @@
## Context ## 背景
<!-- Problem, current state, relevant references, and triggering user request --> <!-- 记录问题、当前状态、相关参考资料，以及触发本次变更的用户请求 -->
## Discussion Notes ## 讨论记录
<!-- Key conclusions from exploration or prior discussion that apply must preserve --> <!-- 记录探索或前序讨论中 apply 阶段必须保留的关键结论 -->
- Agreed conclusions: - 已确认结论：
- User preferences: - 用户偏好：
- Constraints: - 约束：
- Rejected ideas: - 被否决方案：
## Requirements ## 需求
<!-- Expected outcomes, behavior/process/interface/content changes, continuity expectations, and acceptance criteria --> <!-- 记录预期结果、行为/流程/接口/内容变化、连续性要求和验收标准 -->
| Requirement | Acceptance Criteria | | 需求 | 验收标准 |
| ----------- | ------------------- | | ---- | -------- |
| | | | | |
## Goals / Non-Goals ## 目标 / 非目标
**Goals:** **目标：**
<!-- What this design aims to achieve --> <!-- 记录本次 design 要达成的目标 -->
**Non-Goals:** **非目标：**
<!-- What is explicitly out of scope --> <!-- 记录明确不在范围内的内容 -->
## Execution Guardrails ## 执行约束
<!-- Must-follow constraints, forbidden approaches, preserved behavior/processes, dependency limits, and project- or workflow-specific boundaries --> <!-- 记录必须遵守的约束、禁止的做法、需保持的行为/流程、依赖限制，以及项目或 workflow 特有边界 -->
- Dependencies: - 依赖限制：
- Constraints: - 约束：
- Quality Bar: - 质量门禁：
- Stakeholders: - 相关方：
- Documentation / Communication: - 文档 / 沟通：
- Compatibility / Continuity: - 兼容性 / 连续性：
## Affected Areas ## 影响范围
<!-- Concrete artifacts, references, stakeholders, systems, workstreams, documents, configurations, assets, or handoffs relevant to this change --> <!-- 记录与本次变更相关的具体 artifacts、参考资料、相关方、系统、工作流、文档、配置、资产或交接事项 -->
| Area | Artifacts / References | Expected Change | Notes | | 范围 | Artifacts / 参考资料 | 预期变更 | 备注 |
| ---- | ---------------------- | --------------- | ----- | | ---- | -------------------- | -------- | ---- |
| <!-- Area --> | <!-- Artifacts / References --> | <!-- Expected Change --> | <!-- Notes --> | | <!-- 范围 --> | <!-- Artifacts / 参考资料 --> | <!-- 预期变更 --> | <!-- 备注 --> |
## Decisions ## 决策
<!-- Key decisions, rationale, and alternatives considered --> <!-- 记录关键决策、理由和考虑过的替代方案 -->
| Decision | Rationale | Alternatives Rejected | | 决策 | 理由 | 已否决替代方案 |
| -------- | --------- | --------------------- | | ---- | ---- | ---------------- |
| | | | | | | |
## Execution Plan ## 执行计划
<!-- Main workstreams or artifacts to change, integration or handoff points, sequencing, and rollout notes --> <!-- 记录主要工作流或待修改 artifacts、集成或交接点、执行顺序，以及必要的发布/落地说明 -->
## Verification Plan ## 验证计划
<!-- Validation checks, reviews, approvals, acceptance checks, documentation checks, communication checks, and manual checks needed --> <!-- 记录用于证明变更完成所需的验证检查、审查、批准、验收检查、文档检查、沟通检查和人工检查 -->
| Requirement / Risk | Verification | | 需求 / 风险 | 验证方式 |
| ------------------ | ------------ | | ----------- | -------- |
| | | | | |
## Risks / Trade-offs ## 风险 / 权衡
<!-- Format: [Risk] -> Mitigation --> <!-- 格式：[风险] -> 缓解措施 -->
## Open Questions ## 待解决问题
| Status | Question | Decision Needed | | 状态 | 问题 | 所需决策 |
| ------ | -------- | --------------- | | ---- | ---- | -------- |
| None | No open questions. | None | | 无 | 无待解决问题。 | 无需决策 |

24
openspec/schemas/fast-drive/templates/tasks.md
View File

@@ -1,19 +1,19 @@
## 1. Context Review ## 1. 上下文审查
- [ ] 1.1 Read design.md and identify scope, requirements, decisions, guardrails, and open questions - [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题
- [ ] 1.2 Review relevant artifacts and references listed in Affected Areas - [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料
## 2. Execution ## 2. 执行
- [ ] 2.1 Execute first concrete work item from design.md - [ ] 2.1 执行 design.md 中的第一个具体工作项
- [ ] 2.2 Execute next concrete work item from design.md - [ ] 2.2 执行 design.md 中的下一个具体工作项
## 3. Validation ## 3. 验证
- [ ] 3.1 Run required validation from Verification Plan - [ ] 3.1 执行“验证计划”中要求的验证
- [ ] 3.2 Perform quality checks required by the project or workflow - [ ] 3.2 执行项目或 workflow 要求的质量检查
- [ ] 3.3 Perform required manual review or acceptance checks from Verification Plan - [ ] 3.3 执行“验证计划”中要求的人工审查或验收检查
## 4. Documentation / Communication ## 4. 文档 / 沟通
- [ ] 4.1 Update relevant documentation, runbooks, communication materials, or project references if behavior, process, interface, configuration, or usage changed - [ ] 4.1 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档、runbook、沟通材料或项目参考资料