从 “凭感觉写代码” 到 “按规范做开发”：OpenSpec 让 AI 编程回归工程化

效率与混乱的悖论：AI 编程的 "甜蜜烦恼"

先说说规范驱动开发（简称 Spec Coding）到底是什么。简单讲，就是先画好 "工程设计图"，再动手写代码，这张 "设计图" 就是规范文档。和传统开发里 "需求文档只作参考" 不同，在 Spec Coding 里，规范是 "唯一的真相源"------ 代码只要偏离规范，就是不合格的。

Spec Coding：先定规矩，再写代码

Spec Coding 正是为解决这个问题而来。核心思路就是用 "刚性规范" 替代 "柔性迭代"------ 写第一行代码前，先把清晰、结构化的规范文档立起来，让开发者和 AI 对 "要做什么、怎么做、做到什么标准" 达成共识。

当然，Spec Coding 也有短板

• 启动成本高：从零写一份完整规范，比随口跟 AI 描述需求慢得多。有人吐槽这是 "瀑布模型换皮"------ 你花几天写文档的功夫，别人用 Vibe Coding 都跑出 Demo 了。
• 规范易臃肿，维护成本高：如果没把握好度，很容易写出冗长难懂的规范文件，甚至出现 "为了让 AI 理解，手工写一堆详细规则，最后根本没法规模化" 的问题。
• 场景有局限：探索性强的项目、需求天天变的初创产品，Spec Coding 的 "刚性" 反而会拖慢迭代速度。

不过要明确的是，这两种模式不是非此即彼：Vibe Coding 并非一无是处，快速原型阶段用它依然高效；而在复杂功能开发、企业级系统建设中，Spec Coding 的价值会格外突出。

OpenSpec：让 Spec Coding 轻量化落地

聊完理念，可能有人会抵触："规范" 是不是意味着又要写一堆冗长文档、开一堆评审会？

它最核心的设计，是用 "规范增量" 代替 "完整规范"------ 不用一次性写完整个系统的规范，每次只定义本次要改的 "规范差异" 就行。这意味着 OpenSpec 不仅适合新项目，更能无缝适配已有代码库的迭代。

双文件夹模型：管好 "当前态" 和 "变更态"

OpenSpec 不用绑定任何 API Key，核心就是一套 CLI 工具，在项目的 openspec/ 目录下维护两个关键文件夹：

plaintext

openspec/
├── specs/            # 系统"当前该是什么样"------唯一真相源
│   └── auth/
│       └── spec.md
├── changes/          # "想怎么改"------变更提案
│   └── add-2fa/
│       ├── proposal.md
│       ├── tasks.md
│       └── specs/
└── project.md        # 项目级别的约定

这个设计的巧思在于：specs/ 永远是系统的 "真相源"，changes/ 里是待审批的提案。所有变更都以 "差异（delta）" 呈现 ------ 新增、修改、删除了什么，一目了然。变更确认后，差异会自动合并回 specs/，系统的演变历史也能完整保留。

四步工作流：从想法到代码的闭环

OpenSpec 的标准工作流就四个简单命令，上手毫无压力：

表格

步骤	命令	作用
① 探索	/opsx:explore	头脑风暴，和团队（及 AI）讨论想法
② 提案	/opsx:propose	生成变更计划：提案文档 + 任务清单 + 规范差异
③ 实施	/opsx:apply	审核通过后，按规范和任务清单写代码
④ 归档	/opsx:archive	验证通过后，将变更合并回真相源

实战：用 OpenSpec 给登录加双因素认证

光说不练假把式，我们以 "给用户系统加 TOTP 双因素认证" 为例，走一遍完整流程。

Step 0：安装与初始化

先装工具、初始化项目：

bash

运行

npm install -g @fission-ai/openspec@latest
cd my-app
openspec init

初始化时会让你选择常用的 AI 工具（Claude Code、Cursor、GitHub Copilot 等都支持），自动配置好对应的命令。

这里有个容易忽略但超重要的步骤：填好 openspec/project.md。这份文件是 AI 理解项目的基础，直接决定后续生成的代码是否 "对味"：

markdown

# 项目规范
## 项目目标
用户管理后台系统，支持注册、登录、角色权限管理
## 技术栈
Node.js + Express, PostgreSQL, JWT 认证
## 约定
- API 遵循 RESTful 设计
- 数据验证用 Joi
- 敏感信息不写入日志

Step 1：创建变更提案

在 AI 工具里输入指令：

plaintext

/openspec:proposal 为用户登录流程添加双因素认证（TOTP），用户输入正确密码后，需验证一次性验证码（OTP）才能完成登录。

AI 会自动在 openspec/changes/add-two-factor-auth/ 下生成三个文件：

• proposal.md：说明变更原因、影响范围、验收标准；
• tasks.md：拆分好的实施任务清单，标注待完成项；
• specs/auth/spec.md：只记录本次新增的规范差异。

Step 2：审查规范差异

这一步还没写任何代码，核心是把 "要做什么、做到什么标准" 定清楚。打开规范差异文件，内容大概是这样：

markdown

# 认证模块规范变更
## 新增需求：双因素认证
系统必须在用户密码验证通过后，要求进行基于 TOTP 的二次验证。

### 场景1：需要验证OTP
- 当用户提交有效的账号密码时
- 系统返回 200 状态码，包含 `next_step: "otp_required"`，并生成会话令牌（非最终认证令牌）

### 场景2：OTP验证通过
- 当用户提交有效的会话令牌和OTP时
- 系统返回最终的 JWT 认证令牌

这种 "WHEN-THEN" 的场景化描述，是 OpenSpec 的精髓 ------ 每个需求都有明确的验收标准，AI 写代码、生成测试用例时都有清晰依据。这一步可以和团队、AI 反复打磨，比如补充 OTP 过期时间、异常场景处理等，确保规范能覆盖核心诉求。

Step 3：实施开发

规范审核通过后，执行命令：

plaintext

/openspec:apply add-two-factor-auth

AI 会严格按照 tasks.md 的清单一步步来：装 TOTP 依赖、写 OTP 生成 / 验证服务、改登录路由、更新数据库模型、生成测试用例...... 全程 "按清单做事"，而非 "随机发挥"。此时你要做的，是确认 AI 有没有完成清单里的每一项，而非凭感觉判断代码 "好不好"。

Step 4：归档变更

开发完成、测试通过后，执行：

plaintext

/openspec:archive add-two-factor-auth

规范差异会合并回 openspec/specs/auth/spec.md，提案文件夹也会归档。以后再有人问 "系统支不支持双因素认证"，直接看 specs/ 目录就能得到答案。

不止是工具：OpenSpec 背后的工程思维

试过之后你可能会觉得，OpenSpec 无非是 "帮 AI 写任务清单" 的工具，但它真正改变的，是人与 AI 的协作方式。

传统 Vibe Coding 模式下，开发者和 AI 的互动是这样的：提需求→AI 写代码→看代码→觉得不对就改需求→AI 重写→再看...... 反复循环。核心是开发者对 AI 生成的代码做 "审美判断"------"逻辑对不对？命名好不好？异常处理全不全？" 本质上是用人类的审查速度，追 AI 生成代码的速度，最后往往只能 "看起来能跑就行"。

而 OpenSpec 把协作重构为 "以规范为中心的双层架构"：

• 人类负责 "规划与共识" ：写规范、审规范，讨论边界条件和异常场景，明确 "什么算完成"；
• AI 负责 "落地实施" ：按规范写代码、按清单完成任务、按场景生成测试用例。

这里的核心区别是：你不再盯着代码做 "审美判断"，而是对着规范做 "可行性判断"。代码质量靠规范里的场景和验收标准保障，而非事后的人工审查。

打个比方：Vibe Coding 就像你让 AI 建车间，它边建你边看，随时喊 "这里多开扇窗""那里用料不对"，你全程在给 AI 当 "实时纠错员"；而 OpenSpec 是先和 AI 一起打磨好完整的设计图，确认无误后，AI 按图施工，你只需要检查 "施工是否符合图纸"。你的角色，也从 "带着徒弟干活的工匠"，变成了 "把控设计与落地一致性的架构师"。

该选哪种模式？找到效率与规范的平衡点

其实不用纠结 "非此即彼"，关键看场景：

• Vibe Coding：适合快速原型、一次性脚本、探索性项目 ------ 没想清楚最终要做什么，边试边改就是最快的方式；
• Spec Coding：适合多人协作、长期维护的复杂功能、对质量和合规有要求的企业级系统 ------ 此时 "做对" 比 "做快" 更重要。

OpenSpec 的价值就在于 "不强迫二选一"：你可以先用 Vibe Coding 快速探索想法，等方案成型了，用 /opsx:propose 把想法固化成规范，再切换到 Spec Coding 模式严谨落地。这也是它 "轻量级" 的核心 ------ 不添负担，却能在需要时提供结构。

给想尝试 OpenSpec 的开发者几点建议

1. 别在紧急任务上试手：选一个不赶时间、中等复杂度的功能（比如 "今天不做也没事" 的需求），留足学习和磨合的空间；
2. 先把 project.md 写透：这不是走形式，而是给 AI 建立项目上下文，写得越清楚，后续生成的代码越贴合项目；
3. 规范宁简勿滥：把 3 个核心场景写明白，远比 10 页空话连篇的文档有用。用好 WHEN-THEN 描述，让规范 "可验证"，而非 "只讲道理"；
4. 把 "审规范" 当成新的 Code Review：传统开发看 PR 里的代码，现在看提案里的规范，把注意力从 "代码好不好看" 转移到 "规范完不完整"；
5. 别忘归档：每次变更完成后执行 /opsx:archive，否则 specs/ 会和实际代码脱节，规范最终只会变成摆设。

最后想说

AI 编程让 "写代码" 的速度前所未有地快，但速度的背后，是 "代码生成速度超过人类审查理解速度" 带来的混乱。Spec Coding 的出现是必然的 ------ 它不是限制 AI 的能力，而是给 AI 的速度装上 "方向盘"，让效率和方向兼得。