1088 lines
65 KiB
YAML
1088 lines
65 KiB
YAML
name: code-drive
|
||
version: 1
|
||
description: 代码开发 OpenSpec workflow - requirements -> design -> plan -> tasks -> apply
|
||
artifacts:
|
||
- id: requirements
|
||
generates: requirements.md
|
||
description: 需求确认与澄清，包含业务需求、技术需求和全局审查
|
||
template: requirements.md
|
||
instruction: |
|
||
## 目标
|
||
|
||
撰写 requirements.md，把"要解决什么、为什么、需要用户决策哪些业务和技术边界"固定为事实来源。
|
||
|
||
requirements.md 的职责是**确认和澄清**：通过对话把需求、边界、取舍和用户决策固定下来。design.md 负责把它们**翻译**为可执行方案——不要在 requirements 展开详细实现步骤、具体文件修改清单或任务 checkbox。
|
||
|
||
本阶段承接 explore、前序讨论、用户请求和代码库调查结果。文档面向项目开发者（而非外部需求方），因此既要确认业务需求，也要确认技术需求：技术选型、架构方向、集成边界、代码约束、验收方式。
|
||
|
||
## 输入
|
||
|
||
- explore / 前序讨论 / 用户原始请求 / 代码库调查结果
|
||
- 已有 requirements.md（如存在则增量修订，不重写未变部分）
|
||
|
||
## 工具使用（先决说明）
|
||
|
||
本阶段开始前必须确认可用工具，并在整个工作流中按以下规则使用：
|
||
|
||
- **todo / plan 工具**（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite）：
|
||
- 复杂变更**必须**使用它跟踪撰写流程
|
||
- **颗粒度细化到子步骤**——每个工作流的"X.Y"编号子步骤对应一个 todo item（例如步骤 1 拆为 1.1 收集上下文、1.2 评估范围、1.3 拆细提问，每项独立 todo）
|
||
- 简单变更可不使用，但判断"简单"的标准是"单一模块、单一决策点、预期 < 100 行文档"
|
||
- **question / choice 工具**：触发提问流程时**必须优先**使用，而非让用户开放回答
|
||
- **只读工具**（Read / Grep / Glob / Bash 只读命令）：在工作流任意步骤中都允许使用，不视为决策型交互
|
||
- **注意**：todo 跟踪的是**文档撰写进度**，不是整体变更实现进度——后者由 apply 阶段和 tasks.md checkbox 跟踪
|
||
|
||
## 向用户提问的标准流程（强制协议，适用于本阶段所有提问环节）
|
||
|
||
本流程是 requirements 阶段用户决策唯一入口，**任何步骤触发以下条件时必须按本流程执行，不得跳过、不得自行决定、不得延迟到下游**。
|
||
|
||
### 触发条件（命中任一即必须启动提问流程）
|
||
|
||
1. 检测到**潜在冲突**——任意两条需求/约束/决策之间存在矛盾、取舍未定、可解读不一致或可能相互排斥
|
||
2. 遇到**开放问题**——任何形式的"开放问题""TBD""待确认""待讨论"章节或条目
|
||
3. **技术决策点未定**——技术选型有多个合理选项且未排除、架构方向存在分歧、集成边界或代码约束未确认
|
||
4. **YAGNI 取舍未定**——某条需求是否真需要、是否应简化、是否应排除本次范围，存在合理质疑
|
||
5. **需求边界不清**——功能范围、行为定义、验收标准存在一种以上合理理解
|
||
6. **依赖约束未定**——上下游依赖、兼容性要求、外部约束未确认
|
||
7. **范围过大需要拆细**——本次变更涉及多个独立维度、子系统或大量决策点；此时**不是询问用户"是否拆分变更"**，而是 AI 主动把范围拆解为 N 个细粒度问题，按提问格式逐项让用户确认
|
||
8. **最终确认**（步骤 7）——即使前 7 条全部未命中，最终确认仍是强制提问
|
||
|
||
### 提问格式（强制）
|
||
|
||
每次提问必须按以下格式输出，不得让用户从零开放回答（除非真的没有任何可选项）：
|
||
|
||
- **2-3 个候选选项**：每个选项给出明确含义，避免"方案 A""方案 B"这种无信息标签
|
||
- **推荐方案**：明确标注推荐哪一个，不得以"都可以""由你决定"回避
|
||
- **取舍说明**：每个非推荐选项说明未选的理由；推荐选项说明取舍的代价
|
||
- **使用工具**：工具支持 question/choice 时**必须**使用结构化选项；不支持时用 markdown 列表呈现
|
||
|
||
### 强制语义（不得跳过）
|
||
|
||
- 触发条件命中时**必须**启动提问流程，即使你倾向"自己决定"或"延后处理"
|
||
- 即使用户回复"你看着办"，也必须回复"推荐方案 + 主要代价"，请用户**显式确认**推荐方案，不得默认接受"你看着办"作为决策
|
||
- 任何触发条件**不得以"待协调""需进一步讨论""开放问题""TBD"形式残留**在 requirements.md 中
|
||
- 简单问题可以合并提问，复杂问题必须拆细逐项提问；但不得一次抛出大量无关问题
|
||
|
||
### 决策归档规则
|
||
|
||
用户给出决策后：
|
||
|
||
1. **按性质归入对应章节**——功能需求 / 非功能需求 / 技术需求 / 被否决方案等
|
||
2. **冲突本身不得以任何形式单独保留**——不设"冲突解决记录"章节
|
||
3. **被否决方案**归入"讨论记录/被否决方案"，并写明否决理由
|
||
4. **新结论引发新冲突**时回到触发条件 1，重新启动提问流程
|
||
5. **决策结论应可在下游 artifact 直接引用**——明确到 design 阶段无需重新提问
|
||
|
||
## 工作流
|
||
|
||
### 步骤 1: 收集上下文、评估范围、拆细问题
|
||
|
||
合并"理解现状、判断范围、拆分提问粒度"三件事，避免在范围未定时就深入细节。
|
||
|
||
**子步骤 1.1: 收集上下文**
|
||
|
||
- 读取相关讨论、代码库现状、用户原始请求，形成初步理解
|
||
- **先读再问**：不要询问代码库或文档中已经能确认的信息——这种提问会被视为"未做功课"
|
||
|
||
**子步骤 1.2: 评估范围**
|
||
|
||
- 判断本次变更是否涉及多个独立维度、子系统或大量决策点
|
||
- 不涉及 → 进入步骤 2
|
||
- 涉及 → 进入子步骤 1.3
|
||
|
||
**子步骤 1.3: 拆细问题**
|
||
|
||
- AI 主动识别范围内的独立维度（如：业务流程、数据模型、外部集成、迁移路径、性能约束……）
|
||
- 把每个维度拆成 1-3 个具体问题（每个问题独立可决策）
|
||
- **触发提问流程**（触发条件 7），按维度逐项让用户确认
|
||
- 用户全部决策归档后进入步骤 2
|
||
|
||
**注意**：本步骤的"拆细"不是询问用户"是否要把变更拆为多次提交"，而是 AI **主动**把大范围内的决策点拆为细粒度问题逐项确认。变更本身仍可能保持单一 requirements.md。
|
||
|
||
### 步骤 2: 撰写初稿
|
||
|
||
按必需章节填写：**背景与目标 / 讨论记录 / 功能需求 / 非功能需求 / 技术需求 / 全局审查**。
|
||
|
||
撰写要求：
|
||
|
||
- **面向看不到早期对话的人**：必须保留关键上下文、用户偏好、已确认结论、约束和被否决方案
|
||
- **分段呈现**：复杂内容每段约 200-300 字，确认后再继续下一段
|
||
- **功能需求**必须带验收标准
|
||
- **非功能需求**只记录本次变更相关内容
|
||
- **技术需求**记录已确认的选型、架构方向、集成边界、代码约束或禁止事项
|
||
- **不写**具体文件修改步骤、代码结构、任务 checkbox 或详细实现计划
|
||
|
||
撰写过程中遇到触发条件 3/4/5/6 时，立即**启动提问流程**；用户决策归档后继续撰写。
|
||
|
||
简单变更保持精炼；复杂或横切变更必须写足够细节，避免后续 design/plan/apply 依赖未写入文档的聊天上下文。
|
||
|
||
### 步骤 3: 全局审查 + YAGNI 挑战
|
||
|
||
对初稿做两个角度的挑战，发现的问题立即纳入步骤 4 或启动提问流程。
|
||
|
||
**子步骤 3.1: 全局审查**
|
||
|
||
从系统边界、既有行为、相邻模块、配置、文档、迁移、兼容性、安全、性能和用户流程角度挑战当前需求。
|
||
|
||
**子步骤 3.2: YAGNI 挑战**
|
||
|
||
对每条需求问——是否真的需要、能否更简单、是否存在更轻量替代方案、是否超出本次范围。
|
||
|
||
**子步骤 3.3: 结果分类处理**
|
||
|
||
- 发现**潜在冲突** → 进入步骤 4
|
||
- 发现**开放问题 / 技术决策未定 / YAGNI 取舍未定 / 边界不清** → **启动提问流程**
|
||
- 无问题 → 进入步骤 5
|
||
|
||
### 步骤 4: 冲突检测与解决
|
||
|
||
扫描任意两条需求/约束/决策之间是否存在矛盾、取舍未定、可解读不一致或可能相互排斥。
|
||
|
||
- **发现潜在冲突** → 立即暂停撰写，**启动提问流程**（触发条件 1）
|
||
- 用户决策后，结论按性质归入对应章节，冲突本身不得以任何形式单独保留
|
||
- 无冲突 → 进入步骤 5
|
||
|
||
### 步骤 5: 开放问题清零
|
||
|
||
全文扫描是否存在"开放问题""TBD""待确认""待讨论"章节或条目（包括步骤 2-4 撰写过程中产生的疑问）。
|
||
|
||
- **发现开放问题** → **启动提问流程**（触发条件 2/3/4/5/6）
|
||
- 某问题确实需要延续到 design 或 apply 阶段才能解决 → **启动提问流程**，让用户决定是否拆分变更或暂时排除本次范围
|
||
- 全部问题已通过用户决策解决并归档 → 进入步骤 6
|
||
- **不得**在 requirements.md 中以"开放问题"形式保留任何条目
|
||
|
||
### 步骤 6: 自检（逐项内联修复，无需二次 review）
|
||
|
||
按以下清单逐项检查，发现问题立即修复后**重跑该项**：
|
||
|
||
- [ ] **占位符扫描**：无模板注释、英文模板句子、TBD、待补充、空表格行或"开放问题"章节
|
||
- [ ] **章节完整性**：必需章节齐全（背景与目标 / 讨论记录 / 功能需求 / 非功能需求 / 技术需求 / 全局审查）；各章节无遗漏
|
||
- [ ] **上下文一致性**：讨论记录的"已确认结论"都已落入对应章节；被否决方案没有被复用
|
||
- [ ] **冲突清零**：所有需求、约束之间无矛盾/歧义/未决取舍；无"待协调""需进一步讨论"
|
||
- [ ] **待确认问题清零**：全文无"开放问题""TBD""待确认""待讨论"等未决条目
|
||
- [ ] **全局审查充分性**：系统边界、既有行为、相邻模块、配置、迁移、兼容性都被审视过
|
||
- [ ] **YAGNI**：每条需求都经过挑战，没有"未来可能需要但本次不必需"的功能
|
||
- [ ] **范围合适**：能用单一 design.md 承接，或已建议拆分为多个子变更
|
||
|
||
自检全部通过后进入步骤 7；任一项失败 → 修复后从该项重跑，必要时回到步骤 2-5。
|
||
|
||
### 步骤 7: 用户最终确认（不得跳过）
|
||
|
||
**强制触发提问流程**（触发条件 8），即使用户在前 6 步中已经多次决策。工具调用或正文明确提问均可。
|
||
|
||
**提问内容**：
|
||
|
||
1. **展示关键决策点**：功能需求、技术需求各一句话总结
|
||
2. **仍有待确认内容**（步骤 6 自检后发现遗漏）→ 按"提问格式"逐项提问
|
||
3. **无任何待确认内容** → 必须输出最后一问："当前已无更多内容待确认，是否进入下一步"
|
||
|
||
**结束条件**：
|
||
|
||
- 用户**明确肯定**（同意 / 进入下一步）→ 本阶段结束，进入 design
|
||
- 用户选择补充或修改 → 根据反馈调整内容，重跑步骤 6 + 步骤 7
|
||
|
||
## 完成标准
|
||
|
||
- 工作流步骤 1-7 全部走过
|
||
- 步骤 6 自检 8 项全部通过
|
||
- 步骤 7 收到用户明确肯定
|
||
- 所有触发条件命中时都执行了提问流程（事后可被审计）
|
||
|
||
## 规则速查
|
||
|
||
### 阶段职责（强制，适用于整个 code-drive workflow）
|
||
|
||
- 正常流程：requirements 是用户决策入口；design / plan / tasks / apply 自治执行，不发起决策型提问
|
||
- 异常流程：下游无法独立解决时回退上游；apply 生成 blocker.md，由 blocker-revise 决定修订入口
|
||
- 非决策交互仅限读取文件、运行命令、报告回退或 blocker 事实
|
||
requires: []
|
||
- id: design
|
||
generates: design.md
|
||
description: 基于 requirements.md 和必要技术探索的概要技术设计
|
||
template: design.md
|
||
instruction: |
|
||
## 目标
|
||
|
||
撰写 design.md，把 requirements.md 确认的需求**翻译**为概要技术方案——回答"采用什么总体技术方向、关键决策是什么、影响哪些范围"。
|
||
|
||
design.md 的职责是**翻译与补充探索**：基于 requirements.md 已确认的需求和技术方向，补充代码库层面的探索发现，固定为可执行的设计依据。不要在本阶段写详细实现步骤或任务 checkbox；详细实现属于 plan.md，checkbox 只属于 tasks.md。
|
||
|
||
本阶段承接 requirements.md、前序讨论和代码库。文档面向项目开发者。
|
||
|
||
## 输入
|
||
|
||
- requirements.md（必需，作为决策唯一来源）
|
||
- 前序讨论 / 代码库（用于补充探索）
|
||
- 已有 design.md（如存在则增量修订，不重写未变部分）
|
||
|
||
## 工具使用（先决说明）
|
||
|
||
本阶段可用工具：
|
||
|
||
- **todo / plan 工具**：复杂变更必须跟踪到工作流 X.Y 子步骤；简单变更可省略（标准：requirements.md 决策充分、无新增探索、预期 < 100 行文档）
|
||
- **只读工具**：Read / Grep / Glob / Bash 只读命令可用于代码库探索，不视为决策型交互
|
||
- **禁止**：不得使用 question / choice 发起决策型提问；决策型分歧必须走"回退上游流程"
|
||
- **注意**：todo 跟踪文档撰写进度，不跟踪实现进度
|
||
|
||
## 回退上游流程（强制协议，适用于本阶段所有"无法独立解决"环节）
|
||
|
||
本流程是 design 阶段**唯一**的异常出口。design 的默认行为是**自治执行**——AI 自己消化探索发现并写入 design.md，**只在真正无法独立解决时才回流**。回退的成本是打断整个流程让用户重新决策，因此触发条件 reserved 给"AI 真处理不了的高价值错误"，**而不是任何信息增量**。
|
||
|
||
### AI 自决范围（不触发回退，直接处理并写入 design.md）
|
||
|
||
以下情况 AI **自行决策**并落地到 design.md 对应章节，**不**触发回退：
|
||
|
||
- **代码可复用** → 优先复用，记录到"代码库探索/已有代码与模式"
|
||
- **依赖版本细节不符但兼容** → 选兼容方案，记录到"代码库探索/依赖状态"
|
||
- **次要模块需要触碰但不影响核心决策** → 探索后纳入"影响范围"
|
||
- **实现层取舍**（API 设计、数据结构、代码组织、命名）→ AI 给出理由 + 至少一个被否决方案，写入"关键决策"
|
||
- **全局审查发现的非核心边界**（次要配置、文档同步、日志格式）→ 直接补全到"影响范围"或"风险/权衡"
|
||
- **requirements.md 未明确但可从既有代码/项目规范推断** → 按推断方向走，标注"基于代码库规范推断"
|
||
|
||
### 触发条件（命中任一即必须启动回退流程，仅 3 条）
|
||
|
||
1. **核心方向决策真空**——requirements.md 对本次变更的**核心技术方向 / 架构方向 / 业务边界**未给出唯一决策，存在 2 个以上互相排斥且都合理的选择，**且选哪个会导致整体方案有本质差异**（不是细节差异）
|
||
- 不触发示例：API 风格选 REST vs RPC（业务边界已定，纯实现层差异）；选 PostgreSQL vs MySQL（requirements.md 已说明"关系型数据库"且项目无既有约束）
|
||
2. **核心前提错误**——代码库探索发现 requirements.md 的**核心前提**（如"项目已有 X 模块""Y 依赖可用""Z 接口存在"）与事实**不符，且这种不符会让整个方案失效**（必须重新设计才能继续）
|
||
- 不触发示例：依赖版本 v5 vs v6（兼容）；Y 接口存在但参数略不同（AI 适配）；X 模块存在但需要小修改
|
||
3. **必须扩展本次业务范围或引入核心新依赖**——发现要实现 requirements.md 已确认的功能，**必须**做以下之一：
|
||
- (a) **扩展本次变更的业务范围**（如发现功能 A 必须连同功能 B 一起做才合理）
|
||
- (b) **引入 requirements.md 未确认的核心外部依赖**（业务运行依赖，非纯开发/构建工具）
|
||
- 不触发示例：新增开发依赖（lint 插件、类型定义包）；引入项目内已有但未被点名的工具函数
|
||
|
||
### 暂停报告格式（强制）
|
||
|
||
触发回退时，**必须暂停撰写**，按以下格式输出报告，不得在 design.md 中以任何形式保留"待确认/TBD/待讨论"条目：
|
||
|
||
- **触发条件编号 + 命中证据**：明确指出命中了第几条触发条件，附上具体证据（引用 requirements.md 的相关段落或代码库发现），并说明为何不属于"AI 自决范围"
|
||
- **影响的设计章节**：列出哪些章节因此无法继续撰写
|
||
- **回退到哪个 artifact**：明确指向 requirements（默认）或其他上游
|
||
- **需要在回退阶段补充的具体决策点**：列出上游需要补充回答的具体问题，每个问题给出 2-3 个候选选项 + 推荐方案 + 取舍说明（与 requirements 提问格式一致）
|
||
- **本阶段当前进度**：当前已完成到哪个步骤、暂停时正在撰写什么
|
||
|
||
### 强制语义（不得跳过）
|
||
|
||
- 触发条件命中时**必须**启动回退流程，即使你倾向"自己决定"或"假设一个合理默认"
|
||
- **不得**用"等用户回复后再继续"模糊处理——必须明确暂停并报告
|
||
- **不得**在 design.md 中以"待确认""TBD""待讨论""开放问题"形式保留任何条目
|
||
- **反向约束**：未命中触发条件时**不得**主动询问用户——AI 自决范围内的情况一律自决，不得以"为求保险"为由把决策推回用户
|
||
- 用户在 requirements 阶段补充决策后，回到 design 步骤 1 重新评估（不重写已确定章节，但需重跑回退触发条件检查）
|
||
|
||
### 回退归档规则
|
||
|
||
用户在 requirements 阶段补充决策后：
|
||
|
||
1. requirements.md 更新为最新版本，design.md 引用更新后的决策
|
||
2. design 中此前无法继续的章节，按新决策补全
|
||
3. 此前的暂停报告**不得以任何形式保留**在 design.md 中（不设"回退记录"章节）
|
||
4. 新决策若引发新的回退触发条件 → 回到回退流程
|
||
|
||
## 工作流
|
||
|
||
### 步骤 1: 读取上游并评估探索充分性
|
||
|
||
合并"读上游、判断是否需要补充探索"两件事，避免在判断未定时就深入代码库。
|
||
|
||
**子步骤 1.1: 读取 requirements.md 与前序讨论**
|
||
|
||
- 完整读取 requirements.md，识别其中已确认的技术选型、架构方向、集成边界、约束
|
||
- 识别 requirements.md 中已经做过的代码库探索发现（避免重复劳动）
|
||
|
||
**子步骤 1.2: 评估探索充分性**
|
||
|
||
按 3 个判断点逐一检查：
|
||
|
||
- requirements.md 确认了技术选型，是否已检查项目中该依赖的安装状态或版本约束？
|
||
- requirements.md 确认了架构方向，是否已检查现有代码中可复用的组件、工具函数、数据结构、API 模式或架构约定？
|
||
- 需求涉及的模块，是否在 requirements.md 或前序讨论中已被探索过？
|
||
|
||
**子步骤 1.3: 判断是否需要补充探索**
|
||
|
||
- 三项均已充分 → 直接进入步骤 3（跳过步骤 2）
|
||
- 任一项不充分 → 进入步骤 2
|
||
|
||
### 步骤 2: 代码库补充探索（仅当步骤 1.3 判断需要）
|
||
|
||
**子步骤 2.1: 检查依赖状态**
|
||
|
||
- 验证 requirements.md 中确认的技术选型在项目中的实际状态（已安装 / 未安装 / 版本不符）
|
||
- 记录到 design.md "代码库探索 / 依赖状态" 子章节
|
||
|
||
**子步骤 2.2: 检查可复用代码**
|
||
|
||
- 探索现有组件、工具函数、数据结构、API 模式、架构约定
|
||
- 记录到 design.md "代码库探索 / 已有代码与模式" 子章节
|
||
|
||
**子步骤 2.3: 检查项目规范约束**
|
||
|
||
- 探索项目编码规范、命名约定、架构约束、质量门禁
|
||
- 记录到 design.md "代码库探索 / 开发规范约束" 子章节
|
||
|
||
**子步骤 2.4: 检查回退触发条件**
|
||
|
||
- 探索发现 → 先判断是否属于"AI 自决范围"（如可复用代码、依赖兼容、次要模块触碰）；属于则直接落地到对应章节，不触发回退
|
||
- 不属于自决范围 → 检查是否命中触发条件 1/2/3
|
||
- 命中 → 立即**启动回退流程**，暂停本阶段
|
||
- 未命中 → 进入步骤 3
|
||
|
||
### 步骤 3: 撰写初稿
|
||
|
||
按模板的 8 个章节顺序撰写：**代码库探索 / 整体方案 / 目标·非目标 / 关键决策 / 影响范围 / 依赖与约束 / 风险·权衡 / 验证方向**。
|
||
|
||
撰写要求：
|
||
|
||
- **整体方案**：描述模块、组件或流程如何组织和协作，概要说明为什么该方案满足 requirements.md
|
||
- **目标 / 非目标**：目标对齐 requirements.md 的功能需求；非目标明确划界
|
||
- **关键决策**：引用 requirements.md 已确认的决策，仅补充实现层决策（具体 API 设计、数据结构、代码组织方式等）
|
||
- **影响范围**：列出受影响的模块、文件、配置、接口、文档、流程或外部依赖，附"关键实现路径"
|
||
- **依赖与约束**：依赖、兼容性、质量门禁、禁止事项四项必备
|
||
- **风险 / 权衡**：每条风险对应缓解措施
|
||
- **验证方向**：覆盖 requirements.md 的功能验收标准和非功能需求
|
||
|
||
撰写过程中遇到触发条件 1/2/3 时，立即**启动回退流程**；上游补充后继续撰写。注意：实现层取舍属于"AI 自决范围"，直接写入"关键决策"章节即可，不触发回退。
|
||
|
||
简单变更保持精炼；复杂或横切变更必须写足够细节，避免 plan/apply 依赖未写入文档的设计推理。
|
||
|
||
### 步骤 4: 关键决策挑战
|
||
|
||
对初稿做关键决策合理性挑战。
|
||
|
||
**子步骤 4.1: 决策合理性检查**
|
||
|
||
- 每个关键决策是否有理由
|
||
- 每个关键决策是否记录了至少一个被否决方案或主要取舍
|
||
- 不满足 → 补全。注意：取舍的"理由"由 AI 自己给出（属于"AI 自决范围"），不触发回退；**仅当**发现取舍属于"核心方向决策真空"（触发条件 1）才启动回退流程
|
||
|
||
**子步骤 4.2: 回退触发条件复查**
|
||
|
||
- 全文扫描是否在撰写过程中暴露出此前未发现的触发条件 1/2/3
|
||
- 先判断是否属于"AI 自决范围"；不属于再判断是否命中触发条件
|
||
- 命中 → **启动回退流程**
|
||
- 未命中 → 进入步骤 5
|
||
|
||
### 步骤 5: 自检（逐项内联修复，无需二次 review）
|
||
|
||
按以下清单逐项检查，发现问题立即修复后**重跑该项**：
|
||
|
||
- [ ] **占位符扫描**：无模板注释、英文模板句子、TBD、待补充、空表格行或"待确认事项"章节
|
||
- [ ] **需求覆盖**：requirements.md 的每条功能需求都有决策覆盖；技术需求被正确引用或落地
|
||
- [ ] **决策合理性**：每个关键决策有理由，并记录至少一个被否决方案或主要取舍
|
||
- [ ] **代码库现实**：设计基于代码库探索发现，而非从零假设；没有引入 requirements.md 未确认的新依赖
|
||
- [ ] **验证方向对齐**：验证方向覆盖 requirements.md 的功能验收标准和非功能需求
|
||
- [ ] **待确认清零**：全文无"待确认""TBD""待讨论""开放问题"等未决条目
|
||
|
||
自检全部通过 → 本阶段完成；任一项失败 → 修复后从该项重跑，必要时回到步骤 3-4。
|
||
|
||
### 步骤 6: 触发回退（异常路径）
|
||
|
||
此步骤仅在步骤 1-5 中触发回退条件时进入，是**异常出口**而非主线：
|
||
|
||
- 输出**暂停报告**（按"暂停报告格式"执行）
|
||
- 暂停 design 撰写，等待用户回到 requirements 解决
|
||
- 用户补充决策后，从步骤 1 重新评估（不重写已确定章节，但需重跑触发条件检查）
|
||
|
||
## 完成标准
|
||
|
||
- 工作流步骤 1-5 全部走过（步骤 6 是异常路径，正常路径不进入）
|
||
- 步骤 5 自检 6 项全部通过
|
||
- 未触发任何回退条件，或触发的回退已被解决并重新走过工作流
|
||
- design.md 无任何形式的"待确认 / TBD / 待讨论 / 开放问题"
|
||
- 所有触发条件命中时都执行了回退流程（事后可被审计）
|
||
|
||
## 规则速查
|
||
|
||
### 阶段职责（强制，适用于整个 code-drive workflow）
|
||
|
||
- 正常流程：requirements 是用户决策入口；design / plan / tasks / apply 自治执行，不发起决策型提问
|
||
- 异常流程：下游无法独立解决时回退上游；apply 生成 blocker.md，由 blocker-revise 决定修订入口
|
||
- 非决策交互仅限读取文件、运行命令、报告回退或 blocker 事实
|
||
requires:
|
||
- requirements
|
||
- id: plan
|
||
generates: plan.md
|
||
description: 从 design.md 派生的详细实现计划
|
||
template: plan.md
|
||
instruction: |
|
||
## 目标
|
||
|
||
撰写 plan.md，把 design.md 的概要设计**展开**为可独立理解、可验证、可执行的实现阶段——回答"分几个阶段实现、每阶段做什么、如何验证"。
|
||
|
||
plan.md 的职责是**展开与具体化**：把 design.md 的关键决策展开为具体阶段、文件、函数签名、调用流程，使 tasks.md 可以只写 checkbox 而不必重新设计实现方案。不要在本阶段写 checkbox；checkbox 只属于 tasks.md。
|
||
|
||
tasks.md 的分组必须与 plan.md 的阶段一一对应，因此 plan.md 是 apply 阶段理解关键实现细节的主要依据。
|
||
|
||
本阶段承接 requirements.md、design.md。文档面向项目开发者。
|
||
|
||
## 输入
|
||
|
||
- requirements.md（必需，作为需求来源）
|
||
- design.md（必需，作为设计唯一来源）
|
||
- 已有 plan.md（如存在则增量修订，不重写未变部分）
|
||
|
||
## 工具使用（先决说明）
|
||
|
||
本阶段可用工具：
|
||
|
||
- **todo / plan 工具**：复杂变更必须跟踪到工作流 X.Y 子步骤；简单变更可省略（标准：design.md 阶段划分已明确、单文件变更、预期 < 100 行文档）
|
||
- **只读工具**：Read / Grep / Glob / Bash 只读命令可用于核实函数签名、依赖路径、API 契约，不视为决策型交互
|
||
- **禁止**：不得使用 question / choice 发起决策型提问；决策型分歧必须走"回退上游流程"
|
||
- **注意**：todo 跟踪文档撰写进度，不跟踪实现进度
|
||
|
||
## 回退上游流程（强制协议，适用于本阶段所有"无法独立解决"环节）
|
||
|
||
本流程是 plan 阶段**唯一**的异常出口。plan 的默认行为是**自治执行**——AI 自己把 design.md 展开为阶段，**只在真正无法独立解决时才回流**。回退的成本是打断整个流程让上游重新决策，因此触发条件 reserved 给"AI 真处理不了的高价值错误"，**而不是任何信息增量**。
|
||
|
||
### AI 自决范围（不触发回退，直接处理并写入 plan.md）
|
||
|
||
以下情况 AI **自行决策**并落地到 plan.md 对应章节，**不**触发回退：
|
||
|
||
- **阶段划分细节**（design.md 未明确阶段顺序时）→ AI 给出阶段顺序并写明理由，写入"实现概览"
|
||
- **函数/数据结构具体化**（design.md 给出方向但 plan 需要具体签名）→ AI 自决具体签名，写入"关键代码模式"
|
||
- **次要文件归类**（design.md 影响范围列出但未明确归阶段）→ AI 直接归阶段，写入"涉及文件"
|
||
- **验证方式细节**（design.md 验证方向较粗）→ AI 给出具体验证步骤，写入"验证方式"
|
||
- **阶段间依赖关系标注**（阶段间依赖关系）→ AI 自决并标注前置条件
|
||
- **可从 design.md/requirements.md 推断**的细节 → 按推断方向走，标注"基于 design.md/requirements.md 推断"
|
||
- **实现层取舍**（API 风格、命名、错误处理模式）→ AI 给出理由 + 至少一个被否决方案，写入"关键代码模式/约定·模式"
|
||
|
||
### 触发条件（命中任一即必须启动回退流程，仅 3 条）
|
||
|
||
1. **核心实现方向决策真空**——展开 design.md 时发现**核心实现路径**（如阶段边界、关键模块的接入方式、关键数据流的走向）存在 2 个以上互相排斥且都合理的选择，**且选哪个会导致整体阶段划分或文件结构有本质差异**（不是细节差异）
|
||
- 不触发示例：某个函数的参数顺序（实现层）；某个阶段内部步骤的顺序（细节）；新增 vs 复用工具函数（design.md 已暗示方向）
|
||
- 触发示例：design.md 只说"用 ORM 屏蔽数据库差异"但 plan 展开发现需要先重构数据访问层，重构方向有 2 个互斥选项
|
||
2. **核心前提错误**——展开阶段细节时发现 design.md 的**核心设计前提**（如"某接口存在且契约稳定""某依赖 API 满足需求""某模块可独立修改不影响其他"）与代码库事实**不符，且这种不符会让整个实现计划失效**（必须重新设计才能继续）
|
||
- 不触发示例：API 参数略不同（AI 适配）；版本差异但兼容；某模块需要小修改
|
||
- 触发示例：design.md 假设"调用 X 库的 Y 接口"，但展开时发现 Y 接口已被废弃且替代接口契约完全不同
|
||
3. **必须扩展本次业务范围或引入核心新依赖**——发现要落地 design.md 已确认的设计，**必须**做以下之一：
|
||
- (a) **扩展本次变更的业务范围**（如发现某个阶段实际需要重写相邻模块才合理）
|
||
- (b) **引入 design.md 未确认的核心外部依赖**（业务运行依赖，非纯开发/构建工具）
|
||
- 不触发示例：新增开发依赖（lint、类型定义）；引用项目内已有但未被点名的工具函数；新增测试用 mock 库
|
||
|
||
### 暂停报告格式（强制）
|
||
|
||
触发回退时，**必须暂停撰写**，按以下格式输出报告，不得在 plan.md 中以任何形式保留"待确认/TBD/待讨论"条目：
|
||
|
||
- **触发条件编号 + 命中证据**：明确指出命中了第几条触发条件，附上具体证据（引用 design.md / requirements.md 的相关段落或代码库发现），并说明为何不属于"AI 自决范围"
|
||
- **回退到哪个 artifact**：明确指向 design（默认）或 requirements（仅当问题源于需求层决策）
|
||
- **影响 plan.md 哪些阶段或章节**：列出哪些阶段或章节因此无法继续撰写
|
||
- **需要在上游补充的具体决策点**：列出上游需要补充回答的具体问题，每个问题给出 2-3 个候选选项 + 推荐方案 + 取舍说明（与 requirements 提问格式一致）
|
||
- **本阶段当前进度**：当前已完成到哪个步骤、暂停时正在撰写什么
|
||
|
||
### 强制语义（不得跳过）
|
||
|
||
- 触发条件命中时**必须**启动回退流程，即使你倾向"自己决定"或"假设一个合理默认"
|
||
- **不得**用"等用户回复后再继续"模糊处理——必须明确暂停并报告
|
||
- **不得**在 plan.md 中以"待确认""TBD""待讨论""开放问题""待补充"形式保留任何条目
|
||
- **反向约束**：未命中触发条件时**不得**主动询问用户——AI 自决范围内的情况一律自决，不得以"为求保险"为由把决策推回用户
|
||
- 用户在上游补充决策后，回到 plan 步骤 1 重新评估（不重写已确定章节，但需重跑回退触发条件检查）
|
||
|
||
### 回退归档规则
|
||
|
||
用户在 design / requirements 阶段补充决策后：
|
||
|
||
1. 上游 .md 更新为最新版本，plan.md 引用更新后的内容
|
||
2. plan 中此前无法继续的阶段或章节，按新决策补全
|
||
3. 此前的暂停报告**不得以任何形式保留**在 plan.md 中（不设"回退记录"章节）
|
||
4. 新决策若引发新的回退触发条件 → 回到回退流程
|
||
|
||
## 工作流
|
||
|
||
### 步骤 1: 读取上游并评估展开充分性
|
||
|
||
合并"读上游、判断 design 是否够细到可展开"两件事，避免在判断未定时就深入阶段划分。
|
||
|
||
**子步骤 1.1: 读取 requirements.md 与 design.md**
|
||
|
||
- 完整读取 design.md，识别关键决策、影响范围、关键实现路径、验证方向
|
||
- 完整读取 requirements.md，对齐功能需求与非功能需求的验收标准
|
||
|
||
**子步骤 1.2: 评估展开充分性**
|
||
|
||
按 3 个判断点逐一检查：
|
||
|
||
- design.md 的关键决策是否细到可以拆出明确阶段？（如只说"重构数据层"→ 太粗；说"分 3 步：先抽象接口、再实现、再迁移调用方"→ 够细）
|
||
- design.md 的影响范围是否明确到文件级别？
|
||
- design.md 的"关键实现路径"是否给出优先级？
|
||
|
||
**子步骤 1.3: 判断走向**
|
||
|
||
- 三项均已充分 → 进入步骤 2
|
||
- 任一项不充分但属于 AI 自决范围（如阶段顺序推断）→ 标注推断后进入步骤 2
|
||
- 任一项不充分且命中触发条件 1/2/3 → 立即启动回退流程，进入步骤 6
|
||
|
||
### 步骤 2: 阶段划分与"涉及文件"汇总
|
||
|
||
**子步骤 2.1: 划分主要阶段**
|
||
|
||
- 基于 design.md 的"关键实现路径"和"影响范围"识别主要实现阶段
|
||
- 每个阶段必须有明确目标、能独立验证或显式声明前置依赖
|
||
- 阶段顺序按依赖关系排（如先抽象、后实现、再迁移）
|
||
|
||
**子步骤 2.2: 撰写每个阶段的"目标 / 前置条件 / 关联需求"**
|
||
|
||
- 目标：本阶段要完成什么（对齐 design.md 的关键决策）
|
||
- 前置条件：本阶段开始前必须满足什么（依赖哪个前置阶段）；没有则写"无"
|
||
- 关联需求：对齐 requirements.md 的功能编号（如 F1、F2）
|
||
|
||
**子步骤 2.3: 汇总"涉及文件"**
|
||
|
||
- 按阶段列出涉及的核心文件路径、变更类型（新增/修改/删除）
|
||
- 写入 plan.md "涉及文件" 章节（统一表格）
|
||
|
||
**子步骤 2.4: 检查回退触发条件**
|
||
|
||
- 阶段划分过程中是否暴露触发条件 1/2/3？
|
||
- 先判断是否属于"AI 自决范围"；不属于再判断是否命中触发条件
|
||
- 命中 → 启动回退流程；未命中 → 进入步骤 3
|
||
|
||
### 步骤 3: 撰写各阶段细节
|
||
|
||
逐阶段填写"详细实现步骤 / 关键代码模式 / 验证方式 / 验收标准"。
|
||
|
||
**子步骤 3.1: 详细实现步骤**
|
||
|
||
- 写清楚关键文件、函数、数据结构、流程或配置变化
|
||
- **不要使用 checkbox**（checkbox 只属于 tasks.md）
|
||
- 步骤要具体到函数签名级别或调用流程级别，不得只描述"做什么"而不展示"怎么做"
|
||
|
||
**子步骤 3.2: 关键代码模式**
|
||
|
||
- 新增/修改的函数或方法（签名、参数、返回值、核心逻辑）
|
||
- 新增/修改的数据结构（类型定义、字段、约束）
|
||
- 调用顺序/流程（关键调用链、异步流程、状态转换）
|
||
- 约定/模式（命名规范、错误处理模式、日志规范）
|
||
- 没有则写"无"
|
||
|
||
**子步骤 3.3: 验证方式 + 验收标准**
|
||
|
||
- 验证方式：本阶段如何独立验证（自动化测试/手动检查/具体步骤）
|
||
- 验收标准：本阶段完成的可验证标准，对齐 requirements.md 验收标准
|
||
|
||
撰写过程中遇到触发条件 1/2/3 时，立即启动回退流程；上游补充后继续撰写。注意：函数签名、数据结构、命名等实现层取舍属于"AI 自决范围"，直接写入对应章节即可，不触发回退。
|
||
|
||
### 步骤 4: 撰写全局章节
|
||
|
||
**子步骤 4.1: 实现概览**
|
||
|
||
- 概述实现阶段、依赖顺序，以及各阶段如何对应 requirements.md 和 design.md
|
||
|
||
**子步骤 4.2: 验证策略**
|
||
|
||
- 汇总各阶段验证方式 + 整体验证
|
||
- 把 design.md 的"验证方向"作为输入，确保验证角度对齐
|
||
|
||
**子步骤 4.3: 回退/兼容性说明**
|
||
|
||
- 回退策略 / 错误处理 / 兼容性 / 迁移注意事项；没有则写"无"
|
||
|
||
**子步骤 4.4: 检查回退触发条件**
|
||
|
||
- 全文撰写完成后是否暴露此前未发现的触发条件 1/2/3？
|
||
- 先判断是否属于"AI 自决范围"；不属于再判断是否命中触发条件
|
||
- 命中 → 启动回退流程；未命中 → 进入步骤 5
|
||
|
||
### 步骤 5: 自检（逐项内联修复，无需二次 review）
|
||
|
||
按以下清单逐项检查，发现问题立即修复后**重跑该项**：
|
||
|
||
- [ ] **design 覆盖**：design.md 的每个关键决策在 plan.md 中都有实现路径；影响范围的所有项都被某个阶段覆盖
|
||
- [ ] **阶段独立性**：每个阶段能独立验证，或明确说明依赖哪个前置阶段
|
||
- [ ] **占位符扫描**：详细实现步骤和关键代码模式无含糊；以下都属于占位符，必须用具体内容替换：
|
||
- "TBD"、"TODO"、"待补充"、"implement later"、"fill in details"
|
||
- "添加适当的错误处理"、"add validation"、"handle edge cases"（没有具体策略）
|
||
- "类似阶段 N"、"Similar to Task N"（必须重复写出实际内容）
|
||
- 只描述做什么不展示怎么做的步骤（代码步骤必须有具体函数签名、数据结构或调用流程）
|
||
- 引用任何阶段都未定义的函数、类型或方法名
|
||
- [ ] **类型一致性**：后续阶段引用的函数名、参数、类型签名与前置阶段定义的匹配
|
||
- [ ] **验证闭环**：每个阶段的验证方式能独立确认该阶段完成；design.md 的"验证方向"在"验证策略"中有体现
|
||
- [ ] **待确认清零**：全文无"待确认""TBD""待讨论""待补充""开放问题"等未决条目
|
||
|
||
自检全部通过 → 本阶段完成；任一项失败 → 修复后从该项重跑，必要时回到步骤 3-4。
|
||
|
||
### 步骤 6: 触发回退（异常路径）
|
||
|
||
此步骤仅在步骤 1-5 中触发回退条件时进入，是**异常出口**而非主线：
|
||
|
||
- 输出**暂停报告**（按"暂停报告格式"执行）
|
||
- 暂停 plan 撰写，等待用户回到上游解决
|
||
- 用户补充决策后，从步骤 1 重新评估（不重写已确定章节，但需重跑触发条件检查）
|
||
|
||
## 完成标准
|
||
|
||
- 工作流步骤 1-5 全部走过（步骤 6 是异常路径，正常路径不进入）
|
||
- 步骤 5 自检 6 项全部通过
|
||
- 未触发任何回退条件，或触发的回退已被解决并重新走过工作流
|
||
- plan.md 无任何形式的"待确认 / TBD / 待讨论 / 待补充 / 开放问题"
|
||
- 所有触发条件命中时都执行了回退流程（事后可被审计）
|
||
|
||
## 规则速查
|
||
|
||
### 阶段职责（强制，适用于整个 code-drive workflow）
|
||
|
||
- 正常流程：requirements 是用户决策入口；design / plan / tasks / apply 自治执行，不发起决策型提问
|
||
- 异常流程：下游无法独立解决时回退上游；apply 生成 blocker.md，由 blocker-revise 决定修订入口
|
||
- 非决策交互仅限读取文件、运行命令、报告回退或 blocker 事实
|
||
requires:
|
||
- requirements
|
||
- design
|
||
- id: tasks
|
||
generates: tasks.md
|
||
description: 从 plan.md 派生的可跟踪执行清单
|
||
template: tasks.md
|
||
instruction: |
|
||
## 目标
|
||
|
||
撰写 tasks.md，把 plan.md 的实现阶段**拆解**为 OpenSpec apply 可跟踪的 checkbox 任务清单——回答"每个阶段具体做哪几个动作、按什么顺序、何时验证"。
|
||
|
||
tasks.md 的职责是**拆解为可执行动作**：每个任务是单个文件、单个函数或单个可验证行为级别的具体动作，apply 阶段据此执行并跟踪进度。**不要在本阶段重新发明实现方案**——需要关键实现细节时引用 plan.md。
|
||
|
||
本阶段承接 requirements.md、design.md、plan.md。文档面向项目开发者和 apply 阶段的 AI 执行者。
|
||
|
||
## 输入
|
||
|
||
- requirements.md（必需，作为验收标准来源）
|
||
- design.md（必需，作为关键决策来源）
|
||
- plan.md（**主要依据**，作为阶段划分和实现细节来源）
|
||
- 已有 tasks.md（如存在则增量修订，不重写未变部分）
|
||
|
||
## 工具使用（先决说明）
|
||
|
||
本阶段可用工具：
|
||
|
||
- **todo / plan 工具**：复杂变更必须跟踪到工作流 X.Y 子步骤；简单变更可省略（标准：plan.md 阶段数 ≤ 2、单文件变更、预期 < 50 行文档）
|
||
- **只读工具**：Read / Grep / Glob / Bash 只读命令可用于核实文件路径、函数签名、命令是否可执行，不视为决策型交互
|
||
- **禁止**：不得使用 question / choice 发起决策型提问；决策型分歧必须走"回退上游流程"
|
||
- **注意**：todo 跟踪文档撰写进度，不跟踪实现进度
|
||
|
||
## 回退上游流程（强制协议，适用于本阶段所有"无法独立解决"环节）
|
||
|
||
本流程是 tasks 阶段**唯一**的异常出口。tasks 的默认行为是**自治执行**——plan.md 已经把决策做完，AI 只需把决策拆为 checkbox，**只在真正无法独立解决时才回流**。回退的成本是打断整个流程让上游重新决策，因此触发条件 reserved 给"AI 真处理不了的高价值错误"，**而不是任何信息增量**。
|
||
|
||
### AI 自决范围（不触发回退，直接处理并写入 tasks.md，范围最广）
|
||
|
||
以下情况 AI **自行决策**并落地到 tasks.md，**不**触发回退：
|
||
|
||
- **任务拆分粒度**（每阶段 3-6 任务如何分布）→ AI 自决
|
||
- **任务描述措辞**（动词 + 文件路径 + 具体动作）→ AI 自决
|
||
- **测试穿插位置**（哪个验证任务放在哪个阶段）→ AI 自决
|
||
- **阶段内任务的依赖顺序**→ AI 自决
|
||
- **任务编号 X.Y**（X 跟随 plan 阶段编号）→ AI 自决
|
||
- **plan.md 未给出明确函数签名但暗示了方向**→ AI 推断具体动作，描述写"基于 plan 阶段 N 推断"
|
||
- **"验证与收尾"分组的具体条目数**（3-6 条之间调整）→ AI 自决
|
||
- **plan.md 的实现步骤较粗但可拆**（如 plan 说"添加参数校验"→ AI 拆为"定义校验 schema"+"接入到入口函数"+"补单元测试"）→ AI 自决
|
||
- **plan.md 阶段命名需要细化**（如 plan 阶段名过于宽泛时，tasks 分组标题可加补充限定）→ AI 自决
|
||
|
||
### 触发条件（命中任一即必须启动回退流程，仅 3 条，比 plan 阶段更严）
|
||
|
||
1. **plan.md 核心实现路径完全缺失**——某个 plan 阶段完全没有"详细实现步骤"或"关键代码模式"，AI 无法从中拆出任何具体动作，**且该阶段是本次变更的核心**（不是次要阶段、非验证收尾阶段）
|
||
- 不触发：plan 阶段描述较粗但可推断（属于 AI 自决）；次要阶段（如纯文档更新）；plan 给出方向但细节较粗
|
||
- 触发：plan 的核心阶段只写"实现 X 模块"没有任何路径细节，AI 无法拆出任何具体动作
|
||
2. **核心前提错误**——plan.md 假设的**核心接口、函数或数据结构**与代码库事实不符，且这种不符会让整个阶段的任务无法执行（必须重新设计阶段实现路径才能继续）
|
||
- 不触发：函数签名略不同（AI 适配）；版本差异但兼容；某文件路径需要小调整
|
||
- 触发：plan 假设"调用 X 库的 Y 接口"，但拆任务时发现 Y 接口已被废弃且替代接口契约完全不同
|
||
3. **必须扩展本次业务范围或引入核心新依赖**——执行 plan 阶段时发现需要扩展本次变更的业务范围，或引入 plan.md 未确认的核心外部依赖（业务运行依赖，非纯开发/构建工具）
|
||
- 不触发：新增开发依赖（lint、类型定义）；引用项目内已有但未被点名的工具函数；新增测试用 mock 库
|
||
|
||
### 暂停报告格式（强制）
|
||
|
||
触发回退时，**必须暂停撰写**，按以下格式输出报告，不得在 tasks.md 中以任何形式保留"待确认/TBD/待讨论"条目：
|
||
|
||
- **触发条件编号 + 命中证据**：明确指出命中了第几条触发条件，附上具体证据（引用 plan.md 的相关段落或代码库发现），并说明为何不属于"AI 自决范围"
|
||
- **回退到哪个 artifact**：明确指向 plan（默认）或 design/requirements（仅当问题源于更上游）
|
||
- **影响 tasks.md 哪些分组或任务**：列出哪些分组因此无法继续撰写
|
||
- **需要在上游补充的具体决策点**：列出上游需要补充回答的具体问题，每个问题给出 2-3 个候选选项 + 推荐方案 + 取舍说明（与 requirements 提问格式一致）
|
||
- **本阶段当前进度**：当前已完成到哪个步骤、暂停时正在撰写哪个分组
|
||
|
||
### 强制语义（不得跳过）
|
||
|
||
- 触发条件命中时**必须**启动回退流程，即使你倾向"硬拆任务"或"先做能拆的部分"
|
||
- **不得**用"等用户回复后再继续"模糊处理——必须明确暂停并报告
|
||
- **不得**在 tasks.md 中以"待确认""TBD""待讨论""开放问题""待补充"形式保留任何条目
|
||
- **反向约束**：未命中触发条件时**不得**主动询问用户——AI 自决范围内的情况一律自决，不得以"为求保险"为由把决策推回用户
|
||
- 用户在上游补充决策后，回到 tasks 步骤 1 重新评估（不重写已确定分组，但需重跑回退触发条件检查）
|
||
|
||
### 回退归档规则
|
||
|
||
用户在上游补充决策后：
|
||
|
||
1. 上游 .md 更新为最新版本，tasks.md 引用更新后的内容
|
||
2. tasks 中此前无法继续的分组，按新决策补全
|
||
3. 此前的暂停报告**不得以任何形式保留**在 tasks.md 中（不设"回退记录"章节）
|
||
4. 新决策若引发新的回退触发条件 → 回到回退流程
|
||
|
||
## 工作流
|
||
|
||
### 步骤 1: 读取上游并评估可拆分性
|
||
|
||
合并"读上游、判断 plan 是否够细到可拆任务"两件事。
|
||
|
||
**子步骤 1.1: 读取 plan.md（主要依据）**
|
||
|
||
- 完整读取 plan.md，识别阶段划分、每阶段的"详细实现步骤"和"关键代码模式"
|
||
- 对齐 requirements.md 的验收标准和 design.md 的关键决策（避免拆解时偏离）
|
||
|
||
**子步骤 1.2: 评估可拆分性**
|
||
|
||
按 3 个判断点逐一检查每个 plan 阶段：
|
||
|
||
- 该阶段是否有足够细节让你拆出 3-6 个具体动作（每个动作能落到单文件、单函数或单可验证行为级别）？
|
||
- 该阶段的"详细实现步骤"和"关键代码模式"是否覆盖了该阶段要做的事？
|
||
- 该阶段的"验收标准"是否能转化为 1-2 个验证任务？
|
||
|
||
**子步骤 1.3: 判断走向**
|
||
|
||
- 所有阶段均可拆 → 进入步骤 2
|
||
- 某个阶段较粗但属于 AI 自决范围（如实现步骤较粗但可拆）→ 标注推断后进入步骤 2
|
||
- 某个阶段命中触发条件 1/2/3 → 立即启动回退流程，进入步骤 5
|
||
|
||
### 步骤 2: 拆分各 plan 阶段任务
|
||
|
||
逐阶段处理。每个 plan 阶段生成一个 `## X. <分组标题>` 任务分组。
|
||
|
||
**子步骤 2.1: 建立分组对应**
|
||
|
||
- 每个 plan.md 阶段必须有一个对应的 `##` 编号任务分组
|
||
- 分组编号 X 与 plan 阶段编号一致
|
||
- 分组标题应与 plan.md 阶段名称一致或明显对应（plan 阶段名过于宽泛时可加补充限定）
|
||
|
||
**子步骤 2.2: 拆分动作任务（3-6 个/阶段）**
|
||
|
||
- 每个阶段拆解为 3-6 个具体动作任务（不含"阅读 plan.md"的元任务）
|
||
- 每个任务 MUST 是单行 checkbox：`- [ ] X.Y 任务描述`
|
||
- 任务描述格式：动词 + 文件/模块 + 具体动作（如"修改 src/auth.ts 的 login 函数，添加参数校验"）
|
||
- 粒度控制在**单个文件、单个函数或单个可验证行为**级别
|
||
- 按依赖顺序排；可并行任务也明确前置条件
|
||
- 任务粒度控制在"能在单个会话内完成、完成标准明确"
|
||
|
||
**子步骤 2.3: 穿插验证任务**
|
||
|
||
- 每个阶段必须有至少 1 个验证任务（运行测试、手动检查或具体验证命令）
|
||
- 验证任务穿插在阶段内（紧跟关键实现任务之后），**不要**全部集中到最后
|
||
- 阶段最后一个任务建议是"按 plan.md 阶段 N 的验收标准确认阶段完成"
|
||
|
||
**子步骤 2.4: 元任务（每阶段第一条）**
|
||
|
||
- 每个分组的第一条任务建议是"阅读 plan.md 阶段 N，确认涉及文件、关键代码模式和验收标准"
|
||
- 这是给 apply 阶段的"加载上下文"提示，不是实际执行任务
|
||
|
||
**子步骤 2.5: 检查回退触发条件**
|
||
|
||
- 拆分过程中是否暴露触发条件 1/2/3？
|
||
- 先判断是否属于"AI 自决范围"；不属于再判断是否命中触发条件
|
||
- 命中 → 启动回退流程；未命中 → 进入步骤 3
|
||
|
||
### 步骤 3: 撰写"验证与收尾"分组
|
||
|
||
最后一个分组**必须是**"验证与收尾"（编号紧接前一阶段 +1）。
|
||
|
||
**子步骤 3.1: 必需条目**
|
||
|
||
至少包含以下条目（具体可调整数量）：
|
||
|
||
- 阅读 plan.md 验证策略，确认所有验证项已执行
|
||
- 执行完整测试套件，确认无回归
|
||
- 逐项对照 requirements.md 验收标准，确认全部满足
|
||
- 检查 design.md 关键决策是否被正确实现
|
||
|
||
**子步骤 3.2: 可选条目（按需添加）**
|
||
|
||
- 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档或交接说明
|
||
- 检查依赖与约束章节，确认无遗漏
|
||
- 确认所有任务已标记为 `[x]`，未完成或阻塞事项已记录
|
||
|
||
**子步骤 3.3: 检查回退触发条件**
|
||
|
||
- 撰写收尾分组时是否暴露此前未发现的触发条件 1/2/3？
|
||
- 先判断是否属于"AI 自决范围"；不属于再判断是否命中触发条件
|
||
- 命中 → 启动回退流程；未命中 → 进入步骤 4
|
||
|
||
### 步骤 4: 自检（逐项内联修复，无需二次 review）
|
||
|
||
按以下清单逐项检查，发现问题立即修复后**重跑该项**：
|
||
|
||
- [ ] **checkbox 格式**：每个任务都是 `- [ ] X.Y 任务描述` 单行格式；apply 阶段会解析此格式，**未使用 `- [ ]` 的任务不会被跟踪**
|
||
- [ ] **分组对应**：每个 plan.md 阶段都有对应的 `##` 分组；分组编号与 plan 阶段编号一致
|
||
- [ ] **占位符扫描**：无模板注释（`<!-- ... -->`）、英文模板任务、"待补充""TBD""TODO"或占位任务文本；所有任务描述都是具体动作
|
||
- [ ] **粒度合理**：每阶段 3-6 个具体动作任务；每个任务落到单文件/单函数/单可验证行为级别
|
||
- [ ] **测试穿插**：每阶段至少 1 个验证任务，穿插在阶段内而非全部集中到最后
|
||
- [ ] **plan 覆盖**：plan.md 每个阶段的"详细实现步骤"和"关键代码模式"都被拆到任务里；plan 的"验证策略"被收尾分组覆盖
|
||
- [ ] **依赖顺序**：任务按依赖顺序排；可并行任务明确前置条件
|
||
- [ ] **待确认清零**：全文无"待确认""TBD""待讨论""待补充""开放问题"等未决条目
|
||
|
||
自检全部通过 → 本阶段完成；任一项失败 → 修复后从该项重跑，必要时回到步骤 2-3。
|
||
|
||
### 步骤 5: 触发回退（异常路径）
|
||
|
||
此步骤仅在步骤 1-4 中触发回退条件时进入，是**异常出口**而非主线：
|
||
|
||
- 输出**暂停报告**（按"暂停报告格式"执行）
|
||
- 暂停 tasks 撰写，等待用户回到上游解决
|
||
- 用户补充决策后，从步骤 1 重新评估（不重写已确定分组，但需重跑触发条件检查）
|
||
|
||
## 完成标准
|
||
|
||
- 工作流步骤 1-4 全部走过（步骤 5 是异常路径，正常路径不进入）
|
||
- 步骤 4 自检 8 项全部通过
|
||
- 未触发任何回退条件，或触发的回退已被解决并重新走过工作流
|
||
- tasks.md 无任何形式的"待确认 / TBD / 待讨论 / 待补充 / 开放问题 / 模板注释"
|
||
- 所有 checkbox 都是 `- [ ] X.Y 任务描述` 格式（apply 可跟踪）
|
||
- 所有触发条件命中时都执行了回退流程（事后可被审计）
|
||
|
||
## 规则速查
|
||
|
||
### 阶段职责（强制，适用于整个 code-drive workflow）
|
||
|
||
- 正常流程：requirements 是用户决策入口；design / plan / tasks / apply 自治执行，不发起决策型提问
|
||
- 异常流程：下游无法独立解决时回退上游；apply 生成 blocker.md，由 blocker-revise 决定修订入口
|
||
- 非决策交互仅限读取文件、运行命令、报告回退或 blocker 事实
|
||
requires:
|
||
- requirements
|
||
- design
|
||
- plan
|
||
apply:
|
||
requires:
|
||
- requirements
|
||
- design
|
||
- plan
|
||
- tasks
|
||
tracks: tasks.md
|
||
instruction: |
|
||
## 目标
|
||
|
||
按 tasks.md 的 checkbox 顺序**执行变更**——逐项实现任务、收集验证证据、标记完成状态，使本次变更落到代码库中并可被审计。
|
||
|
||
apply 的职责是**执行而非设计**：所有实现路径、函数签名、依赖选择、阶段划分都已在 plan.md / design.md / requirements.md 中确定；apply 只负责把这些设计转化为代码、测试、配置或文档的实际变更。**不要在本阶段重新决策实现方向**——遇到决策型分歧必须走 blocker 机制。
|
||
|
||
本阶段承接 requirements.md / design.md / plan.md / tasks.md（4 份 fact 来源）+ 项目代码库。
|
||
|
||
## 输入
|
||
|
||
- requirements.md（需求/范围/验收/全局审查的事实来源）
|
||
- design.md（技术方向/关键决策的事实来源）
|
||
- plan.md（实现计划/关键代码模式的事实来源）
|
||
- tasks.md（执行进度的事实来源；apply 跟踪其 checkbox）
|
||
- openspec/config.yaml 及 workflow context（项目约束）
|
||
- 项目代码库（实际变更对象）
|
||
|
||
## 工具使用（先决说明）
|
||
|
||
本阶段可用工具：
|
||
|
||
- **todo / plan 工具**：必须跟踪执行进度；每个未完成任务标记为 in_progress 或 pending，完成后标记 completed，并同步回 tasks.md checkbox
|
||
- **subagent / task 派发工具**：用于并行执行独立任务（详见步骤 4）
|
||
- **读写工具**：Read / Edit / Write / Grep / Glob / Bash 是主要工具
|
||
- **禁止**：不得使用 question / choice 发起决策型提问；决策型分歧必须走 blocker 机制
|
||
- **注意**：todo 跟踪实际执行进度，不同于上游文档撰写进度
|
||
|
||
## Blocker 机制（强制协议，适用于本阶段所有"无法独立解决"环节）
|
||
|
||
本机制是 apply 阶段**唯一**的异常出口。apply 的默认行为是**按计划执行**——只在真正无法独立解决时才生成 blocker.md 中断流程。生成 blocker 的成本是中断整个变更流程让用户介入修订上游，因此触发条件 reserved 给"AI 真处理不了的高价值错误"，**而不是任何信息增量**。
|
||
|
||
### AI 自决范围（不触发 blocker，直接处理并落地到代码）
|
||
|
||
以下情况 AI **自行决策**并落地到代码实现，**不**触发 blocker：
|
||
|
||
- **函数体内部实现**（plan.md 给出签名但未给出具体逻辑）→ AI 自决具体实现代码
|
||
- **次要 bug 修复**（执行过程中发现非核心 bug）→ 顺手修复，在 PR 描述或 commit 信息中说明
|
||
- **命名/格式/注释调整**（plan.md 未限定时）→ AI 自决
|
||
- **测试用例具体数据**（plan.md 给出测试方向但未给数据）→ AI 自决具体测试数据
|
||
- **错误消息措辞**（plan.md 未限定时）→ AI 自决
|
||
- **依赖路径或导入顺序调整**（兼容范围内）→ AI 自决
|
||
- **plan.md 阶段内步骤的微调**（不改变阶段目标或文件归属）→ AI 自决
|
||
- **可从 design.md/requirements.md/既有代码规范推断**的细节 → 按推断方向走
|
||
|
||
### 触发条件（命中任一即必须生成 blocker.md，仅 3 条）
|
||
|
||
1. **核心实现路径不可行**——执行过程中发现 plan.md 的核心实现路径（核心模块的接入方式、关键数据流、关键算法）在代码库中**无法落地**，且没有可推断的替代路径
|
||
- 不触发：函数签名略不同（AI 适配）；某 API 调用方式略不同（AI 适配）；某依赖版本差异但兼容
|
||
- 触发：plan 假设"通过 X 库的 Y 接口实现"，但 Y 接口不存在且替代接口契约差异巨大；plan 的核心算法在目标语言中无法实现
|
||
2. **核心前提错误**——执行过程中发现 requirements.md/design.md/plan.md 的核心假设（"某接口存在且稳定""某依赖满足需求""某模块可独立修改"）与代码库事实不符，**且这种不符会让整个变更方向失效**
|
||
- 不触发：API 参数略不同；模块需要小修改；版本差异兼容
|
||
- 触发：design 假设的核心抽象在重构后已不存在；plan 假设的核心数据结构已被替换
|
||
3. **必须扩展本次业务范围或引入核心新依赖**——执行过程中发现要落地已确认的设计，**必须**做以下之一：
|
||
- (a) **扩展本次变更的业务范围**（如发现某个核心模块实际需要重写相邻模块才合理）
|
||
- (b) **引入 plan.md/design.md/requirements.md 未确认的核心外部依赖**（业务运行依赖，非纯开发/构建工具）
|
||
- 不触发：新增开发依赖（lint、类型定义）；引用项目内已有但未被点名的工具函数；新增测试用 mock 库
|
||
|
||
### Blocker 触发动作（强制）
|
||
|
||
触发 blocker 时，**必须暂停执行**，在当前 change 目录生成 blocker.md：
|
||
|
||
- 按 `openspec/schemas/code-drive/templates/blocker.md` 模板结构填写
|
||
- 模板要求的具体章节、字段和填写规范由模板本身和 `openspec/schemas/code-drive/prompts/blocker-revise.md` 定义
|
||
- **apply 阶段不重新发明 blocker.md 的结构**
|
||
|
||
生成 blocker.md 后，明确告诉用户：
|
||
|
||
> 阻塞已记录在 blocker.md。请读取并执行 `openspec/schemas/code-drive/prompts/blocker-revise.md` 中的修订流程。修订完成后可重新运行 apply，已完成的 checkbox 任务会被跳过。
|
||
|
||
### 强制语义（不得跳过）
|
||
|
||
- 触发条件命中时**必须**生成 blocker.md，即使你倾向"先做完能做的"或"假设一个合理默认"
|
||
- **不得**用"等用户回复后再继续"模糊处理——必须明确暂停并生成 blocker.md
|
||
- **不得**在 tasks.md 或代码注释中以"待确认""TBD""待讨论""开放问题"形式保留任何条目
|
||
- **反向约束**：未命中触发条件时**不得**主动询问用户——AI 自决范围内的情况一律自决，不得以"为求保险"为由把决策推回用户
|
||
- 用户通过 blocker-revise 解决阻塞后，apply 从中断点继续（已完成的 checkbox 会被跳过）
|
||
|
||
### Blocker 归档规则
|
||
|
||
用户通过 blocker-revise 解决阻塞后：
|
||
|
||
1. 上游 .md 更新为最新版本（按 blocker-revise 指引）
|
||
2. apply 重新读取上游，从中断点继续；如有任务编号或描述变更，先同步 tasks.md
|
||
3. blocker.md 文件本身**保留**作为审计记录，但不得在任何 artifact 中引用其内容作为决策依据
|
||
4. 新决策若引发新的 blocker 触发条件 → 回到 blocker 流程
|
||
|
||
## 工作流
|
||
|
||
### 步骤 1: 加载上下文
|
||
|
||
**子步骤 1.1: 阅读上游 4 份 artifact**
|
||
|
||
按顺序读取：requirements.md → design.md → plan.md → tasks.md。
|
||
|
||
**子步骤 1.2: 阅读项目 context**
|
||
|
||
读取 openspec/config.yaml 及 workflow context；按 artifacts 引用读取相关项目或 workflow 文档。
|
||
|
||
**子步骤 1.3: 建立 fact 来源映射**
|
||
|
||
明确以下映射（后续步骤遇到分歧时按此优先级判断）：
|
||
|
||
- 需求 / 范围 / 验收 / 全局审查 → requirements.md
|
||
- 技术方向 / 关键决策 → design.md
|
||
- 实现计划 / 关键代码模式 → plan.md
|
||
- 执行进度 / 任务依赖顺序 → tasks.md
|
||
|
||
### 步骤 2: 规划执行
|
||
|
||
**子步骤 2.1: 扫描 tasks.md**
|
||
|
||
- 识别所有未完成的 `- [ ]` 任务
|
||
- 按依赖顺序排序（tasks.md 已给出依赖关系）
|
||
- 识别可并行任务（属于不同 plan.md 阶段或同阶段内明确独立的工作单元）
|
||
|
||
**子步骤 2.2: 建立 todo 列表**
|
||
|
||
- 每个未完成任务对应一个 todo item
|
||
- todo 顺序与 tasks.md 一致
|
||
- 复杂任务可拆为多个 todo item（颗粒度由 AI 自决）
|
||
|
||
**子步骤 2.3: 检查 blocker 触发条件**
|
||
|
||
- 扫描阶段是否暴露触发条件 1/2/3？
|
||
- 先判断是否属于"AI 自决范围"；不属于再判断是否命中触发条件
|
||
- 命中 → 启动 blocker 流程；未命中 → 进入步骤 3
|
||
|
||
### 步骤 3: 逐任务执行（核心循环）
|
||
|
||
对每个未完成任务循环执行子步骤 3.1-3.5。
|
||
|
||
**子步骤 3.1: 加载任务上下文**
|
||
|
||
- 读取该任务在 tasks.md 中的描述
|
||
- 读取 plan.md 对应阶段的"涉及文件""关键代码模式""验收标准"
|
||
- **不要只凭 tasks.md 的短描述自行设计实现方案**
|
||
|
||
**子步骤 3.2: 执行实现**
|
||
|
||
- 按 plan.md 的关键代码模式实现（修改代码、新增文件、调整配置等）
|
||
- 实现 layer 取舍（命名、错误处理、内部逻辑）属于 AI 自决范围
|
||
- 涉及决策型分歧 → 检查触发条件 1/2/3
|
||
|
||
**子步骤 3.3: 收集验证证据**
|
||
|
||
- 运行 plan.md 该阶段"验证方式"指定的命令（测试、构建、lint、手动检查）
|
||
- 必须用**实际命令输出、测试结果或可观察行为**作为证据
|
||
- 完成声明禁用模糊措辞：不得用"应该""大概""看起来"作为完成依据
|
||
|
||
**子步骤 3.4: 标记完成（仅在有证据时）**
|
||
|
||
- 任务执行完成且**获得新的实际验证证据**后，才能将 tasks.md 中对应行标记为 `[x]`
|
||
- 不得基于假设、推测或"应该可以"标记完成
|
||
- 同步更新 todo 工具状态为 completed
|
||
|
||
**子步骤 3.5: 检查 blocker 触发条件**
|
||
|
||
- 本任务执行过程中是否暴露触发条件 1/2/3？
|
||
- 先判断是否属于"AI 自决范围"；不属于再判断是否命中触发条件
|
||
- 命中 → 立即启动 blocker 流程（暂停后续任务）；未命中 → 进入下一个任务
|
||
|
||
### 步骤 4: 并行执行（如可用）
|
||
|
||
仅在工具支持 subagent / task 派发时启用。
|
||
|
||
**子步骤 4.1: 识别可并行任务**
|
||
|
||
满足以下**全部**条件的任务可并行：
|
||
|
||
- 与已派发或正在执行的任务没有文件依赖
|
||
- 不依赖前置任务的输出或运行时副作用
|
||
- 属于不同 plan.md 阶段或同阶段内明确独立的工作单元
|
||
|
||
**子步骤 4.2: 派发 subagent**
|
||
|
||
每个 subagent 完成后必须返回：
|
||
|
||
- 执行结果摘要
|
||
- 变更文件列表
|
||
- 验证证据（命令输出或测试结果）
|
||
|
||
**子步骤 4.3: 合并结果**
|
||
|
||
主 agent 负责：
|
||
|
||
- 合并 subagent 结果
|
||
- 更新 tasks.md checkbox（**不让 subagent 直接写 tasks.md**）
|
||
- 处理冲突（如不同 subagent 改了同一文件的不同部分）
|
||
|
||
**子步骤 4.4: subagent 不可用时**
|
||
|
||
退化为串行执行（步骤 3），不影响正确性。
|
||
|
||
### 步骤 5: 触发 blocker（异常路径）
|
||
|
||
此步骤仅在步骤 2-4 中触发 blocker 条件时进入，是**异常出口**而非主线：
|
||
|
||
- 生成 blocker.md（按"Blocker 触发动作"执行）
|
||
- 暂停执行，等待用户运行 blocker-revise
|
||
- 用户解决阻塞后，apply 从中断点继续
|
||
|
||
### 步骤 6: 完成确认（最后一个任务后）
|
||
|
||
**子步骤 6.1: 扫描完成状态**
|
||
|
||
- tasks.md 中所有任务都是 `[x]`
|
||
- todo 工具中所有 item 都是 completed
|
||
- 最后一个"验证与收尾"分组的所有验证任务都已通过
|
||
|
||
**子步骤 6.2: 最终一致性检查**
|
||
|
||
- 任意任务中产生的 blocker.md 是否已通过 blocker-revise 解决
|
||
- 任意任务中残留的"待确认""TBD""待讨论"是否已清零
|
||
|
||
**子步骤 6.3: 输出完成报告**
|
||
|
||
简要总结：
|
||
|
||
- 完成任务总数
|
||
- 变更文件列表
|
||
- 验证证据汇总（关键测试输出 / lint 结果）
|
||
- 是否产生过 blocker.md（如有，记录解决路径）
|
||
|
||
## 完成标准
|
||
|
||
- tasks.md 中所有任务都已标记为 `[x]`
|
||
- 所有任务都有实际验证证据（命令输出 / 测试结果 / 可观察行为）
|
||
- 未触发任何 blocker 条件，或触发的 blocker 已通过 blocker-revise 解决并继续执行
|
||
- 代码库 / tasks.md / 任何文件中无"待确认 / TBD / 待讨论 / 待补充 / 开放问题"残留
|
||
- 所有触发条件命中时都生成了 blocker.md（事后可被审计）
|
||
- 输出了完成报告
|
||
|
||
## 规则速查
|
||
|
||
### 阶段职责（强制，适用于整个 code-drive workflow）
|
||
|
||
- 正常流程：requirements 是用户决策入口；design / plan / tasks / apply 自治执行，不发起决策型提问
|
||
- 异常流程：下游无法独立解决时回退上游；apply 生成 blocker.md，由 blocker-revise 决定修订入口
|
||
- 非决策交互仅限读取文件、运行命令、报告回退或 blocker 事实
|