Alfred/openspec/schemas/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，作为本次变更“要解决什么、为什么要解决、需要确认哪些业务和技术边界”的事实来源。

      本阶段用于承接 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 任务会被跳过。