OpenSpec：面向 AI 编程助手的规范驱动开发框架
在 AI 编程助手日益普及的今天，一个核心矛盾正在浮现——AI 的代码生成能力越来越强，但开发者的需求表达却依然模糊、分散，且难以追踪。当你在聊天窗口中与 AI 反复对话，需求散落在历史记录里，AI 的输出变得不可预测、不可复现。OpenSpec（https://github.com/Fission-AI/OpenSpec）正是为解决这一问题而生的开源框架：它在人与 AI 之间建立一套轻量级的规范层，让双方在动手写代码之前先就"要构建什么"达成共识。
1 OpenSpec 解决了什么问题
传统的软件开发流程中，需求文档、设计文档和代码之间往往存在巨大的鸿沟。而在 AI 辅助编码的场景下，这个问题被进一步放大：
- 需求散落在聊天记录中：你在对话框里告诉 AI "帮我加个双因素认证"，但下一次对话时 AI 已经忘记了之前的上下文。
- 输出不可预测：相同的模糊指令在不同时刻可能生成截然不同的代码。
- 缺乏审计路径：团队成员无法知道某个功能的需求来源、设计决策和实现细节。
- 存量系统难以应对：大多数开发工作不是从零开始，而是在已有系统上做修改。传统的规范框架往往只关注"全新描述"，对"增量变更"支持不足。
OpenSpec 的核心价值主张可以用一句话概括：先约定、再实现（Agree before you build）。它通过结构化的规范文件和变更提案，将"意图"锁定在代码仓库中，使 AI 和人类开发者在同一份可审查的文档上对齐。
2 设计哲学：四个核心原则
OpenSpec 的设计哲学体现在四个相互关联的原则上，它们共同构成了这个框架区别于其他方案的独特气质。
2.1 流动而非僵硬（Fluid not Rigid）
传统的规范系统往往将工作流锁定在严格的阶段门控中：先规划、再实现、最后完成——不允许回头。OpenSpec 采用了动作模型（Action Model）而非阶段模型（Phase Model）：
传统工作流（阶段锁定）：
规划阶段 ────────► 实现阶段 ────────► 完成阶段
│ │
│ "不能回头" │
└────────────────────┘
OpenSpec OPSX 工作流（流动动作）：
new ◄──► continue ◄──► apply ◄──► archive
│ │ │ │
│ │ │ "设计有问题？"
│ │ │ 直接编辑 design.md
│ │ │ 然后继续！
│ │ │
└──────────┴───────────┴─────────────┘
随时可以在动作之间切换这意味着，如果你在实现阶段发现设计方案有误，不需要"推倒重来"或"硬着头皮继续"，只需修改对应的设计文档并继续实现即可。
2.2 迭代而非瀑布（Iterative not Waterfall）
需求会变化，理解会加深，一开始看起来合理的方案在看到代码后可能站不住脚。OpenSpec 拥抱这种现实，允许在任何时间点更新任何工件（Artifact），而不是强制按顺序完成。
2.3 简单而非复杂（Easy not Complex）
有些规范框架需要大量的前置配置、严格的格式要求或笨重的流程。OpenSpec 只需一条命令即可初始化，开箱即用：
npm install -g @fission-ai/openspec
openspec init整个项目结构只有两个核心目录（specs/ 和 changes/），没有 API 密钥、没有外部服务依赖。
2.4 存量优先（Brownfield-first）
这是 OpenSpec 最独特的设计决策之一。大多数真实世界的开发工作都不是从零开始，而是在现有系统上做修改。OpenSpec 发明了 Delta Specs（增量规范） 的概念，专门描述"什么在变化"，而不是重新描述整个系统——这让增量变更的规范化变得自然而高效。
3 核心架构：Specs 与 Changes 的双目录模型
OpenSpec 的项目结构围绕两个核心目录展开，这构成了整个系统的基石：
openspec/
├── project.md # 项目上下文（技术栈、约定等）
├── AGENTS.md # AI 助手指令
├── config.yaml # 项目配置（可选）
├── specs/ # 📚 当前事实——系统"是什么"
│ └── [capability]/ # 单一、聚焦的能力
│ ├── spec.md # WHAT 和 WHY
│ └── design.md # HOW（可选）
└── changes/ # 📝 提议变更——我们要"改什么"
├── [change-name]/ # 描述性的变更标识
│ ├── proposal.md # 为什么、改什么、影响
│ ├── tasks.md # 实现清单
│ ├── design.md # 技术决策（可选）
│ └── specs/ # Delta Specs（增量规范）
│ └── [capability]/
│ └── spec.md
└── archive/ # 已完成的变更存档
└── YYYY-MM-DD-[name]/用一张概念图来理解这两个目录的关系：
3.1 Specs 目录：单一事实来源
specs/ 目录下的文件描述的是系统当前的行为——它是已部署能力的"活文档"。每个子目录代表一个聚焦的"能力"（Capability），使用动词-名词的命名方式（如 user-auth、payment-capture、order-checkout），并遵循"10 分钟规则"：每个能力应该能在 10 分钟内被理解。
规范文件采用结构化的 Markdown 格式，使用 ### Requirement: 和 #### Scenario: 层级标题，配合 WHEN/THEN/AND 等粗体关键词来描述行为场景：
### Requirement: 用户认证
系统 SHALL 支持基于令牌的用户认证机制。
#### Scenario: 成功登录
- **WHEN** 用户提交有效的凭据
- **THEN** 系统返回一个 JWT 令牌
- **AND** 令牌有效期为 24 小时这种格式既对人类可读，又便于工具解析——OpenSpec 的 CLI 能够将这些 Markdown 文件解析为结构化的 JSON，并通过 Zod Schema 进行验证。
3.2 Changes 目录：结构化的变更提案
当需要修改系统行为时，不是直接改 specs/，而是在 changes/ 下创建一个变更文件夹。每个变更包含多个工件（Artifacts）：
| 工件 | 用途 | 必需 |
|---|---|---|
proposal.md | 为什么要做、改什么、影响范围 | 是 |
specs/**/*.md | Delta Specs——描述变更的增量规范 | 是 |
design.md | 技术决策、架构方案 | 可选 |
tasks.md | 实现清单（带复选框） | 是 |
一个真实的变更例子：当你告诉 AI "添加双因素认证"时，它会创建以下结构：
openspec/changes/add-2fa/
├── proposal.md # 为什么需要 2FA
├── design.md # TOTP vs SMS 的技术决策
├── tasks.md # 实现清单
└── specs/
└── auth/
└── spec.md # Delta Spec：auth 能力的增量变更4 Delta Specs：为存量系统而生的增量规范
Delta Specs 是 OpenSpec 最具创新性的概念。它们不是重写整个规范，而是用 ADDED、MODIFIED、REMOVED 三种操作来描述变更：
## ADDED Requirements
### Requirement: 双因素认证
系统 SHALL 支持基于 TOTP 的双因素认证。
#### Scenario: 启用 2FA
- **WHEN** 用户在安全设置中启用 2FA
- **THEN** 系统生成 TOTP 密钥
- **AND** 显示 QR 码供验证器应用扫描
## MODIFIED Requirements
### Requirement: 登录流程
#### Scenario: 启用 2FA 后的登录
- **WHEN** 已启用 2FA 的用户提交正确密码
- **THEN** 系统提示输入 TOTP 验证码
- **AND** 仅在验证码有效时才签发令牌为什么使用增量描述而非完整重写？
- 减少噪声：审查者只需关注变化的部分，而非整个规范。
- 并行友好：多个变更可以修改同一个能力的不同方面，互不冲突。
- 存量系统优化：对于拥有几十甚至上百个规范的大型系统，增量描述的效率远高于全量重写。
当变更完成并归档时，Delta Specs 会被合并（sync）回 specs/ 目录，成为新的"当前事实"。
5 OPSX 工作流：AI 原生的动作系统
OpenSpec 1.0 引入了全新的 OPSX 工作流，这是一套基于动作（Action-based）的系统，取代了旧的阶段锁定模式。OPSX 提供了 10 个核心命令（以斜杠命令的形式调用）：
| 命令 | 用途 |
|---|---|
/opsx:explore | 探索想法，与 AI 思维碰撞 |
/opsx:new | 启动一个新变更 |
/opsx:continue | 逐步创建下一个工件 |
/opsx:ff | 快进——一次性创建所有规划工件 |
/opsx:apply | 实现任务 |
/opsx:verify | 验证实现是否匹配规范 |
/opsx:sync | 将 Delta Specs 合并到主规范 |
/opsx:archive | 归档已完成的变更 |
/opsx:bulk-archive | 批量归档多个变更 |
/opsx:onboard | 引导式新手教程 |
一个典型的快速开发流程如下：
而对于需要逐步打磨的复杂特性，流程更灵活：
/opsx:new → 创建变更脚手架
/opsx:continue → 创建 proposal（审查）
/opsx:continue → 创建 specs（审查）
/opsx:continue → 创建 design（审查）
/opsx:continue → 创建 tasks（审查）
/opsx:apply → 逐个实现任务
/opsx:verify → 三维度验证（完整性 + 正确性 + 一致性）
/opsx:archive → 合并规范、归档变更5.1 验证的三个维度
/opsx:verify 命令从三个维度检查实现质量：
- 完整性（Completeness）：所有任务是否都已完成？所有规范中的需求是否都有对应代码？
- 正确性（Correctness）：实现是否符合规范的意图？边界场景是否被处理？
- 一致性（Coherence）：代码结构是否反映了设计决策？命名约定是否与设计文档一致？
6 Schema 系统：可定制的工作流引擎
OpenSpec 的另一大亮点是其 Schema 系统——通过 YAML 文件定义工件的依赖关系图，从而支持完全自定义的工作流。
默认的 spec-driven Schema 定义了如下工件依赖：
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # 无依赖，第一个创建
- id: specs
generates: specs/**/*.md
requires: [proposal] # 需要 proposal 才能创建
- id: design
generates: design.md
requires: [proposal] # 可以与 specs 并行创建
- id: tasks
generates: tasks.md
requires: [specs, design] # 需要 specs 和 design对应的依赖图如下：
你可以创建完全自定义的 Schema 来适配团队的工作流。例如，一个"研究优先"的工作流：
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # 先做研究
- id: proposal
generates: proposal.md
requires: [research] # 基于研究结果写提案
- id: tasks
generates: tasks.md
requires: [proposal] # 跳过 specs/design，直接到任务Schema 的解析遵循优先级链：CLI 参数 → 变更元数据 → 项目配置 → 默认值，确保了灵活性和一致性的平衡。
7 广泛的 AI 工具兼容性
OpenSpec 并不绑定特定的 AI 编码助手。它支持 20 多种工具，包括 Claude Code、Cursor、GitHub Copilot、Windsurf、Cline 等。对于支持斜杠命令的工具，OpenSpec 会自动生成对应的命令文件；对于使用 AGENTS.md 或类似机制的工具，OpenSpec 通过上下文规则文件来注入指令。
这意味着团队中的不同成员可以使用各自偏好的 AI 工具，同时共享同一套规范和变更。
8 与竞品的比较
| 维度 | OpenSpec | Spec Kit（GitHub） | Kiro（AWS） |
|---|---|---|---|
| 工作流 | 流动的动作模型 | 严格的阶段门控 | IDE 内置流程 |
| 存量支持 | Delta Specs 原生支持 | 侧重全新描述 | 侧重新功能 |
| 工具锁定 | 支持 20+ AI 工具 | 需要 Python 环境 | 绑定自有 IDE 和 Claude |
| 自定义 | Schema 完全可定制 | 固定结构 | 有限定制 |
| 上手成本 | 一条命令初始化 | 需要较多配置 | 需要注册和 IDE 切换 |
OpenSpec 的核心优势在于它既足够轻量（不需要额外的 API 密钥或服务），又足够灵活（自定义 Schema、多工具支持），特别是在存量系统的增量变更场景下表现优异。
9 适用场景与总结
OpenSpec 特别适合以下场景：
- 团队协作的 AI 辅助开发：确保不同成员、不同 AI 工具之间的需求对齐。
- 存量系统的功能迭代：利用 Delta Specs 精确描述增量变更。
- 需要审计追踪的项目：每个变更的提案、设计、实现都有完整记录。
- 快速原型到正式开发的过渡：从
/opsx:explore探索想法，到/opsx:archive归档完成，一条龙覆盖。
OpenSpec 的核心思想可以归结为：在 AI 时代，规范不是束缚创造力的枷锁，而是释放 AI 生产力的引导轨道。通过将意图结构化、将变更增量化、将工作流流动化，OpenSpec 让人类和 AI 真正成为"先约定、再实现"的协作伙伴。
项目地址：https://github.com/Fission-AI/OpenSpec 文档：https://github.com/Fission-AI/OpenSpec/tree/main/docs 安装命令：
npm install -g @fission-ai/openspec