OpenSpec 深度指南：从原理到实战，让 AI 编程告别返工

AI 辅助编程的痛点不是"AI 不够聪明"，而是"需求没有对齐"。OpenSpec 通过一套轻量级的规范驱动工作流，让开发者在写代码之前先与 AI 达成共识，将 AI 编码从"一次性对话"升级为"可追溯、可复盘、可协作"的工程化实践。

一、OpenSpec 是什么

OpenSpec是由 Fission-AI 团队开源的一款规范驱动开发框架（Spec-Driven Development Framework），专门为解决 AI 编程中的核心痛点——需求对齐而设计。

在传统的 AI 辅助开发中，开发者直接把模糊的需求丢给 AI，AI 生成代码后往往遗漏关键功能、添加冗余逻辑、与现有架构不兼容——更糟糕的是，每次对话结束，需求历史就消失了，下一次又要"从零开始"。

OpenSpec 的设计哲学可以用五个关键词概括：流动而非僵化、迭代而非瀑布、简单而非复杂、为存量项目而生、从个人项目到企业级扩展。它的核心理念非常简单：在写代码之前，先把需求、设计、任务全部落地成文件，让规范和代码一样纳入版本管理。

核心设计哲学

二、OpenSpec 能解决什么问题

传统 AI 编程的三大痛点

与同类工具对比

核心收益

OpenSpec 带来的价值可以浓缩为四点：

• 减少返工——在编码前对齐需求，避免方向性偏差；
• 持久上下文——规范即文档，不随会话结束而消失；
• 团队协作——基于 Git 的规范审查和共享，新人快速上手；
• 工具无关——一套规范，可以在 Cursor、Claude Code、Copilot 等任意工具间复用。

三、基于什么原理：Delta Specs 机制

OpenSpec 最核心的机制是Delta Specs（增量规范）。这是让它能适用于已有项目改造的关键设计。

什么是对比增量规范

传统规范系统要求你描述整个系统的行为，而 OpenSpec 的对比增量规范只记录本次变更涉及的部分。假设系统有 100 个 API，本次只新增 1 个——Delta Spec 只描述这 1 个新 API 的行为，不会把已有的 100 个再写一遍。

每次/opsx:propose在changes/<name>/specs/下生成增量 spec，包含三部分：

整体架构

OpenSpec 将工作组织为两个主要区域：specs/是权威基准，描述系统当前行为，归档时合并；changes/是提议中的修改，每个变更一个独立文件夹。

openspec/ ├── specs/ # 主规范（单一事实来源） │ └── <domain>/ │ └── spec.md ├── changes/ # 提议中的变更 │ └── <change-name>/ │ ├── proposal.md # 做什么、为什么 │ ├── design.md # 技术方案 │ ├── tasks.md # 执行任务清单 │ └── specs/ # 增量规范（正在变化的内容） │ └── <domain>/ │ └── spec.md └── config.yaml

这种分离的精妙之处在于：多个变更可以并行存在而不冲突，在变更影响主规范之前先进行审查，归档时 Delta 会干净地合并回主规范。

四个核心产物

产物之间存在依赖关系：proposal（根节点）→ specs 和 design（可并行）→ tasks（需 specs 和 design 都完成）。这种设计让每个产物都有明确的上下文，AI 不会凭空发挥。

四、怎么干：从安装到归档的完整流程

4.1 环境安装

前置条件：Node.js 20.19.0 或更高版本。OpenSpec 支持 npm、pnpm、yarn、bun 和 nix 多种安装方式：

# npm 全局安装npminstall-g@fission-ai/openspec@latest# 验证安装openspec--version

4.2 项目初始化

进入你的项目目录，执行初始化命令：

cdyour-project openspec init

初始化过程中，OpenSpec 会询问你使用的 AI 工具（Claude Code、Cursor、Windsurf 等 25+ 选项），按空格键勾选你需要的工具，回车确认后会自动生成对应的配置文件。如果你使用 trae 插件，注意 trae 只生成 skills 文件，不会生成 commands 文件。

4.3 核心工作流

OpenSpec 的推荐工作流是：/opsx:explore → /opsx:propose → 人工审核 → /opsx:apply → /opsx:verify → 人工审核代码 → /opsx:archive。

两个关键原则：

原则一：重新开一个会话。Propose（提案）、Apply（实施）、Verify（验收）、Archive（归档）各自使用独立的会话，“该省省该花花”。每次从零开始的上下文，才能保证 AI 输出质量不会逐轮下降。

原则二：不要手动改文件。所有 .md 文件的修改都通过 AI 完成。手动修改 proposal.md 会导致 tasks.md 与 proposal.md/design.md 不一致。如果 AI 理解不对，在同一个会话中告诉它，让它自己改，同时更新所有相关的 .md 文件。

完整工作流七步：

1. 探索需求—/opsx:explore <描述>
2. 提交提案—/opsx:propose <描述>
3. 人工审核— 审查 proposal / design / spec
4. AI 实施—/opsx:apply <spec-id>
5. AI 验收—/opsx:verify <spec-id>
6. 人工验收— 审查代码质量
7. 归档变更—/opsx:archive <spec-id>

4.4 常用命令速查

4.5 两种工作流模式

OpenSpec 提供两种模式：简洁工作流（推荐新手）只需三个命令propose → apply → archive；扩展工作流（适合复杂项目）提供更多控制，包括/opsx:new、/opsx:continue、/opsx:ff、/opsx:bulk-archive等。通过openspec config profile切换。

五、实战案例

案例一：新增一个物流数据推送接口

以下是来自飞书文档的真实案例——在分拣机系统中，需要从"推送简版落格数据"升级为"推送完整分拣明细数据"：

DropChuteEventListener 落格事件触发后，仅推送了简版的 DropChuteOrderBO（批次号、运单号、格口号、组织、分拣序号）到 Order 的 /order/api/sortBag/scan 接口。Order 系统需要一份更完整的分拣明细数据（包含重量、体积、分拣时间、格口备注、是否签出等），以支撑后续的业务分析和状态追踪。需要额外推送一条完整的 sorter_order 数据到新接口 /order/api/sorterApi/receiveChuteData。

步骤一：提交提案

在 Claude Code 中执行：

/opsx:propose DropChuteEventListener 落格事件触发后，仅推送了简版的 DropChuteOrderBO……需要额外推送一条完整的 sorter_order 数据到新接口 /order/api/sorterApi/receiveChuteData

AI 会在openspec/changes/下自动创建order-chute-receive-push/目录，包含 proposal.md、spec.md、design.md、tasks.md 四个文件。

步骤二：人工审核

开发人员需要仔细阅读 spec.md（纯业务描述，可与产品、测试一起看）、proposal.md（需求目的和影响范围）、design.md（技术方案）。如果发现 AI 理解有误，在同一个会话中直接告诉它，让它修改相应的 .md 文件。

步骤三：AI 实施

重新开一个会话，执行：

/opsx:apply order-chute-receive-push

AI 会按照 tasks.md 中的清单逐项实现代码。如果发现 bug，一定要让 AI 改，不要手动改，并且要求 AI 将变更同步回 spec 文档。

步骤四：AI 验收

再次重新开一个会话，执行：

/opsx:verify order-chute-receive-push

AI 会逐项检查 tasks.md 中每个任务是否完成。如果任务非常多，AI 大概率会偷懒，这一步能让它自己发现遗漏项。

步骤五：人工验收 & 归档

人工审查代码质量后，重新开一个会话执行归档：

/opsx:archive order-chute-receive-push

归档操作会将整个变更目录移到 archive/ 下，同时将增量 spec 合并到主规范 specs/ 中。

案例二：为项目添加深色模式

一个更简单的例子——为 Web 应用添加深色模式支持：

/opsx:propose add-dark-mode

AI 生成 proposal.md，描述变更范围：添加主题切换组件、实现 CSS 变量系统、支持 localStorage 记忆用户偏好、默认跟随系统设置。design.md 明确技术方案：使用 React Context 管理主题状态，CSS 自定义属性支持运行时切换。tasks.md 拆分为具体步骤：

## 1. 主题基础设施 - [ ] 1.1 创建带有亮/暗状态的 ThemeContext - [ ] 1.2 为颜色添加 CSS 自定义属性 - [ ] 1.3 实现 localStorage 持久化 - [ ] 1.4 添加系统偏好检测 ## 2. UI 组件 - [ ] 2.1 创建 ThemeToggle 组件 - [ ] 2.2 在设置页面添加切换 - [ ] 2.3 更新 Header 包含快速切换 ## 3. 样式 - [ ] 3.1 定义暗色主题调色板 - [ ] 3.2 更新组件使用 CSS 变量

确认无误后，执行/opsx:apply开始实现，完成后/opsx:archive归档。

六、常见问题与解决方案

Q1：需求不明确怎么办？

使用/opsx:explore与 AI 进行头脑风暴，让 AI 帮你理清需求边界和实现路径。注意：头脑风暴时上下文很容易膨胀，更好的做法是将头脑风暴的结论输出为文档或记住核心要点，然后重新开一个会话，用/opsx:propose创建正式提案。

Q2：生成的提案不符合要求怎么办？

切记：不要手动改提案文件！手动修改会导致 tasks.md 与 proposal.md/design.md 不一致。

正确的做法是：在同一个会话中告诉 AI 哪里不符合要求，让 AI 修改 proposal.md、design.md，同时更新 tasks.md。确认所有 .md 文件一致后，再进行 apply。

Q3：生成的代码有 Bug 怎么办？

让 AI 自己修，不要手动改。在同一个会话中告诉 AI bug 在哪、预期行为是什么。AI 修完代码后，必须要求 AI 把变更同步回 spec 文档（design.md、spec.md）。如果 bug 是需求理解偏差导致的，回溯修改 proposal.md。修完后重新执行/opsx:verify确保所有任务仍然通过。

核心理念：如果你手动改了代码但 spec 没更新，下次别人（或你自己）用 OpenSpec 时会基于过时的 spec 重新生成，bug 就会回来。

Q4：简单需求怎么办？人改还是 AI 改？

如果人改起来比较快，可以直接人改。但改完之后，要让 AI 把当前变更同步回对应的 spec 中。Prompt 可以这样写：“整理当前未提交代码逻辑变更，同步回对应的 spec”。AI 会自己读 openspec 目录下的文件，自己找对应的 spec，完成同步。

Q5：AI 写的代码不符合规范怎么办？

这就是Harness Engineering的核心。当 AI 写出的代码不符合要求，我们就要约束 AI：

• 遇到不规范代码 → 创建rule（如"字符串判空优先使用 StringUtils，为这条规则生成一个 rule，并在编写 Java 代码时生效"）
• 遇到重复性人工操作 → 创建skill（封装常用操作流程）
• 遇到上下文丢失 → 创建memory（项目偏好、个人习惯）

Q6：多人协作时归档会不会产生大量冲突？

理论上冲突概率很低，只要你们修改的不是同一个功能点。OpenSpec 会扫描 specs 目录，自动判断增量是修改已有规格还是创建新规格。如果多人修改了同一个文件的同一区域，才可能产生冲突；否则自动合并。这就是为什么不要手动改 spec——手动修改绕过了 OpenSpec 的合并逻辑，会导致下次归档时出现真正的冲突。

Q7：OpenSpec 和 AI 工具的 Plan Mode 有什么区别？

Plan Mode 适合单次对话内的规划。OpenSpec 专注于跨会话、可共享、可迭代的规划，贯穿整个开发生命周期。规划产物以文件形式存在 Git 仓库中，不随对话结束而消失。

Q8：切换 AI 工具后规范还能用吗？

OpenSpec 的定位是通用规划层，与具体 AI 工具解耦。你的规范可以在 Cursor、Claude Code、Copilot 等任意工具间复用。目前 OpenSpec 已支持 25+ 款 AI 工具。

Q9：AI 验证之后发现任务没完成怎么办？

AI 写完代码后，如果任务非常多，AI 大概率会偷懒。/opsx:verify会逐项检查 tasks.md 中每个任务是否完成。如果发现有未完成的，或者完成的结果不符合预期，AI 都会检查出来。只需要再次执行/opsx:apply <spec-id>命令即可。

Q10：最佳实践总结

四个核心原则：

1. 重新开一个会话—— 提案、实施、验收、归档各自独立
2. 不要手动改文件—— 所有 .md 文件的修改都通过 AI 完成
3. 规范先行—— 如果 AI 代码不符合项目规范，立即创建 rule/skill/memory 约束它
4. Bug 溯源—— 修完 bug 必须同步更新 spec，否则下次 AI 会重新引入

七、总结

OpenSpec 为 AI 辅助编程带来了一种全新的工作方式：规范先行，代码随后。它不是要取代你与 AI 的对话，而是将对话中产生的共识沉淀为可追溯、可共享、可迭代的文档。

如果你正在使用 AI 辅助编程，不妨花 10 分钟尝试一下 OpenSpec。这 10 分钟的规划，可能会为你省下数小时的返工时间。AI 编码的瓶颈从来不是"AI 不够聪明"，而是**“需求没有对齐”**——OpenSpec 解决的正是这个问题。

参考资源