diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 8855a2a..b2fb902 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -77,7 +77,7 @@ tests/ Bun test 测试（结构镜像 src 目录） web/ 前端测试 App.test.tsx test-utils.tsx -openspec/ OpenSpec 变更与规格文档 +openspec/ OpenSpec 变更、规格文档与 fast-drive workflow schema config.example.yaml 配置文件示例 ``` diff --git a/README.md b/README.md index ee99dda..e2e57bd 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ rm -rf openspec/specs/* rm -rf openspec/changes/* ``` -> `openspec/config.yaml` 需要保留，其中包含项目开发规范配置。 +> `openspec/config.yaml` 和 `openspec/schemas/fast-drive/` 需要保留，其中包含项目开发规范配置与自定义 OpenSpec workflow schema。 ### 4. 安装依赖 @@ -133,7 +133,7 @@ bun run dev │ ├── menu.tsx # 菜单配置 │ └── routes.tsx # 路由配置 ├── tests/ # 测试文件（镜像 src 目录结构） -├── openspec/ # OpenSpec 规格与变更管理 +├── openspec/ # OpenSpec 规格、变更与 fast-drive workflow schema └── docs/ # 项目文档 ``` diff --git a/docs/prompts/README.md b/docs/prompts/README.md index 1b8fb77..bc6ac44 100644 --- a/docs/prompts/README.md +++ b/docs/prompts/README.md @@ -4,12 +4,12 @@ ## 提示词 -| 文件 | 用途 | -| ------------------------------------------------------ | ------------------------------------------------------------------------ | -| [prompt-smart-merge.md](prompt-smart-merge.md) | 批量合并 `dev*` 分支到目标分支，含规则探测、依赖分析、冲突处理、安全回退 | -| [prompt-spec-review.md](prompt-spec-review.md) | 审查和整理 `openspec/specs/` 下的稳定规范，提升可检索性和一致性 | -| [prompt-proposal-review.md](prompt-proposal-review.md) | 审查 proposal/design/tasks/specs 与讨论、代码现状、OpenSpec 规范的一致性 | -| [prompt-apply-review.md](prompt-apply-review.md) | 审查 apply 后代码、测试、变更文档的一致性，并补齐遗漏或回写文档 | +| 文件 | 用途 | +| ------------------------------------------------------ | ------------------------------------------------------------------------- | +| [prompt-smart-merge.md](prompt-smart-merge.md) | 批量合并 `dev*` 分支到目标分支，含规则探测、依赖分析、冲突处理、安全回退 | +| [prompt-spec-review.md](prompt-spec-review.md) | 审查和整理 `openspec/specs/` 下的稳定规范，提升可检索性和一致性 | +| [prompt-proposal-review.md](prompt-proposal-review.md) | 审查 fast-drive design/tasks 与讨论、实际状态、OpenSpec workflow 的一致性 | +| [prompt-apply-review.md](prompt-apply-review.md) | 审查 apply 后实际产物、验证、design/tasks 的一致性，并补齐遗漏或回写文档 | ## 设计目标 diff --git a/docs/prompts/prompt-apply-review.md b/docs/prompts/prompt-apply-review.md index 377506a..f1d66ff 100644 --- a/docs/prompts/prompt-apply-review.md +++ b/docs/prompts/prompt-apply-review.md @@ -1,15 +1,17 @@ -审查 OpenSpec apply 完成后以及后续手动修补后的实际实现，判断代码、测试、变更文档是否一致，识别偏离、漏记和可优化点，并将确认后的实际变更同步回变更文档，按以下流程执行。 +审查 OpenSpec apply 完成后以及后续手动修补后的实际变更，判断实际产物、验证结果和变更文档是否与 `design.md` source of truth 一致，识别偏离、漏记和可优化点，并将确认后的实际变更同步回变更文档，按以下流程执行。 ## 约束 -- 先审查再修复；未经用户确认，不修改代码或变更文档 -- 默认按 `spec-driven` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查 -- 禁止同步或修改 `openspec/specs/` 下的主规范——主规范同步属于 archive 阶段，不在此提示词范围内；本次 change 目录下的 `specs/*.md`、代码、测试、README 等均可修改 -- 优先使用当前会话中的实现说明、测试结论、手动修补记录和已生成的变更文档；仅在无法明确 change、`schemaName`、改动范围或修补来源时，再用提问工具或 OpenSpec 命令补充定位 -- 不要因为代码已经存在就自动以代码为准；先判断差异属于"文档要求未实现"、"测试后新增修补"还是"意外偏离/回归" -- 每批代码或文档修改执行前用提问工具获得用户确认 +- 先审查再修复；未经用户确认，不修改实际产物或变更文档 +- 默认按 `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 文件 +- 禁止同步或修改 `openspec/specs/` 下的主规范；若实际 schema 包含 `specs/*.md`，也只允许修改本次 change 目录下实际存在的 spec artifacts，主规范同步属于 archive 阶段，不在此提示词范围内 +- 优先使用当前会话中的执行说明、验证结论、手动修补记录和已生成的变更文档；仅在无法明确 change、`schemaName`、改动范围或修补来源时，再用提问工具或 OpenSpec 命令补充定位 +- 不要因为实际产物已经存在就自动以实际产物为准；先判断差异属于“design 要求未完成”、“验证后新增修补”、“合理落地细化”还是“意外偏离/回归” +- 每批实际产物或文档修改执行前用提问工具获得用户确认 - 删除/重写前用提问工具获得用户确认，并先备份原文件为 `{file}.bak.{timestamp}` -- 若修改代码涉及新逻辑、模块结构、API、实体或用户可见行为，同步更新测试、相关变更文档和 README +- 若修改实际产物涉及新行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，同步更新验证材料、相关变更文档和必要的文档/沟通材料 ## 1. 收集 @@ -22,18 +24,34 @@ a) 先并行读取核心入口和配置，确定范围： -- 本次 change 的 `proposal.md` -- `openspec/config.yaml` +- 本次 change 的 `design.md` +- 本次 change 的 `tasks.md` +- workflow context/configuration，例如存在时读取 `openspec/config.yaml` +- 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml` -b) 从 `proposal.md` 提取 `Capabilities` / `Modified Capabilities`，确定 proposal 已声明的 spec 列表 +b) 从 `design.md` 提取审查基准： -c) 并行获取改动范围：`git diff --name-only`、`git diff --name-only --cached`；若工作区已干净，再结合文档和代码模块反推 +- `Context` +- `Discussion Notes` +- `Requirements` +- `Goals / Non-Goals` +- `Execution Guardrails` +- `Affected Areas` +- `Decisions` +- `Execution Plan` +- `Verification Plan` +- `Risks / Trade-offs` +- `Open Questions` -d) 对比 git diff 涉及的模块与 proposal 已声明的 spec，识别 apply 阶段新增改动触及但 proposal 未覆盖的现有 spec，合并为完整 spec 读取列表；相关性来源还包括：手动修补涉及的受影响能力、`design.md` Impact 中提到的模块、相关代码对应的现有能力 +c) 从 `tasks.md` 提取任务状态、已完成项、未完成项、验证任务和文档/沟通任务；重点记录所有已标记完成的 `- [x]` 或等价完成状态。 -e) 并行读取完整 spec 列表和其余 artifacts（`design.md`、`tasks.md`、相关源码、测试文件、README、架构文档） +d) 获取实际改动范围：若在版本控制工作区中，优先使用 `git diff --name-only`、`git diff --name-only --cached`；若工作区已干净或不适用版本控制，再结合 `design.md`、`tasks.md`、验证记录和执行记录反推。 -f) 收集当前会话中与本次变更相关的实现说明、apply 过程中的偏离、测试失败、手动修补原因、待确认事项 +e) 并行读取实际改动范围、`Affected Areas`、`Execution Plan`、`Verification Plan` 涉及的实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料。 + +f) 收集当前会话中与本次变更相关的执行说明、apply 过程中的偏离、验证失败、手动修补原因、验证命令或检查结果、待确认事项。 + +g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；若存在 `proposal.md`、`specs/*.md`，再按该 schema 的要求补充读取和审查。 若当前上下文无法明确 change 或文档路径： @@ -42,66 +60,75 @@ f) 收集当前会话中与本次变更相关的实现说明、apply 过程中 若已明确 change，但尚未确认 `schemaName`，先读取 change 元数据或执行 `openspec status --change "{name}" --json` 确认。 -若缺少测试结果或手动修补记录，明确说明本次无法可靠判断部分差异的来源，仅能基于代码与文档现状审查。 +若缺少验证结果或手动修补记录，明确说明本次无法可靠判断部分差异的来源，仅能基于实际产物与文档现状审查。 ## 2. 分析 按以下优先级检查： -| 优先级 | 维度 | 检查点 | -| ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| P0 | 实际实现与测试结论 | 当前代码的真实行为是什么；apply 后是否有手动改动或测试后修补；测试是否证明这些实现有效；若缺少测试结果，标记相关结论为"未验证"；检查是否存在回归、未覆盖场景或被掩盖的问题 | -| P1 | 文档同步性 | 对本次 change 目录下实际存在的 artifacts 检查：已落地的实现、测试后新增修补、边界处理、异常路径、验证结论是否已同步回变更文档；若影响模块结构、API、实体或用户可见行为，再检查 README 是否同步 | -| P2 | Spec 覆盖完整性 | 对比实际代码改动范围与 proposal 中定义的 `Capabilities` / `Modified Capabilities`，识别 apply 阶段新增的功能是否触及了更多现有 spec；若触及，列入补充清单，在本次 change 的 specs 中新增对应的 spec 文件，并更新 `proposal.md` 的 `Modified Capabilities` | -| P3 | 文档要求覆盖 | 对实际存在的 artifacts 检查：文档中承诺的目标、方案、Requirement、Scenario 是否都已实现；在 `spec-driven` 下重点检查 `proposal.md`、`design.md`、`specs/*.md`、`tasks.md` | -| P4 | 实现质量 | 代码结构、复用、命名、复杂度、错误处理、测试质量、与项目现有模式的一致性是否存在明显问题或可优化点 | +| 优先级 | 维度 | 检查点 | +| ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 是否仍保留模板注释、空表格行或占位任务文本 | -分析时区分三类差异： +分析时区分四类差异： -- 文档要求已明确，但代码未实现或实现不完整 → 需补充代码或测试 -- 代码因测试暴露问题、手动修补或合理落地细化而新增/变更 → 需回写文档 -- 代码与文档不一致，且无法判断应以哪边为准 → 列入待确认清单 +- `design.md` 要求已明确，但实际变更未完成或完成不充分 → 需补充实际工作或验证 +- 实际变更因验证暴露问题、手动修补或合理落地细化而新增/变更 → 需回写 `design.md` 和/或 `tasks.md` +- 实际变更与 `design.md` 不一致，且无法判断应以哪边为准 → 列入待确认清单 +- `tasks.md` 状态与实际完成情况或验证结果不一致 → 修正任务状态或补充任务 不要把以下情况直接视为合理修补： -- 通过 `skip`、`only`、弱化断言、绕过错误处理来让测试通过 -- 为了贴合现有代码而降低已确认的 Requirement 或行为约束 -- 未经过讨论和验证就扩大功能范围 +- 通过跳过、弱化或绕过验证来声称变更完成 +- 为了贴合当前实际产物而降低已确认的 requirement、acceptance criteria 或 guardrail +- 未经过讨论和验证就扩大功能、流程、内容或责任范围 +- 违反 `Execution Guardrails`、被拒绝方案或 `Open Questions` 中尚未解决的 blocker 重点识别： -- 文档要求但未落地的功能、场景、异常处理或验证步骤 -- apply 完成后新增的代码修补、边界处理、接口调整、行为变化未同步到文档 -- `tasks.md` 标记完成，但代码、测试或文档未闭环 -- `Modified Capabilities` 在本次 change 的 specs 中是否已更新（注意：仅更新 change 目录下的 specs，不动 `openspec/specs/`）；apply 阶段新增功能触及的未覆盖 spec 是否已补充到本次 change 的 `specs/` 目录 -- 代码存在明显的重复、复杂度过高、命名不清、错误处理薄弱、测试质量不足等问题 +- `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` 等未解决占位内容 +- 必要的文档/沟通材料未同步影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果的变更 +- 实际产物存在明显的重复、复杂度过高、表达不清、责任不明、风险处理薄弱、验证质量不足等问题 +- `fast-drive` change 中仍错误依赖 `proposal.md`、`specs/*.md`、`Capabilities` 或 `Modified Capabilities` 的内容 输出审查结果： 1. **问题总览表**：问题类型 × 涉及文件数 -2. **实际改动与修补清单**：本次实现中已落地的主要功能、后续修补和验证结论；若缺少测试结果，对未验证部分单独标记 -3. **未覆盖清单**：文档要求但未在代码中实现或未充分验证的内容 -4. **需回写文档清单**：代码和测试中已确认、但文档未体现的实现、修补或约束变化 -5. **方向待确认清单**：代码与文档不一致，且无法判断应以哪边为准的事项 -6. **Spec 补充清单**：apply 阶段新增功能触及但 proposal 未覆盖的现有 spec，列出需新增的 spec 文件名、对应的主 spec 路径、需描述的变更内容 -7. **任务状态问题清单**：未真正完成、状态错误或需补充的新任务 -8. **测试问题清单**：缺失覆盖、掩盖错误、验证不足或修补后未回归验证的测试问题 -9. **代码质量/优化清单**：可优化的实现问题和建议 +2. **实际变更与修补清单**：本次已落地的主要变更、后续修补和验证结论；若缺少验证结果，对未验证部分单独标记 +3. **Design 偏离清单**：实际变更未完成、完成不充分或偏离 `design.md` 的内容 +4. **需回写文档清单**：实际产物和验证中已确认、但 `design.md`、`tasks.md` 或相关文档/沟通材料未体现的变更、修补或约束变化 +5. **方向待确认清单**：实际变更与 `design.md` 不一致，且无法判断应以哪边为准的事项 +6. **任务状态问题清单**：未真正完成、状态错误或需补充的新任务 +7. **验证问题清单**：缺失覆盖、掩盖错误、验证不足或修补后未回归验证的问题 +8. **质量/优化清单**：可优化的实际产物问题和建议 +9. **Schema 差异清单**：实际 schema 与默认 `fast-drive` 不同时，列出因此跳过或改按实际 artifacts 审查的内容 10. **逐项分析**：每个问题说明位置、问题、影响、建议和建议修复方向 -若所有清单均为空，输出"审查通过，未发现问题"，跳至步骤 5。 +若所有清单均为空，输出“审查通过，未发现问题”，跳至步骤 5。 ## 3. 计划（用户确认） -先针对"方向待确认清单"用提问工具逐项向用户确认。 +先针对“方向待确认清单”用提问工具逐项向用户确认。 再整理完整修复方案，按类别列出： -- 代码或测试补充：补实现、补异常处理、补回归测试、修复掩盖错误的测试 -- 文档回写：同步本次 change 目录下的 `proposal.md`、`design.md`、`tasks.md`、`specs/*.md`、README 中遗漏或过时的内容（禁止同步到 `openspec/specs/`） -- Spec 补充：将 apply 阶段新增功能触及的现有 spec 复制到本次 change 的 `specs/` 目录并更新，同步更新 `proposal.md` 的 `Modified Capabilities` +- 实际工作或验证补充：补完成、补异常处理、补回归验证、修复被弱化或绕过的验证 +- Design 回写：同步 `design.md` 中遗漏或过时的 requirements、guardrails、affected areas、decisions、execution plan、verification plan、risks 或 open questions - 任务状态修正：修正已完成/未完成状态，补充 apply 后新增但已完成的修补任务或验证任务 -- 代码质量优化：在不改变目标行为的前提下优化结构、复用、命名或可维护性 +- 文档/沟通同步：同步行为、流程、接口、内容、数据、配置、责任边界或用户可见结果变化 +- 质量优化：在不改变目标结果的前提下优化结构、表达、一致性、可维护性或移交质量 +- Schema 兼容处理：若实际 schema 不是 `fast-drive`，按实际存在的 artifacts 说明额外文档同步项 对每个拟修改的文件说明： @@ -115,36 +142,38 @@ f) 收集当前会话中与本次变更相关的实现说明、apply 过程中 ## 4. 执行 -逐项执行已确认的代码、测试和文档修复。 +逐项执行已确认的实际产物、验证和文档修复。 若涉及删除或重写： - 先创建备份文件 `{file}.bak.{timestamp}` - 再执行修改 -若修改了代码或测试： +若修改了实际产物或验证材料： -- 同步更新相关变更文档；若影响模块结构、API、实体或用户可见行为，再同步 README -- 运行相关测试；若修补影响范围较大，再补充执行受影响的回归测试 +- 同步更新相关变更文档；若影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，再同步必要的文档/沟通材料 +- 运行或执行相关验证；若修补影响范围较大，再补充执行受影响的回归验证 若修改了文档： -- 确认本次 change 目录下的变更文档之间保持一致；重点检查 `proposal.md`、`design.md`、`tasks.md`、`specs/*.md` -- 若 apply 后新增修补改变了能力边界或行为约束，同步更新本次 change 的 `Capabilities` / `Modified Capabilities` -- 若"Spec 补充清单"中有需新增的 spec：先从 `openspec/specs/` 复制对应的原 spec 到本次 change 的 `specs/` 目录，再基于实际改动更新其内容；禁止修改 `openspec/specs/` 下的原文件 -- 禁止将本次 change 的 specs 同步到 `openspec/specs/`，该操作属于 archive 阶段 +- 在 `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 与实际变更一致 +- 确认 `tasks.md` 每个完成任务都有对应实际产物和必要验证，新增修补已补充任务或记录在合适任务中 +- 禁止将本次 change 内容同步到 `openspec/specs/`，该操作属于 archive 阶段 +- 在 `fast-drive` workflow 下不创建 `proposal.md` 或 `specs/*.md`；若实际 schema 不是 `fast-drive`，则按实际 schema 的 required artifacts 创建或更新本次 change 目录下的 artifacts -执行后重新读取所有被修改的代码、测试和文档，并复核： +执行后重新读取所有被修改的实际产物、验证材料和文档，并复核： -- "未覆盖清单" 是否已清空或已标注保留原因 -- "需回写文档清单" 是否已清空 -- "Spec 补充清单" 是否已清空或已标注保留原因 -- "方向待确认清单" 是否已清空或已记录用户决策 -- "任务状态问题清单" 和 "测试问题清单" 是否已清空或已标注残留原因 -- "代码质量/优化清单" 中哪些已处理，哪些有意延期 +- “Design 偏离清单” 是否已清空或已标注保留原因 +- “需回写文档清单” 是否已清空 +- “方向待确认清单” 是否已清空或已记录用户决策 +- “任务状态问题清单” 和 “验证问题清单” 是否已清空或已标注残留原因 +- “质量/优化清单” 中哪些已处理，哪些有意延期 +- 必要的文档/沟通材料是否已按影响范围同步 +- 所有模板注释、空表格行和占位文本是否已清空或替换为有效内容 ## 5. 收尾 -列出所有修改的文件、备份文件、测试命令与结果、文档同步摘要和剩余风险。 +列出所有修改的文件、备份文件、验证命令或检查结果、文档同步摘要和剩余风险。 -若本次因缺少测试结果、修补记录或上下文而降级执行，或有问题因信息不足暂未处理，单独说明。 +若本次因缺少验证结果、修补记录或上下文而降级执行，或有问题因信息不足暂未处理，单独说明。 diff --git a/docs/prompts/prompt-proposal-review.md b/docs/prompts/prompt-proposal-review.md index 4ebb5f2..eac650a 100644 --- a/docs/prompts/prompt-proposal-review.md +++ b/docs/prompts/prompt-proposal-review.md @@ -1,10 +1,12 @@ -审查本次 OpenSpec 变更文档是否与前序讨论、当前代码现状和 OpenSpec 文档规范一致，识别遗漏、冲突和不合理假设，并给出可执行的补充建议，按以下流程执行。 +审查本次 OpenSpec 变更文档是否与前序讨论、当前实际状态和实际 OpenSpec workflow 一致，重点检查 `fast-drive` workflow 下的 `design.md` 是否足以在上下文压缩或新会话中指导后续 `apply`，并识别遗漏、冲突和不合理假设，给出可执行的补充建议，按以下流程执行。 ## 约束 -- 仅修改本次变更文档，不修改源码 -- 默认按 `spec-driven` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查 -- 优先使用当前会话中的讨论和已生成的变更文档；仅在无法明确 change、`schemaName` 或文档范围时，再用提问工具或 OpenSpec 命令补充定位 +- 仅修改本次变更文档，不修改实际产物 +- 默认按 `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` 派生 +- 优先使用当前会话中的讨论、explore/propose 阶段结论和已生成的变更文档；仅在无法明确 change、`schemaName` 或文档范围时，再用提问工具或 OpenSpec 命令补充定位 - 每批文档修改建议执行前用提问工具获得用户确认 - 删除/重写前用提问工具获得用户确认，并先备份原文件为 `{file}.bak.{timestamp}` @@ -19,12 +21,28 @@ a) 先并行读取核心入口和配置，确定范围： -- 本次 change 的 `proposal.md` -- `openspec/config.yaml` +- 本次 change 的 `design.md` +- 本次 change 的 `tasks.md` +- workflow context/configuration，例如存在时读取 `openspec/config.yaml` +- 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml` -b) 从 `proposal.md` 提取 `Capabilities` / `Modified Capabilities`，确定需要读取的 spec 列表；相关性来源还包括：讨论中提到的受影响能力、`design.md` Impact 中提到的模块、相关代码对应的现有能力 +b) 从 `design.md` 提取审查基准： -c) 并行读取已确定的 spec 和其余 artifacts（`design.md`、`tasks.md`、相关源码、测试、README、架构文档） +- `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`、讨论中提到的受影响范围，并行读取相关实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料，确认文档是否贴合当前实际状态。 + +d) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；若存在 `proposal.md`、`specs/*.md`，再按该 schema 的要求补充读取和审查。 若当前上下文无法明确 change 或文档路径： @@ -33,47 +51,55 @@ c) 并行读取已确定的 spec 和其余 artifacts（`design.md`、`tasks.md` 若已明确 change，但尚未确认 `schemaName`，先读取 change 元数据或执行 `openspec status --change "{name}" --json` 确认。 -若缺少讨论记录，明确说明本次降级为"文档 + 代码现状审查"，不做讨论一致性结论。 +若缺少讨论记录，明确说明本次降级为“文档 + 当前实际状态审查”，不做讨论一致性结论。 ## 2. 分析 按以下优先级检查： -| 优先级 | 维度 | 检查点 | -| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| P0 | 讨论一致性 | 仅在存在讨论记录时检查：文档是否完整覆盖已确认的目标、范围、非目标、约束、边界条件、风险、决策点、待办事项；若无讨论记录，标记为"跳过" | -| P1 | 代码现实性 | 文档对当前模块、接口、数据结构、命名、依赖、目录结构、复用路径的描述是否准确；是否把"计划变更"误写成"当前现状"；是否遗漏真实受影响的现有能力 | -| P2 | 文档内部一致性 | 对实际存在的 artifacts 检查是否互相支撑；在 `spec-driven` 下重点检查 `proposal.md`、`design.md`、`tasks.md`、`specs/*.md`；`Capabilities` / `Modified Capabilities` 是否完整；每个 capability 是否有对应 spec；`tasks.md` 是否覆盖 `design.md` 和 `specs/*.md` | -| P3 | OpenSpec 合规性 | 对实际存在的 artifacts 检查是否遵循 OpenSpec 格式和术语；`specs/*.md` 是否只描述行为与约束、不混入实现细节；`tasks.md` 是否一行一个任务；是否混入 git 操作任务 | +| 优先级 | 维度 | 检查点 | +| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 是否仍保留模板注释、空表格行或占位任务文本 | 分析时区分两类情况： -- 文档对当前代码现状的描述错误 -- 文档描述的是预期变更，本来就应当与当前代码不同 +- 文档对当前实际状态的描述错误 +- 文档描述的是预期变更，本来就应当与当前状态不同 重点识别： -- 讨论中已确定但文档未记录的内容 -- 文档基于错误现状做出的设计或任务拆分 -- 文档之间相互冲突的目标、方案、约束、任务 -- `Modified Capabilities` 在本次 change 的 specs 中是否已更新（注意：仅更新 change 目录下的 specs，不动 `openspec/specs/`） +- 讨论中已确定但 `design.md` 未记录的内容 +- `design.md` 中缺失或含糊的 requirements、acceptance criteria、guardrails、decisions、verification expectations +- `Open Questions` 未明确区分 blocking / non-blocking、与 `tasks.md` 冲突，或包含 apply 前必须解决的 blocker +- `tasks.md` 未覆盖 `design.md` 的要求、约束、执行计划、验证计划或文档/沟通更新要求 +- `tasks.md` 标记了无法验证、跨行、过大、顺序错误或包含无关仓库/版本控制/发布操作的任务 +- 文档仍保留 `` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容 +- 文档基于错误当前状态做出的设计或任务拆分 +- 文档之间相互冲突的目标、方案、约束、任务和验证要求 +- `fast-drive` change 中仍错误依赖 `proposal.md`、`specs/*.md`、`Capabilities` 或 `Modified Capabilities` 的内容 输出审查结果： 1. **问题总览表**：问题类型 × 涉及文档数 -2. **讨论遗漏清单**：讨论已确定但文档未体现的内容；若缺少讨论记录，标记为"未审查" -3. **现实性问题清单**：与当前代码现状不符的描述、假设或影响分析 -4. **文档冲突清单**：proposal、design、tasks、specs 之间的不一致 -5. **OpenSpec 规范问题清单**：格式、术语、结构问题 -6. **待澄清清单**：仅靠讨论和代码仍无法判断的事项 -7. **逐项分析**：每个问题说明位置、问题、影响、建议 -8. **补充建议方案**：按文件列出建议补充/修正的内容、原因和可选方案 +2. **讨论遗漏清单**：讨论已确定但 `design.md` 未体现的内容；若缺少讨论记录，标记为“未审查” +3. **Design 自包含性问题清单**：缺失、含糊或无法指导新会话 apply 的内容 +4. **当前状态问题清单**：与当前实际状态不符的描述、假设或影响分析 +5. **Tasks 派生与覆盖问题清单**：`tasks.md` 未从 `design.md` 正确派生或覆盖不足的内容 +6. **文档冲突清单**：`design.md`、`tasks.md` 和实际存在的其他 artifacts 之间的不一致 +7. **OpenSpec 规范问题清单**：格式、术语、结构问题 +8. **待澄清清单**：仅靠讨论和当前状态仍无法判断的事项 +9. **逐项分析**：每个问题说明位置、问题、影响、建议 +10. **补充建议方案**：按文件列出建议补充/修正的内容、原因和可选方案 -若所有清单均为空，输出"审查通过，未发现问题"，跳至步骤 5。 +若所有清单均为空，输出“审查通过，未发现问题”，跳至步骤 5。 ## 3. 计划（用户确认） -先针对"待澄清清单"用提问工具逐项向用户确认。 +先针对“待澄清清单”用提问工具逐项向用户确认。 再整理完整修复方案，按文件列出： @@ -86,7 +112,9 @@ c) 并行读取已确定的 spec 和其余 artifacts（`design.md`、`tasks.md` ## 4. 执行 -逐项修改已确认的变更文档，不修改源码。 +逐项修改已确认的变更文档，不修改实际产物。 + +在 `fast-drive` workflow 下，通常只修改本次 change 的 `design.md` 和 `tasks.md`；若实际 schema 存在其他 artifacts，仅在确有必要且用户确认后修改实际存在的 artifacts。 若涉及删除或重写： @@ -95,11 +123,14 @@ c) 并行读取已确定的 spec 和其余 artifacts（`design.md`、`tasks.md` 执行后重新读取所有被修改的文档，并复核： -- "讨论遗漏清单" 是否已清空或已标注保留原因 -- "现实性问题清单" 是否已清空或已标注为预期变更 -- "文档冲突清单" 是否已清空 -- "OpenSpec 规范问题清单" 是否已清空 -- "待澄清清单" 是否已清空或已记录用户决策 +- “讨论遗漏清单” 是否已清空或已标注保留原因 +- “Design 自包含性问题清单” 是否已清空 +- “当前状态问题清单” 是否已清空或已标注为预期变更 +- “Tasks 派生与覆盖问题清单” 是否已清空 +- “文档冲突清单” 是否已清空 +- “OpenSpec 规范问题清单” 是否已清空 +- “待澄清清单” 是否已清空或已记录用户决策 +- 所有模板注释、空表格行和占位文本是否已清空或替换为有效内容 ## 5. 收尾 diff --git a/docs/prompts/prompt-spec-review.md b/docs/prompts/prompt-spec-review.md deleted file mode 100644 index 1237151..0000000 --- a/docs/prompts/prompt-spec-review.md +++ /dev/null @@ -1,142 +0,0 @@ -请审查并整理 `openspec/specs/` 下的稳定规范，使其成为可搜索、边界清晰、无冗余、与当前业务一致的能力索引，按以下流程执行。 - -## 约束 - -- `openspec/specs/` 描述长期稳定的业务能力、规则和外部行为，不记录变更过程、迁移说明、实现路径、内部类型名、组件 props、样式数值、层级分层等实现细节 -- 用户可感知或对外暴露的契约可以保留：公开 API 路径、请求/响应字段、协议名、错误码、数据约束、交互结果 -- `Requirement` 和 `Scenario` 应描述业务能力、外部行为或稳定约束，不以“使用某层/某组件/某库实现”作为标题或核心表述 -- 不把当前代码自动视为唯一真相；若代码、README、现有 spec 冲突且无法判断应以哪边为准，列入待确认清单，不直接改写规范 -- 仅删除内容已被其他规范完整覆盖且无独立检索价值的规范；非冗余内容仅迁移、合并、拆分或重命名 -- 每批重构执行前用提问工具获得用户确认；删除或重写前先备份原文件为 `{file}.bak.{timestamp}` -- 命名、Purpose、Requirement 标题都必须保留用户下一次最可能搜索的业务关键词 - -## 1. 收集 - -并行读取： - -- `openspec/config.yaml` -- `README.md`，以及与模块结构、API、架构相关的 README 或文档 -- `openspec/specs/*/spec.md` - -默认不读取 `openspec/changes/**`、历史 proposal/design/tasks 作为稳定规范整理依据；仅在用户明确要求“连同历史变更一起校对”时再纳入。 - -先建立索引，不直接开始改写： - -| 索引 | 内容 | -| -------------- | ----------------------------------------------------------------------------- | -| `spec_index[]` | 每个 spec 的目录名、Purpose、Requirement 摘要、关键词、外部契约、疑似重叠对象 | -| `domain_map[]` | 从 README、API、模块文档中提炼的核心业务域、横切能力和术语 | -| `term_map[]` | 同义词、旧名、缩写和推荐标准术语 | -| `suspects[]` | 需要进一步对照代码或测试确认的 spec | - -仅对 `suspects[]` 做定向读取： - -- 读取与该 spec 对应的源码、测试、README 或架构文档 -- 不对 `backend/`、`frontend/` 做无差别逐文件扫描 - -判定依据优先级： - -- 当前稳定 spec 与 README 共同支持的事实，可直接视为高置信度 -- 仅代码可见但 README 和 spec 未体现的内容，先判断它是稳定外部行为还是临时实现细节 -- 代码、README、现有 spec 互相冲突且无法自动定夺时，进入 `待确认清单` - -## 2. 审查 - -按 spec、Requirement、Scenario 三层检查： - -| 维度 | 检查点 | -| --------- | --------------------------------------------------------------------------------- | -| 过时 | 描述的能力、术语、外部契约是否仍成立；是否存在 `TBD`、`TODO`、占位说明 | -| 冲突 | 不同规范是否对同一行为给出不同约束、命名或边界 | -| 重复/重叠 | 是否在文件级、Requirement 级、Scenario 级重复描述同一能力 | -| 错位 | 内容是否放错能力域；横切规则是否混入实体规范；平台实现是否混入通用能力规范 | -| 粒度 | 是否过大导致难检索，或过碎导致回答一个问题必须同时打开多个 spec | -| 术语 | 同一概念是否混用多个名字；旧名、别名、缩写是否需要归一并保留检索入口 | -| 命名/检索 | 目录名、Purpose、Requirement 标题是否准确；是否能被 README、API、业务术语直接命中 | -| 规范性 | 是否使用 SHALL/WHEN/THEN；是否混入变更记录、迁移说明、内部实现或 UI/代码细节 | -| 完整性 | Purpose 是否明确；是否存在空目录、非 spec 噪音文件、无清晰归属的孤立规范 | - -重构判定规则： - -- 若两个 spec 回答的是同一个核心问题，或其中一个只是另一个的子集，优先合并 -- 若一个 spec 混合多个独立检索意图，或同时包含横切规则与业务流程，优先拆分 -- 若内容正确但目录名、Purpose 或 Requirement 标题不利于检索，优先重命名或改写标题 -- 若多个术语指向同一概念，统一到一个标准术语，并在 Purpose 或 Requirement 中保留必要别名以支持搜索 -- 若某段内容只是内部实现细节，且不影响外部行为理解，删除该段而不是为其单独保留 spec -- 若某个具体值同时属于外部契约与内部实现，按“是否对调用方可见、是否影响兼容性”判断是否保留 - -### 命名约定 - -命名优先复用仓库已存在的稳定术语，如 `provider`、`model`、`stats`、`protocol`、`proxy`、`logging`、`validation`、`migration`、`frontend`、`desktop`、`mysql`。 - -| 类型 | 模式 | 示例 | -| ------------ | ---------------------------------------------------------- | -------------------------------------------------- | -| 实体生命周期 | `{entity}-management` | `provider-management`、`model-management` | -| 横切能力 | `{concern}` 或 `{concern}-{qualifier}` | `error-handling`、`structured-logging` | -| 协议/适配 | `{protocol}-{capability}` 或 `protocol-adapter-{protocol}` | `openai-protocol-proxy`、`protocol-adapter-openai` | -| 运行面/入口 | `{surface}` 或 `{surface}-{capability}` | `frontend`、`desktop-app` | -| 基础设施 | `{resource}-{operation}` | `database-migration`、`mysql-driver` | - -命名原则： - -- 1-4 个词，保持单一主题 -- 优先使用业务名词，不使用 `basic`、`general`、`misc`、`info`、`data` 等泛化词 -- 不使用 `crud`、`list`、`table`、`display` 等实现模式词，除非它本身就是外部契约的一部分 -- 同一主题的命名模式保持一致，不同时混用多套前后缀 - -## 3. 报告 - -输出分析结果： - -1. **问题总览表**：问题类型 × 涉及规范数 -2. **规范关系表**：每个 spec 的主主题、重叠对象、冲突对象、建议动作 -3. **术语归一表**：旧术语 / 别名 / 缩写 → 推荐标准术语 -4. **逐项分析**：每个有问题的规范说明位置、问题、影响、建议和目标规范 -5. **待确认清单**：代码、README、现有 spec 冲突且无法自动定夺的事项 -6. **重构方案**：按优先级分批 -7. **重构后目录结构**：预期的新 `openspec/specs/` 目录树 - -优先级建议： - -- P0：删除空目录、非 spec 噪音文件、占位内容 -- P1：删除完全冗余规范；将其内容映射到主规范 -- P2：合并重复/子集规范；拆分错位或过大规范 -- P3：重命名目录、改写 Purpose 和 Requirement 标题以提升检索性 -- P4：修正过时描述，清理实现细节、迁移说明和变更记录 - -若所有问题清单为空，输出“审查通过，未发现问题”，跳至步骤 5。 - -## 4. 计划（用户确认） - -先针对 `待确认清单` 用提问工具逐项向用户确认。 - -再按批次展示完整重构计划，每批必须包含： - -- 操作类型：删除、重命名、迁移、合并、拆分、改写 -- 路径变化：源路径 → 目标路径 -- 内容映射：源 spec 的 Requirement / Scenario 将迁移到哪里 -- 术语处理：哪些旧词保留为检索入口，哪些词统一替换 -- 执行原因：为什么这样做更利于检索、去重和边界清晰 -- 验证方式：如何确认没有丢失约束或引入新的冲突 - -用提问工具获得当前批次确认后再执行。 - -## 5. 执行 - -按 P0 → P4 逐批执行已确认的重构。 - -执行要求： - -- 合并或拆分时先写目标 spec，再删除或重命名源 spec -- 删除前确认其 Requirement 和 Scenario 已被完整保留、迁移或判定为纯冗余 -- 每批执行后重新读取受影响的 spec，并复核结构和内容 - -每批执行后至少验证： - -- 目录结构完整，`openspec/specs/*/spec.md` 可正常读取 -- 不存在未承接的 Requirement 或 Scenario -- Purpose、Requirement 标题、目录名可以直接表达主能力 -- 不再包含 `TBD`、变更记录、迁移说明、内部实现细节或噪音文件 -- 若本批涉及代码对照项，相关外部契约描述与当前仓库现状一致，或已列入残留待确认 - -收尾时输出：修改文件清单、备份文件清单、最终目录树、残留待确认事项和整理摘要。 diff --git a/openspec/config.yaml b/openspec/config.yaml index 96c2170..4432528 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,4 +1,4 @@ -schema: spec-driven +schema: fast-drive context: | - 使用中文（注释、文档、交流），面向中文开发者 @@ -20,8 +20,8 @@ context: | - 本项目为 Bun 全栈应用模板，README.md记录模板使用方法，DEVELOPMENT.md记录模板使用的技术细节 rules: - proposal: - - 仔细审查每一个过往spec判断是否存在Modified Capabilities + explore: + - 本项目openspec使用fast-drive自定义schema，变更文档只包含design.md和tasks.md，无proposal.md和specs design: - 先前的讨论技术方案要尽可能体现在设计文档中，便于指导实现阶段不偏离已定的技术路线 tasks: diff --git a/openspec/schemas/fast-drive/schema.yaml b/openspec/schemas/fast-drive/schema.yaml new file mode 100644 index 0000000..f8ed152 --- /dev/null +++ b/openspec/schemas/fast-drive/schema.yaml @@ -0,0 +1,181 @@ +name: fast-drive +version: 1 +description: Fast OpenSpec workflow - design -> tasks -> apply +artifacts: + - id: design + generates: design.md + description: Self-contained solution brief and execution plan + 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. + + 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. + + 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 + + - New dependency, integration, vendor, tool, policy, or external input + + - Significant information model, process model, data model, or ownership + changes + + - Security, privacy, compliance, performance, operational, or migration + 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 + or handoff points, sequencing, and any rollout notes. + + - **Verification Plan**: Validation checks, reviews, approvals, + 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 + wrong. + Format: [Risk] -> Mitigation + + - **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. + + 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. + + 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. + requires: [] + - id: tasks + generates: tasks.md + description: Trackable execution checklist derived from design.md + template: tasks.md + instruction: | + Create tasks.md by breaking design.md into executable work. + + **IMPORTANT: Follow the template below exactly.** The apply phase parses + 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 + artifacts; any relevant prior discussion must already be captured in + design.md. + + - Group related tasks under `##` numbered headings + + - Each task MUST be a single-line checkbox: `- [ ] X.Y Task description` + + - Tasks should be small enough to complete in one session + + - Order tasks by dependency (what must be done first?) + + - 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 + + - 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: + + ``` + ## 1. Context Review + + - [ ] 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 + + ## 2. Execution + + - [ ] 2.1 Execute first concrete work item from design.md + - [ ] 2.2 Execute next concrete work item from design.md + + ## 3. Validation + + - [ ] 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 + + ## 4. Documentation / Communication + + - [ ] 4.1 Update relevant documentation, runbooks, communication materials, or project references if behavior, process, interface, configuration, or usage changed + ``` + + Reference design.md for scope, requirements, decisions, execution + direction, and verification expectations. + + Each task should be verifiable: it must be clear when the task is done. + requires: + - design +apply: + requires: + - design + - 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. diff --git a/openspec/schemas/fast-drive/templates/design.md b/openspec/schemas/fast-drive/templates/design.md new file mode 100644 index 0000000..f6971ab --- /dev/null +++ b/openspec/schemas/fast-drive/templates/design.md @@ -0,0 +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 | +| ---- | ---------------------- | --------------- | ----- | +| | | | | + +## 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 new file mode 100644 index 0000000..c394f23 --- /dev/null +++ b/openspec/schemas/fast-drive/templates/tasks.md @@ -0,0 +1,19 @@ +## 1. Context Review + +- [ ] 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 + +## 2. Execution + +- [ ] 2.1 Execute first concrete work item from design.md +- [ ] 2.2 Execute next concrete work item from design.md + +## 3. Validation + +- [ ] 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 + +## 4. Documentation / Communication + +- [ ] 4.1 Update relevant documentation, runbooks, communication materials, or project references if behavior, process, interface, configuration, or usage changed diff --git a/openspec/specs/admin-layout/spec.md b/openspec/specs/admin-layout/spec.md deleted file mode 100644 index 0c2ef24..0000000 --- a/openspec/specs/admin-layout/spec.md +++ /dev/null @@ -1,139 +0,0 @@ -## Requirements - -### Requirement: 企业 Admin 后台布局 - -系统 SHALL 实现 Header + 侧边栏 + 内容区的企业 Admin 后台布局，使用 TDesign Layout 组件。 - -#### Scenario: 布局结构 - -- **WHEN** 用户访问应用 -- **THEN** 系统 SHALL 渲染包含 Header、Aside、Content 的 Layout 结构 - -#### Scenario: Layout 嵌套结构 - -- **WHEN** 布局渲染 -- **THEN** 系统 SHALL 使用嵌套 Layout 结构：`Layout > (Header + Layout > (Aside + Content))` - -### Requirement: Header 布局 - -Header SHALL 包含折叠按钮、页面标题、主题切换控件。 - -#### Scenario: Header 左侧折叠按钮 - -- **WHEN** Header 渲染 -- **THEN** 系统 SHALL 在左侧显示侧边栏折叠/展开按钮 - -#### Scenario: Header 页面标题 - -- **WHEN** Header 渲染 -- **THEN** 系统 SHALL 显示当前路由对应的页面标题（从 menu 获取） -- **AND** 若当前路由无匹配菜单项，SHALL 显示 `APP.title` 作为 fallback - -#### Scenario: Header 右侧主题切换 - -- **WHEN** Header 渲染 -- **THEN** 系统 SHALL 在右侧显示主题切换 RadioGroup（系统/明亮/黑暗） - -### Requirement: 侧边栏菜单 - -系统 SHALL 提供侧边栏菜单组件（Sidebar），使用 TDesign Menu 组件，支持折叠/展开。 - -#### Scenario: 侧边栏渲染菜单项 - -- **WHEN** 侧边栏渲染 -- **THEN** 系统 SHALL 根据 `menu.tsx` 渲染所有菜单项 - -#### Scenario: 菜单项点击导航 - -- **WHEN** 用户点击菜单项 -- **THEN** 系统 SHALL 使用 React Router 的 `navigate` 跳转到对应路径 - -#### Scenario: 菜单项激活状态 - -- **WHEN** 当前路由与菜单项路径匹配 -- **THEN** 系统 SHALL 高亮显示该菜单项 - -### Requirement: 侧边栏折叠 - -侧边栏 SHALL 支持折叠/展开，折叠状态持久化到 localStorage。 - -#### Scenario: 侧边栏折叠交互 - -- **WHEN** 用户点击 Header 左侧的折叠按钮 -- **THEN** 系统 SHALL 切换侧边栏折叠状态 - -#### Scenario: 侧边栏折叠宽度 - -- **WHEN** 侧边栏折叠 -- **THEN** Aside 宽度 SHALL 变为 80px，Menu 仅显示图标 - -#### Scenario: 侧边栏展开宽度 - -- **WHEN** 侧边栏展开 -- **THEN** Aside 宽度 SHALL 变为 232px，Menu 显示图标和文字 - -#### Scenario: 折叠状态持久化 - -- **WHEN** 用户切换侧边栏折叠状态 -- **THEN** 系统 SHALL 将状态存储到 localStorage key `"sidebar.collapsed"` - -#### Scenario: 折叠状态恢复 - -- **WHEN** 应用初始化 -- **THEN** 系统 SHALL 从 localStorage 读取 `"sidebar.collapsed"` 并恢复折叠状态 - -### Requirement: 侧边栏主题跟随全局 - -侧边栏 Menu 的主题 SHALL 跟随全局主题设置，不单独设置 `theme` prop。 - -#### Scenario: 侧边栏跟随全局主题 - -- **WHEN** 全局主题切换为 dark -- **THEN** 侧边栏 SHALL 自动应用 dark 主题样式 - -### Requirement: 菜单配置单一数据源 - -系统 SHALL 在 `src/web/menu.tsx` 定义菜单项配置，包含 `value`、`label`、`path`、`icon` 字段。 - -#### Scenario: 菜单配置类型安全 - -- **WHEN** 定义菜单配置 -- **THEN** 系统 SHALL 使用 `as const` 保证字面量类型推断 - -#### Scenario: Sidebar 引用菜单配置 - -- **WHEN** Sidebar 渲染 -- **THEN** 系统 SHALL 遍历 `MENU_ITEMS` 渲染 MenuItem - -### Requirement: 示例页面 - -系统 SHALL 提供示例页面组件：Dashboard、Users、Settings、NotFound。 - -#### Scenario: Dashboard 页面 - -- **WHEN** 用户访问 `/` -- **THEN** 系统 SHALL 渲染 Dashboard 页面（包含原 app.tsx 的欢迎语和 /health 展示） - -#### Scenario: Users 页面占位 - -- **WHEN** 用户访问 `/users` -- **THEN** 系统 SHALL 渲染用户管理占位页面 - -#### Scenario: Settings 页面占位 - -- **WHEN** 用户访问 `/settings` -- **THEN** 系统 SHALL 渲染系统设置占位页面 - -#### Scenario: NotFound 页面 - -- **WHEN** 用户访问未定义路径 -- **THEN** 系统 SHALL 渲染 404 页面，提供返回首页按钮 - -### Requirement: CSS 类名迁移 - -原 `.dashboard-*` CSS 类名 SHALL 变更为 `.app-*`。 - -#### Scenario: 布局类名 - -- **WHEN** 样式应用 -- **THEN** 系统 SHALL 使用 `.app-layout`、`.app-header`、`.app-content`、`.app-sidebar` 类名 diff --git a/openspec/specs/app-constants/spec.md b/openspec/specs/app-constants/spec.md deleted file mode 100644 index 6857b92..0000000 --- a/openspec/specs/app-constants/spec.md +++ /dev/null @@ -1,75 +0,0 @@ -## Purpose - -定义应用全局常量，作为应用元信息（name、title、subtitle、description、version）的唯一真实来源，供前后端及构建脚本统一引用，消除硬编码散落。 - -## Requirements - -### Requirement: 应用元信息唯一来源 - -系统 SHALL 在 `src/shared/app.ts` 中定义应用全局常量 `APP`，包含以下字段： -- `name`：机器标识（kebab-case 格式） -- `title`：人类可读标题 -- `subtitle`：副标题 -- `description`：应用描述（用于 SEO meta） -- `version`：语义版本号 - -`APP` SHALL 使用 `as const` 声明，保证字面量类型推断。 - -#### Scenario: 后端引用应用名称 - -- **WHEN** 后端代码需要应用名称（如 CLI 帮助文本、health 响应、启动日志） -- **THEN** 系统 SHALL 从 `src/shared/app.ts` 导入 `APP.name` - -#### Scenario: 前端引用应用标题 - -- **WHEN** 前端代码需要应用标题（如 Header logo、欢迎文本） -- **THEN** 系统 SHALL 从 `src/shared/app.ts` 导入 `APP.title` - -#### Scenario: 构建脚本引用应用名称 - -- **WHEN** 构建脚本需要确定可执行文件名 -- **THEN** 系统 SHALL 从 `src/shared/app.ts` 导入 `APP.name` - -### Requirement: 前端 HTML 元信息动态设置 - -系统 SHALL 在 React 应用挂载时动态设置 HTML 元信息： -- `document.title` SHALL 设置为 `APP.title` -- `` 内容 SHALL 设置为 `APP.description` - -#### Scenario: 页面标题显示应用名称 - -- **WHEN** 用户访问应用 -- **THEN** 浏览器标签页标题 SHALL 显示 `APP.title` - -#### Scenario: meta description 设置 - -- **WHEN** 搜索引擎爬取页面 -- **THEN** meta description SHALL 包含 `APP.description` - -### Requirement: localStorage key 语义化命名 - -主题偏好存储 key SHALL 为 `"theme.preference"`，不包含应用名前缀。 - -#### Scenario: 主题偏好持久化 - -- **WHEN** 用户选择主题偏好（system/light/dark） -- **THEN** 系统 SHALL 将偏好值存储到 localStorage key `"theme.preference"` - -#### Scenario: 主题偏好读取 - -- **WHEN** 应用初始化时读取用户主题偏好 -- **THEN** 系统 SHALL 从 localStorage key `"theme.preference"` 读取 - -### Requirement: 侧边栏折叠状态 localStorage key - -侧边栏折叠状态存储 key SHALL 为 `"sidebar.collapsed"`，不包含应用名前缀。 - -#### Scenario: 折叠状态持久化 - -- **WHEN** 用户切换侧边栏折叠状态 -- **THEN** 系统 SHALL 将状态存储到 localStorage key `"sidebar.collapsed"` - -#### Scenario: 折叠状态读取 - -- **WHEN** 应用初始化时读取侧边栏折叠状态 -- **THEN** 系统 SHALL 从 localStorage key `"sidebar.collapsed"` 读取 diff --git a/openspec/specs/frontend-routing/spec.md b/openspec/specs/frontend-routing/spec.md deleted file mode 100644 index 2151f2b..0000000 --- a/openspec/specs/frontend-routing/spec.md +++ /dev/null @@ -1,57 +0,0 @@ -## Requirements - -### Requirement: 前端 SPA 路由 - -系统 SHALL 使用 React Router v7 (Declarative mode) 实现前端 SPA 路由，支持多页面导航。 - -#### Scenario: 应用启动时初始化路由 - -- **WHEN** 应用启动 -- **THEN** 系统 SHALL 在 `main.tsx` 中使用 `BrowserRouter` 包裹根组件 - -#### Scenario: 路由匹配渲染对应页面 - -- **WHEN** 用户访问路径 `/` -- **THEN** 系统 SHALL 渲染 Dashboard 页面 - -#### Scenario: 用户管理页面路由 - -- **WHEN** 用户访问路径 `/users` -- **THEN** 系统 SHALL 渲染用户管理页面 - -#### Scenario: 系统设置页面路由 - -- **WHEN** 用户访问路径 `/settings` -- **THEN** 系统 SHALL 渲染系统设置页面 - -#### Scenario: 未知路径返回 404 页面 - -- **WHEN** 用户访问未定义的路径（如 `/unknown`） -- **THEN** 系统 SHALL 渲染 NotFound 页面 - -### Requirement: 路由定义独立文件 - -路由定义 SHALL 抽离为独立文件 `src/web/routes.tsx`，`app.tsx` 引用该文件。 - -#### Scenario: 路由配置集中管理 - -- **WHEN** 开发者需要新增或修改路由 -- **THEN** 系统 SHALL 在 `routes.tsx` 中统一管理所有 `` 定义 - -### Requirement: 路由守卫预留 - -系统 SHALL 预留路由守卫接口（`ProtectedRoute` 组件），但暂不实现认证逻辑。 - -#### Scenario: 路由守卫组件存在 - -- **WHEN** 需要实现认证保护 -- **THEN** 系统 SHALL 提供 `ProtectedRoute` wrapper 组件供 Routes 使用 - -### Requirement: Vite code splitting 包含路由库 - -`vite.config.ts` 的 code splitting 配置 SHALL 新增 `vendor-router` 组，包含 `react-router`。 - -#### Scenario: 路由库独立分包 - -- **WHEN** 执行生产构建 -- **THEN** `react-router` SHALL 被打包到独立的 `vendor-router` chunk 中