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

当 AI 提笔就能写代码时，我们真正缺的是什么？其实不是更猛的代码生成器，而是能让大家达成共识的靠谱机制。

引言：大家肯定都遇到过这种坑

每天免费领 1亿 Token，白嫖DeepSeek、GLM、MiniMax、Kimi等大模型！

想象一下，你正跟 AI 编程助手聊得热火朝天，新功能眼看就要写好了。你觉得一切尽在掌握，但现实往往会打脸：

• 隔了一阵子再想接着干，发现之前的聊天上下文全丢了。
• 需求全散落在碎碎念的聊天记录里，每次问 AI 得到的理解都不一样。
• 队友一脸懵逼，完全不知道这功能当初是怎么拍脑袋定的。
• 代码是跑起来了，但没人说得清为什么要这么写。
  这事儿其实不赖 AI，关键是咱跟 AI 伙计配合的姿势不对。
  每天免费领 1亿 Token，白嫖DeepSeek、GLM、MiniMax、Kimi等大模型！
  今天我想聊聊一个叫 OpenSpec 的开源小工具。它没玩什么虚的概念，就是想让"规范驱动开发"这套理论在 AI 时代真正接上地气。

啥叫规范驱动开发？

简单说，规范驱动开发（Spec-Driven Development）就是一句话：动笔写代码前，先抠清楚系统到底要干啥 。

这其实是老生常谈了，以前的 BDD（行为驱动开发）或者 ATDD（验收测试驱动开发）都在捣鼓这事儿。但在 AI 满地走的今天，这个老办法有了新用法：

以前开发：拿需求文档 → 脑子消化 → 手撸代码
AI 时代：说需求 → AI 琢磨 → 自动出码 → 结果好坏看运气

毛病出在 AI 的"理解力"是即兴发挥的。需求要是只停留在嘴边或聊天框里，那一致性基本就是天方夜谭。

OpenSpec 的作用，就是在人和 AI 之间垒起一层能持久保存的共识墙。

OpenSpec 到底是怎么设计的？

增量式规范（Delta Specs）

以前写规范最头疼的就是：改个小功能，还得翻遍整本"大部头"，还得琢磨哪块儿被动了。

OpenSpec 搞了个"增量规范"的法子：

# 登录模块的增量更新
## 新加的需求
### 需求点：二次验证（2FA）
系统登录时必须得过第二道关。
#### 测试场景：需要输入验证码
- 假如：用户开了 2FA
- 当：账号密码输对了
- 那么：跳出个验证码输入框
## 改掉的需求
### 需求点：登录有效期
没操作 30 分钟就踢下线。（以前是 60 分钟）
## 删掉的需求
### 需求点：记住我
（有了 2FA 后，这功能就撤了）

这么搞有啥好处？

1. 一目了然：变了啥一眼就能瞅见。
2. 好收拾：想归档时直接往主规范里一合就行。
3. 有据可查 ：所有的变更黑历史都存在 archive 文件夹里。
   每天免费领 1亿 Token，白嫖DeepSeek、GLM、MiniMax、Kimi等大模型！

围着"工件"转的工作流

每一个功能改动（Change）都有自己的小窝，里面雷打不动放着四样宝贝：

openspec/changes/add-dark-mode/
├── proposal.md    # 动机：为啥干，干点啥
├── specs/         # 规矩：增量格式的需求
├── design.md      # 方案：技术上怎么搞
└── tasks.md       # 活儿清单：一步步怎么走

这几个文件是怎么串起来的：

提案 (why) ───► 规范 (what) ───► 设计 (how) ───► 任务 (steps) ───► 干活
    │               │               │                       │
    └───────────────┴───────────────┴───────────────────────┘
                     感觉不对劲？随时回去改

这里有个细节：这些文件不是一成不变的阶段，而是看问题的不同视角。干活时发现设计不合理，或者设计时发现需求有漏洞，随时回头改，一点不纠结。

顺滑的操作体验

OpenSpec 讲究的是"灵活"，不是要把你捆死：

想快点搞定：
/opsx:propose ──► /opsx:apply ──► /opsx:archive
想仔细琢磨：
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ...

没什么硬性规定。你可以：

• 用 /opsx:propose 一口气把活儿全排好。
• 用 /opsx:explore 先跟 AI 瞎聊，把思路理清。
• 用 /opsx:continue 一步步把文档补齐。
• 用 /opsx:verify 在收工前看看代码跟规范对不对得上。

练手案例：整一个深色模式

光说不练假把式，咱以加个"深色模式"为例。

第一步：甩出提案

你: /opsx:propose add-dark-mode
AI: 文件夹 openspec/changes/add-dark-mode/ 搞定了！
    ✓ proposal.md --- 动机和范围定好了
    ✓ specs/       --- 需求场景写好了
    ✓ design.md    --- 方案定在用 CSS 变量
    ✓ tasks.md     --- 任务单子列好了
    老板，随时开工！

第二步：过一遍，改改细节

看看 AI 写的 proposal.md：

# 提案：加上深色模式
## 目的
用户嫌晚上用着扎眼，得加个深色主题。
## 范围
要做：
- 设置里能切主题
- 自动跟系统颜色走
- 关了网页也能记住选了啥
不做：
- 各种花里胡哨的自定义颜色
- 每个页面单独设主题
## 大致思路
用 CSS 自定义属性搞定皮肤，用 React Context 管状态。

每天免费领 1亿 Token，白嫖DeepSeek、GLM、MiniMax、Kimi等大模型！

看哪儿不爽直接改文件，这可不是死文档，这是你跟 AI 沟通的底稿。

第三步：直接开干

你: /opsx:apply
AI: 正在埋头苦干...
    ✓ 1.1 把 ThemeContext 写好了
    ✓ 1.2 搞定了 CSS 自定义属性
    ✓ 1.3 记住了用户的选择
    ✓ 2.1 做了个切换开关
    ✓ 2.2 塞进了设置页
    全部搞定，请过目！

第四步：打包归档

你: /opsx:archive
AI: 正在整理 add-dark-mode...
    ✓ 增量规范已经合进总表了
    ✓ 资料都挪进 openspec/changes/archive/2025-01-24-add-dark-mode/ 了
    利索！可以干下一个活了。

收工后，规范更新了，过程也存好了。下次有人问"当初为啥这么写？"，直接让他去 archive 翻。

凭啥选 OpenSpec？

跟别的工具比比看

对比 GitHub Spec Kit

那位是大而全的重量级选手。流程硬、文档多、还得配 Python。大厂正规军用着香，但对于追求速度的小团队来说，实在是有点沉。
对比 AWS Kiro

挺厉害，但你得被绑在人家的 IDE 和模型上。OpenSpec 就不一样，你爱用啥工具都行。
对比"啥也不用"

啥也不用就纯靠嘴说，AI 给你的结果就像开盲盒。今天运气好给套神码，明天可能就给你整堆垃圾。

核心卖点

1. 共识第一：写代码前，人和 AI 先把"我们要干啥"对齐了。
2. 整整齐齐：一个变动一个坑，前因后果清清楚楚。
3. 不死板：流程能进能退，怎么舒服怎么来。
4. 不挑食 ：20 多种 AI 编程助手都能带得动。
   每天免费领 1亿 Token，白嫖DeepSeek、GLM、MiniMax、Kimi等大模型！

背后的一点技术细节

架构长啥样

OpenSpec 是分层设计的：

┌─────────────────────────────────────────────────────────┐
│                     命令行层 (CLI)                       │
│  各种指令：init, update, list, show, validate, view      │
└─────────────────────────────────────────────────────────┘
                           │
┌─────────────────────────────────────────────────────────┐
│                     核心逻辑层                           │
│  管文件的、对格式的、管逻辑依赖的                          │
└─────────────────────────────────────────────────────────┘
                           │
┌─────────────────────────────────────────────────────────┐
│                     工具适配层                           │
│  接 Claude Code, Cursor, Windsurf, Copilot 等等         │
└─────────────────────────────────────────────────────────┘

工件之间的依赖

它是根据 Schema 来定谁先谁后的：

工件规则:
  - id: proposal (提案)
    requires: []              # 谁也不靠，第一个出来
  - id: specs (规范)
    requires: [proposal]      # 提案定了再写规范
  - id: design (设计)
    requires: [proposal]      # 跟规范一块儿干也行
  - id: tasks (任务)
    requires: [specs, design] # 需求和方案齐了再分活

这依赖是用来帮忙的，不是用来卡人的。它只是告诉 AI 啥时候该干啥事。

会动的指令生成

OpenSpec 没用死板的提示词，而是搞了动态组装：

老办法：AI 每次都听那一套磨耳朵的话
OpenSpec 办法：指令现场攒，分三层
├── 项目背景（技术栈、老规矩）
├── 各种约束（比如"不确定的先去探索"）
└── 模板样子（文件最后长啥样）

AI 会自己调 CLI 去问现在的状态：有什么文件了、该建啥了、条件够不够。

团队怎么一起玩？

自己撸代码

哪怕是单机玩家，这玩意儿也挺好使：

• 歇个周末回来，看眼 proposal.md 瞬间回魂。
• 任务清单在那儿摆着，干到哪儿了心里有数。
• archive 就是你的个人决策日记。
  每天免费领 1亿 Token，白嫖DeepSeek、GLM、MiniMax、Kimi等大模型！

团队合砍项目

多人协作时，OpenSpec 的威力就出来了：

• 先看动机再看代码：方案行不行，代码没写前就能吵个明白。
• 各忙各的：几个改动同时开工，互不耽误。
• 新人救星：新同学想了解过去的事儿，翻翻 archive 就行。

企业级用法

OpenSpec 还支持：

• 自己定规范格式（去 openspec/schemas/ 改）。
• 项目定制化配置（openspec/config.yaml）。
• 离线跑（纯 npm 包，不用连外网）。

避坑指南与最佳实践

别把活儿揽得太杂

一个改动就干一件事。要是你想"加个功能顺便重构一下"，听我的，分两个文件夹。
为啥？

• 别人审你代码时不头大。
• 历史记录干净利索。
• 撤回也方便。

起名别太随性

靠谱的名字：           别这么起：
add-dark-mode          feature-1
fix-login-redirect     update
optimize-product-query changes
implement-2fa          wip

名字起得好，openspec list 看起来才顺眼。

别过度工程

没必要非得按最严的标准来，够用就行：
轻量级（平时多半用这个）：

• 简单说下要干嘛。
• 划清界限。
• 搞几个关键测试点。
  全量级（碰大事儿才用）：
• 涉及好几个团队或仓库。
• 动了 API 契约。
• 关乎安全和隐私。
• 错了得赔大钱的买卖。

归档前扫一眼

你: /opsx:verify
AI: 正检查 add-auth 呢...
    
    干完没？
    ✓ 12 个活儿都利索了
    ✓ 规范里的需求代码都写了
    ⚠ "登录超时"那个场景没测呢
    
    对不对？
    ✓ 确实按当初的想法写的
    ✓ 边角料情况也考虑了
    
    乱不乱？
    ✓ 代码结构跟设计对得上
    
    结论
    ─────────────────────
    没大毛病，有一个警告，归不归档你看着办。

每天免费领 1亿 Token，白嫖DeepSeek、GLM、MiniMax、Kimi等大模型！

验证只是提个醒，决定权还在你手里。

几分钟上手

安装

确认你本地 Node.js 至少是 20.19.0 版本。

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

初始配置

cd 你的项目
openspec init

这步会帮你：

1. 看看你电脑上有啥 AI 工具。
2. 让你选一个喜欢的搭档。
3. 把 openspec/ 的地盘占好。
4. 把那些好用的斜杠指令整出来。

怎么玩

直接跟你的 AI 助理事先打个招呼：/opsx:propose <你想干的活>

接下来的事儿就水到渠成了。

指令全家桶

指令	干啥用的	啥时候调
/opsx:propose	规划加开工	想要快点出活
/opsx:explore	瞎琢磨	还没想好咋整
/opsx:new	搭个空架子	想自己慢慢填
/opsx:continue	接茬干下一个文档	循序渐进
/opsx:ff	方案全拉满	思路特清晰的时候
/opsx:apply	写代码	该动手了
/opsx:verify	自检一下	收工之前
/opsx:archive	撤场归档	全干完了
CLI 自己的命令：

openspec list          # 看看手头有哪些活
openspec show <名字>   # 瞅瞅某个活的细节
openspec validate      # 查查规范写错没
openspec view          # 搞个仪表盘看看
openspec update        # 给 AI 指令升个级

总结：AI 编程到底在搞什么？

每天免费领 1亿 Token，白嫖DeepSeek、GLM、MiniMax、Kimi等大模型！

现在的 AI 确实越来越猛，但咱们跟它打交道的方式还是老一套------漫无目的地聊，聊完就忘，没留个抓手。

OpenSpec 走的是另一条道：别指望 AI 每次都能精准猜中你的心思，而是要把你的心思清清楚楚写下来，让这份意图变得能追溯、能协作、能核对。

这可不是让你回去写那种死板的老派文档。它的核心就是"轻快"------够用就行，不磨叽，一切为了实战。

如果你想让 AI 编程变得靠谱点、有迹可循点，OpenSpec 值得一试。说到底，AI 能写代码不稀奇，能让大家（包括 AI）对目标达成共识，才是真正的硬实力。