From fe55c532b8a28b3b3bc8cea6d8f2033537173502 Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Sun, 7 Jun 2026 13:35:26 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=20code-drive=20?= =?UTF-8?q?=E8=87=AA=E5=AE=9A=E4=B9=89=20schema=20=E4=B8=8E=E5=8F=82?= =?UTF-8?q?=E8=80=83=E8=B5=84=E6=96=99=E9=87=8D=E7=BB=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 code-drive schema（5 阶段：requirements -> design -> plan -> tasks -> apply） - 每阶段含 instruction、self-review、用户确认门和工具集成指引 - apply 支持阻塞回退机制（blocker.md + blocker-revise.md skill） - apply 支持 subagent 并行执行独立任务 - TodoWrite 职责区分：撰写阶段跟踪文档撰写流程，apply 跟踪执行进度 - 将 OpenSpec 子模块移至 references/，新增 superpowers 和 spec-kit 参考 - 添加项目规范 AGENT.md --- .gitmodules | 10 +- AGENT.md | 8 + code-drive/prompts/blocker-revise.md | 132 +++++++++++++++ code-drive/schema.yaml | 231 +++++++++++++++++++++++++++ code-drive/templates/blocker.md | 52 ++++++ code-drive/templates/design.md | 76 +++++++++ code-drive/templates/plan.md | 114 +++++++++++++ code-drive/templates/requirements.md | 66 ++++++++ code-drive/templates/tasks.md | 26 +++ OpenSpec => references/OpenSpec | 0 references/spec-kit | 1 + references/superpowers | 1 + 12 files changed, 715 insertions(+), 2 deletions(-) create mode 100644 AGENT.md create mode 100644 code-drive/prompts/blocker-revise.md create mode 100644 code-drive/schema.yaml create mode 100644 code-drive/templates/blocker.md create mode 100644 code-drive/templates/design.md create mode 100644 code-drive/templates/plan.md create mode 100644 code-drive/templates/requirements.md create mode 100644 code-drive/templates/tasks.md rename OpenSpec => references/OpenSpec (100%) create mode 160000 references/spec-kit create mode 160000 references/superpowers diff --git a/.gitmodules b/.gitmodules index e0d3415..3fc7e36 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,9 @@ -[submodule "OpenSpec"] - path = OpenSpec +[submodule "references/superpowers"] + path = references/superpowers + url = https://github.com/obra/superpowers.git +[submodule "references/spec-kit"] + path = references/spec-kit + url = https://github.com/github/spec-kit.git +[submodule "references/OpenSpec"] + path = references/OpenSpec url = https://github.com/Fission-AI/OpenSpec.git diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 0000000..82c7ede --- /dev/null +++ b/AGENT.md @@ -0,0 +1,8 @@ +# 项目规范 + +- 使用中文（注释、文档、交流），面向中文开发者 +- **优先阅读 README.md** 获取项目信息 +- Git提交: 仅中文; 格式"类型: 简短描述", 类型: feat/fix/refactor/docs/style/test/chore; 多行描述空行后写详细说明 +- 禁止创建git操作task +- 积极使用subagents精心设计并行任务，节省上下文空间，加速任务执行 +- 优先使用提问工具对用户进行提问 diff --git a/code-drive/prompts/blocker-revise.md b/code-drive/prompts/blocker-revise.md new file mode 100644 index 0000000..b939e58 --- /dev/null +++ b/code-drive/prompts/blocker-revise.md @@ -0,0 +1,132 @@ +# blocker-revise + +当 OpenSpec `code-drive` 的 apply 阶段生成 `blocker.md` 并暂停时，按照本提示词修订规划 artifacts。目标是修正不成立的部分，而不是强行继续实现。 + +## 输入 + +- 当前 OpenSpec change 目录 +- `blocker.md` +- `requirements.md` +- `design.md` +- `plan.md` +- `tasks.md` +- `openspec/schemas/code-drive/schema.yaml`（用于读取各 artifact 的 instruction） + +## 工作流 + +### 1. 阅读并理解阻塞 + +阅读 `blocker.md`，识别： + +- 阻塞点的本质（不是症状） +- 当前位置：任务编号、`plan.md` 阶段、相关文件 +- 已尝试的方案及失败原因（避免重复） +- `blocker.md` 建议的修订目标 + +### 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` 需要修订：只影响当前任务及其直接依赖 + +记录每个 artifact 的影响程度：必须修订 / 可能受影响 / 无影响。 + +### 3. 确定修订入口 + +根据影响分析，确定需要修订的最上游 artifact： + +- 如果需要修订 `requirements.md`：从 requirements 开始，依次修订 design、plan、tasks +- 如果需要修订 `design.md`：从 design 开始，依次修订 plan、tasks +- 如果需要修订 `plan.md`：从 plan 开始，修订 tasks +- 如果只需要修订 `tasks.md`：只修订 tasks + +### 4. 用户决策 + +让用户从 `blocker.md` 中列出的可选方案中选择。如果选项不足，提出 2-3 个方案并说明取舍。工具支持时优先使用 question/choice 工具。 + +### 5. 执行修订 + +从修订入口开始，按正常 code-drive 流程逐层修订下游 artifacts。 + +每个 artifact 的修订必须遵循该 artifact 的 instruction 和 template： + +1. 读取 `schema.yaml` 中该 artifact 的 `instruction` +2. 读取该 artifact 的 `template` +3. 按 instruction 的工作规则和必需章节进行修订 +4. 确保修订后的 artifact 符合 template 结构 + +修订范围原则： + +- 只改错误的部分，不重写整个章节（除非整个章节的基础假设不成立） +- 改了 `plan.md` 阶段的实现步骤时，同步更新 `tasks.md` 对应 checkbox 的描述 +- 改了 `design.md` 的关键决策时，检查 `plan.md` 的代码模式是否需要同步，但不自动重写 +- 改了 `requirements.md` 时，逐层向下检查影响，每层只改受影响的部分 +- 如果修订导致 `tasks.md` 分组结构变化，重新对齐 plan -> tasks 映射 + +保留已完成任务： + +- 已完成且不受阻塞影响的 tasks：保留 checkbox +- 已完成但被阻塞证明无效的 tasks：取消 checkbox，并在修订记录中说明原因 +- 未完成的 tasks：根据修订结果更新描述或删除 +- 如果阶段需要拆分：在 `plan.md` 中新增阶段，将已完成部分和待完成部分分开 + +### 6. 修订后验证 + +每个被修订的 artifact 完成后，执行以下一致性检查： + +Instruction 合规性： + +- 每个被修订的 artifact 是否符合其 instruction 中的工作规则 +- 每个被修订的 artifact 是否包含其 instruction 中要求的必需章节 +- 每个被修订的 artifact 是否符合其 template 结构 + +上下游一致性： + +- 需求覆盖：`requirements.md` 的每条需求是否仍有 `design.md` 决策覆盖 +- 决策落地：`design.md` 的每个关键决策是否在 `plan.md` 中有实现路径 +- 阶段覆盖：`plan.md` 的每个阶段是否在 `tasks.md` 中有对应分组 +- 任务可追溯：`tasks.md` 的每个 checkbox 是否能回溯到 `plan.md` 的某个阶段 +- 验证闭环：`design.md` 的“验证方向”是否在 `plan.md` 的“验证策略”中有体现 + +### 7. 处理 blocker.md + +在 `blocker.md` 末尾追加“修订记录”： + +```markdown +## 修订记录 + +- 选择方案： +- 选择理由： +- 修改的 artifacts： + - `xxx.md`：具体变更描述 + - `xxx.md`：具体变更描述 +- 被取消勾选的 tasks： + - X.Y：取消原因 +``` + +按项目约定保留或归档 `blocker.md`（建议保留作为审计线索）。 + +### 8. 完成 + +告诉用户重新运行 `/opsx:apply `；apply 应跳过已完成 checkbox 并从修订后的待办任务继续。 + +## 规则 + +- 除非用户明确要求，不要在使用本提示词时实现代码；本提示词只负责修订规划 artifacts。 +- 不要默认重写全部 artifacts，只修订解决阻塞所需的最小上游点及其下游影响。 +- 不要未经用户确认新增需求、依赖、架构方向或范围。 +- 不要取消已完成任务的勾选，除非阻塞证明该已完成工作不正确。 +- 每个被修订的 artifact 必须遵循其 instruction 和 template，即使只是局部修订。 +- 如果工具支持，使用 todo/plan 工具跟踪修订流程，但最终事实必须写回 artifacts。 + +## 完成检查 + +- `blocker.md` 已追加修订记录，并被保留或归档。 +- 选定的修订方向已记录在受影响 artifact 中。 +- 每个被修订的 artifact 符合其 instruction 的工作规则和必需章节。 +- 下游 artifacts 与修订后的上游内容一致。 +- 已完成任务的 checkbox 被保留，除非明确失效。 +- 用户知道需要重新运行 apply 继续实现。 diff --git a/code-drive/schema.yaml b/code-drive/schema.yaml new file mode 100644 index 0000000..147d00c --- /dev/null +++ b/code-drive/schema.yaml @@ -0,0 +1,231 @@ +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，作为本次变更“要解决什么、为什么要解决、需要确认哪些业务和技术边界”的事实来源。 + + 本阶段用于承接 explore、前序讨论、用户请求和代码库调查结果。requirements.md 面向项目开发者，而不是外部需求方；因此本阶段既要确认业务需求，也要确认技术需求，例如技术选型、架构方向、集成边界、代码约束和验收方式。 + + requirements.md 的职责是“确认和澄清”：通过对话把需求、边界、取舍和用户决策固定下来。design.md 的职责是“翻译”：把 requirements.md 中确认的内容转化为可执行的技术方案。不要在 requirements.md 展开详细实现步骤、具体文件修改清单或任务 checkbox。 + + 语言规则（强制）： + + - code-drive 的 requirements.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 + - 最终 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 或详细实现计划 + + 必需章节（建议使用模板中的中文章节标题）：背景与目标、讨论记录、功能需求、非功能需求、技术需求、全局审查、开放问题。 + + 简单变更保持精炼；复杂或横切变更必须写足够细节，避免后续 design/plan/apply 依赖未写入文档的聊天上下文。 + + 写完后自检（逐项检查并内联修复，无需二次 review）： + + - 占位符扫描：是否残留模板注释、英文模板句子、TBD、待补充或空表格行 + - 章节完整性：所有必需章节都已填写；功能需求、非功能需求和技术需求没有明显遗漏 + - 上下文一致性：讨论记录中的“已确认结论”都已落入对应章节；被否决方案没有被复用 + - 全局审查充分性：系统边界、既有行为、相邻模块、配置、迁移、兼容性都被审视过 + - YAGNI：每条需求都经过挑战，没有“未来可能需要但本次不必需”的功能 + - 范围合适：变更聚焦到能用单一 design.md 承接，还是需要拆分为多个子变更 + + 写完并自检后，向用户简要展示关键决策点（功能需求、技术需求、阻塞性开放问题），并请求确认。用户提出修改时，修改后重跑上述自检。 + 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。 + + 语言规则（强制）： + + - code-drive 的 design.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 + - 最终 design.md 不得残留英文模板句子、英文占位内容、空表格行或未解决的模板注释 + + 在编写 design.md 之前，先确认 requirements.md 和前序讨论中是否已有足够的技术探索结果。如果已有，直接引用，不重复探索；只补充 requirements.md 未覆盖的部分。 + + 补充探索的触发条件（满足任一即可）： + + - requirements.md 确认了技术选型，但未检查项目中该依赖的安装状态或版本约束 + - requirements.md 确认了架构方向，但未检查现有代码中是否有可复用的组件、工具函数、数据结构、API 模式或架构约定 + - 需求涉及的模块在 requirements.md 或前序讨论中未被探索过 + - 用户在 design 阶段提出了新的技术问题 + + 探索深度根据变更规模和既有探索充分度调整： + + - 简单变更且 requirements.md 已有充分探索：快速确认即可，无需详细重复记录 + - 复杂变更或 requirements.md 探索不足：详细检查依赖、现有代码、项目规范，并记录发现 + + 探索结果记录在 design.md 的“代码库探索”章节。如果探索发现与 requirements.md 的假设冲突，暂停并告知用户。 + + 工作规则： + + - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），复杂变更必须使用它跟踪 design.md 的撰写流程（读取 requirements、代码库探索、编写各章节、自检），避免遗漏；简单变更可不使用。注意：这里跟踪的是文档撰写进度，不是整体变更的实现进度 + - 对关键技术决策给出理由，并记录至少一个被否决方案或主要取舍 + - 如果存在多个合理技术方向，先向用户呈现 2-3 个方案、适用条件和风险；如果工具支持，优先使用 question/choice 工具收敛决策 + - 明确目标、非目标、影响范围、依赖约束、风险权衡和待确认事项 + - 如果 requirements.md 仍有阻塞性开放问题，不要猜测答案；暂停并请求用户决策 + - 设计必须基于代码库现实，而非从零假设；如果探索发现现有代码可复用，优先复用而非新建 + - 不要引入 requirements.md 未确认的新需求、外部依赖或架构方向；不要引入 requirements.md 未确认且代码库中不存在的新依赖，除非有充分理由并经用户确认 + + 必需章节（建议使用模板中的中文章节标题）：代码库探索、整体方案、目标 / 非目标、关键决策、影响范围、依赖与约束、风险 / 权衡、验证方向、待确认事项。 + + 写完后自检（逐项检查并内联修复，无需二次 review）： + + - 占位符扫描：是否残留模板注释、英文占位内容或空表格行 + - 需求覆盖：requirements.md 的每条功能需求都有决策覆盖；技术需求被正确引用或落地 + - 决策合理性：每个关键决策有理由，并记录至少一个被否决方案或主要取舍 + - 代码库现实：设计基于代码库探索发现，而非从零假设；没有引入 requirements.md 未确认的新依赖 + - 验证方向对齐：验证方向覆盖了 requirements.md 的功能验收标准和非功能需求 + requires: + - requirements + - id: plan + generates: plan.md + description: 从 design.md 派生的详细实现计划 + template: plan.md + instruction: | + 创建 plan.md，作为本次变更的详细实现计划。先阅读 requirements.md 和 design.md。 + + plan.md 负责把概要设计转化为可独立理解、可验证、可执行的实现阶段。tasks.md 的分组必须与 plan.md 的阶段一一对应，因此 plan.md 是 apply 阶段理解关键实现细节的主要依据。 + + 语言规则（强制）： + + - code-drive 的 plan.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 + - 最终 plan.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、验证策略、回退 / 兼容性说明、待确认事项。 + + 写完后自检（逐项检查并内联修复，无需二次 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 的“验证方向”在“验证策略”中有体现 + requires: + - requirements + - design + - id: tasks + generates: tasks.md + description: 从 plan.md 派生的可跟踪执行清单 + template: tasks.md + instruction: | + 创建 tasks.md，将 plan.md 拆解为 OpenSpec apply 可跟踪的 checkbox 任务。 + + **重要：必须遵守以下模板中的 checkbox 行格式。** apply 阶段会解析 checkbox 格式跟踪进度。未使用 `- [ ]` 的任务不会被跟踪。 + + 语言规则（强制）： + + - code-drive 的 tasks.md 使用中文分组标题和中文任务描述；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 + - 每个可跟踪任务必须保留 OpenSpec CLI 可解析的单行 checkbox 格式，例如 `- [ ] 1.1 任务描述` 或 `- [x] 1.1 已完成任务描述` + - 最终 tasks.md 不得残留英文模板任务、英文占位内容、空分组或占位任务文本 + + 编写规则： + + - 任务必须从 requirements.md、design.md 和 plan.md 派生，其中 plan.md 是任务分组和关键实现细节的主要依据 + - 每个 plan.md 阶段必须有一个对应的 `##` 编号任务分组，分组标题应与 plan.md 阶段名称一致或明显对应 + - 每个任务 MUST 是单行 checkbox：`- [ ] X.Y 任务描述` + - 任务描述可以保持简洁灵活，但必须指向具体动作，并在必要时引用 plan.md 的阶段或小节 + - 每个阶段应拆解为 3-6 个具体动作任务（不含阅读 plan.md 的元任务），粒度控制在单个文件、单个函数或单个可验证行为级别 + - 测试验证任务应穿插在各阶段内，而非仅在最后统一验证 + - 任务描述格式建议：动词 + 文件/模块 + 具体动作（如“修改 src/auth.ts 的 login 函数，添加参数校验”） + - 任务粒度应足够小，能在一个会话内完成，并且完成标准明确 + - 按依赖顺序排序；可并行任务也要明确前置条件 + - 必须包含验证与收尾分组，覆盖 plan.md 的验证策略、必要文档更新和人工验收 + - 如果 plan.md 过粗、不可验证或与上游 artifact 冲突，不要硬拆 tasks；先暂停并要求修订 plan.md + + 不要在 tasks.md 重新发明实现方案。需要关键实现细节时，引用 plan.md。 + requires: + - requirements + - design + - plan +apply: + requires: + - requirements + - design + - plan + - 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 任务 + - 如果工具支持 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 冲突，以暂停修订为优先，不要硬执行 + + 并行执行（如可用）： + + - 如果工具支持 subagent 或 task 派发（如 Claude Code 的 Task tool、OpenCode 的 task tool），遇到满足以下全部条件的任务时，应 dispatch 独立 subagent 并行执行： + - 与已派发或正在执行的任务没有文件依赖 + - 不依赖前置任务的输出或运行时副作用 + - 属于不同 plan.md 阶段或同阶段内明确独立的工作单元 + - 每个 subagent 完成后必须返回：执行结果摘要、变更文件列表、验证证据（命令输出或测试结果） + - 主 agent 负责合并 subagent 结果、更新 tasks.md checkbox、处理冲突；不要让 subagent 直接写 tasks.md + - subagent 不可用时（如工具不支持或会话限制），退化为串行执行，不影响正确性 + + 阻塞处理（强制）： + + 遇到以下情况必须暂停，而不是硬着头皮继续： + + - plan.md 的实现路径不可行或关键假设不成立 + - design.md 的技术决策与代码库现实冲突 + - requirements.md 存在阻塞性开放问题 + - 继续执行会引入未确认的依赖、安全、兼容性、迁移或用户体验风险 + - 任务要求与用户意图、全局审查结论或既有系统行为明显冲突 + + 暂停时，在当前 change 目录生成 blocker.md，使用 `openspec/schemas/code-drive/templates/blocker.md` 模板结构，至少填写以下章节： + + - 阻塞点（简述阻塞本质） + - 当前位置（任务编号、plan.md 阶段、相关文件） + - 已尝试（已尝试方案及失败原因） + - 影响范围（对上下游 artifacts 的影响分析） + - 可选方案（2-3 个方向及取舍） + - 修订建议（推荐方案及修订路径：从哪个 artifact 入口开始，下游需同步哪些） + + 生成 blocker.md 后，明确告诉用户：阻塞已记录，请读取并执行 `openspec/schemas/code-drive/prompts/blocker-revise.md` 中的修订流程；修订完成后可重新运行 apply，已完成的 checkbox 任务会被跳过。 diff --git a/code-drive/templates/blocker.md b/code-drive/templates/blocker.md new file mode 100644 index 0000000..8d34e2c --- /dev/null +++ b/code-drive/templates/blocker.md @@ -0,0 +1,52 @@ +## 阻塞点 + + + +## 当前位置 + +- 任务编号： +- plan.md 阶段： +- 相关文件： + +## 已尝试 + + + +| 方案 | 失败原因 | +| ---- | -------- | +| | | + +## 影响范围 + + + +| Artifact | 影响内容 | 影响程度 | +| -------- | -------- | -------- | +| | | 必须修订 / 可能受影响 / 无影响 | + +## 可选方案 + +### 方案 A： + +- 描述： +- 需修订： +- 优势： +- 风险 / 代价： + +### 方案 B： + +- 描述： +- 需修订： +- 优势： +- 风险 / 代价： + +### 方案 C：（可选） + +- 描述： +- 需修订： +- 优势： +- 风险 / 代价： + +## 修订建议 + + diff --git a/code-drive/templates/design.md b/code-drive/templates/design.md new file mode 100644 index 0000000..6ce5478 --- /dev/null +++ b/code-drive/templates/design.md @@ -0,0 +1,76 @@ +## 代码库探索 + + + +### 已有代码与模式 + + + +### 依赖状态 + + + +### 开发规范约束 + + + +## 整体方案 + +### 架构概览 + + + +### 关键交互流程 + + + +## 目标 / 非目标 + +**目标：** + + +**非目标：** + + +## 关键决策 + + + +| 决策 | 来源 | 理由 | +| ---- | ---- | ---- | +| | | | + +## 影响范围 + + + +| 范围 | 变更类型 | 原因 | +| ---- | -------- | ---- | +| | | | + +### 关键实现路径 + + + +## 依赖与约束 + + + +- 依赖： +- 兼容性： +- 质量门禁： +- 禁止事项： + +## 风险 / 权衡 + + + +## 验证方向 + + + +## 待确认事项 + +| 状态 | 问题 | 所需决策 | +| ---- | ---- | -------- | +| 无 | 无待确认事项。 | 无需决策 | diff --git a/code-drive/templates/plan.md b/code-drive/templates/plan.md new file mode 100644 index 0000000..738f0cb --- /dev/null +++ b/code-drive/templates/plan.md @@ -0,0 +1,114 @@ +## 实现概览 + + + +## 涉及文件 + + + +| 文件路径 | 变更类型 | 所属阶段 | +| -------- | -------- | -------- | +| | | | + +## 阶段 1: + +### 目标 + + + +### 前置条件 + + + +### 详细实现步骤 + + + +### 关键代码模式 + + + +**新增 / 修改的函数或方法：** + + +**新增 / 修改的数据结构：** + + +**调用顺序 / 流程：** + + +**约定 / 模式：** + + +### 验证方式 + + + +### 验收标准 + + + +### 关联需求 + + + +## 阶段 2: + +### 目标 + + + +### 前置条件 + + + +### 详细实现步骤 + + + +### 关键代码模式 + + + +**新增 / 修改的函数或方法：** + + +**新增 / 修改的数据结构：** + + +**调用顺序 / 流程：** + + +**约定 / 模式：** + + +### 验证方式 + + + +### 验收标准 + + + +### 关联需求 + + + +## 验证策略 + + + +## 回退 / 兼容性说明 + + + +- 回退策略： +- 错误处理： +- 兼容性： +- 迁移注意事项： + +## 待确认事项 + +| 状态 | 问题 | 所需决策 | +| ---- | ---- | -------- | +| 无 | 无待确认事项。 | 无需决策 | diff --git a/code-drive/templates/requirements.md b/code-drive/templates/requirements.md new file mode 100644 index 0000000..e55fca0 --- /dev/null +++ b/code-drive/templates/requirements.md @@ -0,0 +1,66 @@ +## 背景与目标 + + + +## 讨论记录 + + + +### 已确认结论 + +- +- + +### 用户偏好 + +- + +### 被否决方案 + +- + +## 功能需求 + + + +| 编号 | 需求 | 验收标准 | +| ---- | ---- | -------- | +| F1 | | | + +## 非功能需求 + + + +| 类别 | 要求 | +| ---- | ---- | +| | | + +## 技术需求 + + + +| 编号 | 类别 | 决策 | 理由 | 被否决方案 | +| ---- | ---- | ---- | ---- | ---------- | +| T1 | | | | | + +## 全局审查 + + + +### 与现有系统的关联 + + + +### 潜在冲突 + + + +### 前置条件 + + + +## 开放问题 + +| 状态 | 问题 | 所需决策 | +| ---- | ---- | -------- | +| 无 | 无待解决问题。 | 无需决策 | diff --git a/code-drive/templates/tasks.md b/code-drive/templates/tasks.md new file mode 100644 index 0000000..2110703 --- /dev/null +++ b/code-drive/templates/tasks.md @@ -0,0 +1,26 @@ +## 1. + +- [ ] 1.1 阅读 plan.md 阶段 1，确认涉及文件、关键代码模式和验收标准 +- [ ] 1.2 +- [ ] 1.3 +- [ ] 1.4 +- [ ] 1.5 +- [ ] 1.6 按 plan.md 阶段 1 的验收标准确认阶段完成 + +## 2. + +- [ ] 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]`，未完成或阻塞事项已记录 diff --git a/OpenSpec b/references/OpenSpec similarity index 100% rename from OpenSpec rename to references/OpenSpec diff --git a/references/spec-kit b/references/spec-kit new file mode 160000 index 0000000..7106858 --- /dev/null +++ b/references/spec-kit @@ -0,0 +1 @@ +Subproject commit 7106858c4e636098815fffa23f6c6b99eb0e156b diff --git a/references/superpowers b/references/superpowers new file mode 160000 index 0000000..6fd4507 --- /dev/null +++ b/references/superpowers @@ -0,0 +1 @@ +Subproject commit 6fd4507659784c351abbd2bc264c7162cfd386dc