lanyuanxiaoyao/bun-app-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: 切换 OpenSpec workflow 从 spec-driven 到 fast-drive

Browse Source 
- 新增 fast-drive 自定义 schema 及模板（design.md、tasks.md）
- 更新 config.yaml schema 为 fast-drive，调整 rules
- 重构 proposal-review 和 apply-review 提示词适配 fast-drive
- 删除 spec-review 提示词（fast-drive 不需要 spec 审查）
- 删除 openspec/specs/ 下的稳定规范文件
- 更新 README 和 DEVELOPMENT.md 相关描述
This commit is contained in:
兰缘小妖
2026-05-24 22:45:46 +08:00
parent 1e3269380e
commit bc54f8352a
13 changed files with 451 additions and 527 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
DEVELOPMENT.md
View File

@@ -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 配置文件示例
```

4
README.md
View File

@@ -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/ # 项目文档
```

12
docs/prompts/README.md
View File

@@ -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 的一致性，并补齐遗漏或回写文档 |
## 设计目标

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

@@ -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. 收尾
列出所有修改的文件、备份文件、测试命令与结果、文档同步摘要和剩余风险。
列出所有修改的文件、备份文件、验证命令或检查结果、文档同步摘要和剩余风险。
若本次因缺少测试结果、修补记录或上下文而降级执行，或有问题因信息不足暂未处理，单独说明。
若本次因缺少验证结果、修补记录或上下文而降级执行，或有问题因信息不足暂未处理，单独说明。

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

@@ -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. 收尾

142
docs/prompts/prompt-spec-review.md
View File

@@ -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`、变更记录、迁移说明、内部实现细节或噪音文件
- 若本批涉及代码对照项，相关外部契约描述与当前仓库现状一致，或已列入残留待确认
收尾时输出：修改文件清单、备份文件清单、最终目录树、残留待确认事项和整理摘要。

6
openspec/config.yaml
View File

@@ -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:

181
openspec/schemas/fast-drive/schema.yaml Normal file
View File

@@ -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.

77
openspec/schemas/fast-drive/templates/design.md Normal file
View File

@@ -0,0 +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 -->
- 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 -->
**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 -->
- 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 -->
| Area | Artifacts / References | Expected Change | Notes |
| ---- | ---------------------- | --------------- | ----- |
| <!-- Area --> | <!-- Artifacts / References --> | <!-- Expected Change --> | <!-- Notes --> |
## 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 -->
## 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 |

19
openspec/schemas/fast-drive/templates/tasks.md Normal file
View File

@@ -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

139
openspec/specs/admin-layout/spec.md
View File

@@ -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` 类名

75
openspec/specs/app-constants/spec.md
View File

@@ -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`
- `<meta name="description">` 内容 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"` 读取

57
openspec/specs/frontend-routing/spec.md
View File

@@ -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` 中统一管理所有 `<Route>` 定义
### 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 中