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

docs: 中文化 fast-drive 文档模板

Browse Source
This commit is contained in:
兰缘小妖
2026-05-27 18:30:03 +08:00
parent 348b35ef8c
commit be4b85126b
7 changed files with 195 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/development/README.md
View File

@@ -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 协作方式或开发文档索引时，必须更新本文档。
修改常用命令、质量门禁、全局工程规则、目录边界或开发文档索引时，必须更新本文档。

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

@@ -1,11 +1,11 @@
审查 OpenSpec apply 完成后以及后续手动修补后的实际变更，判断实际产物、验证结果和变更文档是否与 `design.md` source of truth 一致，识别偏离、漏记和可优化点，并将确认后的实际变更同步回变更文档，按以下流程执行。
审查 OpenSpec apply 完成后以及后续手动修补后的实际变更，判断实际产物、验证结果和变更文档是否与 `design.md` 事实来源一致，识别偏离、漏记和可优化点，并将确认后的实际变更同步回变更文档，按以下流程执行。
## 约束
- 先审查再修复；未经用户确认，不修改实际产物或变更文档
- 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查
- 在 `fast-drive` workflow 下，核心 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

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

@@ -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` 等未解决占位内容
- 文档基于错误当前状态做出的设计或任务拆分