diff --git a/docs/development/README.md b/docs/development/README.md index 2bc3bc1..2f7bdb7 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -95,13 +95,6 @@ 如果无需更新文档，必须在收尾说明中说明原因。详细规则见 [文档总览](../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 顺序执行，完成后立即标记任务状态。 - ## 事实来源 | 主题 | 事实来源 | @@ -112,4 +105,4 @@ ## 更新触发条件 -修改常用命令、质量门禁、全局工程规则、目录边界、OpenSpec 协作方式或开发文档索引时，必须更新本文档。 +修改常用命令、质量门禁、全局工程规则、目录边界或开发文档索引时，必须更新本文档。 diff --git a/docs/prompts/prompt-apply-review.md b/docs/prompts/prompt-apply-review.md index f1d66ff..d926786 100644 --- a/docs/prompts/prompt-apply-review.md +++ b/docs/prompts/prompt-apply-review.md @@ -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 下，核心 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 阶段，不在此提示词范围内 - 优先使用当前会话中的执行说明、验证结论、手动修补记录和已生成的变更文档；仅在无法明确 change、`schemaName`、改动范围或修补来源时，再用提问工具或 OpenSpec 命令补充定位 - 不要因为实际产物已经存在就自动以实际产物为准；先判断差异属于“design 要求未完成”、“验证后新增修补”、“合理落地细化”还是“意外偏离/回归” @@ -29,25 +29,25 @@ a) 先并行读取核心入口和配置，确定范围： - workflow context/configuration，例如存在时读取 `openspec/config.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]` 或等价完成状态。 d) 获取实际改动范围：若在版本控制工作区中，优先使用 `git diff --name-only`、`git diff --name-only --cached`；若工作区已干净或不适用版本控制，再结合 `design.md`、`tasks.md`、验证记录和执行记录反推。 -e) 并行读取实际改动范围、`Affected Areas`、`Execution Plan`、`Verification Plan` 涉及的实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料。 +e) 并行读取实际改动范围、“影响范围”“执行计划”“验证计划”涉及的实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料。 f) 收集当前会话中与本次变更相关的执行说明、apply 过程中的偏离、验证失败、手动修补原因、验证命令或检查结果、待确认事项。 @@ -66,14 +66,14 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts； 按以下优先级检查： -| 优先级 | 维度 | 检查点 | -| ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| P0 | 实际变更与验证结论 | 当前实际产物的真实状态是什么；apply 后是否有手动改动或验证后修补；验证是否证明这些变更有效；若缺少验证结果，标记相关结论为“未验证”；检查是否存在回归、未覆盖场景或被掩盖的问题 | -| P1 | `design.md` 一致性 | 实际变更是否符合 `Requirements`、`Goals / Non-Goals`、`Execution Guardrails`、`Decisions`、`Execution Plan` 和 `Verification Plan`；`Open Questions` 是否已明确区分 blocking / non-blocking 或写出 `None`；是否违反被明确否决的方案、用户偏好或约束 | -| 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 | 文档回写完整性 | 已落地的实际变更、验证后新增修补、边界处理、异常路径、验证结论、实际触达产物是否已同步回 `design.md` 和 `tasks.md`；若影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，再检查必要的文档/沟通材料是否同步 | +| P4 | 质量与可维护性 | 实际产物的结构、清晰度、一致性、可维护性、风险处理、移交质量、验证质量、与现有模式的一致性是否存在明显问题或可优化点 | +| 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` 要求但未落地的结果、流程、内容、场景、异常处理、文档/沟通更新或验证步骤 -- 实际变更偏离 `Goals / Non-Goals`、`Execution Guardrails`、`Decisions` 或 `Execution Plan` 的地方 +- 实际变更偏离“目标 / 非目标”“执行约束”“决策”或“执行计划”的地方 - apply 完成后新增的修补、边界处理、接口调整、行为变化、流程变化或内容变化未同步到 `design.md` -- `Affected Areas` 与实际改动范围不一致，导致新会话无法复盘真实影响面 -- `Verification Plan` 中要求的验证、质量检查、审阅、批准、沟通检查或 manual checks 未执行或未记录 +- “影响范围”与实际改动范围不一致，导致新会话无法复盘真实影响面 +- “验证计划”中要求的验证、质量检查、审阅、批准、沟通检查或人工检查未执行或未记录 - `tasks.md` 标记完成，但实际产物、验证、文档或沟通未闭环 - `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 后新增但已完成的修补任务或验证任务 - 文档/沟通同步：同步行为、流程、接口、内容、数据、配置、责任边界或用户可见结果变化 - 质量优化：在不改变目标结果的前提下优化结构、表达、一致性、可维护性或移交质量 @@ -156,8 +156,8 @@ g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts； 若修改了文档： -- 在 `fast-drive` workflow 下，确认 `design.md` 仍是 source of truth，`tasks.md` 仍从 `design.md` 派生 -- 确认 `design.md` 的 requirements、guardrails、affected areas、decisions、execution plan、verification plan、risks 和 open questions 与实际变更一致 +- 在 `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 diff --git a/docs/prompts/prompt-proposal-review.md b/docs/prompts/prompt-proposal-review.md index eac650a..2692596 100644 --- a/docs/prompts/prompt-proposal-review.md +++ b/docs/prompts/prompt-proposal-review.md @@ -5,7 +5,7 @@ - 仅修改本次变更文档，不修改实际产物 - 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查 - 在 `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 命令补充定位 - 每批文档修改建议执行前用提问工具获得用户确认 - 删除/重写前用提问工具获得用户确认，并先备份原文件为 `{file}.bak.{timestamp}` @@ -26,21 +26,21 @@ a) 先并行读取核心入口和配置，确定范围： - workflow context/configuration，例如存在时读取 `openspec/config.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 的要求补充读取和审查。 @@ -57,13 +57,13 @@ d) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts； 按以下优先级检查： -| 优先级 | 维度 | 检查点 | -| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| P0 | 讨论承接性 | 仅在存在讨论记录时检查：`design.md` 是否完整记录已确认的目标、非目标、用户偏好、约束、边界条件、风险、关键决策、被否决方案和待澄清事项；若无讨论记录，标记为“跳过” | -| P1 | `design.md` 自包含性 | `design.md` 是否足以让看不到前序对话的执行者继续工作；是否包含完整 required sections；`Open Questions` 是否明确区分 blocking / non-blocking 或写出 `None`；是否存在依赖未记录聊天上下文的隐含要求 | -| P2 | 当前状态真实性 | `design.md` 对当前实际产物、流程、接口、内容、数据、配置、依赖、责任边界、参考材料和验证入口的描述是否准确；是否把“计划变更”误写成“当前现状”；`Affected Areas` 是否遗漏真实受影响区域 | -| P3 | `tasks.md` 派生性 | `tasks.md` 是否从 `design.md` 派生；是否覆盖 requirements、guardrails、decisions、execution plan 和 verification plan；是否依赖 `proposal.md` 或 `specs/*.md` 中未写入 `design.md` 的内容 | -| P4 | OpenSpec 合规性 | 对实际存在的 artifacts 检查是否遵循对应 schema 和 OpenSpec 术语；`tasks.md` 是否一行一个 `- [ ]` checkbox 任务、按 `##` numbered headings 分组、无无关的仓库/版本控制/发布操作任务；`design.md` 是否避免 task checkbox；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 | +| 优先级 | 维度 | 检查点 | +| ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| P0 | 讨论承接性 | 仅在存在讨论记录时检查：`design.md` 是否完整记录已确认的目标、非目标、用户偏好、约束、边界条件、风险、关键决策、被否决方案和待澄清事项；若无讨论记录，标记为“跳过” | +| P1 | `design.md` 自包含性 | `design.md` 是否足以让看不到前序对话的执行者继续工作；是否包含完整必需章节；“待解决问题”是否明确区分 blocking / non-blocking 或写出“无”；是否存在依赖未记录聊天上下文的隐含要求 | +| P2 | 当前状态真实性 | `design.md` 对当前实际产物、流程、接口、内容、数据、配置、依赖、责任边界、参考材料和验证入口的描述是否准确；是否把“计划变更”误写成“当前现状”；“影响范围”是否遗漏真实受影响区域 | +| P3 | `tasks.md` 派生性 | `tasks.md` 是否从 `design.md` 派生；是否覆盖需求、执行约束、决策、执行计划和验证计划；是否依赖 `proposal.md` 或 `specs/*.md` 中未写入 `design.md` 的内容 | +| 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` 中缺失或含糊的 requirements、acceptance criteria、guardrails、decisions、verification expectations -- `Open Questions` 未明确区分 blocking / non-blocking、与 `tasks.md` 冲突，或包含 apply 前必须解决的 blocker -- `tasks.md` 未覆盖 `design.md` 的要求、约束、执行计划、验证计划或文档/沟通更新要求 +- `design.md` 中缺失或含糊的需求、验收标准、执行约束、决策或验证预期 +- “待解决问题”未明确区分 blocking / non-blocking、与 `tasks.md` 冲突，或包含 apply 前必须解决的 blocker +- `tasks.md` 未覆盖 `design.md` 的需求、约束、执行计划、验证计划或文档/沟通更新要求 - `tasks.md` 标记了无法验证、跨行、过大、顺序错误或包含无关仓库/版本控制/发布操作的任务 - 文档仍保留 `` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容 - 文档基于错误当前状态做出的设计或任务拆分 diff --git a/openspec/config.yaml b/openspec/config.yaml index aded1ff..a41d446 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -2,7 +2,6 @@ schema: fast-drive context: | - 使用中文（注释、文档、交流），面向中文开发者 - - openspec文档的关键字按openspec规范使用，不要翻译为中文 - **优先阅读 docs/README.md** 获取文档路由、归属矩阵和影响分析规则 - **其次阅读 docs/development/README.md** 获取开发规范、常用命令、质量门禁和全局规则 - 文档文件名优先使用单个英文单词（usage.md、config.md、deploy.md、troubleshoot.md），目录上下文足以消歧时不在文件名重复限定词 @@ -29,8 +28,10 @@ context: | rules: design: + - fast-drive的design.md章节标题和正文使用中文；仅OpenSpec术语、文件名、schema字段名、命令和代码符号保留英文 - 先前的讨论技术方案要尽可能体现在设计文档中，便于指导实现阶段不偏离已定的技术路线 tasks: + - fast-drive的tasks.md分组标题、任务描述和验证说明使用中文；每个任务必须保留OpenSpec CLI可解析的单行checkbox格式 - 一行一个任务，严禁任务内容跨行 - 如果是代码存在更新必须 - 执行完整的测试、代码检查、格式检查等质量保障手段 diff --git a/openspec/schemas/fast-drive/schema.yaml b/openspec/schemas/fast-drive/schema.yaml index f8ed152..9bf1f29 100644 --- a/openspec/schemas/fast-drive/schema.yaml +++ b/openspec/schemas/fast-drive/schema.yaml @@ -1,170 +1,139 @@ name: fast-drive version: 1 -description: Fast OpenSpec workflow - design -> tasks -> apply +description: 快速 OpenSpec workflow - design -> tasks -> apply artifacts: - id: design generates: design.md - description: Self-contained solution brief and execution plan + description: 自包含的方案说明和执行计划 template: design.md instruction: | - Create design.md as the self-contained source of truth for what will - change, why it is changing, and how the work will be executed. + 创建 design.md，作为本次变更“改什么、为什么改、如何执行”的自包含事实来源。 - This workflow does not use proposal or specs artifacts. design.md MUST - 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. + 本 workflow 不使用 proposal 或 specs artifacts。design.md MUST 保留前序探索和用户讨论中的重要结论，确保后续 apply 阶段即使经历上下文压缩或进入新会话，也能正确继续执行。 - 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 - artifacts + - fast-drive 的 design.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 - - 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 - complexity + - 跨多个系统、团队、工作流或 artifacts 的横切变更 - - 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 - or handoff points, sequencing, and any rollout notes. + - **执行约束**：必须遵守的约束、禁止的做法、需保持的行为/流程、依赖限制，以及项目或 workflow 特有边界 - - **Verification Plan**: Validation checks, reviews, approvals, - acceptance checks, documentation checks, communication checks, and manual - checks needed to prove the change is complete. + - **影响范围**：与本次变更相关的具体 artifacts、参考资料、相关方、系统、工作流、文档、配置、资产或交接事项 - - **Risks / Trade-offs**: Known limitations and things that could go - wrong. - Format: [Risk] -> Mitigation + - **决策**：关键选择及理由（为什么选 X 而不是 Y）。每个重要决策都要包含考虑过的替代方案，以及未选择它们的原因 - - **Open Questions**: Outstanding decisions, assumptions, or unknowns to - resolve before execution. Separate blocking questions that must pause - apply from non-blocking follow-ups. Use "None" if there are no open - questions. + - **执行计划**：主要工作流或待修改 artifacts、集成或交接点、执行顺序，以及必要的发布/落地说明 - Optional sections when relevant: + - **验证计划**：用于证明变更完成所需的验证检查、审查、批准、验收检查、文档检查、沟通检查和人工检查 - - **Migration / Rollout Plan**: Rollout steps, communication, ownership, - rollback, or continuity strategy. + - **风险 / 权衡**：已知限制和可能出错的事项 + 格式：[风险] -> 缓解措施 - Focus on preserving requirements, rationale, constraints, and approach. - Avoid line-by-line or step-by-step details unless a detail is a deliberate - decision from the discussion. + - **待解决问题**：执行前仍需解决的决策、假设或未知项。必须区分会阻塞 apply 的问题和非阻塞后续问题。没有未决问题时使用“无” - 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 - of inventing hidden requirements. Do not rely on unstated chat context. + 优先写可长期使用的摘要，而不是聊天记录转写。当具体 artifact 名称、数据/信息形状、示例、相关方、归属和边界场景会影响执行时，必须写清楚。 + + 不要在 design.md 使用任务 checkbox；checkbox 只属于 tasks.md。 + + 最终 design.md 不得包含未解决的模板注释、空表格行或占位文本。 + + 如果信息缺失，写明假设和待解决问题，不要编造隐藏需求。不要依赖未写入文档的聊天上下文。 requires: [] - id: tasks generates: tasks.md - description: Trackable execution checklist derived from design.md + description: 从 design.md 派生的可跟踪执行清单 template: tasks.md 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 format to track progress. Tasks not using `- [ ]` will not be - tracked. + **重要：必须遵守以下模板中的 checkbox 行格式。** apply 阶段会解析 checkbox 格式跟踪进度。未使用 `- [ ]` 的任务不会被跟踪。 - Guidelines: + 语言规则（强制）： - - Derive tasks from design.md. Do not depend on proposal.md or specs - artifacts; any relevant prior discussion must already be captured in - design.md. + - fast-drive 的 tasks.md 使用中文分组标题和中文任务描述；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 - - 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, - documentation, communication, and manual checks when required + - 每个任务 MUST 是单行 checkbox：`- [ ] X.Y 任务描述` - - 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.2 Review relevant artifacts and references listed in Affected Areas + - [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题 + - [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料 - ## 2. Execution + ## 2. 执行 - - [ ] 2.1 Execute first concrete work item from design.md - - [ ] 2.2 Execute next concrete work item from design.md + - [ ] 2.1 执行 design.md 中的第一个具体工作项 + - [ ] 2.2 执行 design.md 中的下一个具体工作项 - ## 3. Validation + ## 3. 验证 - - [ ] 3.1 Run required validation from Verification Plan - - [ ] 3.2 Perform quality checks required by the project or workflow - - [ ] 3.3 Perform required manual review or acceptance checks from Verification Plan + - [ ] 3.1 执行“验证计划”中要求的验证 + - [ ] 3.2 执行项目或 workflow 要求的质量检查 + - [ ] 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 - direction, and verification expectations. + 以 design.md 中的范围、需求、决策、执行方向和验证预期为依据。 - Each task should be verifiable: it must be clear when the task is done. + 每个任务都应可验证：必须能明确判断任务何时完成。 requires: - design apply: @@ -173,9 +142,9 @@ apply: - tasks tracks: tasks.md instruction: | - Read design.md first, then 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. - Treat design.md as the source of truth for scope, requirements, decisions, guardrails, execution direction, and verification expectations. - 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. + 先阅读 design.md，再阅读 tasks.md。 + 同时遵守 workflow context/configuration，例如存在时读取 openspec/config.yaml，以及 design.md 引用的相关项目或 workflow 文档。 + 将 design.md 视为范围、需求、决策、执行约束、执行方向和验证预期的事实来源。 + 按依赖顺序处理待办任务，并在完成后及时标记。 + 只有任务执行完成且必要验证完成后，才能标记任务完成。 + 如果 tasks 与 design.md 冲突、design.md 存在阻塞性待解决问题，或需要澄清，必须暂停。 diff --git a/openspec/schemas/fast-drive/templates/design.md b/openspec/schemas/fast-drive/templates/design.md index f6971ab..34647c2 100644 --- a/openspec/schemas/fast-drive/templates/design.md +++ b/openspec/schemas/fast-drive/templates/design.md @@ -1,77 +1,77 @@ -## Context +## 背景 - + -## Discussion Notes +## 讨论记录 - + -- Agreed conclusions: -- User preferences: -- Constraints: -- Rejected ideas: +- 已确认结论： +- 用户偏好： +- 约束： +- 被否决方案： -## Requirements +## 需求 - + -| Requirement | Acceptance Criteria | -| ----------- | ------------------- | +| 需求 | 验收标准 | +| ---- | -------- | | | | -## Goals / Non-Goals +## 目标 / 非目标 -**Goals:** - +**目标：** + -**Non-Goals:** - +**非目标：** + -## Execution Guardrails +## 执行约束 - + -- Dependencies: -- Constraints: -- Quality Bar: -- Stakeholders: -- Documentation / Communication: -- Compatibility / Continuity: +- 依赖限制： +- 约束： +- 质量门禁： +- 相关方： +- 文档 / 沟通： +- 兼容性 / 连续性： -## Affected Areas +## 影响范围 - + -| Area | Artifacts / References | Expected Change | Notes | -| ---- | ---------------------- | --------------- | ----- | -| | | | | +| 范围 | Artifacts / 参考资料 | 预期变更 | 备注 | +| ---- | -------------------- | -------- | ---- | +| | | | | -## Decisions +## 决策 - + -| Decision | Rationale | Alternatives Rejected | -| -------- | --------- | --------------------- | +| 决策 | 理由 | 已否决替代方案 | +| ---- | ---- | ---------------- | | | | | -## Execution Plan +## 执行计划 - + -## Verification Plan +## 验证计划 - + -| Requirement / Risk | Verification | -| ------------------ | ------------ | +| 需求 / 风险 | 验证方式 | +| ----------- | -------- | | | | -## Risks / Trade-offs +## 风险 / 权衡 - + -## Open Questions +## 待解决问题 -| Status | Question | Decision Needed | -| ------ | -------- | --------------- | -| None | No open questions. | None | +| 状态 | 问题 | 所需决策 | +| ---- | ---- | -------- | +| 无 | 无待解决问题。 | 无需决策 | diff --git a/openspec/schemas/fast-drive/templates/tasks.md b/openspec/schemas/fast-drive/templates/tasks.md index c394f23..465c63e 100644 --- a/openspec/schemas/fast-drive/templates/tasks.md +++ b/openspec/schemas/fast-drive/templates/tasks.md @@ -1,19 +1,19 @@ -## 1. Context Review +## 1. 上下文审查 -- [ ] 1.1 Read design.md and identify scope, requirements, decisions, guardrails, and open questions -- [ ] 1.2 Review relevant artifacts and references listed in Affected Areas +- [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题 +- [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料 -## 2. Execution +## 2. 执行 -- [ ] 2.1 Execute first concrete work item from design.md -- [ ] 2.2 Execute next concrete work item from design.md +- [ ] 2.1 执行 design.md 中的第一个具体工作项 +- [ ] 2.2 执行 design.md 中的下一个具体工作项 -## 3. Validation +## 3. 验证 -- [ ] 3.1 Run required validation from Verification Plan -- [ ] 3.2 Perform quality checks required by the project or workflow -- [ ] 3.3 Perform required manual review or acceptance checks from Verification Plan +- [ ] 3.1 执行“验证计划”中要求的验证 +- [ ] 3.2 执行项目或 workflow 要求的质量检查 +- [ ] 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、沟通材料或项目参考资料