AI 编程时代的规范驱动开发：OpenSpec 实践指南

当 AI 能写代码时，我们真正需要的是什么？不是更快的代码生成，而是更可靠的共识构建。

引言：一个熟悉的场景

你正在使用 AI 编程助手开发一个新功能。你描述了需求，AI 生成了代码，看起来一切正常。但是：

当你稍后回来继续开发时，之前的对话上下文已经丢失
需求只存在于聊天记录中，每次对话都可能产生不同的解读
团队成员不知道这个功能的设计决策和背景
代码实现了，但没有人知道"为什么这样做"

这不是 AI 的问题，而是我们与 AI 协作方式的问题。

今天，我想分享一个解决这个问题的开源工具 ------ OpenSpec，它不是一个新概念，而是一个让规范驱动开发在 AI 时代真正落地的实践框架。

什么是规范驱动开发？

规范驱动开发（Spec-Driven Development）的核心思想很简单：在编写代码之前，先定义清楚系统应该做什么。

这不是新概念 ------ 从 BDD（行为驱动开发）到 ATDD（验收测试驱动开发），软件行业一直在尝试各种"先想清楚再动手"的方法。但在 AI 编程时代，这个理念有了新的意义：

复制代码

传统开发：需求文档 → 开发者理解 → 编写代码
AI 时代：需求描述 → AI 理解 → 生成代码 → ???

问题是，AI 的"理解"是每次对话都重新构建的。如果需求只存在于聊天中，一致性就无从谈起。

OpenSpec 做的事情，就是在人类与 AI 之间建立一个持久化的共识层。

OpenSpec 的核心设计

增量规范（Delta Specs）

传统规范系统的痛点在于：修改现有功能时，你需要阅读整个规范，然后搞清楚哪部分在变化。

OpenSpec 引入了"增量规范"的概念：

markdown 复制代码

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

这种格式的好处是：

清晰：一眼就能看出什么在变化
可合并：归档时自动合并到主规范
可追溯：历史变更保存在 archive 中

工件驱动的工作流

每个功能变更（Change）都是一个独立的文件夹，包含四种工件：

复制代码

openspec/changes/add-dark-mode/
├── proposal.md    # 为什么做，做什么
├── specs/         # 规范（增量格式）
├── design.md      # 技术方案
└── tasks.md       # 实施清单

工件之间的关系：

复制代码

proposal ───► specs ───► design ───► tasks ───► implement
    │           │           │                       │
   why        what        how                    steps
    │           │           │                       │
    └───────────┴───────────┴───────────────────────┘
                 随时可以回溯更新

关键洞察：这些工件不是阶段，而是维度。你可以随时回到任何工件进行更新，因为实施过程中的发现可能改变设计，设计发现可能改变规范。

流畅的工作流

OpenSpec 的核心理念是"流畅而非僵化"：

text 复制代码

默认快速路径：
/opsx:propose ──► /opsx:apply ──► /opsx:archive

探索性路径：
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ...

没有强制的阶段门控。你可以：

用 /opsx:propose 一步创建完整的变更提案
用 /opsx:explore 先探索问题空间
用 /opsx:continue 逐步迭代每个工件
用 /opsx:verify 在归档前验证实施与规范的一致性

实战示例：添加深色模式

让我们看一个实际的例子。假设我们要给应用添加深色模式支持。

第一步：创建提案

text 复制代码

你: /opsx:propose add-dark-mode

AI: 创建了 openspec/changes/add-dark-mode/
    ✓ proposal.md --- 我们为什么做这个，范围是什么
    ✓ specs/       --- 需求和场景
    ✓ design.md    --- 技术方案
    ✓ tasks.md     --- 实施清单
    准备实施！

第二步：审查和调整

AI 生成的 proposal.md：

markdown 复制代码

# Proposal: Add Dark Mode

## Intent
用户请求添加深色模式选项，以减少夜间使用时的眼睛疲劳。

## Scope
In scope:
- 设置中的主题切换
- 系统偏好检测
- localStorage 持久化

Out of scope:
- 自定义颜色主题（未来工作）
- 每页主题覆盖

## Approach
使用 CSS 自定义属性进行主题化，React Context 进行状态管理。

如果需要调整，直接编辑文件即可。这不是静态生成的文档，而是活的协作媒介。

第三步：实施

text 复制代码

你: /opsx:apply

AI: 正在执行任务...
    ✓ 1.1 创建 ThemeContext
    ✓ 1.2 添加 CSS 自定义属性
    ✓ 1.3 实现 localStorage 持久化
    ✓ 2.1 创建 ThemeToggle 组件
    ✓ 2.2 添加到设置页面
    所有任务完成！

第四步：归档

text 复制代码

你: /opsx:archive

AI: 归档 add-dark-mode...
    ✓ 将增量规范合并到 openspec/specs/ui/spec.md
    ✓ 移动到 openspec/changes/archive/2025-01-24-add-dark-mode/
    完成！准备下一个功能。

归档后，变更记录被保存，规范被更新。下次有人问"为什么我们选择了这个方案？"，答案就在 archive 里。

为什么选择 OpenSpec？

对比其他方案

vs. GitHub Spec Kit

Spec Kit 功能全面但重量级。严格的阶段门控、大量文档、Python 环境配置。适合严格的工程团队，但对于追求速度的项目来说负担过重。

vs. AWS Kiro

Kiro 功能强大，但你被锁定在他们的 IDE 和有限的模型选择中。OpenSpec 可以与你现有的工具链配合使用。

vs. 什么都不用

没有规范的 AI 编程意味着模糊的提示词和不可预测的结果。你可能今天得到一个好的实现，明天用同样的描述得到完全不同的代码。

核心优势

共识优先：人类和 AI 在编写代码前先就规范达成一致
组织有序：每个变更独立文件夹，完整的上下文
灵活迭代：随时更新任何工件，没有僵化的流程
工具无关：支持 20+ 种 AI 编程助手

技术实现亮点

架构设计

OpenSpec 采用分层架构：

复制代码

┌─────────────────────────────────────────────────────────┐
│                     CLI Layer                            │
│  openspec init | update | list | show | validate | view │
└─────────────────────────────────────────────────────────┘
                           │
┌─────────────────────────────────────────────────────────┐
│                   Core Layer                             │
│  Artifact Graph | Schema Resolution | Validation        │
└─────────────────────────────────────────────────────────┘
                           │
┌─────────────────────────────────────────────────────────┐
│                Tool Adapters Layer                       │
│  Claude Code | Cursor | Windsurf | Copilot | ...        │
└─────────────────────────────────────────────────────────┘

工件依赖图

基于 Schema 定义工件间的依赖关系：

yaml 复制代码

artifacts:
  - id: proposal
    requires: []              # 无依赖，可以首先创建
    
  - id: specs
    requires: [proposal]      # 需要 proposal 先存在
    
  - id: design
    requires: [proposal]      # 可以与 specs 并行
    
  - id: tasks
    requires: [specs, design] # 需要两者都存在

依赖是使能器，不是门控。它们告诉 AI 什么可以创建，而不是强制执行顺序。

动态指令生成

OpenSpec 的一个关键创新是从静态提示词转向动态指令：

text 复制代码

传统方式：AI 每次收到相同的静态指令

OpenSpec 方式：指令动态组装自三层
├── Context（项目背景：技术栈、约定）
├── Rules（工件约束：如"为未知项创建探索任务"）
└── Template（输出文件的实际结构）

AI 通过 CLI 查询实时状态：哪些工件存在、什么可以创建、依赖是否满足。

与团队协作

个人项目

即使是个人项目，OpenSpec 也有价值：

隔周回来，看 proposal.md 就能回忆起当初的思考
任务清单让你随时知道进度
archive 是活的决策日志

团队项目

对于团队，OpenSpec 提供：

代码评审前先评审意图：变更提案可以在实施前讨论
并行开发：多个变更可以同时进行而不冲突
知识传承：新成员可以阅读 archive 了解历史决策

企业部署

OpenSpec 支持：

自定义 Schema（在 openspec/schemas/ 中定义）
项目级配置（openspec/config.yaml）
私有部署（纯 npm 包，无需外部服务）

最佳实践

保持变更聚焦

一个变更应该是一个逻辑工作单元。如果你在"添加功能 X 并且重构 Y"，考虑分成两个变更。

为什么？

更容易评审和理解
更清晰的 archive 历史
可以独立发布
必要时更容易回滚

命名要清晰

text 复制代码

好的命名：              避免：
add-dark-mode          feature-1
fix-login-redirect     update
optimize-product-query changes
implement-2fa          wip

好的命名让 openspec list 的输出真正有用。

渐进式严格性

不要过度工程化。使用能实现目标的最轻量级别：

轻量模式（大多数情况）：

简短的行为优先需求
清晰的范围和非目标
几个关键的验收场景

完整模式（高风险变更）：

跨团队或跨仓库
API/契约变更
安全/隐私相关
模糊会导致高昂返工成本

验证后再归档

text 复制代码

你: /opsx:verify

AI: 验证 add-auth...
    
    完整性
    ✓ tasks.md 中所有 12 个任务已完成
    ✓ 规范中所有需求都有对应代码
    ⚠ 场景"会话超时"缺少测试
    
    正确性
    ✓ 实施符合规范意图
    ✓ 边界情况已处理
    
    一致性
    ✓ 设计决策体现在代码结构中
    
    总结
    ─────────────────────
    关键问题：0
    警告：1
    可以归档：是（带警告）

验证不会阻止归档，但它会让你看到可能需要先处理的问题。

快速开始

安装

要求 Node.js 20.19.0 或更高版本。

bash 复制代码

npm install -g @fission-ai/openspec@latest

初始化

bash 复制代码

cd your-project
openspec init

初始化过程会：

检测项目中已有的 AI 工具配置
让你选择要集成的工具
创建 openspec/ 目录结构
生成斜杠命令

开始使用

告诉你的 AI：/opsx:propose <你想要构建的功能>

就这么简单！

命令速查

命令	用途	何时使用
`/opsx:propose`	创建变更+规划工件	快速默认路径
`/opsx:explore`	探索想法	需求不清晰时
`/opsx:new`	创建变更框架	扩展模式
`/opsx:continue`	创建下一个工件	逐步迭代
`/opsx:ff`	快速创建所有规划工件	范围清晰时
`/opsx:apply`	实施任务	准备写代码
`/opsx:verify`	验证实施	归档前
`/opsx:archive`	归档变更	所有工作完成

CLI 命令：

bash 复制代码

openspec list          # 列出活动变更
openspec show <name>   # 查看变更详情
openspec validate      # 验证规范格式
openspec view          # 交互式仪表板
openspec update        # 更新 AI 指令

结语：AI 编程的本质

AI 编程助手的能力在飞速提升，但我们与它们协作的方式却没有本质改变 ------ 仍然是对话式的、临时的、难以追溯的。

OpenSpec 提供了一个不同的思路：不是让 AI 更聪明地理解我们的意图，而是让我们更清晰地表达意图，并让这个表达变得可追溯、可协作、可验证。

这不是回到重量级文档的时代。OpenSpec 的哲学是"轻量但足以实现目标"------ 流畅而非僵化，迭代而非瀑布式，简单而非复杂。

如果你正在寻找一种方式，让 AI 编程变得可预测、可追溯、可协作，不妨试试 OpenSpec。毕竟，在 AI 能写代码的时代，真正稀缺的不是代码生成能力，而是共识构建能力。

资源链接

GitHub ：https://github.com/Fission-AI/OpenSpec
npm ：@fission-ai/openspec
Discord ：加入社区讨论
Twitter ：关注 @0xTab 获取更新

本文基于 OpenSpec v1.2.0 撰写。OpenSpec 是 MIT 许可的开源项目，欢迎贡献！