告别死板流程：OpenSpec OPSX 如何重塑 SDD 开发工作流

引言：SDD 与 OpenSpec

规范驱动开发（SDD）是什么？

近两年，AI 编码助手已经能"听懂人话"，从一段自然语言描述里生成大段代码。但很多团队也发现：如果需求只是散落在聊天记录里、脑补在每个人的心里，AI 很容易"发挥过度"------代码写出来了，却不是你真正想要的系统行为。

规范驱动开发（Spec-Driven Development，SDD）试图解决的，就是这个问题。它把规范（spec）而不是代码 当成系统的"单一事实来源"：先用结构化、机器可读的方式，把系统应该做什么、有哪些边界和不变量写清楚，再让代码、测试和文档都围绕这份规范生成和验证。在 InfoQ 的文章中，SDD 被形容为一种"可执行架构"：规范不只是说明书，而是驱动生成代码、检测漂移、持续验证行为的控制平面，架构不再是建议，而是可以被执行和强制的规则。

在 AI 时代，这种思路格外契合：

人类更多精力放在表达意图、约束和政策上；
机器根据规范去生成代码、测试和各种工件，并不断对照规范做校验；
一旦实现和规范不一致，就通过自动化验证或"漂移检测"及时发现和纠正。

换句话说，SDD 把人与 AI 的分工，从"人写代码、AI 帮补全"提升为"人维护意图和规范、AI 负责具体实现"，让协作的重心回到"说清楚要什么"上。

OpenSpec：一套轻量的 SDD 工作流

OpenSpec 就是在这个背景下长出来的一个开源框架，它不是再造一门 DSL，而是用非常接地气的方式，把 SDD 变成日常可以落地的工作流。项目本身在 GitHub 上开源，OPSX 工作流的详细说明则在官方文档中有完整介绍：docs/opsx.md。

OpenSpec 的核心结构可以概括成两块：

openspec/specs/：系统当前"事实"的所在，按业务域组织的规范文件，描述的是现在这个系统实际如何工作。
openspec/changes/：正在进行中的变更，每个变更一个文件夹，里面通常包含：
- proposal.md：为什么要做、准备做什么；
- design.md：怎么做、关键技术决策；
- tasks.md：拆分出的实施任务；
- specs/：本次变更对应的 delta specs（增量规范），只写"新增/修改/删除了哪些行为"。

当一个变更完成、归档时，OpenSpec 会把这些 delta specs 合并回主目录下的 specs/，并把整个 change 文件夹挪到 changes/archive/，形成一条可追溯的"规范演化历史"。

从理念上看，OpenSpec 还强调几个关键特性：

fluid / iterative：不再把工作强行切成"规划 → 实现 → 结束"的刚性阶段，而是鼓励在实现过程中不断回头修正规范与设计；
easy：初始化成本尽量低，文件就是 Markdown / YAML，任何编辑器都能打开；
brownfield-first：尤其关注"在已有系统上做增量变更"的场景，用 delta specs 把"今天要改什么"说清楚，而不是重写一份大而全的文档。

在这样的设计下，人与 AI 的协作模式也发生了改变：人通过 OpenSpec 的目录结构和文档规范，把上下文、约束和预期行为喂给 AI；AI 则在这些约束之内，去生成代码、补全文档、拆解任务甚至回填测试。两者真正对齐的，是那一份份可以被执行、可以被验证的规范。

下面这篇文章，就从"为什么需要 OPSX"开始，展开介绍 OpenSpec 在 OPSX 工作流中如何把这些 SDD 的理念落到实处，以及它和我们熟悉的 OpenAPI、BDD、RFC 流程之间的关系。

为何需要 OPSX：从"阶段"到"行动"的进化

传统的软件开发流程，即便是敏捷模型，也常常被一种无形的"阶段论"所束缚。我们习惯于说"现在是规划阶段"、"接下来是实现阶段"，最后是"完成阶段"。这种线性的思维模式看似有序，却与真实的工作场景格格不入。在实际开发中，我们常常在实现某个功能时才发现最初的设计存在缺陷，需要回过头去修改规范，然后再继续编码。线性阶段划分对抗的正是这种"边做边学、边学边改"的自然迭代过程。

旧版的 OpenSpec 工作流在一定程度上也固化了这种线性思维。它通过一个全有或全无的大命令一次性生成所有规划制品，当 AI 的输出不理想，或者在实现过程中需要调整设计时，用户很难优雅地"回头"修改，只能手动编辑文件（这会破坏上下文）、放弃并重新开始，或者硬着头皮继续然后寄望于未来修复。

OPSX 的诞生，正是为了打破这种僵化的"阶段制"，转向一种更符合直觉的"行动化"工作流。

OPSX 的核心理念是：重要的不是你处在哪个"阶段"，而是你可以采取哪些"行动" 。它将开发过程解构为一系列离散的、可随时调用的动作，如 propose（提议）、explore（探索）、apply（应用）、archive（归档）等。这些动作之间由依赖关系连接，但这种依赖是"赋能"而非"锁定"。例如，你需要先有一个 proposal（提案），才能开始编写 specs（规范），但这并不意味着你不能在编写规范的过程中回头更新提案。

这种从"阶段锁定"到"行动赋能"的转变，带来了根本性的体验提升：

告别"全有或全无"：你可以一次只生成一个制品，验证其输出，然后再决定下一步行动。
拥抱迭代 ：在实现（apply）过程中发现设计不合理？没问题，直接编辑 design.md 文件，然后继续 apply，OPSX 会智能地从你中断的地方继续。
高度可定制 ：所有指令和工作流定义都从代码中解耦，变成了你可以直接编辑的 YAML (schema.yaml) 和 Markdown (templates/*.md) 文件。这意味着团队可以根据自己的工作习惯，定义专属的制品、依赖关系和提示词。
透明可控：当 AI 输出质量不佳时，你不再是面对一个"黑盒"。你可以直接调整模板文件中的提示指令，然后立即重试，快速找到最佳实践。

可以说，OPSX 将 OpenSpec 从一个相对固定的框架，变成了一个高度可塑的、鼓励实验和持续改进的平台。它让"规范"真正地"流动"了起来。

OPSX 核心理念与差异化解析

要深入理解 OPSX，我们需要剖析其背后的几个关键设计。正是这些设计的组合，使其在众多开发流程中显得与众不同。

1. "制品"（Artifacts）与依赖图（DAG）

OPSX 将每一次变更（Change）所需的所有文档都定义为"制品"（Artifacts）。在默认的 spec-driven 模式下，一次典型的变更包含以下四个核心制品：

proposal.md：定义变更的意图（Why） 、范围（What）和高层方法（How）。
specs/**/*.md：以增量（Delta）形式描述行为变更的细节，是可验证的需求。
design.md：阐述技术实现方案和架构决策。
tasks.md：具体的实现步骤清单。

这些制品并非孤立存在，而是构成了一个有向无环图（Directed Acyclic Graph, DAG） 。schema.yaml 文件负责定义这个图的结构，明确指出创建某个制品需要哪些前置制品。

yaml 复制代码

# 摘自 OpenSpec 默认的 schema.yaml
artifacts:
  - id: proposal
    generates: proposal.md
    requires: [] # 无依赖，是根节点
  - id: specs
    generates: specs/**/*.md
    requires: [proposal] # 依赖 proposal
  - id: design
    generates: design.md
    requires: [proposal] # 也依赖 proposal
  - id: tasks
    generates: tasks.md
    requires: [specs, design] # 依赖 specs 和 design

这个 DAG 模型是 OPSX 流动性的基石。它清晰地展示了信息流：从高层的"为什么"到具体的"做什么"，再到"怎么做"和"分几步做"。同时，它也赋予了流程极大的灵活性------specs 和 design 都可以基于 proposal 并行创建，开发者可以根据情况决定先思考哪一个。

2. 基于文件系统的"状态机"

OPSX 如何知道一个制品是否"完成"？它的状态机模型异常简单：通过检查文件系统中是否存在对应的制品文件来判断。

一个制品有三种状态：

BLOCKED：其依赖的前置制品尚未创建。
READY：所有依赖都已创建（即对应的文件存在），可以被创建。
DONE：该制品自身的文件已经存在于文件系统中。

当你执行 /opsx:continue 或其他命令时，OPSX 会查询当前变更目录下各个制品的状态，并基于 DAG 找出处于 READY 状态的制品，然后引导 AI 生成它。这种简单而有效的设计，使得整个工作流的状态都明确地反映在你的版本控制系统里，既直观又可靠。

3. 可定制的 Schema 与模板

OPSX 的强大之处在于，上述的 DAG 结构和生成制品所用的提示词都不是固化的。你可以通过创建自己的 schema.yaml 来定义全新的工作流。

例如，一个团队可能认为在 proposal 之前需要先进行一步 research（调研），并且在简单的项目中可以直接从 proposal 跳到 tasks，那么他们可以这样定义自己的 Schema：

yaml 复制代码

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []
  - id: proposal
    generates: proposal.md
    requires: [research]
  - id: tasks
    generates: tasks.md
    requires: [proposal]

对应的，他们只需在 templates/ 目录下提供 research.md、proposal.md 和 tasks.md 三个模板文件，里面包含了指导 AI 生成该制品的 Markdown 格式的提示。这种高度的可定制性，让不同团队能够将自己独特的、经过验证的最佳实践沉淀为工具，而不是让工具来约束人。

4. 开放的迭代模型

前面提到，OPSX 允许在任何时候回头修改已生成的制品。这不仅是一种"允许"，更是一种被鼓励的"迭代模型"。

当更新 vs. 开启一个新变更？ OpenSpec 的文档给出了明确的启发式规则：

更新现有变更 ：当变更的核心意图不变 ，只是执行细节、方法或范围的微调时。比如，在实现中发现某个库不如预期，需要更换技术方案；或者，在add-dark-mode（添加暗黑模式）的需求中，决定先发布一个 MVP 版本，将"跟随系统偏好"的功能留到 v2。这些都属于对现有上下文的"精炼"，保留变更历史是有价值的。
创建全新变更 ：当意图发生根本性改变 时。比如，add-dark-mode 演变成了 add-a-comprehensive-theme-system（添加一个完整的自定义主题系统）；或者，fix-login-bug（修复登录bug）膨胀成了 rewrite-auth-system（重写认证系统）。此时，强行在旧的变更上打补丁只会让历史记录混乱不堪，开启一个清晰的新变更才是更合理的选择。

这个决策模型的核心原则是：更新是为了保留有价值的思考上下文，而新建是为了追求清晰性。这与我们使用 Git 分支的逻辑不谋而合。

与其他实践的对比

将 OPSX 与业界其他流行实践进行比较，能更清晰地看到它的独特价值。

vs. OpenAPI/Swagger + 代码生成

OpenAPI (前身 Swagger) 是 API 设计领域的"规范驱动"典范。它通过一个 YAML 或 JSON 文件精确定义 API 的端点、数据结构和行为，然后可以基于这个规范文件自动生成客户端 SDK、服务端桩代码（stub）和 API 文档。参见 Swagger 官方博客《Code-First vs. Design-First API Approaches》。

相似之处：二者都遵循"规范先行"的理念，都拥有一个机器可读的规范文件作为核心，并能据此生成代码或文档。
差异与互补 ：
- 范围不同 ：OpenAPI 主要聚焦于 API 契约 层面，它精确描述"接口长什么样"，但对"为什么要有这个接口"（业务意图）、"接口背后的复杂业务逻辑"以及"如何分步实现"等关注较少。而 OPSX 覆盖了从意图（Proposal）到任务（Tasks）的完整生命周期 ，OpenAPI 规范本身更像是 specs 或 design 制品的一部分，用于承载具体的 API 设计。
- 灵活性与迭代 ："设计优先"（Design-First）的 OpenAPI 流程，一旦规范确定，后续的变更管理相对严肃。如果代码实现与规范产生"漂移"，就会带来一致性问题。（可参考 Swagger 官方《Code-First vs. Design-First API Approaches》中对设计优先流程的讨论。）OPSX 的流动性设计，使得在实现过程中回头修正 specs 或 design 成为常态，它更侧重于开发过程中的动态演进，而非仅仅是发布前的契约定义。
- 人工与 AI 的角色：OpenAPI 的代码生成器是确定性的工具，输入一份规范，输出固定的代码结构。而 OPSX 从设计之初就与 AI 编码助手深度绑定，它生成的不是死板的模板代码，而是结合了项目上下文、规范要求和 AI 推理能力的、更接近最终实现的业务逻辑代码。规范在这里是指导 AI 进行"创作"的蓝图。

总的来说，OpenAPI 和 OPSX 并非竞争关系，而是理想的互补关系 。我们完全可以在 OPSX 的 design.md 制品中嵌入 OpenAPI 规范，用它来精确描述 API，同时利用 OPSX 的其他制品来管理整个变更的生命周期。

vs. BDD/Gherkin

行为驱动开发（BDD）及其描述语言 Gherkin（使用 Given-When-Then 语法）是另一种强调"规范即测试、规范即文档"的实践。它通过编写业务人员和开发者都能理解的自然语言场景，来驱动软件功能的开发。（可参考 Cucumber 官方博客《Gherkin Rules》）

相似之处 ：二者都强调使用接近自然语言的方式来描述系统行为，并以此作为团队协作的共同语言。OpenSpec 的 spec.md 中也推荐使用 Gherkin 风格的场景描述。
差异与互补 ：
- 关注点不同 ：Gherkin 主要关注可验证的外部行为 ，它的核心目标是让"需求"本身可以变成自动化测试用例。而 OPSX 的 specs 虽然也描述行为，但整个工作流还包含了 proposal（意图）和 design（技术实现）等更上游和更下游的环节。
- "人"与"机器"的平衡 ：BDD 的初衷是促进"人与人"（业务、开发、测试）之间的对话与共识。（可参考 Cucumber 官方博客《Gherkin Rules》对 Gherkin 作为团队通用语言的阐述。）Gherkin 场景虽然可以被 Cucumber 等工具自动化，但其首要价值在于沟通。OPSX 则更进一步，它不仅要让人能读懂，还要让 AI 能读懂。OPSX 的制品是写给人和 AI 的"双向文档"，其结构和内容都经过精心设计，以优化 AI 的理解和生成效果。
- 工作流的封装 ：BDD/Gherkin 本身是一种描述需求的"语言"，它并不内建一套完整的工作流。团队需要自己决定如何组织和管理这些 .feature 文件。而 OPSX 提供了一套开箱即用且可定制的、围绕制品生命周期管理的完整工作流。

可以说，Gherkin 是实践 OPSX 中 specs 制品的优秀"语法"，而 OPSX 则是承载和驱动这些 specs 从诞生到实现的"操作系统"。

vs. 传统 RFC 流程

在许多技术公司，尤其是拥有分布式团队的公司，都采用"请求意见"（Request for Comments, RFC）流程来对重要技术变更进行决策。工程师会撰写一份详细的技术设计文档，发送给相关人员征求反馈，达成共识后再开始实施。（可参考 The Pragmatic Engineer《Scaling Engineering Teams via RFCs: Writing Things Down》中对大型团队 RFC 流程的总结。）

相似之处 ：二者都是为了在重大变更前，通过书面化的方式进行深入思考、暴露风险、达成共识。OPSX 的 proposal.md 和 design.md 就扮演了轻量级 RFC 的角色。
差异与互补 ：
- 重量级 vs. 轻量级：传统的 RFC 往往是一个相对"重"的过程，适用于大型、复杂或跨团队的架构性变更。对于日常的、单一团队内的功能开发，走一次完整的 RFC 流程可能会显得过于繁琐。OPSX 则更加轻量，它将 RFC 的精神融入到每一次独立的"变更"中，使其成为日常开发的标准动作，而不是一个需要特意启动的"仪式"。
- 静态文档 vs. 动态制品：RFC 文档一旦被批准，其生命周期往往就结束了，它更多是一个"决策快照"。而 OPSX 的制品是"活"的，它们在整个开发过程中持续演进，并且与最终的代码实现紧密关联，甚至可以由 AI 直接转换为代码。
- 异步沟通 vs. 人机协作：RFC 的核心是"人与人"之间的异步沟通。而 OPSX 的核心是"人机协作"，制品不仅要给人看，更要给 AI 看，并由 AI 将其"具象化"。

因此，OPSX 可以被看作是一种将 RFC 理念"日常化"、"轻量化"和"AI 原生化"的现代实践 。对于特别重大的变更，团队仍然可以走正式的 RFC 流程，然后将最终的 RFC 文档作为 OPSX proposal 的输入，再利用 OPSX 的工作流来驱动后续的详细设计、任务拆解和 AI 编码。

架构剖析与命令概览

理解了 OPSX 的理念，我们再深入其技术架构和常用命令，看看它是如何将这些理念转化为实际工具的。

架构：从硬编码到外部 Schema

OPSX 的架构演进，是从一个硬编码模板 的封闭系统，走向一个由外部 Schema 和依赖图引擎驱动的开放系统的过程。

旧版工作流：其核心逻辑和提示模板都硬编码在 TypeScript 代码中。这意味着任何定制都需要修改源码、重新构建和发布，对普通用户来说基本是黑盒。
OPSX 工作流 ：其核心是一个"制品图谱引擎"（Artifact Graph Engine）。这个引擎负责：
1. 读取 Schema ：解析 schema.yaml 文件，了解有哪些制品以及它们之间的依赖关系。
2. 状态检测 ：通过扫描文件系统，判断每个制品当前处于 BLOCKED、READY 还是 DONE 状态。
3. 生成指令 ：当需要创建一个制品时，它会加载对应的 .md 模板，并智能地注入项目配置 (openspec/config.yaml) 中定义的全局 context 和特定于该制品的 rules。
4. 与 AI 交互：将整合好的、富含上下文的指令发送给 AI 编码助手，并接收其生成的制品内容。

这种架构的转变，是 OPSX 灵活和可定制的根本原因。它将"工作流定义"彻底从"工具实现"中剥离了出来。

常用命令概览

OPSX 提供了一套围绕"行动"设计的命令，可以通过 AI 助手的斜杠命令 /opsx:* 或在终端中直接使用 openspec CLI 来调用。

核心命令 (默认)	作用
`/opsx:explore`	探索想法。一个自由的"头脑风暴"空间，没有固定结构，在你还不确定要做什么时非常有用。
`/opsx:propose`	提出变更。这是启动一个新变更最快捷的方式，它会一次性生成所有规划阶段的制品（proposal, specs, design, tasks）。
`/opsx:apply`	实施变更。进入编码阶段，AI 会根据 `tasks.md` 中的任务清单逐一实现功能，并在你确认后勾选任务。
`/opsx:archive`	归档变更。当所有任务完成，用此命令来结束变更。它会将增量规范合并到主规范库，并把整个变更文件夹移入存档。

除了这套核心命令，OpenSpec 还提供了一套扩展工作流 （可通过 openspec config profile 开启），提供更细粒度的控制：

扩展命令	作用
`/opsx:new`	新建变更脚手架。只创建一个空的变更目录，让你决定下一步做什么。
`/opsx:continue`	步进式创建制品。每次只创建一个处于 `READY` 状态的制品，适合需要仔细思考和验证每一步的场景。
`/opsx:ff`	快进式创建制品。与 `propose` 类似，一次性生成所有规划制品，适合需求非常明确的场景。
`/opsx:verify`	验证实现。检查代码实现是否与 `specs` 中的规范保持一致。

这套命令系统，让开发者可以根据任务的确定性程度，自由选择"快进"或"慢走"，在效率和审慎之间取得平衡。

适用场景与落地建议

那么，在实际工作中，我们该如何应用 OPSX 呢？

从 0 到 1：开启你的第一个 OPSX 变更

安装与初始化 ：首先，确保你已经安装了 OpenSpec CLI。在你的项目根目录下运行 openspec init。这会自动在你的项目中创建 openspec/ 目录结构，并为你的 AI 编码助手（如 VS Code 的 Claude 插件）安装好技能（Skills）。
（可选）配置项目上下文 ：打开 openspec/config.yaml，在 context 字段下填写你项目的基本情况，如技术栈、编码规范、API 风格、测试框架等。这一步非常关键，它能极大地提升 AI 生成代码的质量和一致性。你还可以为特定制品添加 rules，强制 AI 遵循某些规则，例如要求 proposal 必须包含回滚计划。
探索或提议 ：
- 如果需求还比较模糊，使用 /opsx:explore 和 AI 进行对话，梳理思路。
- 如果需求已经明确，直接使用 /opsx:propose "一句话描述你的变更" 来快速启动。例如：/opsx:propose "为用户个人资料页添加头像上传功能"。
审查与微调制品 ：AI 会为你生成 proposal.md, specs/, design.md, tasks.md。花点时间审查这些由 AI 生成的文档，特别是 specs 和 design，确保它们准确地反映了你的意图。此时，你可以随时手动修改它们，或者要求 AI 重新生成。
开始实施 ：一切就绪后，执行 /opsx:apply。AI 会开始根据 tasks.md 编码，每完成一步都会向你确认。这是一个与 AI 结对编程的绝佳过程，你可以随时介入、指导或修正。
完成并归档 ：所有任务都打上勾后，运行 /opsx:archive，漂亮地完成这次变更。你的项目规范也随之自动更新。

团队如何定制与推广

当团队希望引入 OPSX 时，可以采取渐进式策略：

建立共识与培训：首先，让团队成员理解 SDD 和 OPSX 的核心价值。可以从一两个试点项目或"创新日"活动开始，体验完整的工作流。
共建项目 config.yaml ：组织一次团队会议，共同编写项目的 config.yaml。这个过程本身就是一次对齐团队技术规范和约定的好机会。
从默认 Schema 开始 ：初期不必急于创建自定义 Schema，先在默认的 spec-driven 工作流上跑顺。
沉淀自定义 Schema ：当团队发现默认流程无法满足某些特定场景时（例如，需要引入"安全审查"或"数据模型设计"等独立制品），再由资深成员牵头，通过 openspec schema fork 命令复刻一份现有 Schema，并在此基础上进行修改，沉淀出团队的专属工作流。
建立审查机制 ：将 OPSX 制品的审查（尤其是 proposal 和 specs）作为 Code Review 之前的一个环节。这能确保在投入大量精力编码前，需求和设计已经得到了充分的评审。

风险与误用场景

和任何工具一样，OPSX 也有被误用的风险。以下是一些需要警惕的场景：

过度模板化，僵化流程：虽然 OPSX 提供了强大的定制能力，但如果团队设计出过于繁琐、复杂的 Schema，强迫每个小变更都经过几十个制品的审批，那就会违背其"轻量"、"流动"的初衷，重新陷入官僚主义的泥潭。
上下文注入不当 ：config.yaml 中的 context 是一个强大的工具，但如果注入了过多无关、过时或自相矛盾的信息，反而会干扰 AI 的判断，导致其生成低质量的代码。context 应该保持简洁、准确和高信息密度。
忽视制品审查 ：完全信任 AI 生成的制品，不加审查直接进入 apply 阶段是极其危险的。AI 可能会误解你的意图或遗漏关键的边界条件。制品本身也应被视为代码，需要经过人的审查和确认。
仓库治理问题 ：随着项目进行，changes/ 目录下可能会堆积大量进行中或已废弃的变更。团队需要建立良好的"卫生"习惯，定期清理和归档变更，保持工作区的整洁。

关键在于，工具是手段而非目的。OPSX 的目标是促进"更清晰的思考"和"更顺畅的协作"，任何让这个过程变得更笨拙的做法，都值得警惕。

小结：让思考回归开发的核心

OPSX 工作流并非要取代开发者的思考，恰恰相反，它的目标是将思考的过程重新置于开发活动的核心，并将其显性化、结构化和可追溯。它承认软件开发天然的探索性和迭代性，并试图提供一套足够灵活的脚手架，来承载和引导这个过程。

通过将开发流程解构为一系列离散的、由 AI 赋能的"行动"，OPSX 成功地打破了传统线性阶段的束缚，让开发者可以在"规范的确定性"和"迭代的灵活性"之间找到一个动态的平衡点。它不仅仅是一个工具，更是一种思维方式的转变：

从关注交付速度 ，转向关注理解深度。
从人适应工具 ，转向工具适应团队。
从与 AI 的模糊对话 ，转向与 AI 的精准协作。

在 AI 真正成为软件工程领域"副驾驶"的今天，如何与之高效、可靠地协作，决定了我们能走多远。像 OpenSpec OPSX 这样的实践，正是对这个问题的有力回答。它提醒我们，在代码生成能力日益强大的未来，真正稀缺的、不可替代的，永远是高质量的思考和清晰的表达。

下一次当你面对一个复杂需求时，不妨抛开直接动手的冲动，尝试用 /opsx:propose 来开启一次"规范先行"的旅程。或许，你会发现，让思考先行一步，最终会让你跑得更快、更稳。