diff --git a/.lintstagedrc.json b/.lintstagedrc.json index a745ba9..c400868 100644 --- a/.lintstagedrc.json +++ b/.lintstagedrc.json @@ -1,4 +1,5 @@ { "*.{ts,tsx,js,jsx}": ["oxlint --fix", "oxfmt"], - "*.{md,json,yaml,yml}": ["oxfmt"] + "*.{md,json,yaml,yml}": ["oxfmt"], + "!openspec/**": [] } diff --git a/openspec/schemas/code-drive/prompts/blocker-revise.md b/openspec/schemas/code-drive/prompts/blocker-revise.md index b939e58..94f5e6e 100644 --- a/openspec/schemas/code-drive/prompts/blocker-revise.md +++ b/openspec/schemas/code-drive/prompts/blocker-revise.md @@ -2,6 +2,12 @@ 当 OpenSpec `code-drive` 的 apply 阶段生成 `blocker.md` 并暂停时，按照本提示词修订规划 artifacts。目标是修正不成立的部分，而不是强行继续实现。 +## 目标 + +读取 `blocker.md` 及上下游 artifacts，识别阻塞本质，定位最上游的修订入口，通过用户决策流程选定修订方向，按 code-drive 各 artifact 的 instruction 逐层修订受影响的部分，最终让 apply 可以从修订后的待办任务继续。 + +本提示词是 code-drive 中除 requirements 之外**唯一允许向用户发起决策型提问**的入口，决策能力受"用户决策流程（强制协议）"约束。 + ## 输入 - 当前 OpenSpec change 目录 @@ -11,89 +17,179 @@ - `plan.md` - `tasks.md` - `openspec/schemas/code-drive/schema.yaml`（用于读取各 artifact 的 instruction） +- `openspec/schemas/code-drive/templates/*.md`（用于读取各 artifact 的模板结构） + +## 工具使用（先决说明） + +- **todo 工具**：用于跟踪步骤 5/6/7 内的子步骤进度；子步骤颗粒度（如 5.1 / 5.2 / 5.3）直接对应 todo 条目；todo 只是过程跟踪，最终事实必须写回对应 artifact 文件 +- **question / choice 工具**：触发用户决策流程时必须优先使用（如工具支持），按"用户决策格式（强制）"组织候选与说明 +- **读写工具**：本提示词需要写入多个 artifact，但写入前必须先读取对应 artifact 的当前内容；禁止凭印象重写 +- **只读探索工具**：用于步骤 2 的代码库调查（仅在阻塞点涉及未被探索过的代码时使用） + +## 用户决策流程（强制协议） + +本协议是 blocker-revise 阶段的**唯一决策出口**。任何超出"修订执行细节"层级的方向选择必须走本协议，不得 AI 自决。 + +### 触发条件（命中即必须启动） + +1. **核心修订方向存在多种可行路径**：blocker.md 列出的可选方案 ≥ 2 个，或 AI 补充的方案与原方案构成真正的取舍（不是同一思路的两种写法） +2. **blocker.md 建议的修订方向会扩展本次业务范围或引入核心新依赖**：与原 requirements / design 不一致，必须显式征得用户同意 +3. **修订入口在不同 artifact 之间犹豫**：例如 blocker 表面指向 plan，但根因可能在 design 或 requirements，需要用户判断修订起点 +4. **blocker.md 未列出可选方案，仅描述了阻塞现象**：AI 必须主动补充 2-3 个候选方向并请用户选择 + +未命中以上任何条件时，**不得**主动发起决策型提问；AI 自决范围参见下文。 + +### AI 自决范围（无需启动用户决策流程） + +以下类型的修订属于执行细节，AI 自决后直接执行，无需启动用户决策流程： + +1. **执行步骤的局部调整**：plan.md 阶段内步骤的拆分、合并、重排 +2. **任务粒度细化或合并**：tasks.md checkbox 的拆分/合并，但不删除整个分组 +3. **描述措辞修正**：澄清歧义、补充缺失细节、修正笔误 +4. **已完成任务的保留决策**：阻塞未证明无效时，已完成 checkbox 必须保留 +5. **修订记录的措辞与格式**：blocker.md 末尾的修订记录按本提示词模板填写 +6. **工具使用顺序**：todo / 读写工具的使用顺序与时机 + +### 用户决策格式（强制） + +每次启动用户决策流程时，输出必须包含： + +1. **2-3 个候选选项**：每个选项含义明确，避免"方案 A / 方案 B"这类无信息标签 +2. **推荐方案**：AI 必须明确推荐其中一项，不得回避或"中立呈现" +3. **取舍说明**： + - 每个非推荐方案：说明未选它的核心理由（一句话即可） + - 推荐方案：说明选择它的核心理由 + 主要代价 +4. **影响范围预测**（blocker-revise 特有）：每个选项预测将影响哪些 artifact 需要修订，并粗估修订量（小改 / 中改 / 重写章节） +5. **使用工具**：优先使用 question/choice 工具；工具不可用时以 markdown 形式直接呈现 + +### 强制语义（不得跳过） + +- 触发条件命中时**必须**启动用户决策流程，即使你倾向"自己决定"或"按 blocker.md 建议执行" +- 即使用户回复"你看着办"，也必须回复"推荐方案 + 主要代价"，请用户**显式确认**推荐方案，不得默认接受"你看着办"作为决策 +- 决策方向涉及扩展本次业务范围或引入核心新依赖时（触发条件 2），必须**额外显式提示**"本选项将扩展本次范围 / 引入新依赖"，并征得用户的明确同意（不接受默认） +- 用户未决策前**不得**进入步骤 5 的实际修订 + +### 决策归档规则 + +用户给出决策后： + +1. **决策结论融入对应 artifact 的相关章节**——不设独立的"决策记录"章节 +2. **在 `blocker.md` 末尾追加"修订记录"段**：记录选择方案、选择理由、修改的 artifacts 列表、被取消勾选的 tasks——这是审计线索，不是二次决策入口 +3. **决策引发的修订如果触及 requirements / design 的关键决策**，按各 artifact instruction 中"决策归档规则"融入对应章节 +4. **决策结论应可在 apply 恢复后直接使用**——明确到 apply 阶段无需重新发起决策 ## 工作流 -### 1. 阅读并理解阻塞 +### 步骤 1: 阅读并理解阻塞 阅读 `blocker.md`，识别： -- 阻塞点的本质（不是症状） +- 阻塞点的**本质**（不是症状） - 当前位置：任务编号、`plan.md` 阶段、相关文件 - 已尝试的方案及失败原因（避免重复） -- `blocker.md` 建议的修订目标 +- `blocker.md` 建议的修订目标（如有） -### 2. 影响分析 +完成本步骤后进入步骤 2。 + +### 步骤 2: 影响分析 根据 `blocker.md` 的影响范围，系统分析上下游影响链： -- 如果 `requirements.md` 需要修订：检查 `design.md` 的哪些决策依赖它，再检查 `plan.md` 的哪些阶段受影响，最后检查 `tasks.md` 的哪些 checkbox 需要取消 -- 如果 `design.md` 需要修订：检查 `plan.md` 的哪些阶段依赖它，再检查 `tasks.md` 的哪些 checkbox 需要取消 -- 如果 `plan.md` 需要修订：检查 `tasks.md` 的哪些 checkbox 依赖它，以及是否有下游阶段依赖被阻塞阶段的输出 -- 如果 `tasks.md` 需要修订：只影响当前任务及其直接依赖 +- 如果 `requirements.md` 需要修订 → 检查 `design.md` 的哪些决策依赖它，再检查 `plan.md` 的哪些阶段受影响，最后检查 `tasks.md` 的哪些 checkbox 需要取消 +- 如果 `design.md` 需要修订 → 检查 `plan.md` 的哪些阶段依赖它，再检查 `tasks.md` 的哪些 checkbox 需要取消 +- 如果 `plan.md` 需要修订 → 检查 `tasks.md` 的哪些 checkbox 依赖它，以及是否有下游阶段依赖被阻塞阶段的输出 +- 如果 `tasks.md` 需要修订 → 只影响当前任务及其直接依赖 -记录每个 artifact 的影响程度：必须修订 / 可能受影响 / 无影响。 +记录每个 artifact 的影响程度：**必须修订 / 可能受影响 / 无影响**。 -### 3. 确定修订入口 +如阻塞点涉及未被探索过的代码模块，使用只读探索工具补充上下文；否则不发起额外探索。 -根据影响分析，确定需要修订的最上游 artifact： +完成本步骤后进入步骤 3。 -- 如果需要修订 `requirements.md`：从 requirements 开始，依次修订 design、plan、tasks -- 如果需要修订 `design.md`：从 design 开始，依次修订 plan、tasks -- 如果需要修订 `plan.md`：从 plan 开始，修订 tasks -- 如果只需要修订 `tasks.md`：只修订 tasks +### 步骤 3: 确定修订入口 -### 4. 用户决策 +根据影响分析，确定需要修订的**最上游** artifact： -让用户从 `blocker.md` 中列出的可选方案中选择。如果选项不足，提出 2-3 个方案并说明取舍。工具支持时优先使用 question/choice 工具。 +- 需要修订 `requirements.md` → 从 requirements 开始，依次修订 design、plan、tasks +- 需要修订 `design.md` → 从 design 开始，依次修订 plan、tasks +- 需要修订 `plan.md` → 从 plan 开始，修订 tasks +- 只需要修订 `tasks.md` → 只修订 tasks -### 5. 执行修订 +如果"修订入口在不同 artifact 之间犹豫"（触发条件 3），先暂停并启动用户决策流程；用户决策后回到本步骤。 -从修订入口开始，按正常 code-drive 流程逐层修订下游 artifacts。 +完成本步骤后进入步骤 4。 -每个 artifact 的修订必须遵循该 artifact 的 instruction 和 template： +### 步骤 4: 用户决策 + +检查是否命中"用户决策流程（强制协议）"中任一触发条件： + +- **命中** → 按强制格式输出候选 + 推荐 + 取舍 + 影响范围预测，等待用户决策 +- **未命中** → 直接进入步骤 5（属于 AI 自决范围） + +用户决策后或确认无需决策后，进入步骤 5。 + +### 步骤 5: 执行修订 + +从步骤 3 确定的修订入口开始，按 code-drive 正常流程逐层修订下游 artifacts。 + +**子步骤 5.1: 读取 instruction 与 template** + +对每个待修订的 artifact： 1. 读取 `schema.yaml` 中该 artifact 的 `instruction` 2. 读取该 artifact 的 `template` -3. 按 instruction 的工作规则和必需章节进行修订 -4. 确保修订后的 artifact 符合 template 结构 +3. 后续修订必须遵循 instruction 工作流和 template 结构 -修订范围原则： +**子步骤 5.2: 局部修订** + +按修订范围原则执行： - 只改错误的部分，不重写整个章节（除非整个章节的基础假设不成立） - 改了 `plan.md` 阶段的实现步骤时，同步更新 `tasks.md` 对应 checkbox 的描述 - 改了 `design.md` 的关键决策时，检查 `plan.md` 的代码模式是否需要同步，但不自动重写 - 改了 `requirements.md` 时，逐层向下检查影响，每层只改受影响的部分 -- 如果修订导致 `tasks.md` 分组结构变化，重新对齐 plan -> tasks 映射 +- 如果修订导致 `tasks.md` 分组结构变化，重新对齐 plan → tasks 映射 -保留已完成任务： +**子步骤 5.3: 保留已完成任务** -- 已完成且不受阻塞影响的 tasks：保留 checkbox -- 已完成但被阻塞证明无效的 tasks：取消 checkbox，并在修订记录中说明原因 -- 未完成的 tasks：根据修订结果更新描述或删除 -- 如果阶段需要拆分：在 `plan.md` 中新增阶段，将已完成部分和待完成部分分开 +按以下规则处理 tasks.md 中已完成任务： -### 6. 修订后验证 +- 已完成且**不受**阻塞影响的 tasks → 保留 checkbox +- 已完成但被阻塞证明**无效**的 tasks → 取消 checkbox，并在修订记录中说明原因 +- 未完成的 tasks → 根据修订结果更新描述或删除 +- 如果阶段需要拆分 → 在 `plan.md` 中新增阶段，将已完成部分和待完成部分分开 -每个被修订的 artifact 完成后，执行以下一致性检查： +完成本步骤后进入步骤 6。 -Instruction 合规性： +### 步骤 6: 修订后验证 -- 每个被修订的 artifact 是否符合其 instruction 中的工作规则 -- 每个被修订的 artifact 是否包含其 instruction 中要求的必需章节 +每个被修订的 artifact 完成后，按两层一致性检查。 + +**子步骤 6.1: Instruction 合规性检查** + +- 每个被修订的 artifact 是否符合其 instruction 中的工作流和完成标准 +- 每个被修订的 artifact 是否包含其 instruction / template 要求的章节 - 每个被修订的 artifact 是否符合其 template 结构 -上下游一致性： +**子步骤 6.2: 上下游一致性检查** -- 需求覆盖：`requirements.md` 的每条需求是否仍有 `design.md` 决策覆盖 -- 决策落地：`design.md` 的每个关键决策是否在 `plan.md` 中有实现路径 -- 阶段覆盖：`plan.md` 的每个阶段是否在 `tasks.md` 中有对应分组 -- 任务可追溯：`tasks.md` 的每个 checkbox 是否能回溯到 `plan.md` 的某个阶段 -- 验证闭环：`design.md` 的“验证方向”是否在 `plan.md` 的“验证策略”中有体现 +- **需求覆盖**：`requirements.md` 的每条需求是否仍有 `design.md` 决策覆盖 +- **决策落地**：`design.md` 的每个关键决策是否在 `plan.md` 中有实现路径 +- **阶段覆盖**：`plan.md` 的每个阶段是否在 `tasks.md` 中有对应分组 +- **任务可追溯**：`tasks.md` 的每个 checkbox 是否能回溯到 `plan.md` 的某个阶段 +- **验证闭环**：`design.md` 的"验证方向"是否在 `plan.md` 的"验证策略"中有体现 -### 7. 处理 blocker.md +任一项失败 → 回到步骤 5 局部修复，修复后从该项重跑。 -在 `blocker.md` 末尾追加“修订记录”： +全部通过后进入步骤 7。 + +### 步骤 7: 处理 blocker.md + +按以下子步骤追加修订记录并归档。 + +**子步骤 7.1: 追加修订记录** + +在 `blocker.md` 末尾追加： ```markdown ## 修订记录 @@ -107,26 +203,32 @@ Instruction 合规性： - X.Y：取消原因 ``` +**子步骤 7.2: 保留或归档** + 按项目约定保留或归档 `blocker.md`（建议保留作为审计线索）。 -### 8. 完成 +完成本步骤后进入步骤 8。 + +### 步骤 8: 完成 告诉用户重新运行 `/opsx:apply `；apply 应跳过已完成 checkbox 并从修订后的待办任务继续。 -## 规则 +## 完成标准 -- 除非用户明确要求，不要在使用本提示词时实现代码；本提示词只负责修订规划 artifacts。 -- 不要默认重写全部 artifacts，只修订解决阻塞所需的最小上游点及其下游影响。 -- 不要未经用户确认新增需求、依赖、架构方向或范围。 -- 不要取消已完成任务的勾选，除非阻塞证明该已完成工作不正确。 -- 每个被修订的 artifact 必须遵循其 instruction 和 template，即使只是局部修订。 -- 如果工具支持，使用 todo/plan 工具跟踪修订流程，但最终事实必须写回 artifacts。 +- 工作流步骤 1-8 全部走过 +- 步骤 6 的 instruction 合规性 + 上下游一致性全部通过 +- `blocker.md` 已追加修订记录，并被保留或归档 +- 选定的修订方向已记录在受影响 artifact 中 +- 每个被修订的 artifact 符合其 instruction 的工作流和 template 结构 +- 已完成任务的 checkbox 被保留，除非明确失效 +- 所有触发条件命中时都执行了用户决策流程（事后可被审计） +- 用户知道需要重新运行 apply 继续实现 -## 完成检查 +## 规则速查 -- `blocker.md` 已追加修订记录，并被保留或归档。 -- 选定的修订方向已记录在受影响 artifact 中。 -- 每个被修订的 artifact 符合其 instruction 的工作规则和必需章节。 -- 下游 artifacts 与修订后的上游内容一致。 -- 已完成任务的 checkbox 被保留，除非明确失效。 -- 用户知道需要重新运行 apply 继续实现。 +- 本提示词只负责**修订规划 artifacts**，除非用户明确要求，不要在本提示词中实现代码 +- **最小修订**：只修订解决阻塞所需的最小上游点及其下游影响，不要默认重写全部 artifacts +- **不得擅自扩展**：未经用户确认不得新增需求、依赖、架构方向或范围 +- **已完成任务保护**：不要取消已完成任务的勾选，除非阻塞证明该已完成工作不正确 +- **遵循各 artifact 自身的 instruction**：每个被修订的 artifact 必须遵循其 instruction 和 template，即使只是局部修订 +- **todo 跟踪修订流程**：如果工具支持，使用 todo/plan 工具跟踪修订流程，但最终事实必须写回 artifacts diff --git a/openspec/schemas/code-drive/schema.yaml b/openspec/schemas/code-drive/schema.yaml index 147d00c..ba4e325 100644 --- a/openspec/schemas/code-drive/schema.yaml +++ b/openspec/schemas/code-drive/schema.yaml @@ -7,97 +7,395 @@ artifacts: description: 需求确认与澄清，包含业务需求、技术需求和全局审查 template: requirements.md instruction: | - 创建 requirements.md，作为本次变更“要解决什么、为什么要解决、需要确认哪些业务和技术边界”的事实来源。 + ## 目标 - 本阶段用于承接 explore、前序讨论、用户请求和代码库调查结果。requirements.md 面向项目开发者，而不是外部需求方；因此本阶段既要确认业务需求，也要确认技术需求，例如技术选型、架构方向、集成边界、代码约束和验收方式。 + 撰写 requirements.md，把"要解决什么、为什么、需要用户决策哪些业务和技术边界"固定为事实来源。 - requirements.md 的职责是“确认和澄清”：通过对话把需求、边界、取舍和用户决策固定下来。design.md 的职责是“翻译”：把 requirements.md 中确认的内容转化为可执行的技术方案。不要在 requirements.md 展开详细实现步骤、具体文件修改清单或任务 checkbox。 + requirements.md 的职责是**确认和澄清**：通过对话把需求、边界、取舍和用户决策固定下来。design.md 负责把它们**翻译**为可执行方案——不要在 requirements 展开详细实现步骤、具体文件修改清单或任务 checkbox。 - 语言规则（强制）： + 本阶段承接 explore、前序讨论、用户请求和代码库调查结果。文档面向项目开发者（而非外部需求方），因此既要确认业务需求，也要确认技术需求：技术选型、架构方向、集成边界、代码约束、验收方式。 - - code-drive 的 requirements.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 - - 最终 requirements.md 不得残留英文模板句子、英文占位内容、空表格行或未解决的模板注释，除非该英文是必要技术名词 + ## 输入 - 工作规则： + - explore / 前序讨论 / 用户原始请求 / 代码库调查结果 + - 已有 requirements.md（如存在则增量修订，不重写未变部分） - - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），复杂变更必须使用它跟踪 requirements.md 的撰写流程（读取上下文、评估范围、提问、全局审查、编写、自检、用户确认），避免遗漏；简单变更可不使用。注意：这里跟踪的是文档撰写进度，不是整体变更的实现进度——整体变更进度由 apply 阶段和 tasks.md checkbox 跟踪 - - 面向看不到早期对话的人编写，必须保留关键上下文、用户偏好、已确认结论、约束和被否决方案 - - 先读取相关上下文并形成初步理解，再向用户提问；不要询问代码库或文档中已经能确认的信息 - - 先评估范围：如果变更涉及多个独立子系统或过大范围，先建议拆解，再对第一个子问题继续澄清 - - 复杂问题必须拆成多个小问题逐步确认；简单问题可以合并确认，但不得一次抛出大量无关问题 - - 优先使用 2-3 个选项 + 推荐方案 + 取舍说明来提问，而不是让用户从零开放回答；如果工具支持，优先使用 question/choice 工具 - - 对每个需求进行 YAGNI 挑战：是否真的需要、能否更简单、是否存在更轻量替代方案、是否超出本次范围 - - 分段呈现理解并逐段确认；复杂内容每段控制在约 200-300 字，确认后再继续下一段 - - 必须进行“全局审查”：从系统边界、既有行为、相邻模块、配置、文档、迁移、兼容性、安全、性能和用户流程角度挑战当前需求 - - 功能需求必须带验收标准；非功能需求只记录本次变更相关内容 - - 技术需求必须记录已确认的技术选型、架构方向、集成边界、代码约束或禁止事项；未确认的技术选项放入开放问题，不要擅自定论 - - 待解决问题必须区分阻塞 apply 的问题和非阻塞后续问题；阻塞性开放问题最多 3 个，超过时必须先与用户决策或建议拆分变更；没有问题时写“无” - - 不要写具体文件修改步骤、代码结构、任务 checkbox 或详细实现计划 + ## 工具使用（先决说明） - 必需章节（建议使用模板中的中文章节标题）：背景与目标、讨论记录、功能需求、非功能需求、技术需求、全局审查、开放问题。 + 本阶段开始前必须确认可用工具，并在整个工作流中按以下规则使用： + + - **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 依赖未写入文档的聊天上下文。 - 写完后自检（逐项检查并内联修复，无需二次 review）： + ### 步骤 3: 全局审查 + YAGNI 挑战 - - 占位符扫描：是否残留模板注释、英文模板句子、TBD、待补充或空表格行 - - 章节完整性：所有必需章节都已填写；功能需求、非功能需求和技术需求没有明显遗漏 - - 上下文一致性：讨论记录中的“已确认结论”都已落入对应章节；被否决方案没有被复用 - - 全局审查充分性：系统边界、既有行为、相邻模块、配置、迁移、兼容性都被审视过 - - YAGNI：每条需求都经过挑战，没有“未来可能需要但本次不必需”的功能 - - 范围合适：变更聚焦到能用单一 design.md 承接，还是需要拆分为多个子变更 + 对初稿做两个角度的挑战，发现的问题立即纳入步骤 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 负责回答“采用什么总体技术方向、关键决策是什么、影响哪些范围”。不要在本阶段写详细实现步骤或任务 checkbox；详细实现属于 plan.md，checkbox 只属于 tasks.md。 + 撰写 design.md，把 requirements.md 确认的需求**翻译**为概要技术方案——回答"采用什么总体技术方向、关键决策是什么、影响哪些范围"。 - 语言规则（强制）： + design.md 的职责是**翻译与补充探索**：基于 requirements.md 已确认的需求和技术方向，补充代码库层面的探索发现，固定为可执行的设计依据。不要在本阶段写详细实现步骤或任务 checkbox；详细实现属于 plan.md，checkbox 只属于 tasks.md。 - - code-drive 的 design.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 - - 最终 design.md 不得残留英文模板句子、英文占位内容、空表格行或未解决的模板注释 + 本阶段承接 requirements.md、前序讨论和代码库。文档面向项目开发者。 - 在编写 design.md 之前，先确认 requirements.md 和前序讨论中是否已有足够的技术探索结果。如果已有，直接引用，不重复探索；只补充 requirements.md 未覆盖的部分。 + ## 输入 - 补充探索的触发条件（满足任一即可）： + - requirements.md（必需，作为决策唯一来源） + - 前序讨论 / 代码库（用于补充探索） + - 已有 design.md（如存在则增量修订，不重写未变部分） - - requirements.md 确认了技术选型，但未检查项目中该依赖的安装状态或版本约束 - - requirements.md 确认了架构方向，但未检查现有代码中是否有可复用的组件、工具函数、数据结构、API 模式或架构约定 - - 需求涉及的模块在 requirements.md 或前序讨论中未被探索过 - - 用户在 design 阶段提出了新的技术问题 + ## 工具使用（先决说明） - 探索深度根据变更规模和既有探索充分度调整： + 本阶段可用工具： - - 简单变更且 requirements.md 已有充分探索：快速确认即可，无需详细重复记录 - - 复杂变更或 requirements.md 探索不足：详细检查依赖、现有代码、项目规范，并记录发现 + - **todo / plan 工具**：复杂变更必须跟踪到工作流 X.Y 子步骤；简单变更可省略（标准：requirements.md 决策充分、无新增探索、预期 < 100 行文档） + - **只读工具**：Read / Grep / Glob / Bash 只读命令可用于代码库探索，不视为决策型交互 + - **禁止**：不得使用 question / choice 发起决策型提问；决策型分歧必须走"回退上游流程" + - **注意**：todo 跟踪文档撰写进度，不跟踪实现进度 - 探索结果记录在 design.md 的“代码库探索”章节。如果探索发现与 requirements.md 的假设冲突，暂停并告知用户。 + ## 回退上游流程（强制协议，适用于本阶段所有"无法独立解决"环节） - 工作规则： + 本流程是 design 阶段**唯一**的异常出口。design 的默认行为是**自治执行**——AI 自己消化探索发现并写入 design.md，**只在真正无法独立解决时才回流**。回退的成本是打断整个流程让用户重新决策，因此触发条件 reserved 给"AI 真处理不了的高价值错误"，**而不是任何信息增量**。 - - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），复杂变更必须使用它跟踪 design.md 的撰写流程（读取 requirements、代码库探索、编写各章节、自检），避免遗漏；简单变更可不使用。注意：这里跟踪的是文档撰写进度，不是整体变更的实现进度 - - 对关键技术决策给出理由，并记录至少一个被否决方案或主要取舍 - - 如果存在多个合理技术方向，先向用户呈现 2-3 个方案、适用条件和风险；如果工具支持，优先使用 question/choice 工具收敛决策 - - 明确目标、非目标、影响范围、依赖约束、风险权衡和待确认事项 - - 如果 requirements.md 仍有阻塞性开放问题，不要猜测答案；暂停并请求用户决策 - - 设计必须基于代码库现实，而非从零假设；如果探索发现现有代码可复用，优先复用而非新建 - - 不要引入 requirements.md 未确认的新需求、外部依赖或架构方向；不要引入 requirements.md 未确认且代码库中不存在的新依赖，除非有充分理由并经用户确认 + ### AI 自决范围（不触发回退，直接处理并写入 design.md） - 必需章节（建议使用模板中的中文章节标题）：代码库探索、整体方案、目标 / 非目标、关键决策、影响范围、依赖与约束、风险 / 权衡、验证方向、待确认事项。 + 以下情况 AI **自行决策**并落地到 design.md 对应章节，**不**触发回退： - 写完后自检（逐项检查并内联修复，无需二次 review）： + - **代码可复用** → 优先复用，记录到"代码库探索/已有代码与模式" + - **依赖版本细节不符但兼容** → 选兼容方案，记录到"代码库探索/依赖状态" + - **次要模块需要触碰但不影响核心决策** → 探索后纳入"影响范围" + - **实现层取舍**（API 设计、数据结构、代码组织、命名）→ AI 给出理由 + 至少一个被否决方案，写入"关键决策" + - **全局审查发现的非核心边界**（次要配置、文档同步、日志格式）→ 直接补全到"影响范围"或"风险/权衡" + - **requirements.md 未明确但可从既有代码/项目规范推断** → 按推断方向走，标注"基于代码库规范推断" - - 占位符扫描：是否残留模板注释、英文占位内容或空表格行 - - 需求覆盖：requirements.md 的每条功能需求都有决策覆盖；技术需求被正确引用或落地 - - 决策合理性：每个关键决策有理由，并记录至少一个被否决方案或主要取舍 - - 代码库现实：设计基于代码库探索发现，而非从零假设；没有引入 requirements.md 未确认的新依赖 - - 验证方向对齐：验证方向覆盖了 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 @@ -105,40 +403,224 @@ artifacts: description: 从 design.md 派生的详细实现计划 template: plan.md instruction: | - 创建 plan.md，作为本次变更的详细实现计划。先阅读 requirements.md 和 design.md。 + ## 目标 - plan.md 负责把概要设计转化为可独立理解、可验证、可执行的实现阶段。tasks.md 的分组必须与 plan.md 的阶段一一对应，因此 plan.md 是 apply 阶段理解关键实现细节的主要依据。 + 撰写 plan.md，把 design.md 的概要设计**展开**为可独立理解、可验证、可执行的实现阶段——回答"分几个阶段实现、每阶段做什么、如何验证"。 - 语言规则（强制）： + plan.md 的职责是**展开与具体化**：把 design.md 的关键决策展开为具体阶段、文件、函数签名、调用流程，使 tasks.md 可以只写 checkbox 而不必重新设计实现方案。不要在本阶段写 checkbox；checkbox 只属于 tasks.md。 - - code-drive 的 plan.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 - - 最终 plan.md 不得残留英文模板句子、英文占位内容、空表格行或未解决的模板注释 + tasks.md 的分组必须与 plan.md 的阶段一一对应，因此 plan.md 是 apply 阶段理解关键实现细节的主要依据。 - 工作规则： + 本阶段承接 requirements.md、design.md。文档面向项目开发者。 - - 按主要实现阶段组织，每个阶段必须包含目标、前置条件、详细实现步骤、关键代码模式、验证方式、验收标准和关联需求 - - 每个阶段必须列出涉及的文件路径、变更类型，汇总到“涉及文件”章节 - - 将 design.md 的“验证方向”作为“验证策略”的输入，确保验证角度对齐 - - 阶段应足够清晰，使后续 tasks.md 可以只写 checkbox 任务，而不必重新设计实现方案 - - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），复杂变更必须使用它跟踪 plan.md 的撰写流程（读取上游、编写实现概览、编写各阶段、编写验证策略、自检），避免遗漏；简单变更可不使用。注意：这里跟踪的是文档撰写进度，不是整体变更的实现进度 - - 每个阶段应能独立验证，或明确说明依赖哪个前置阶段 - - 不要写 checkbox；不要新增未经 design.md 确认的架构、依赖或范围 - - 如果 design.md 太粗、关键决策缺失或与 requirements.md 冲突，先暂停并要求修订上游 artifact + ## 输入 - 必需章节：实现概览、涉及文件、阶段 1..N、验证策略、回退 / 兼容性说明、待确认事项。 + - requirements.md（必需，作为需求来源） + - design.md（必需，作为设计唯一来源） + - 已有 plan.md（如存在则增量修订，不重写未变部分） - 写完后自检（逐项检查并内联修复，无需二次 review）： + ## 工具使用（先决说明） - - design 覆盖：design.md 的每个关键决策在 plan.md 中都有实现路径；影响范围的所有项都被某个阶段覆盖 - - 阶段独立性：每个阶段能独立验证，或明确说明依赖哪个前置阶段 - - 占位符扫描：检查详细实现步骤和关键代码模式是否含糊；以下都属于占位符，必须用具体内容替换： - - “TBD”、“TODO”、“待补充”、“implement later”、“fill in details” - - “添加适当的错误处理”、“add validation”、“handle edge cases”（没有具体策略） - - “类似阶段 N”、“Similar to Task N”（必须重复写出实际内容） + 本阶段可用工具： + + - **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 的“验证方向”在“验证策略”中有体现 + - [ ] **类型一致性**：后续阶段引用的函数名、参数、类型签名与前置阶段定义的匹配 + - [ ] **验证闭环**：每个阶段的验证方式能独立确认该阶段完成；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 @@ -147,31 +629,211 @@ artifacts: description: 从 plan.md 派生的可跟踪执行清单 template: tasks.md instruction: | - 创建 tasks.md，将 plan.md 拆解为 OpenSpec apply 可跟踪的 checkbox 任务。 + ## 目标 - **重要：必须遵守以下模板中的 checkbox 行格式。** apply 阶段会解析 checkbox 格式跟踪进度。未使用 `- [ ]` 的任务不会被跟踪。 + 撰写 tasks.md，把 plan.md 的实现阶段**拆解**为 OpenSpec apply 可跟踪的 checkbox 任务清单——回答"每个阶段具体做哪几个动作、按什么顺序、何时验证"。 - 语言规则（强制）： + tasks.md 的职责是**拆解为可执行动作**：每个任务是单个文件、单个函数或单个可验证行为级别的具体动作，apply 阶段据此执行并跟踪进度。**不要在本阶段重新发明实现方案**——需要关键实现细节时引用 plan.md。 - - code-drive 的 tasks.md 使用中文分组标题和中文任务描述；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 - - 每个可跟踪任务必须保留 OpenSpec CLI 可解析的单行 checkbox 格式，例如 `- [ ] 1.1 任务描述` 或 `- [x] 1.1 已完成任务描述` - - 最终 tasks.md 不得残留英文模板任务、英文占位内容、空分组或占位任务文本 + 本阶段承接 requirements.md、design.md、plan.md。文档面向项目开发者和 apply 阶段的 AI 执行者。 - 编写规则： + ## 输入 - - 任务必须从 requirements.md、design.md 和 plan.md 派生，其中 plan.md 是任务分组和关键实现细节的主要依据 - - 每个 plan.md 阶段必须有一个对应的 `##` 编号任务分组，分组标题应与 plan.md 阶段名称一致或明显对应 + - 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 任务描述` - - 任务描述可以保持简洁灵活，但必须指向具体动作，并在必要时引用 plan.md 的阶段或小节 - - 每个阶段应拆解为 3-6 个具体动作任务（不含阅读 plan.md 的元任务），粒度控制在单个文件、单个函数或单个可验证行为级别 - - 测试验证任务应穿插在各阶段内，而非仅在最后统一验证 - - 任务描述格式建议：动词 + 文件/模块 + 具体动作（如“修改 src/auth.ts 的 login 函数，添加参数校验”） - - 任务粒度应足够小，能在一个会话内完成，并且完成标准明确 - - 按依赖顺序排序；可并行任务也要明确前置条件 - - 必须包含验证与收尾分组，覆盖 plan.md 的验证策略、必要文档更新和人工验收 - - 如果 plan.md 过粗、不可验证或与上游 artifact 冲突，不要硬拆 tasks；先暂停并要求修订 plan.md + - 任务描述格式：动词 + 文件/模块 + 具体动作（如"修改 src/auth.ts 的 login 函数，添加参数校验"） + - 粒度控制在**单个文件、单个函数或单个可验证行为**级别 + - 按依赖顺序排；可并行任务也明确前置条件 + - 任务粒度控制在"能在单个会话内完成、完成标准明确" - 不要在 tasks.md 重新发明实现方案。需要关键实现细节时，引用 plan.md。 + **子步骤 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 @@ -184,48 +846,242 @@ apply: - tasks tracks: tasks.md instruction: | - 先按顺序阅读 requirements.md、design.md、plan.md，再阅读 tasks.md。 - 同时遵守 workflow context/configuration，例如存在时读取 openspec/config.yaml，以及 artifacts 引用的相关项目或 workflow 文档。 + ## 目标 - 将 requirements.md 视为需求、范围、验收和全局审查的事实来源；将 design.md 视为概要技术方向和关键决策的事实来源；将 plan.md 视为详细实现计划和关键代码模式的事实来源；将 tasks.md 视为执行进度的事实来源。 + 按 tasks.md 的 checkbox 顺序**执行变更**——逐项实现任务、收集验证证据、标记完成状态，使本次变更落到代码库中并可被审计。 - 执行规则： + apply 的职责是**执行而非设计**：所有实现路径、函数签名、依赖选择、阶段划分都已在 plan.md / design.md / requirements.md 中确定；apply 只负责把这些设计转化为代码、测试、配置或文档的实际变更。**不要在本阶段重新决策实现方向**——遇到决策型分歧必须走 blocker 机制。 - - 按 tasks.md 的依赖顺序处理未完成 checkbox 任务 - - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），必须使用它跟踪当前执行进度：每个未完成任务标记为 in_progress 或 pending，完成后标记为 completed；最终完成状态必须同步回 tasks.md checkbox - - 每个任务执行前，先读取 plan.md 对应阶段的“涉及文件”“关键代码模式”和“验收标准”，再开始实现；不要只凭 tasks.md 的短描述自行设计实现方案 - - 不要引入 plan.md 未描述的实现路径、依赖、架构或范围；如确需偏离，先暂停并请求用户确认 - - 只有任务执行完成且获得新的实际验证证据后，才能标记 `[x]`；不得基于假设、推测或“应该可以”标记完成 - - 完成声明禁用模糊措辞：不得用“应该”、“大概”、“看起来”作为完成依据；必须用实际命令输出、测试结果或可观察行为作为证据 - - 如果 tasks.md 与 plan.md 冲突，以暂停修订为优先，不要硬执行 + 本阶段承接 requirements.md / design.md / plan.md / tasks.md（4 份 fact 来源）+ 项目代码库。 - 并行执行（如可用）： + ## 输入 - - 如果工具支持 subagent 或 task 派发（如 Claude Code 的 Task tool、OpenCode 的 task tool），遇到满足以下全部条件的任务时，应 dispatch 独立 subagent 并行执行： - - 与已派发或正在执行的任务没有文件依赖 - - 不依赖前置任务的输出或运行时副作用 - - 属于不同 plan.md 阶段或同阶段内明确独立的工作单元 - - 每个 subagent 完成后必须返回：执行结果摘要、变更文件列表、验证证据（命令输出或测试结果） - - 主 agent 负责合并 subagent 结果、更新 tasks.md checkbox、处理冲突；不要让 subagent 直接写 tasks.md - - subagent 不可用时（如工具不支持或会话限制），退化为串行执行，不影响正确性 + - requirements.md（需求/范围/验收/全局审查的事实来源） + - design.md（技术方向/关键决策的事实来源） + - plan.md（实现计划/关键代码模式的事实来源） + - tasks.md（执行进度的事实来源；apply 跟踪其 checkbox） + - openspec/config.yaml 及 workflow context（项目约束） + - 项目代码库（实际变更对象） - 阻塞处理（强制）： + ## 工具使用（先决说明） - 遇到以下情况必须暂停，而不是硬着头皮继续： + 本阶段可用工具： - - plan.md 的实现路径不可行或关键假设不成立 - - design.md 的技术决策与代码库现实冲突 - - requirements.md 存在阻塞性开放问题 - - 继续执行会引入未确认的依赖、安全、兼容性、迁移或用户体验风险 - - 任务要求与用户意图、全局审查结论或既有系统行为明显冲突 + - **todo / plan 工具**：必须跟踪执行进度；每个未完成任务标记为 in_progress 或 pending，完成后标记 completed，并同步回 tasks.md checkbox + - **subagent / task 派发工具**：用于并行执行独立任务（详见步骤 4） + - **读写工具**：Read / Edit / Write / Grep / Glob / Bash 是主要工具 + - **禁止**：不得使用 question / choice 发起决策型提问；决策型分歧必须走 blocker 机制 + - **注意**：todo 跟踪实际执行进度，不同于上游文档撰写进度 - 暂停时，在当前 change 目录生成 blocker.md，使用 `openspec/schemas/code-drive/templates/blocker.md` 模板结构，至少填写以下章节： + ## Blocker 机制（强制协议，适用于本阶段所有"无法独立解决"环节） - - 阻塞点（简述阻塞本质） - - 当前位置（任务编号、plan.md 阶段、相关文件） - - 已尝试（已尝试方案及失败原因） - - 影响范围（对上下游 artifacts 的影响分析） - - 可选方案（2-3 个方向及取舍） - - 修订建议（推荐方案及修订路径：从哪个 artifact 入口开始，下游需同步哪些） + 本机制是 apply 阶段**唯一**的异常出口。apply 的默认行为是**按计划执行**——只在真正无法独立解决时才生成 blocker.md 中断流程。生成 blocker 的成本是中断整个变更流程让用户介入修订上游，因此触发条件 reserved 给"AI 真处理不了的高价值错误"，**而不是任何信息增量**。 - 生成 blocker.md 后，明确告诉用户：阻塞已记录，请读取并执行 `openspec/schemas/code-drive/prompts/blocker-revise.md` 中的修订流程；修订完成后可重新运行 apply，已完成的 checkbox 任务会被跳过。 + ### 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 事实 diff --git a/openspec/schemas/code-drive/templates/blocker.md b/openspec/schemas/code-drive/templates/blocker.md index 8d34e2c..f6ac0cd 100644 --- a/openspec/schemas/code-drive/templates/blocker.md +++ b/openspec/schemas/code-drive/templates/blocker.md @@ -26,21 +26,21 @@ ## 可选方案 -### 方案 A： +### 方案 1： - 描述： - 需修订： - 优势： - 风险 / 代价： -### 方案 B： +### 方案 2： - 描述： - 需修订： - 优势： - 风险 / 代价： -### 方案 C：（可选） +### 方案 3： - 描述： - 需修订： diff --git a/openspec/schemas/code-drive/templates/design.md b/openspec/schemas/code-drive/templates/design.md index 6ce5478..8fcc511 100644 --- a/openspec/schemas/code-drive/templates/design.md +++ b/openspec/schemas/code-drive/templates/design.md @@ -68,9 +68,3 @@ ## 验证方向 - -## 待确认事项 - -| 状态 | 问题 | 所需决策 | -| ---- | ---- | -------- | -| 无 | 无待确认事项。 | 无需决策 | diff --git a/openspec/schemas/code-drive/templates/plan.md b/openspec/schemas/code-drive/templates/plan.md index 738f0cb..4822a2a 100644 --- a/openspec/schemas/code-drive/templates/plan.md +++ b/openspec/schemas/code-drive/templates/plan.md @@ -10,49 +10,7 @@ | -------- | -------- | -------- | | | | | -## 阶段 1: - -### 目标 - - - -### 前置条件 - - - -### 详细实现步骤 - - - -### 关键代码模式 - - - -**新增 / 修改的函数或方法：** - - -**新增 / 修改的数据结构：** - - -**调用顺序 / 流程：** - - -**约定 / 模式：** - - -### 验证方式 - - - -### 验收标准 - - - -### 关联需求 - - - -## 阶段 2: +## 阶段 N: ### 目标 @@ -106,9 +64,3 @@ - 错误处理： - 兼容性： - 迁移注意事项： - -## 待确认事项 - -| 状态 | 问题 | 所需决策 | -| ---- | ---- | -------- | -| 无 | 无待确认事项。 | 无需决策 | diff --git a/openspec/schemas/code-drive/templates/requirements.md b/openspec/schemas/code-drive/templates/requirements.md index e55fca0..d644b71 100644 --- a/openspec/schemas/code-drive/templates/requirements.md +++ b/openspec/schemas/code-drive/templates/requirements.md @@ -51,16 +51,7 @@ -### 潜在冲突 - - - ### 前置条件 - + -## 开放问题 - -| 状态 | 问题 | 所需决策 | -| ---- | ---- | -------- | -| 无 | 无待解决问题。 | 无需决策 | diff --git a/openspec/schemas/code-drive/templates/tasks.md b/openspec/schemas/code-drive/templates/tasks.md index 2110703..16b372f 100644 --- a/openspec/schemas/code-drive/templates/tasks.md +++ b/openspec/schemas/code-drive/templates/tasks.md @@ -1,26 +1,16 @@ -## 1. +## X. -- [ ] 1.1 阅读 plan.md 阶段 1，确认涉及文件、关键代码模式和验收标准 -- [ ] 1.2 -- [ ] 1.3 -- [ ] 1.4 -- [ ] 1.5 -- [ ] 1.6 按 plan.md 阶段 1 的验收标准确认阶段完成 +- [ ] X.1 阅读 plan.md 阶段 X，确认涉及文件、关键代码模式和验收标准 +- [ ] X.2 +- [ ] X.3 +- [ ] X.4 +- [ ] X.5 按 plan.md 阶段 X 的验收标准确认阶段完成 -## 2. +## N. 验证与收尾 -- [ ] 2.1 阅读 plan.md 阶段 2，确认涉及文件、关键代码模式和验收标准 -- [ ] 2.2 -- [ ] 2.3 -- [ ] 2.4 -- [ ] 2.5 -- [ ] 2.6 按 plan.md 阶段 2 的验收标准确认阶段完成 - -## 3. 验证与收尾 - -- [ ] 3.1 阅读 plan.md 验证策略，确认所有验证项已执行 -- [ ] 3.2 执行完整测试套件，确认无回归 -- [ ] 3.3 逐项对照 requirements.md 验收标准，确认全部满足 -- [ ] 3.4 检查 design.md 关键决策是否被正确实现 -- [ ] 3.5 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档或交接说明 -- [ ] 3.6 确认所有任务已标记为 `[x]`，未完成或阻塞事项已记录 +- [ ] N.1 阅读 plan.md 验证策略，确认所有验证项已执行 +- [ ] N.2 执行完整测试套件，确认无回归 +- [ ] N.3 逐项对照 requirements.md 验收标准，确认全部满足 +- [ ] N.4 检查 design.md 关键决策是否被正确实现 +- [ ] N.5 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档或交接说明 +- [ ] N.6 确认所有任务已标记为 `[x]`，未完成或阻塞事项已记录