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

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

一、OpenSpec 是什么

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

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

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

核心设计哲学

原则	含义
流动而非僵化	传统规范系统将你锁定在阶段中：先规划，再实现，然后完成。OpenSpec 允许你按任何有意义的顺序创建产物，随时更新任何文档。
迭代而非瀑布	需求会变化，理解会加深。最初看起来不错的方案在看到代码库后可能无法成立。OpenSpec 拥抱这种现实。
简单而非复杂	几秒钟初始化，立即开始工作。不挡你的路，不要求大量设置、严格格式或繁重流程。
存量项目优先	大多数软件工作不是从零开始，而是在已有系统上迭代改造。OpenSpec 基于 Delta 的方法，让描述"改了什么"变得自然而直观。

二、OpenSpec 能解决什么问题

传统 AI 编程的三大痛点

痛点	传统方式	OpenSpec 方案
上下文膨胀	长对话后 AI 开始"遗忘"早期指令，输出质量断崖式下降	每一次 apply / verify / archive 都建议重新开一个会话，上下文从零开始，始终保持高质量
AI 容易偷懒	任务多时 AI 跳过步骤、敷衍实现、"假装完成"	任务拆成 tasks.md 清单，verify 命令逐项检查是否完成，AI 无法跳过
无法复盘	对话结束就没了，没有文档沉淀，换人接手无从查起	每次变更都在 openspec/ 目录下留下 proposal、design、tasks、spec，形成活文档

与同类工具对比

工具	特点	OpenSpec 的优势
Spec Kit (GitHub)	功能全面但重量级，Python 依赖，严格阶段门控	更轻量，流程灵活，自由迭代
Kiro (AWS)	IDE 深度集成，仅限 Claude 模型	不锁定工具，支持 25+ 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，包含三部分：

Delta 节	含义	归档时操作
`ADDED Requirements`	新增的行为	追加到主规范
`MODIFIED Requirements`	修改的已有行为	替换主规范中现有需求
`REMOVED Requirements`	废弃的行为	从主规范中删除

整体架构

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.md`	需求变更说明：做什么、为什么、影响范围	所有人	`/opsx:propose`
`design.md`	技术实现方案：架构、接口、数据模型	开发	`/opsx:propose`
`tasks.md`	任务拆分清单：可执行的 step-by-step	开发 + AI	`/opsx:propose`
`spec.md`	增量规格：本次变更的行为描述	产品 + 测试	`/opsx:propose`

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

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

4.1 环境安装

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

bash 复制代码

# npm 全局安装
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

4.2 项目初始化

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

bash 复制代码

cd your-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 文件。

完整工作流七步：

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

4.4 常用命令速查

命令	用途	备注
`openspec init`	初始化项目	仅首次
`/opsx:explore <描述>`	需求探索 / 头脑风暴	可在空项目使用，不产生文件
`/opsx:propose <描述>`	创建变更提案	生成 proposal/design/tasks/spec
`/opsx:apply <spec-id>`	AI 实施代码	重新开会话
`/opsx:verify <spec-id>`	AI 验收代码	重新开会话，逐项检查 tasks
`/opsx:archive <spec-id>`	归档变更	重新开会话，合并到主规范
`openspec config profile`	配置 AI Agent / 工作流	切换简洁模式或扩展模式
`openspec update`	刷新项目中的 AI 指引和斜杠命令	升级后需要运行

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 拆分为具体步骤：

markdown 复制代码

## 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：最佳实践总结

四个核心原则：

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

七、总结

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

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

参考资源

资源	链接
OpenSpec 中文官方文档	https://radebit.github.io/OpenSpec-Docs-zh/#overview
OpenSpec 中文文档 - 概览	https://radebit.github.io/OpenSpec-Docs-zh/#overview
CSDN：OpenSpec 安装与使用详解	https://blog.csdn.net/qq_18948359/article/details/162639656
GitHub 仓库	https://github.com/Fission-AI/OpenSpec
官方网站	https://openspec.dev/
npm 包	https://www.npmjs.com/package/@fission-ai/openspec
Discord 社区	https://discord.gg/YctCnvvshC