AI 编程时代的规范驱动开发：OpenSpec 实践指南
AI 编程时代的规范驱动开发：OpenSpec 实践指南
当 AI 能写代码时，我们真正需要的是什么？不是更快的代码生成，而是更可靠的共识构建。
引言：一个熟悉的场景
你正在使用 AI 编程助手开发一个新功能。你描述了需求，AI 生成了代码，看起来一切正常。但是：
- 当你稍后回来继续开发时，之前的对话上下文已经丢失
- 需求只存在于聊天记录中，每次对话都可能产生不同的解读
- 团队成员不知道这个功能的设计决策和背景
- 代码实现了，但没有人知道"为什么这样做"
这不是 AI 的问题，而是我们与 AI 协作方式的问题。
今天，我想分享一个解决这个问题的开源工具 ——OpenSpec，它不是一个新概念，而是一个让规范驱动开发在 AI 时代真正落地的实践框架。
什么是规范驱动开发？
规范驱动开发（Spec-Driven Development）的核心思想很简单：在编写代码之前，先定义清楚系统应该做什么。
这不是新概念 —— 从 BDD（行为驱动开发）到 ATDD（验收测试驱动开发），软件行业一直在尝试各种"先想清楚再动手"的方法。但在 AI 编程时代，这个理念有了新的意义：
传统开发：需求文档 → 开发者理解 → 编写代码 AI 时代：需求描述 → AI 理解 → 生成代码 → ???问题是，AI 的"理解"是每次对话都重新构建的。如果需求只存在于聊天中，一致性就无从谈起。
OpenSpec 做的事情，就是在人类与 AI 之间建立一个持久化的共识层。
OpenSpec 的核心设计
增量规范（Delta Specs）
传统规范系统的痛点在于：修改现有功能时，你需要阅读整个规范，然后搞清楚哪部分在变化。
OpenSpec 引入了"增量规范"的概念：
# 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 的核心理念是"流畅而非僵化"：
默认快速路径： /opsx:propose ──► /opsx:apply ──► /opsx:archive 探索性路径： /opsx:explore ──► /opsx:new ──► /opsx:continue ──► ...没有强制的阶段门控。你可以：
- 用
/opsx:propose一步创建完整的变更提案 - 用
/opsx:explore先探索问题空间 - 用
/opsx:continue逐步迭代每个工件 - 用
/opsx:verify在归档前验证实施与规范的一致性
实战示例：添加深色模式
让我们看一个实际的例子。假设我们要给应用添加深色模式支持。
第一步：创建提案
你: /opsx:propose add-dark-mode AI: 创建了 openspec/changes/add-dark-mode/ ✓ proposal.md — 我们为什么做这个，范围是什么 ✓ specs/ — 需求和场景 ✓ design.md — 技术方案 ✓ tasks.md — 实施清单 准备实施！第二步：审查和调整
AI 生成的 proposal.md：
# Proposal: Add Dark Mode ## Intent 用户请求添加深色模式选项，以减少夜间使用时的眼睛疲劳。 ## Scope In scope: - 设置中的主题切换 - 系统偏好检测 - localStorage 持久化 Out of scope: - 自定义颜色主题（未来工作） - 每页主题覆盖 ## Approach 使用 CSS 自定义属性进行主题化，React Context 进行状态管理。如果需要调整，直接编辑文件即可。这不是静态生成的文档，而是活的协作媒介。
第三步：实施
你: /opsx:apply AI: 正在执行任务... ✓ 1.1 创建 ThemeContext ✓ 1.2 添加 CSS 自定义属性 ✓ 1.3 实现 localStorage 持久化 ✓ 2.1 创建 ThemeToggle 组件 ✓ 2.2 添加到设置页面 所有任务完成！第四步：归档
你: /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 定义工件间的依赖关系：
artifacts:-id:proposalrequires:[]# 无依赖，可以首先创建-id:specsrequires:[proposal]# 需要 proposal 先存在-id:designrequires:[proposal]# 可以与 specs 并行-id:tasksrequires:[specs,design]# 需要两者都存在依赖是使能器，不是门控。它们告诉 AI 什么可以创建，而不是强制执行顺序。
动态指令生成
OpenSpec 的一个关键创新是从静态提示词转向动态指令：
传统方式：AI 每次收到相同的静态指令 OpenSpec 方式：指令动态组装自三层 ├── Context（项目背景：技术栈、约定） ├── Rules（工件约束：如"为未知项创建探索任务"） └── Template（输出文件的实际结构）AI 通过 CLI 查询实时状态：哪些工件存在、什么可以创建、依赖是否满足。
与团队协作
个人项目
即使是个人项目，OpenSpec 也有价值：
- 隔周回来，看 proposal.md 就能回忆起当初的思考
- 任务清单让你随时知道进度
- archive 是活的决策日志
团队项目
对于团队，OpenSpec 提供：
- 代码评审前先评审意图：变更提案可以在实施前讨论
- 并行开发：多个变更可以同时进行而不冲突
- 知识传承：新成员可以阅读 archive 了解历史决策
企业部署
OpenSpec 支持：
- 自定义 Schema（在
openspec/schemas/中定义） - 项目级配置（
openspec/config.yaml） - 私有部署（纯 npm 包，无需外部服务）
最佳实践
保持变更聚焦
一个变更应该是一个逻辑工作单元。如果你在"添加功能 X 并且重构 Y"，考虑分成两个变更。
为什么？
- 更容易评审和理解
- 更清晰的 archive 历史
- 可以独立发布
- 必要时更容易回滚
命名要清晰
好的命名： 避免： add-dark-mode feature-1 fix-login-redirect update optimize-product-query changes implement-2fa wip好的命名让openspec list的输出真正有用。
渐进式严格性
不要过度工程化。使用能实现目标的最轻量级别：
轻量模式（大多数情况）：
- 简短的行为优先需求
- 清晰的范围和非目标
- 几个关键的验收场景
完整模式（高风险变更）：
- 跨团队或跨仓库
- API/契约变更
- 安全/隐私相关
- 模糊会导致高昂返工成本
验证后再归档
你: /opsx:verify AI: 验证 add-auth... 完整性 ✓ tasks.md 中所有 12 个任务已完成 ✓ 规范中所有需求都有对应代码 ⚠ 场景"会话超时"缺少测试 正确性 ✓ 实施符合规范意图 ✓ 边界情况已处理 一致性 ✓ 设计决策体现在代码结构中 总结 ───────────────────── 关键问题：0 警告：1 可以归档：是（带警告）验证不会阻止归档，但它会让你看到可能需要先处理的问题。
快速开始
安装
要求 Node.js 20.19.0 或更高版本。
npminstall-g@fission-ai/openspec@latest初始化
cdyour-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 命令：
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 许可的开源项目，欢迎贡献！