告别「改一个 Bug 引入三个 Bug」的 AI 编程噩梦------OpenSpec 在需求与代码之间插入一层规范，先共识再编码，让 AI 编程从「赌运气」变成「可预期」。
写在前面
上周有个朋友跟我吐槽。
他让 Cursor 给登录页加一个「记住密码」功能------挺简单的事。结果 AI 不仅加了功能，还顺手把整个登录页的 UI 重构了一遍，顺便删掉了验证码校验。
改完 Bug 引入三个新 Bug？家常便饭。
更离谱的是，他上个月明明跟 AI 说过「用户权限分三级」，这周开了个新对话，AI 像失忆了一样，又给他搞了一套两级权限。
这不是个别现象。问题的核心在于：你的需求只活在聊天记录里。 聊天窗口一关，上下文清零；换一个模型、切一个工具，之前讨论的所有规范全部归零。
这就是为什么 GitHub 上一个叫 OpenSpec 的项目，短时间内拿下了近 5 万 Star。
GitHub 地址：Fission-AI/OpenSpec 官网：openspec.dev License：MIT
一、什么是 SDD（规范驱动开发）？
1.1 传统 AI 编程的困境
AI 编程助手的典型工作模式是这样的：
用户：给登录页加个「记住密码」功能
AI：好的！（开始改代码）
------ 5 分钟后 ------
用户：等等，为什么登录页的 UI 全变了？？
AI：我觉得新的更好看......
用户：验证码校验怎么没了？？？
AI：呃，那个我重构的时候不小心覆盖了......问题出在哪？AI 没有理解你到底要改什么、改多少、改哪里。它凭自己的「感觉」写代码，而这个感觉每次都不同。
1.2 SDD 的解决思路
SDD（Spec-Driven Development，规范驱动开发）的核心思想很简单：
css
传统开发：需求 → [写代码] → 完成
SDD 开发：需求 → [写规范] → 人与 AI 对齐 → [写代码] → 完成任务 → [归档规范]在「需求」和「代码」之间，插入一个规范层（Spec Layer） 。
这个规范不是上百页的 PRD 文档，而是直接存在代码仓库里的结构化 Markdown 文件。每个功能模块一个 spec 文件，每次变更自动生成四样东西：
| 文件 | 作用 | 谁来看 |
|---|---|---|
proposal.md |
变更描述：做什么、为什么 | 所有人 |
design.md |
技术方案：怎么实现、有哪些决策 | 开发者 |
tasks.md |
任务拆解：分几步、每步做什么 | AI / 执行者 |
specs/*.md |
规范增量：哪些模块的规范会变（diff 格式） | Reviewer |
在敲下第一行代码之前，你和 AI 就已经对齐了「要做什么、怎么做、影响什么」。代码审查也从「看代码猜意图」变成了「先看 spec 变更，一目了然」。
二、OpenSpec 是什么？
2.1 项目速览
OpenSpec 是 Fission-AI 开发的 SDD 框架实现，MIT 开源协议。
| 项目 | 详情 |
|---|---|
| 作者 | Fission-AI |
| Stars | 49,600+ |
| License | MIT |
| 技术栈 | TypeScript (99.1%) |
| 安装 | npm install -g @fission-ai/openspec@latest |
| Node 要求 | 20.19.0+ |
| 支持工具 | Claude Code / Cursor / Codex / GitHub Copilot / Windsurf / Gemini CLI / CodeBuddy 等 25+ 款 AI 工具 |
2.2 核心理念
OpenSpec 明确提出了几个设计原则：
- 规范是 source of truth，代码是规范的派生产物 ------ 这是最根本的一条
- 流动而非僵化（fluid not rigid） ------ 不设刚性阶段门禁，随时可回头修改任何工件
- 迭代而非瀑布（iterative not waterfall） ------ 轻量规划后立即编码，遇到变化更新规范继续
- 棕地优先（brownfield first） ------ 专为已有项目设计，不是只在全新项目里管用
2.3 工作流概览
整个开发流程精简为三个命令：
bash
/opsx:propose → /opsx:apply → /opsx:archive下面我们来详细拆解每一步。
三、三分钟上手：安装与初始化
3.1 环境要求
- Node.js ≥ 20.19.0
- 任意支持的 AI 编程工具（Cursor / Claude Code / CodeBuddy 等）
3.2 安装步骤
bash
# 步骤 1：全局安装
npm install -g @fission-ai/openspec@latest
# 步骤 2：进入项目，执行初始化
cd your-project
openspec init
# 步骤 3：在 AI 工具里使用
/opsx:propose 我想给用户加一个暗黑模式切换
初始化后，项目根目录会生成 openspec/ 目录：
bash
openspec/
├── specs/ # 项目整体规范（按能力/capability 组织）
│ ├── auth-login/
│ │ └── spec.md
│ ├── auth-session/
│ │ └── spec.md
│ └── checkout-payment/
│ └── spec.md
└── changes/ # 每次变更的独立文件夹
└── ... # (propose 后自动生成)3.3 安装流程可视化
四、深入使用：三步工作流详解
4.1 Step 1：/opsx:propose ------ 写代码前先说清楚
bash
/opsx:propose 给登录页增加「记住我」功能，用户可勾选保持 30 天免登录执行这个命令后，OpenSpec 会：
- 扫描项目 ------ 分析现有代码结构，理解系统现状
- 读取已有规范 ------ 查看相关 capability 的 spec 文件
- 自动生成变更包 ------ 在
openspec/changes/下创建一个新文件夹：
bash
openspec/changes/add-remember-me/
├── proposal.md ← 变更描述：要做什么、为什么
├── design.md ← 技术方案：怎么实现、关键决策及理由
├── tasks.md ← 任务拆解：[ ] 分步清单
└── specs/ ← 规范增量（diff 格式）
└── auth-session/
└── spec.md ← 展示规范的变化：+ 新增了什么，- 改了什么这里有一个关键设计 ：spec 文件以 diff 格式 呈现，reviewer 不需要通读全文，直接看 + 和 - 就知道这次变更改了什么。
例如：
markdown
## Session Duration
+ 会话过期时间改为可配置，默认 30 天
+ 新增「记住我」勾选框场景：勾选保持 30 天，不勾选浏览器关闭即失效
- 旧逻辑：固定 24 小时过期，无区分4.2 Step 2：/opsx:apply ------ 审查完开始干活
审查 proposal 和 design，确认方案合理后：
bash
/opsx:applyAI 会按照 tasks.md 里的清单，逐个完成任务。关键点：
- 不越界 ------ 只改 proposal 里界定的范围
- 不脑补 ------ 不会自作主张重构其他代码
- 不乱改 ------ tasks 清单就是执行边界
4.3 Step 3：/opsx:archive ------ 做完归档
bash
/opsx:archive变更完成，规范文件随代码一起提交到仓库。这意味着：
- 下一次任何人（同事、新人、未来的你）打开项目，读 spec 文件就能理解系统
- 下一次任何 AI（Cursor、Claude Code、CodeBuddy）打开项目，自动获得完整上下文
- 下一次任何时间（下周、下个月、明年），上下文不会丢失
4.4 工作流总览
五、到底好在哪？六大维度对比
5.1 裸用 AI vs OpenSpec
| 维度 | 裸用 AI（Chat 模式） | 使用 OpenSpec |
|---|---|---|
| 需求存在哪 | 聊天记录，关了窗口就没了 | 仓库里的 spec 文件，永久可查 |
| 变更范围 | AI 自己脑补，经常越界 | proposal 明确界定边界 |
| 团队协作 | 你的人和同事的人理解不同 | 同一份 spec，大家对齐 |
| 新人/新工具接手 | 翻聊天记录？不存在的 | 读 spec 文件即可理解系统 |
| 换模型/换工具 | 上下文全丢，从头解释 | spec 文件是模型无关的 |
| 代码审查 | 看代码猜意图 | 先看 spec 变更，一目了然 |
真实感受：用了 OpenSpec 之后，AI 写代码这件事终于从「赌运气」变成了「可预期」。
5.2 核心差异类比
纯对话式 AI 编程 就像在黑板上写字------下课就擦。
OpenSpec 是把内容写进笔记本------翻到哪一页都在，换谁来看都懂。
为什么这个类比成立？
- 黑板（聊天记录）：容量有限，擦了就没了，其他人看不到
- 笔记本（spec 文件）：随代码一起版本控制，Git history 可追溯，PR 可 review
5.3 四大核心优势
持久上下文 ------ 规范存仓库里，聊天关了也不丢，新人读 spec 就能上手
精准可控 ------ proposal 明确边界，AI 不再越界脑补，改什么一清二楚
工具无关 ------ 支持 25+ AI 工具，不绑定任何模型或 IDE，规范文件可随你切换到任何工具
轻量极简 ------ 一条 npm 命令安装，无 API Key、无 MCP 依赖，3 分钟即可上手
六、竞品对比：OpenSpec vs Spec Kit vs Kiro
| 对比维度 | OpenSpec | GitHub Spec Kit | AWS Kiro |
|---|---|---|---|
| 安装 | ✅ 一条 npm 命令 | ❌ 需要 Python 环境 | ❌ 绑定 IDE |
| 工作流 | ✅ 流动灵活，可随时修改 | ❌ 阶段门禁严格，像小瀑布 | ➖ IDE 内置 |
| 模型绑定 | ✅ 不绑定任何模型 | ✅ 不绑定 | ❌ 只能用 Claude |
| 棕地项目 | ✅ 专为已有项目设计 | ❌ 偏绿地项目 | ➖ 未明确 |
| 支持工具数 | ✅ 25+ 款 AI 工具 | ➖ 有限 | ❌ 仅 Kiro IDE |
| 学习成本 | ✅ 3 个命令上手 | ❌ proposal→spec→plan→tasks→implement | ➖ 中等 |
| 开源 | ✅ MIT | ✅ MIT | ❌ 闭源 |
选择建议
- 已有项目、多工具切换 → OpenSpec
- GitHub 深度绑定、喜欢严格流程 → Spec Kit
- 只用 Kiro IDE + Claude → Kiro（但你被锁定了）
七、进阶实践：最佳使用姿势
7.1 Spec 怎么写？
好的 spec 不是流水账，要回答三个问题：
markdown
# auth-session
## Behavior（行为）
- 用户登录后，服务端生成 session token，有效期可配置（默认 30 天）
- 前端存储 token 于 httpOnly cookie
## States（状态）
- `authenticated`：已登录，token 有效
- `expired`：token 过期，需重新登录
- `anonymous`：未登录
## Scenarios（场景）
### 正常登录
Given 用户输入正确凭证
When 点击登录
Then 返回 token，跳转首页，cookie 写入
### 「记住我」勾选
Given 用户勾选「记住我」
When 登录成功
Then token 有效期设为 30 天，关闭浏览器不影响
### 「记住我」未勾选
Given 用户未勾选「记住我」
When 登录成功
Then token 有效期设为 session，关闭浏览器即失效7.2 什么场景该写 spec？
不是每个小改动都需要完整的 propose → apply → archive 流程。建议分级：
| 级别 | 场景 | 流程 |
|---|---|---|
| L1：小修小补 | 修个 typo、调个样式 | 直接用 AI 改，结束后 /opsx:archive 补记录 |
| L2：功能迭代 | 加个新功能、改个逻辑 | 完整 /opsx:propose → apply → archive |
| L3：架构变更 | 重构、迁移、大改 | 写详细的 design.md，team review 后再 apply |
7.3 团队协作模式
bash
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 产品/PM │ │ 开发者 │ │ Reviewer │
│ │ │ │ │ │
│ 提出需求 │ ──→ │ /opsx:propose│ ──→ │ 审查 proposal │
│ │ │ 生成四件套 │ │ + design │
│ │ │ │ │ + spec delta │
└──────────────┘ └──────┬───────┘ └──────┬────────┘
│ │
│ LGTM ✅ │
↓ │
┌──────────────┐ │
│ /opsx:apply │ ←─────────┘
│ AI 按 tasks │
│ 逐步实现 │
└──────┬───────┘
↓
┌──────────────┐
│ /opsx:archive│
│ 提交 + 归档 │
└──────────────┘八、常见问题
Q：OpenSpec 适合小项目吗？
完全适合。越是小项目越容易做到「规范全量覆盖」。大项目反而需要渐进式迁移------每次改哪个模块，就给哪个模块补上 spec。
Q：跟 AI 工具自带的计划模式有什么区别？
一句话：计划模式活在当前会话里，OpenSpec 活在代码仓库里。 你换台电脑、换个工具、甚至过一个月再回来，spec 文件都在。
Q：是不是在搞「微瀑布」？
不是。OpenSpec 强调「流动」，proposal 和 design 随时可以回头改。它不是「先写死再执行」，而是「先对齐再迭代」。
Q：有没有成功案例？
OpenSpec 本身就是用 OpenSpec 开发的（吃自己的狗粮）。Fission-AI 团队用它管理整个项目的开发流程，5 万 Star 的社区也在用。
写在最后
AI 编程工具已经很强了，但「没有记忆、不懂规范」这件事，是几乎所有工具的硬伤。
OpenSpec 做的事情不复杂：把规范变成一个与代码同等重要的一等公民。持久化、可追溯、可审查。
它解决的，是 AI 编程最痛的那个问题：人和 AI 之间的那道信息鸿沟。
📎 参考链接
- GitHub：github.com/Fission-AI/...
- 官网：openspec.dev
- Discord 社区：discord.gg/YctCnvvshC
- npm 包：@fission-ai/openspec
你用 AI 写代码时遇到过哪些翻车瞬间？欢迎评论区分享。如果这篇文章对你有帮助，点赞、收藏 支持一下 🙏