在之前的实战经验文章Claude Code 实战：八条心得经验我提到过一个关键原则：动手写代码前，先确认意图和方案。这个原则在 AI 编程时代变得更加重要。规格驱动开发（Specification-Driven Development，SDD）的思路：把需求、设计、任务清单都写下来，让 AI 按照明确的规格来工作。
OpenSpec 就是一个实现 SDD 的轻量级框架。
OpenSpec 是什么
OpenSpec 类似传统软件开发流程的简化版，核心思想很简单：写代码之前，先让人和 AI 在规格上达成一致。把需求、设计、任务清单都持久化为 Markdown 文件，存放在代码库的 openspec/ 目录下。AI 不会忘记你的需求，团队成员能看到完整的变更历史，每次修改都有清晰的意图记录。
OpenSpec 支持 30+ 种 AI 编程工具，包括 Claude Code、Cursor、GitHub Copilot、Gemini CLI 等。你不会被锁定在某个特定的 IDE 或模型上。
快速上手
安装
OpenSpec 需要 Node.js 20.19.0 或更高版本。全局安装：
npm install -g @fission-ai/openspec@latest
在项目目录中初始化：
cd your-project
openspec init
初始化后，项目中会生成 openspec/ 目录结构：
openspec/
├── specs/ # 当前系统的规格（真相源）
├── changes/ # 进行中的变更
└── config.yaml # 项目配置（可选）
第一个变更：添加用户登录接口
通过一个实际例子来理解 OpenSpec 的工作流程。假设你正在开发一个 Spring Boot Web 项目，需要添加用户登录接口。
步骤 1：提出变更
告诉你的 AI 助手：
/opsx:propose add-user-login-api
AI 会自动创建变更目录并生成四个文件：
openspec/changes/add-user-login-api/
├── proposal.md # 为什么做、做什么
├── specs/ # 增量规格（新增/修改/删除的需求）
├── design.md # 技术方案
└── tasks.md # 实施清单
步骤 2：实施变更
/opsx:apply
AI 会按照 tasks.md 中的清单逐项实施，每完成一项就打勾。你可以随时查看进度，也可以在实施过程中调整设计文档。
步骤 3：归档
/opsx:archive
归档时，OpenSpec 会把增量规格合并到主规格目录 openspec/specs/，并将变更文件夹移到 openspec/changes/archive/。代码库就有了完整的变更历史。
核心概念：增量规格
OpenSpec 最巧妙的设计是"增量规格"（Delta Specs）。它不重写整个规格文档，只描述变化的部分。
增量规格使用三个标记来表示变更类型：
# Delta for Auth
## ADDED Requirements
### Requirement: 双因素认证
系统必须在登录时要求第二因素验证。
## MODIFIED Requirements
### Requirement: 会话超时
系统应在 30 分钟无活动后使会话过期。
（之前：60 分钟）
## REMOVED Requirements
### Requirement: 记住我功能
（已弃用，改用双因素认证）
归档时的合并逻辑：
ADDED的需求追加到主规格MODIFIED的需求替换现有版本REMOVED的需求从主规格删除
这种方式类似 Git 的 diff，变更清晰可追溯。
工作流模式
OpenSpec 提供两种工作流模式：
默认快速路径（core 配置）
新安装默认使用 core 配置，提供最精简的命令集：
/opsx:propose → /opsx:apply → /opsx:archive
适合快速迭代和小型项目。
扩展工作流
如果需要更细粒度的控制，可以启用扩展命令,扩展工作流提供更多命令：
| 命令 | 用途 |
|---|---|
/opsx:new | 创建变更脚手架 |
/opsx:continue | 逐步创建下一个制品 |
/opsx:ff | 快进创建所有规划制品 |
/opsx:verify | 验证实施是否符合规范 |
/opsx:explore | 探索需求和技术方案 |
典型的扩展工作流：
graph TD
A[/opsx:new 创建变更/] --> B{需求清晰?}
B -->|是| C[/opsx:ff 快进/]
B -->|否| D[/opsx:explore 探索/]
D --> E[/opsx:continue 逐步推进/]
C --> F[/opsx:apply 实施/]
E --> F
F --> G[/opsx:verify 验证/]
G --> H{通过?}
H -->|是| I[/opsx:archive 归档/]
H -->|否| J[修复问题]
J --> F
classDef primary fill:#1A9090,stroke:#156b6b,color:#fff
classDef secondary fill:#2d4a4a,stroke:#1A9090,color:#fff
classDef decision fill:#3d5a5a,stroke:#1A9090,color:#fff
class C,F,I primary
class A,D,E,G,J secondary
class B,H decision
实用技巧
何时使用 /opsx:ff vs /opsx:continue
需求明确、准备开工时用 /opsx:ff。边探索边推进、想逐步审查时用 /opsx:continue。时间紧迫时用 /opsx:ff。复杂变更、需要精细控制时用 /opsx:continue。
何时更新现有变更 vs 创建新变更
更新现有变更：意图相同，只是执行方式调整；缩小范围（先做 MVP，其余后续）；实施中发现代码库结构与预期不符。
创建新变更：意图根本改变；范围扩大到完全不同的工作；原变更可以独立标记为完成。
保持变更聚焦
一个变更对应一个逻辑单元。如果你在做"添加功能 X 并重构 Y"，考虑拆成两个独立变更。好处是更易审查和理解，归档历史更清晰，可以独立发布，回滚更简单。
使用 CLI 命令查看状态
# 列出活跃变更
openspec list
# 查看变更详情
openspec show add-dark-mode
# 验证规格格式
openspec validate add-user-login-api
# 交互式仪表板
openspec view
OpenSpec vs Spec Kit
| 对比项 | OpenSpec | Spec Kit (GitHub) |
|---|---|---|
| 轻量级 | ✓ | ✗ 较重 |
| 工具兼容性 | 30+ AI 工具 | 通用 |
| IDE 限制 | 无限制 | 无限制 E |
| 阶段门控 | 灵活迭代 | 严格门控 |
| 环境要求 | Node.js | Python |
| 需求持久化 | ✓ | ✓ |
| 可预测性 | 高 | 高 |
| 学习成本 | 低 | 中 |
最佳实践建议
模型选择
OpenSpec 在高推理能力的模型上表现最佳，所以推荐使用各模型厂商高级模型版本，比如Claude Code选OPUS。
上下文管理
OpenSpec 受益于干净的上下文窗口。在开始实施前清理上下文，并在整个会话中保持良好的上下文卫生。
验证后再归档
使用 /opsx:verify 检查实施是否符合制品要求：
/opsx:verify
验证会检查三个维度：完整性（所有任务完成，所有需求已实施）、正确性（实施符合规格意图，边界情况已处理）、一致性（设计决策体现在代码中，命名约定一致）。
小结
OpenSpec 解决了 AI 编程助手的两个痛点：需求易失和输出不可预测。它的轻量设计和广泛兼容性，让你可以在不改变现有工具链的前提下，获得更可控的 AI 协作体验。
从安装到第一个变更，整个流程不超过 5 分钟。如果你正在使用 AI 编程助手，不妨试试 OpenSpec。
