feat: 初始化项目,添加 OpenSpec 子模块和 fast-drive 自定义 schema
This commit is contained in:
150
fast-drive/schema.yaml
Normal file
150
fast-drive/schema.yaml
Normal file
@@ -0,0 +1,150 @@
|
||||
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 存在阻塞性待解决问题,或需要澄清,必须暂停。
|
||||
Reference in New Issue
Block a user