openspec-shcema/code-drive/schema.yaml

name: code-drive
version: 1
description: 代码开发 OpenSpec workflow - requirements -> design -> plan -> tasks -> apply
artifacts:
  - id: requirements
    generates: requirements.md
    description: 需求确认与澄清，包含业务需求、技术需求和全局审查
    template: requirements.md
    instruction: |
      创建 requirements.md，作为本次变更“要解决什么、为什么要解决、需要确认哪些业务和技术边界”的事实来源。

      阶段职责原则（适用于整个 code-drive workflow，强制）：requirements 是用户决策的唯一入口；design / plan / tasks / apply 不得向用户发起任何决策型提问，遇到本阶段无法独立解决的分歧、上游不完整或边界未定时，必须暂停并回退到上游 artifact（apply 阶段通过 blocker.md 触发，由 blocker-revise 决定回退到哪一层）。允许的非决策型交互仅限：读取文件、运行命令、向用户报告"需要回退到上游"这一事实。本原则意味着用户主动参与的流程集中在 requirements 阶段，下游阶段是自治执行 + 异常回退。

      本阶段用于承接 explore、前序讨论、用户请求和代码库调查结果。requirements.md 面向项目开发者，而不是外部需求方；因此本阶段既要确认业务需求，也要确认技术需求，例如技术选型、架构方向、集成边界、代码约束和验收方式。

      requirements.md 的职责是“确认和澄清”：通过对话把需求、边界、取舍和用户决策固定下来。design.md 的职责是“翻译”：把 requirements.md 中确认的内容转化为可执行的技术方案。不要在 requirements.md 展开详细实现步骤、具体文件修改清单或任务 checkbox。

      语言规则（强制）：

      - code-drive 的 requirements.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文
      - 最终 requirements.md 不得残留英文模板句子、英文占位内容、空表格行或未解决的模板注释，除非该英文是必要技术名词

      工作规则：

      - 用户交互（强制，不得跳过）：requirements 阶段必须向用户至少请求一次显式确认（工具调用或正文明确提问均可）。即使所有内容都已在 explore 阶段或前序讨论中确认充分、YAGNI 挑战无遗留、无任何待确认问题，仍必须执行最终确认；没有任何待确认内容时，最后一问必须是"当前已无更多内容待确认，是否进入下一步"。未得到用户明确肯定回复（同意 / 进入下一步）前，不得结束 requirements 阶段，不得进入 design 阶段
      - 潜在冲突处理（强制）：撰写过程中或自检时一旦发现"潜在冲突"——即任何两条需求、约束或决策之间存在矛盾、取舍未定、可解读不一致或可能相互排斥的情况——必须立即暂停撰写，把冲突点加入向用户确认的流程，按"2-3 个选项 + 推荐方案 + 取舍说明"逐项让用户决策。用户决策后，结论按性质归入对应章节（功能需求 / 非功能需求 / 技术需求 / 被否决方案等），冲突本身不得以任何形式单独保留，也不得以"待协调""需进一步讨论"等模糊措辞残留
      - 待解决问题处理（强制）：requirements.md 不得残留任何形式的"开放问题""TBD""待确认"章节或条目。撰写过程中产生的任何疑问（技术选型分歧、需求边界不清、YAGNI 取舍、依赖约束未定等）必须立即纳入用户确认流程，按"2-3 个选项 + 推荐方案"逐项让用户决策；决策结论按性质归入对应章节（功能需求 / 非功能需求 / 技术需求 / 被否决方案等）。如果某问题确实需要延续到 design 或 apply 阶段才能解决，必须先与用户确认是否拆分变更或暂时不纳入本次范围，不得在 requirements.md 中以"开放问题"形式保留
      - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），复杂变更必须使用它跟踪 requirements.md 的撰写流程（读取上下文、评估范围、提问、全局审查、编写、自检、用户确认），避免遗漏；简单变更可不使用。注意：这里跟踪的是文档撰写进度，不是整体变更的实现进度——整体变更进度由 apply 阶段和 tasks.md checkbox 跟踪
      - 面向看不到早期对话的人编写，必须保留关键上下文、用户偏好、已确认结论、约束和被否决方案
      - 先读取相关上下文并形成初步理解，再向用户提问；不要询问代码库或文档中已经能确认的信息
      - 先评估范围：如果变更涉及多个独立子系统或过大范围，先建议拆解，再对第一个子问题继续澄清
      - 复杂问题必须拆成多个小问题逐步确认；简单问题可以合并确认，但不得一次抛出大量无关问题
      - 优先使用 2-3 个选项 + 推荐方案 + 取舍说明来提问，而不是让用户从零开放回答；如果工具支持，优先使用 question/choice 工具
      - 对每个需求进行 YAGNI 挑战：是否真的需要、能否更简单、是否存在更轻量替代方案、是否超出本次范围
      - 分段呈现理解并逐段确认；复杂内容每段控制在约 200-300 字，确认后再继续下一段
      - 必须进行“全局审查”：从系统边界、既有行为、相邻模块、配置、文档、迁移、兼容性、安全、性能和用户流程角度挑战当前需求
      - 功能需求必须带验收标准；非功能需求只记录本次变更相关内容
      - 技术需求必须记录已确认的技术选型、架构方向、集成边界、代码约束或禁止事项；未确认的技术选项必须先暂停向用户确认，不得擅自定论也不得以未决形式残留
      - 不要写具体文件修改步骤、代码结构、任务 checkbox 或详细实现计划

      必需章节（建议使用模板中的中文章节标题）：背景与目标、讨论记录、功能需求、非功能需求、技术需求、全局审查。

      简单变更保持精炼；复杂或横切变更必须写足够细节，避免后续 design/plan/apply 依赖未写入文档的聊天上下文。

      写完后自检（逐项检查并内联修复，无需二次 review）：

      - 占位符扫描：是否残留模板注释、英文模板句子、TBD、待补充、空表格行或"开放问题"章节
      - 章节完整性：所有必需章节都已填写；功能需求、非功能需求和技术需求没有明显遗漏
      - 上下文一致性：讨论记录中的"已确认结论"都已落入对应章节；被否决方案没有被复用
      - 冲突清零：扫描所有功能需求、非功能需求、技术需求和约束之间是否存在矛盾、歧义或取舍未定；任何"潜在冲突"必须已通过用户确认解决，文档中不得残留"待协调""需进一步讨论"或未决矛盾
      - 待确认问题清零：扫描全文是否存在"开放问题""TBD""待确认""待讨论"等未决条目；任何撰写过程中产生的疑问必须已通过用户确认解决并归入对应章节
      - 全局审查充分性：系统边界、既有行为、相邻模块、配置、迁移、兼容性都被审视过
      - YAGNI：每条需求都经过挑战，没有"未来可能需要但本次不必需"的功能
      - 范围合适：变更聚焦到能用单一 design.md 承接，还是需要拆分为多个子变更

      自检完成后，必须向用户请求最终确认（不得跳过，工具调用或正文明确提问均可）：

      - 展示关键决策点：功能需求、技术需求各一句话总结
      - 如果仍有需要确认的内容（技术选型分歧、YAGNI 取舍、依赖约束未定等），按"2-3 个选项 + 推荐方案"逐项提问
      - 如果确实没有任何待确认内容，必须输出最后一问："当前已无更多内容待确认，是否进入下一步"
      - 用户明确肯定（同意 / 进入下一步）后，本阶段才算结束；用户选择补充或提出修改时，根据用户反馈调整内容并重跑自检 + 再次请求确认
    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 或前序讨论中未被探索过

      探索深度根据变更规模和既有探索充分度调整：

      - 简单变更且 requirements.md 已有充分探索：快速确认即可，无需详细重复记录
      - 复杂变更或 requirements.md 探索不足：详细检查依赖、现有代码、项目规范，并记录发现

      探索结果记录在 design.md 的“代码库探索”章节。如果探索发现与 requirements.md 的假设冲突，视为 requirements 不完整，暂停并要求回退到 requirements 阶段补充决策；不在 design 阶段代替用户做需求层决策。

      工作规则：

      - 阶段职责（强制）：design 阶段不得向用户发起任何决策型提问。本阶段遇到本阶段无法独立解决的分歧、上游不完整或边界未定，必须暂停并回退到 requirements 阶段（让用户在 requirements 上下文中做决策）；允许的非决策型交互仅限：读取文件、运行命令、向用户报告"需要回退到 requirements"这一事实
      - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），复杂变更必须使用它跟踪 design.md 的撰写流程（读取 requirements、代码库探索、编写各章节、自检），避免遗漏；简单变更可不使用。注意：这里跟踪的是文档撰写进度，不是整体变更的实现进度
      - 对关键技术决策给出理由，并记录至少一个被否决方案或主要取舍
      - 如果发现 requirements.md 未对关键技术方向做出唯一决策（即存在多个合理且未排除的方向），视为 requirements 不完整，暂停并要求回退到 requirements 阶段补充决策；不得在 design 阶段代替用户做需求层决策
      - 明确目标、非目标、影响范围、依赖约束、风险权衡
      - 设计必须基于代码库现实，而非从零假设；如果探索发现现有代码可复用，优先复用而非新建
      - 不得引入 requirements.md 未确认的需求、外部依赖、架构方向或范围；如发现必须依赖 requirements.md 未确认的新内容，视为 requirements 不完整，暂停并回退到 requirements 阶段

      必需章节（建议使用模板中的中文章节标题）：代码库探索、整体方案、目标 / 非目标、关键决策、影响范围、依赖与约束、风险 / 权衡、验证方向。

      写完后自检（逐项检查并内联修复，无需二次 review）：

      - 占位符扫描：是否残留模板注释、英文占位内容、空表格行或"待确认事项"章节
      - 需求覆盖：requirements.md 的每条功能需求都有决策覆盖；技术需求被正确引用或落地
      - 决策合理性：每个关键决策有理由，并记录至少一个被否决方案或主要取舍
      - 代码库现实：设计基于代码库探索发现，而非从零假设；没有引入 requirements.md 未确认的新依赖
      - 验证方向对齐：验证方向覆盖了 requirements.md 的功能验收标准和非功能需求
      - 待确认问题清零：扫描全文是否存在"待确认""TBD""待讨论"等未决条目；任何撰写过程中产生的疑问必须已通过回退到 requirements 阶段解决，design.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 不得残留英文模板句子、英文占位内容、空表格行或未解决的模板注释

      工作规则：

      - 阶段职责（强制）：plan 阶段不得向用户发起任何决策型提问。本阶段遇到 design.md 太粗、关键决策缺失或与 requirements.md 冲突，必须暂停并要求修订上游 artifact（回退到 design 或 requirements）；允许的非决策型交互仅限：读取文件、运行命令、向用户报告"需要回退到上游"这一事实
      - 按主要实现阶段组织，每个阶段必须包含目标、前置条件、详细实现步骤、关键代码模式、验证方式、验收标准和关联需求
      - 每个阶段必须列出涉及的文件路径、变更类型，汇总到“涉及文件”章节
      - 将 design.md 的“验证方向”作为“验证策略”的输入，确保验证角度对齐
      - 阶段应足够清晰，使后续 tasks.md 可以只写 checkbox 任务，而不必重新设计实现方案
      - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），复杂变更必须使用它跟踪 plan.md 的撰写流程（读取上游、编写实现概览、编写各阶段、编写验证策略、自检），避免遗漏；简单变更可不使用。注意：这里跟踪的是文档撰写进度，不是整体变更的实现进度
      - 每个阶段应能独立验证，或明确说明依赖哪个前置阶段
      - 不要写 checkbox；不要新增未经 design.md 确认的架构、依赖或范围
      - plan.md 不得残留任何形式的"待确认事项""TBD""待补充"章节或条目；撰写过程中发现的实现层未决问题必须基于 design.md 已有决策自行确定最优解，无法确定则回退到 design 或 requirements 阶段

      必需章节：实现概览、涉及文件、阶段 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 的“验证方向”在“验证策略”中有体现
      - 待确认问题清零：扫描全文是否存在"待确认事项""TBD""待补充"等未决条目；任何撰写过程中产生的疑问必须已通过上游回退解决
    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 不得残留英文模板任务、英文占位内容、空分组或占位任务文本

      编写规则：

      - 阶段职责（强制）：tasks 阶段不得向用户发起任何决策型提问。本阶段遇到 plan.md 过粗、不可验证或与上游 artifact 冲突，必须暂停并要求修订上游 artifact；允许的非决策型交互仅限：读取文件、运行命令、向用户报告"需要回退到上游"这一事实
      - 任务必须从 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 视为执行进度的事实来源。

    执行规则：

    - 阶段职责（强制）：apply 阶段不得向用户发起任何决策型提问。本阶段遇到任何需要决策型用户介入的情况（plan 不可行、需要偏离、引入未确认依赖、与既有行为冲突等），必须通过 blocker 机制统一出口，由 blocker-revise 流程决定是否回退到上游 artifact；允许的非决策型交互仅限：读取文件、运行命令、向用户报告阻塞事实并请求其运行 blocker-revise
    - 按 tasks.md 的依赖顺序处理未完成 checkbox 任务
    - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），必须使用它跟踪当前执行进度：每个未完成任务标记为 in_progress 或 pending，完成后标记为 completed；最终完成状态必须同步回 tasks.md checkbox
    - 每个任务执行前，先读取 plan.md 对应阶段的“涉及文件”“关键代码模式”和“验收标准”，再开始实现；不要只凭 tasks.md 的短描述自行设计实现方案
    - 不得引入 plan.md 未描述的实现路径、依赖、架构或范围；如确需偏离，按本阶段的阻塞处理流程生成 blocker.md，不在 apply 阶段向用户请求决策
    - 只有任务执行完成且获得新的实际验证证据后，才能标记 `[x]`；不得基于假设、推测或“应该可以”标记完成
    - 完成声明禁用模糊措辞：不得用“应该”、“大概”、“看起来”作为完成依据；必须用实际命令输出、测试结果或可观察行为作为证据
    - 如果 tasks.md 与 plan.md 冲突，按本阶段的阻塞处理流程生成 blocker.md，不在 apply 阶段向用户请求决策

    并行执行（如可用）：

    - 如果工具支持 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 / design.md / plan.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 任务会被跳过。