openspec工作流解析：proposal、spec、tasks的明确分工与协作

火车叼位
133 阅读5分钟

OpenSpec 是一个专为 AI 编码助手设计的规范驱动开发系统，旨在编写代码之前建立人与 AI 之间的对齐。通过在实现之前锁定意图，OpenSpec 提供了确定性、可审查的输出，而无需 API 密钥。

OpenSpec 引入了一个轻量级的规范工作流，改变了你与 AI 编码助手的协作方式。它不再依赖聊天历史记录来获取需求，而是创建了一个明确的结构化契约，供人类和 AI 工具持续参考。这种方法确保提案、任务和规范更新在整个开发生命周期中保持可见、可审计和明确。

该系统通过原生斜杠命令或 AGENTS.md 约定支持 20 多种 AI 工具，使其既灵活地集成到你现有的工作流中，又能提供足够的结构以在复杂的多文件更改中保持一致性。

三者定位：OpenSpec工具中的角色

在OpenSpec工具中，这三份文档具有明确的定位：

  • proposal.md = 变更提案文档（为什么改、改什么、影响范围）
  • spec.md = 规格定义文档（系统最终应该怎么工作）
  • tasks.md = 任务执行清单（具体怎么完成、进度跟踪）

它们在OpenSpec工作流中的主次关系：

  1. proposal.md 是决策起点：在使用OpenSpec管理变更时，任何改动都从创建proposal.md开始。它阐述变更的理由（Why）、概述内容（What）、明确影响范围（Impact）。这份文档是团队讨论是否接受该变更的决策依据，通常篇幅较短。

  2. spec.md 定义验收标准：当proposal被接受后，需要编写spec.md来详细定义系统行为的规格说明。在OpenSpec中，spec通常采用BDD风格（WHEN/THEN）来定义需求和场景，它是验收的黄金标准，也是篇幅最长的文档。

  3. tasks.md 指导具体执行：基于proposal的目标和spec的规格，tasks.md将变更拆解为可执行、可跟踪的任务列表，每个任务都带有checkbox。在OpenSpec工作流中，开发者按照tasks.md一步步完成，并打钩标记进度。

核心区别可以概括为：

  • Proposal 回答"为什么要做这个变更"
  • Spec 回答"变更后系统应该是什么样"
  • Tasks 回答"如何一步步完成这个变更"

OpenSpec工作流中的可视化关系

为了更直观地理解它们在OpenSpec工具中的协作关系，我们可以用图表来描述。

结构关系图展示了文档间的产出与参照关系：

graph TD
    A[proposal.md<br/>变更提案] -->|产出| B[spec.md<br/>规格定义]
    A -->|分解为| C[tasks.md<br/>任务清单]
    B -.参照.-> C
    
    classDef proposal fill:#e1f5ff,stroke:#0366d6,stroke-width:2px
    classDef spec fill:#fff5e1,stroke:#d73a49,stroke-width:2px
    classDef tasks fill:#e1ffe1,stroke:#22863a,stroke-width:2px

图表说明：在OpenSpec中，proposal.md是变更的起点，产出spec.md（定义验收标准）并分解为tasks.md（执行清单）。tasks在执行过程中会参照spec的验收标准。

时序图展示了OpenSpec工作流中的时间顺序：

sequenceDiagram
    participant Dev as 开发者
    participant P as proposal.md
    participant S as spec.md
    participant T as tasks.md
    participant Code as 代码实现

    Dev->>P: 1. 创建变更提案<br/>(Why/What/Impact)
    Note over P: 团队决策：是否接受变更？
    
    Dev->>S: 2. 编写规格说明<br/>(WHEN/THEN 场景)
    Note over S: 定义验收标准
    
    Dev->>T: 3. 分解任务清单<br/>(可执行步骤)
    Note over T: 规划实施路径
    
    loop 迭代开发
        Dev->>Code: 4. 实现代码
        Code-->>T: 完成任务打钩 [x]
        Code-->>S: 满足规格场景
    end
    
    Note over Dev,Code: 所有 tasks 完成 + spec 通过验证<br/>→ 准备归档

图表说明：OpenSpec工作流始于变更提案决策，经过规格定义和任务规划，进入迭代开发，最终以完成所有任务并满足规格为结束标志，准备归档。

OpenSpec工作流的关键阶段

在使用OpenSpec工具管理变更时，整个流程可以分为五个清晰的阶段：

  1. 提案阶段：在OpenSpec的changes目录下创建proposal.md，阐述变更理由，团队讨论并决定是否接受该变更。
  2. 设计阶段：编写spec.md，明确变更后系统行为的详细契约和验收标准。这是OpenSpec强调的"设计先行"原则。
  3. 规划阶段：编写tasks.md，将变更拆解为具体、可执行的任务项，每个任务都带有checkbox。
  4. 开发阶段：按照tasks.md进行编码，并持续对照spec.md进行验证，完成一项打钩一项。OpenSpec鼓励"小步快跑"的迭代方式。
  5. 归档阶段：当所有tasks完成且spec通过验证后，将整个变更文档从changes目录移至archive/目录，标志变更完结。

实际案例：add-feedback-command

以OpenSpec项目本身的github.com/openspec/op…

文件核心内容行数（约）在OpenSpec中的作用
proposal.mdWhy: 需要收集用户反馈
What: 添加 openspec feedback 命令
Impact: 新增CLI命令、依赖 gh CLI		21 行变更决策依据，说明变更必要性和范围
spec.md6个主要需求、20+个具体场景
详细定义命令行为、错误处理、跨平台兼容性		189 行验收标准定义，详细定义"正确"行为
tasks.md4大模块、30+个子任务
从命令实现、参数解析到测试覆盖，全部带checkbox		31 行执行路线图，指导开发一步步完成变更

从这个案例可以看出，在OpenSpec工具中，spec.md是篇幅最大、最详细的文档，因为它承载了最终的质量标准；而proposal.md和tasks.md则更偏向于变更管理和执行规划。

小结与延伸

在OpenSpec工具中，将proposal.md、spec.md和tasks.md清晰分离，是工具设计哲学的核心体现。这种分离确保了：

  • 关注点分离：决策者、设计者和执行者都能获得最相关、最清晰的信息
  • 强制设计先行：在动手编码前必须思考清楚"为什么改"、"改什么"和"怎么改"
  • 可追溯性：从提案到实现，每个环节都有明确文档记录
  • 质量可控：通过spec.md的详细定义，确保最终交付符合预期

如果你想进一步了解OpenSpec工具的设计哲学：

清晰定义每个文档的职责，是使用OpenSpec工具进行高效变更管理的重要基础。希望这篇解析能帮助你更好地理解和应用OpenSpec的文档工作流。

avatar
文章
阅读
粉丝