151 lines
7.4 KiB
YAML
151 lines
7.4 KiB
YAML
name: fast-drive
|
||
version: 1
|
||
description: 快速 OpenSpec workflow - design -> tasks -> apply
|
||
artifacts:
|
||
- id: design
|
||
generates: design.md
|
||
description: 自包含的方案说明和执行计划
|
||
template: design.md
|
||
instruction: |
|
||
创建 design.md，作为本次变更“改什么、为什么改、如何执行”的自包含事实来源。
|
||
|
||
本 workflow 不使用 proposal 或 specs artifacts。design.md MUST 保留前序探索和用户讨论中的重要结论，确保后续 apply 阶段即使经历上下文压缩或进入新会话，也能正确继续执行。
|
||
|
||
语言规则（强制）：
|
||
|
||
- fast-drive 的 design.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文
|
||
|
||
- 最终 design.md 不得残留英文模板句子或英文占位内容，除非该英文是 OpenSpec 术语、文件名、schema 字段名、代码符号、命令或必要技术名词
|
||
|
||
面向看不到早期对话的人编写。简单变更保持精炼，但必须包含足够细节让执行无歧义。遇到以下情况时增加细节：
|
||
|
||
- 跨多个系统、团队、工作流或 artifacts 的横切变更
|
||
|
||
- 新增依赖、集成、供应商、工具、策略或外部输入
|
||
|
||
- 重要的信息模型、流程模型、数据模型或归属关系变化
|
||
|
||
- 涉及安全、隐私、合规、性能、运维或迁移复杂度
|
||
|
||
- 执行前需要先做决策才能降低歧义
|
||
|
||
- 前序讨论已经确认非显而易见的需求、约束或被否决方案
|
||
|
||
必需章节（建议使用以下中文章节标题）：
|
||
|
||
- **背景**：问题、当前状态、相关参考资料，以及触发本次变更的用户请求
|
||
|
||
- **讨论记录**：探索或前序讨论中必须保留的关键点，包括已确认结论、用户偏好、约束和重要的被否决方案
|
||
|
||
- **需求**：预期结果、行为/流程/接口/内容变化、连续性要求和验收标准
|
||
|
||
- **目标 / 非目标**：本次变更要达成的目标，以及明确不在范围内的内容
|
||
|
||
- **执行约束**：必须遵守的约束、禁止的做法、需保持的行为/流程、依赖限制，以及项目或 workflow 特有边界
|
||
|
||
- **影响范围**：与本次变更相关的具体 artifacts、参考资料、相关方、系统、工作流、文档、配置、资产或交接事项
|
||
|
||
- **决策**：关键选择及理由（为什么选 X 而不是 Y）。每个重要决策都要包含考虑过的替代方案，以及未选择它们的原因
|
||
|
||
- **执行计划**：主要工作流或待修改 artifacts、集成或交接点、执行顺序，以及必要的发布/落地说明
|
||
|
||
- **验证计划**：用于证明变更完成所需的验证检查、审查、批准、验收检查、文档检查、沟通检查和人工检查
|
||
|
||
- **风险 / 权衡**：已知限制和可能出错的事项
|
||
格式：[风险] -> 缓解措施
|
||
|
||
- **待解决问题**：执行前仍需解决的决策、假设或未知项。必须区分会阻塞 apply 的问题和非阻塞后续问题。没有未决问题时使用“无”
|
||
|
||
可选章节（相关时添加，建议使用中文章节标题）：
|
||
|
||
- **迁移 / 发布计划**：发布步骤、沟通安排、归属、回滚或连续性策略
|
||
|
||
聚焦保留需求、理由、约束和方案。除非某个细节是讨论中明确做出的决策，否则避免逐行或逐步骤展开。
|
||
|
||
优先写可长期使用的摘要，而不是聊天记录转写。当具体 artifact 名称、数据/信息形状、示例、相关方、归属和边界场景会影响执行时，必须写清楚。
|
||
|
||
不要在 design.md 使用任务 checkbox；checkbox 只属于 tasks.md。
|
||
|
||
最终 design.md 不得包含未解决的模板注释、空表格行或占位文本。
|
||
|
||
如果信息缺失，写明假设和待解决问题，不要编造隐藏需求。不要依赖未写入文档的聊天上下文。
|
||
requires: []
|
||
- id: tasks
|
||
generates: tasks.md
|
||
description: 从 design.md 派生的可跟踪执行清单
|
||
template: tasks.md
|
||
instruction: |
|
||
创建 tasks.md，将 design.md 拆解为可执行工作项。
|
||
|
||
**重要：必须遵守以下模板中的 checkbox 行格式。** apply 阶段会解析 checkbox 格式跟踪进度。未使用 `- [ ]` 的任务不会被跟踪。
|
||
|
||
语言规则（强制）：
|
||
|
||
- fast-drive 的 tasks.md 使用中文分组标题和中文任务描述；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文
|
||
|
||
- 每个可跟踪任务必须保留 OpenSpec CLI 可解析的单行 checkbox 格式，例如 `- [ ] 1.1 任务描述` 或 `- [x] 1.1 已完成任务描述`
|
||
|
||
- 最终 tasks.md 不得残留英文模板任务或英文占位内容，除非该英文是 OpenSpec 术语、文件名、schema 字段名、代码符号、命令或必要技术名词
|
||
|
||
编写规则：
|
||
|
||
- 任务必须从 design.md 派生。不要依赖 proposal.md 或 specs artifacts；任何相关前序讨论都必须已经记录在 design.md 中
|
||
|
||
- 相关任务按 `##` 编号标题分组，分组标题使用中文
|
||
|
||
- 每个任务 MUST 是单行 checkbox：`- [ ] X.Y 任务描述`
|
||
|
||
- 任务粒度应足够小，能在一个会话内完成
|
||
|
||
- 按依赖顺序排序（先做必须先完成的事项）
|
||
|
||
- 当执行依赖执行约束、影响范围或待解决问题时，从上下文审查任务开始
|
||
|
||
- 需要时包含验证任务，覆盖检查、审查、批准、验收、文档、沟通和人工检查
|
||
|
||
- 除非仓库、版本控制或发布操作明确属于本次变更范围，否则不要包含这类任务
|
||
|
||
- 最终 tasks.md 不得包含未解决的模板注释、空表格行或占位任务文本
|
||
|
||
示例：
|
||
|
||
```
|
||
## 1. 上下文审查
|
||
|
||
- [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题
|
||
- [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料
|
||
|
||
## 2. 执行
|
||
|
||
- [ ] 2.1 执行 design.md 中的第一个具体工作项
|
||
- [ ] 2.2 执行 design.md 中的下一个具体工作项
|
||
|
||
## 3. 验证
|
||
|
||
- [ ] 3.1 执行“验证计划”中要求的验证
|
||
- [ ] 3.2 执行项目或 workflow 要求的质量检查
|
||
- [ ] 3.3 执行“验证计划”中要求的人工审查或验收检查
|
||
|
||
## 4. 文档 / 沟通
|
||
|
||
- [ ] 4.1 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档、runbook、沟通材料或项目参考资料
|
||
```
|
||
|
||
以 design.md 中的范围、需求、决策、执行方向和验证预期为依据。
|
||
|
||
每个任务都应可验证：必须能明确判断任务何时完成。
|
||
requires:
|
||
- design
|
||
apply:
|
||
requires:
|
||
- design
|
||
- tasks
|
||
tracks: tasks.md
|
||
instruction: |
|
||
先阅读 design.md，再阅读 tasks.md。
|
||
同时遵守 workflow context/configuration，例如存在时读取 openspec/config.yaml，以及 design.md 引用的相关项目或 workflow 文档。
|
||
将 design.md 视为范围、需求、决策、执行约束、执行方向和验证预期的事实来源。
|
||
按依赖顺序处理待办任务，并在完成后及时标记。
|
||
只有任务执行完成且必要验证完成后，才能标记任务完成。
|
||
如果 tasks 与 design.md 冲突、design.md 存在阻塞性待解决问题，或需要澄清，必须暂停。
|