chore: 移除 superpowers 插件,恢复 openspec 工作流
This commit is contained in:
@@ -1,6 +1,5 @@
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"plugin": ["superpowers@git+https://github.com/obra/superpowers.git"],
|
||||
"mcp": {
|
||||
"antd": {
|
||||
"enabled": true,
|
||||
|
||||
36
openspec/config.yaml
Normal file
36
openspec/config.yaml
Normal file
@@ -0,0 +1,36 @@
|
||||
schema: code-drive
|
||||
|
||||
context: |
|
||||
## 项目概览
|
||||
- 本项目为 Bun 全栈应用（Alfred·阿福），Bun 是唯一包管理器和运行时，严禁使用 npm、pnpm、yarn、npx、pnpx
|
||||
- docs/user/ 记录用户使用方法，docs/development/ 记录开发技术细节
|
||||
- 使用中文（注释、文档、交流），面向中文开发者
|
||||
- 本项目无需考虑向前兼容性
|
||||
|
||||
## 文档入口（按顺序阅读）
|
||||
- **优先阅读 docs/README.md** 获取文档路由、归属矩阵和影响分析规则
|
||||
- **其次阅读 docs/development/README.md** 获取完整开发规范、常用命令和质量门禁
|
||||
|
||||
## 全局红线
|
||||
- 前端禁止导入 src/server/ 的后端运行时实现
|
||||
- 后端运行时代码禁止直接使用 console.*，通过 Logger 实例输出
|
||||
- 新增逻辑必须编写完善的测试，不允许跳过任何测试
|
||||
- 每次代码变更必须执行文档影响分析（详见 docs/README.md）
|
||||
- 新增代码优先复用已有组件、工具、依赖库，不轻易引入新依赖
|
||||
|
||||
## Git 规范
|
||||
- 提交信息中文，格式"类型: 简短描述"，类型：feat/fix/refactor/docs/style/test/chore
|
||||
- 禁止创建 git 操作 task
|
||||
|
||||
## 工作方式
|
||||
- 积极使用 subagent 并行独立子任务，节省上下文空间；能并行的步骤明确并行
|
||||
- subagent 仅用于只读收集和分析，禁止用于文件修改、代码生成、git 操作或依赖安装
|
||||
- 单个文件或目录只分配给一个 subagent，不重复分配；subagent 输出文件路径、行号和问题摘要，不输出大段源码
|
||||
- 主 agent 负责最终结论：去重、交叉验证、合并同根因问题
|
||||
- 优先使用提问工具对用户确认
|
||||
|
||||
rules:
|
||||
tasks:
|
||||
- 如果是代码存在更新必须
|
||||
- 执行完整的测试、代码检查、格式检查等质量保障手段
|
||||
- 执行文档影响分析，更新 README.md 和/或 docs/ 下对应文档
|
||||
132
openspec/schemas/code-drive/prompts/blocker-revise.md
Normal file
132
openspec/schemas/code-drive/prompts/blocker-revise.md
Normal file
@@ -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 <change-name>`；apply 应跳过已完成 checkbox 并从修订后的待办任务继续。
|
||||
|
||||
## 规则
|
||||
|
||||
- 除非用户明确要求，不要在使用本提示词时实现代码；本提示词只负责修订规划 artifacts。
|
||||
- 不要默认重写全部 artifacts，只修订解决阻塞所需的最小上游点及其下游影响。
|
||||
- 不要未经用户确认新增需求、依赖、架构方向或范围。
|
||||
- 不要取消已完成任务的勾选，除非阻塞证明该已完成工作不正确。
|
||||
- 每个被修订的 artifact 必须遵循其 instruction 和 template，即使只是局部修订。
|
||||
- 如果工具支持，使用 todo/plan 工具跟踪修订流程，但最终事实必须写回 artifacts。
|
||||
|
||||
## 完成检查
|
||||
|
||||
- `blocker.md` 已追加修订记录，并被保留或归档。
|
||||
- 选定的修订方向已记录在受影响 artifact 中。
|
||||
- 每个被修订的 artifact 符合其 instruction 的工作规则和必需章节。
|
||||
- 下游 artifacts 与修订后的上游内容一致。
|
||||
- 已完成任务的 checkbox 被保留，除非明确失效。
|
||||
- 用户知道需要重新运行 apply 继续实现。
|
||||
231
openspec/schemas/code-drive/schema.yaml
Normal file
231
openspec/schemas/code-drive/schema.yaml
Normal file
@@ -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 任务会被跳过。
|
||||
52
openspec/schemas/code-drive/templates/blocker.md
Normal file
52
openspec/schemas/code-drive/templates/blocker.md
Normal file
@@ -0,0 +1,52 @@
|
||||
## 阻塞点
|
||||
|
||||
<!-- 简述阻塞的本质，不是症状而是根因 -->
|
||||
|
||||
## 当前位置
|
||||
|
||||
- 任务编号：
|
||||
- plan.md 阶段：
|
||||
- 相关文件：
|
||||
|
||||
## 已尝试
|
||||
|
||||
<!-- 列出已尝试的方案和失败原因，避免重复尝试 -->
|
||||
|
||||
| 方案 | 失败原因 |
|
||||
| ---- | -------- |
|
||||
| | |
|
||||
|
||||
## 影响范围
|
||||
|
||||
<!-- 阻塞对上下游 artifacts 的系统性影响 -->
|
||||
|
||||
| Artifact | 影响内容 | 影响程度 |
|
||||
| -------- | -------- | -------- |
|
||||
| | | 必须修订 / 可能受影响 / 无影响 |
|
||||
|
||||
## 可选方案
|
||||
|
||||
### 方案 A：<!-- 方案名称 -->
|
||||
|
||||
- 描述：
|
||||
- 需修订：
|
||||
- 优势：
|
||||
- 风险 / 代价：
|
||||
|
||||
### 方案 B：<!-- 方案名称 -->
|
||||
|
||||
- 描述：
|
||||
- 需修订：
|
||||
- 优势：
|
||||
- 风险 / 代价：
|
||||
|
||||
### 方案 C：<!-- 方案名称 -->（可选）
|
||||
|
||||
- 描述：
|
||||
- 需修订：
|
||||
- 优势：
|
||||
- 风险 / 代价：
|
||||
|
||||
## 修订建议
|
||||
|
||||
<!-- 推荐方案及修订路径：从哪个 artifact 入口开始修订，下游需要同步哪些 -->
|
||||
76
openspec/schemas/code-drive/templates/design.md
Normal file
76
openspec/schemas/code-drive/templates/design.md
Normal file
@@ -0,0 +1,76 @@
|
||||
## 代码库探索
|
||||
|
||||
<!-- 记录 requirements.md 未覆盖的技术探索发现，作为后续设计的依据。如果 requirements.md 中已有充分的探索结果，在此引用并仅补充缺失部分。 -->
|
||||
|
||||
### 已有代码与模式
|
||||
|
||||
<!-- 记录与本次变更相关的现有代码、组件、工具函数、架构模式；requirements.md 已覆盖则写“见 requirements.md”；无相关现有代码则写“无” -->
|
||||
|
||||
### 依赖状态
|
||||
|
||||
<!-- 记录相关依赖的安装状态、版本约束；requirements.md 已覆盖则引用；未安装的依赖需标注 -->
|
||||
|
||||
### 开发规范约束
|
||||
|
||||
<!-- 记录项目规范、代码风格、命名约定、架构模式等对设计的约束；无特殊约束则写“无” -->
|
||||
|
||||
## 整体方案
|
||||
|
||||
### 架构概览
|
||||
|
||||
<!-- 描述本次变更涉及的模块、组件或流程如何组织和协作，用概要方式说明为什么该方案满足 requirements.md -->
|
||||
|
||||
### 关键交互流程
|
||||
|
||||
<!-- 如果变更涉及模块间交互、API 调用、数据流变化或状态转换，在此描述关键路径；无则写“无” -->
|
||||
|
||||
## 目标 / 非目标
|
||||
|
||||
**目标：**
|
||||
<!-- 记录本次技术设计要达成的目标 -->
|
||||
|
||||
**非目标：**
|
||||
<!-- 记录明确不在范围内的内容 -->
|
||||
|
||||
## 关键决策
|
||||
|
||||
<!-- 引用 requirements.md 中已确认的技术决策，仅补充 requirements.md 未覆盖的实现层决策（如具体 API 设计、数据结构、代码组织方式） -->
|
||||
|
||||
| 决策 | 来源 | 理由 |
|
||||
| ---- | ---- | ---- |
|
||||
| <!-- 决策 --> | <!-- requirements.md T1 / 本阶段新增 --> | <!-- 理由或补充说明 --> |
|
||||
|
||||
## 影响范围
|
||||
|
||||
<!-- 记录会受影响的模块、文件、配置、接口、文档、流程或外部依赖 -->
|
||||
|
||||
| 范围 | 变更类型 | 原因 |
|
||||
| ---- | -------- | ---- |
|
||||
| <!-- 范围 --> | <!-- 新增 / 修改 / 删除 / 验证 --> | <!-- 原因 --> |
|
||||
|
||||
### 关键实现路径
|
||||
|
||||
<!-- 按优先级列出 plan.md 应首先处理的核心文件、模块或流程；简单变更可写“同上” -->
|
||||
|
||||
## 依赖与约束
|
||||
|
||||
<!-- 记录依赖限制、兼容性约束、项目规则、质量门禁和禁止事项 -->
|
||||
|
||||
- 依赖：
|
||||
- 兼容性：
|
||||
- 质量门禁：
|
||||
- 禁止事项：
|
||||
|
||||
## 风险 / 权衡
|
||||
|
||||
<!-- 格式：[风险] -> 缓解措施 -->
|
||||
|
||||
## 验证方向
|
||||
|
||||
<!-- 概要说明本次变更应从哪些角度验证，作为 plan.md “验证策略”的输入 -->
|
||||
|
||||
## 待确认事项
|
||||
|
||||
| 状态 | 问题 | 所需决策 |
|
||||
| ---- | ---- | -------- |
|
||||
| 无 | 无待确认事项。 | 无需决策 |
|
||||
114
openspec/schemas/code-drive/templates/plan.md
Normal file
114
openspec/schemas/code-drive/templates/plan.md
Normal file
@@ -0,0 +1,114 @@
|
||||
## 实现概览
|
||||
|
||||
<!-- 概述实现阶段、依赖顺序，以及各阶段如何对应 requirements.md 和 design.md -->
|
||||
|
||||
## 涉及文件
|
||||
|
||||
<!-- 按阶段列出本次变更涉及的核心文件路径，apply 阶段据此定位代码 -->
|
||||
|
||||
| 文件路径 | 变更类型 | 所属阶段 |
|
||||
| -------- | -------- | -------- |
|
||||
| <!-- 文件路径 --> | <!-- 新增 / 修改 / 删除 --> | <!-- 阶段编号 --> |
|
||||
|
||||
## 阶段 1: <!-- 阶段名称 -->
|
||||
|
||||
### 目标
|
||||
|
||||
<!-- 本阶段要完成什么 -->
|
||||
|
||||
### 前置条件
|
||||
|
||||
<!-- 本阶段开始前必须满足什么；没有则写“无” -->
|
||||
|
||||
### 详细实现步骤
|
||||
|
||||
<!-- 写清楚关键文件、函数、数据结构、流程或配置变化。不要使用 checkbox。 -->
|
||||
|
||||
### 关键代码模式
|
||||
|
||||
<!-- 记录本阶段的关键实现细节，apply 据此编写代码。至少覆盖以下内容中适用的部分： -->
|
||||
|
||||
**新增 / 修改的函数或方法：**
|
||||
<!-- 函数签名、参数、返回值、核心逻辑；无则写“无” -->
|
||||
|
||||
**新增 / 修改的数据结构：**
|
||||
<!-- 类型定义、字段、约束；无则写“无” -->
|
||||
|
||||
**调用顺序 / 流程：**
|
||||
<!-- 关键调用链、异步流程、状态转换；无则写“无” -->
|
||||
|
||||
**约定 / 模式：**
|
||||
<!-- 命名规范、错误处理模式、日志规范等；无则写“无” -->
|
||||
|
||||
### 验证方式
|
||||
|
||||
<!-- 本阶段如何独立验证 -->
|
||||
|
||||
### 验收标准
|
||||
|
||||
<!-- 本阶段完成的可验证标准；与 requirements.md 验收标准对齐 -->
|
||||
|
||||
### 关联需求
|
||||
|
||||
<!-- 例如：F1、F2 -->
|
||||
|
||||
## 阶段 2: <!-- 阶段名称 -->
|
||||
|
||||
### 目标
|
||||
|
||||
<!-- 本阶段要完成什么 -->
|
||||
|
||||
### 前置条件
|
||||
|
||||
<!-- 本阶段开始前必须满足什么；没有则写“无” -->
|
||||
|
||||
### 详细实现步骤
|
||||
|
||||
<!-- 写清楚关键文件、函数、数据结构、流程或配置变化。不要使用 checkbox。 -->
|
||||
|
||||
### 关键代码模式
|
||||
|
||||
<!-- 记录本阶段的关键实现细节，apply 据此编写代码。至少覆盖以下内容中适用的部分： -->
|
||||
|
||||
**新增 / 修改的函数或方法：**
|
||||
<!-- 函数签名、参数、返回值、核心逻辑；无则写“无” -->
|
||||
|
||||
**新增 / 修改的数据结构：**
|
||||
<!-- 类型定义、字段、约束；无则写“无” -->
|
||||
|
||||
**调用顺序 / 流程：**
|
||||
<!-- 关键调用链、异步流程、状态转换；无则写“无” -->
|
||||
|
||||
**约定 / 模式：**
|
||||
<!-- 命名规范、错误处理模式、日志规范等；无则写“无” -->
|
||||
|
||||
### 验证方式
|
||||
|
||||
<!-- 本阶段如何独立验证 -->
|
||||
|
||||
### 验收标准
|
||||
|
||||
<!-- 本阶段完成的可验证标准；与 requirements.md 验收标准对齐 -->
|
||||
|
||||
### 关联需求
|
||||
|
||||
<!-- 例如：F1、F2 -->
|
||||
|
||||
## 验证策略
|
||||
|
||||
<!-- 汇总自动化测试、手动检查、文档检查、兼容性检查和验收方式 -->
|
||||
|
||||
## 回退 / 兼容性说明
|
||||
|
||||
<!-- 记录回退策略、错误处理策略、兼容性要求、迁移注意事项；没有则写“无” -->
|
||||
|
||||
- 回退策略：
|
||||
- 错误处理：
|
||||
- 兼容性：
|
||||
- 迁移注意事项：
|
||||
|
||||
## 待确认事项
|
||||
|
||||
| 状态 | 问题 | 所需决策 |
|
||||
| ---- | ---- | -------- |
|
||||
| 无 | 无待确认事项。 | 无需决策 |
|
||||
66
openspec/schemas/code-drive/templates/requirements.md
Normal file
66
openspec/schemas/code-drive/templates/requirements.md
Normal file
@@ -0,0 +1,66 @@
|
||||
## 背景与目标
|
||||
|
||||
<!-- 记录问题、当前状态、相关参考资料，以及触发本次变更的用户请求 -->
|
||||
|
||||
## 讨论记录
|
||||
|
||||
<!-- 记录 explore 或前序讨论中后续 design/plan/apply 必须保留的关键结论 -->
|
||||
|
||||
### 已确认结论
|
||||
|
||||
- <!-- 结论 1 -->
|
||||
- <!-- 结论 2 -->
|
||||
|
||||
### 用户偏好
|
||||
|
||||
- <!-- 偏好 1 -->
|
||||
|
||||
### 被否决方案
|
||||
|
||||
- <!-- 方案及否决原因 -->
|
||||
|
||||
## 功能需求
|
||||
|
||||
<!-- 每条功能需求必须有明确验收标准 -->
|
||||
|
||||
| 编号 | 需求 | 验收标准 |
|
||||
| ---- | ---- | -------- |
|
||||
| F1 | <!-- 需求 --> | <!-- 验收标准 --> |
|
||||
|
||||
## 非功能需求
|
||||
|
||||
<!-- 只记录与本次变更相关的非功能要求 -->
|
||||
|
||||
| 类别 | 要求 |
|
||||
| ---- | ---- |
|
||||
| <!-- 性能 / 兼容性 / 安全 / 可维护性 / 运维 / 文档 --> | <!-- 要求 --> |
|
||||
|
||||
## 技术需求
|
||||
|
||||
<!-- 记录需要确认的技术选型、架构方向、集成边界、代码约束或禁止事项；详细设计属于 design.md -->
|
||||
|
||||
| 编号 | 类别 | 决策 | 理由 | 被否决方案 |
|
||||
| ---- | ---- | ---- | ---- | ---------- |
|
||||
| T1 | <!-- 选型 / 架构 / 约束 / 集成 --> | <!-- 已确认的决策 --> | <!-- 理由 --> | <!-- 被否决方案及原因 --> |
|
||||
|
||||
## 全局审查
|
||||
|
||||
<!-- 从系统边界、既有行为、相邻模块、配置、文档、迁移、兼容性、安全、性能和用户流程角度审查当前需求 -->
|
||||
|
||||
### 与现有系统的关联
|
||||
|
||||
<!-- 记录相关模块、流程、配置、文档、外部接口或用户路径 -->
|
||||
|
||||
### 潜在冲突
|
||||
|
||||
<!-- 记录可能与既有行为、约束、依赖、兼容性或用户预期冲突的点 -->
|
||||
|
||||
### 前置条件
|
||||
|
||||
<!-- 记录执行前必须满足的条件；没有则写“无” -->
|
||||
|
||||
## 开放问题
|
||||
|
||||
| 状态 | 问题 | 所需决策 |
|
||||
| ---- | ---- | -------- |
|
||||
| 无 | 无待解决问题。 | 无需决策 |
|
||||
26
openspec/schemas/code-drive/templates/tasks.md
Normal file
26
openspec/schemas/code-drive/templates/tasks.md
Normal file
@@ -0,0 +1,26 @@
|
||||
## 1. <!-- 对应 plan.md 阶段 1 的名称 -->
|
||||
|
||||
- [ ] 1.1 阅读 plan.md 阶段 1，确认涉及文件、关键代码模式和验收标准
|
||||
- [ ] 1.2 <!-- 动词 + 文件路径：具体动作描述，详见 plan.md 阶段 1 -->
|
||||
- [ ] 1.3 <!-- 动词 + 文件路径：具体动作描述，详见 plan.md 阶段 1 -->
|
||||
- [ ] 1.4 <!-- 动词 + 文件路径：具体动作描述，详见 plan.md 阶段 1 -->
|
||||
- [ ] 1.5 <!-- 运行测试或验证命令，确认阶段 1 的关键行为 -->
|
||||
- [ ] 1.6 按 plan.md 阶段 1 的验收标准确认阶段完成
|
||||
|
||||
## 2. <!-- 对应 plan.md 阶段 2 的名称 -->
|
||||
|
||||
- [ ] 2.1 阅读 plan.md 阶段 2，确认涉及文件、关键代码模式和验收标准
|
||||
- [ ] 2.2 <!-- 动词 + 文件路径：具体动作描述，详见 plan.md 阶段 2 -->
|
||||
- [ ] 2.3 <!-- 动词 + 文件路径：具体动作描述，详见 plan.md 阶段 2 -->
|
||||
- [ ] 2.4 <!-- 动词 + 文件路径：具体动作描述，详见 plan.md 阶段 2 -->
|
||||
- [ ] 2.5 <!-- 运行测试或验证命令，确认阶段 2 的关键行为 -->
|
||||
- [ ] 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]`，未完成或阻塞事项已记录
|
||||
Reference in New Issue
Block a user