OpenSpec：让 AI 编程从碰运气到有章可循

发表于 分类于 ， 阅读次数： 本文字数： 3.5k 阅读时长 ≈ 13 分钟

用 AI 写代码久了，你可能会遇到这些场景：

  • 和 AI 反复拉扯，修改了 N 遍还是不对
  • 明明上次说好的规范，新会话又忘了
  • 代码改完不敢合并，因为不知道到底改了啥
  • 几个人一起用 AI 开发，结果代码风格完全不统一

如果这些问题你都遇到过，说明你不是一个人。这篇文章想聊聊为什么会这样，以及如何用 OpenSpec 来解决这些问题。

第一部分：Vibe Coding 的困境

什么是 Vibe Coding？

Vibe Coding，也叫”氛围编程”，就是用自然语言和 AI 对话来完成编程任务。比如：

  • “帮我写个用户登录功能”
  • “这个按钮的样式改成蓝色”
  • “优化一下这段代码的性能”

听起来很美好对吧？但实际使用中，我们遇到了一系列问题。

10 个常见痛点

我总结了 AI 编程中的 10 个常见痛点：

表达层问题：

  1. 词不达意（Expression Gap）：想得清楚但说不清楚。你脑子里有个很清晰的概念，但就是说不出来，或者说出来 AI 理解的不是你想的那个意思。
  2. 意图偏离（Intent Drift）：AI 理解和你想的不一样。你说”加个缓存”，AI 给你上了 Redis 分布式缓存，其实你只想要个内存缓存。
  3. 范围蔓延（Scope Creep）：边界模糊导致功能膨胀。你说”加个搜索”，AI 给你实现了关键词搜索、模糊匹配、拼音搜索、搜索历史、热门推荐……你只要一个简单的关键词搜索。你说”加个头像功能”，AI 给你头像上传、裁剪、历史记录、审核功能全套……你只是想显示个头像而已。

记忆层问题：

  1. 上下文断裂（Context Fragmentation）：跨会话丢失约定。上周和 AI 说好用 Tailwind，今天新会话又给你用 styled-components。
  2. 变更混乱（Change Chaos）：不知道改了什么、为什么改。AI 说”帮你优化了一下”，结果改了 15 个文件，你都不知道为什么要改。
  3. 重复劳动（Repetitive Work）：每次都要重新解释。每个新会话都要重新介绍项目背景、技术栈、代码规范……
  4. 协作困难（Collaboration Friction）：多人信息不对称。你让 AI 实现了用户模块用方案 A，同事不知道，也让 AI 实现了用户相关功能用方案 B，结果产生冲突。

执行层问题：

  1. 不可预测（Unpredictability）：同样的话，不同的结果。第一次问”写个表单验证”用 Yup，第二次问可能用 Zod。
  2. 场景遗漏（Scenario Gaps）：只考虑正常路径。AI 实现了登录成功的情况，但密码错误、账号锁定、网络超时这些异常情况都没考虑。
  3. 机械执行（Blind Execution）：不质疑明显问题。你说”在登录页加个删除用户按钮”，AI 也不问为什么，直接给你加上了。

问题的根源

这些问题的根源是什么？

AI 的不确定性。

AI 大语言模型是基于概率的。它的工作原理是：

1
输入 Token → 概率分布 → 采样 → 输出 Token

这中间有个 temperature 参数控制随机性。这意味着：

  • 同样的输入，可能产生不同的输出
  • AI 的”理解”是概率性的，而非确定性的
  • 无法保证每次都得到一致的结果

我们无法改变 AI 的本质。但我们可以通过结构化的输入和约束来降低输出的不确定性。

第二部分：解决思路

既然知道了问题的根源，我们就可以想对策了。

七大解决策略

  1. 结构化的表达格式：用模板替代自由文本，减少表达歧义
  2. 强制的对齐环节：在执行前确保理解一致
  3. 明确的边界定义：定义”做什么”和”不做什么”
  4. 持久化的上下文：项目信息跨会话保持一致
  5. 完整的变更记录：每次变更都有清晰的追溯
  6. 可复用的知识库：积累的项目知识可以持续复用
  7. 统一的规范来源：团队共享同一份”真相”

这些策略都很好，但如果人工来执行：

  • 每次手写模板，格式不统一
  • 人工组织 Review，流程不固化
  • 复制粘贴项目信息，繁琐易错
  • 手动创建目录和文件，结构不一致

结论：策略是好策略，但人工执行成本太高，难以坚持。

我们需要一个工具来帮我们自动化这些事情。这个工具就是 —— OpenSpec。

第三部分：OpenSpec 介绍

什么是 OpenSpec？

OpenSpec 是一个面向 AI 编码助手的规范驱动开发（Spec-driven Development）工具。

核心理念是：在编写代码之前，让人类与 AI 达成一致。

用一个公式来表达：

1
OpenSpec = 结构化需求 + 变更管理 + AI 指令 + CLI 工具

六大核心特性

  1. 无需 API 密钥：OpenSpec 不调用 AI API，只生成指令文件供各种 AI 工具读取
  2. 轻量级工作流：文件即文档，Markdown 即规范，Git 即版本控制
  3. 支持 20+ AI 工具：Claude Code、Cursor、Copilot、CodeBuddy 等主流工具都支持
  4. Brownfield 友好：可以渐进式引入到现有项目
  5. Delta-based 变更：只记录变化，不复制全量
  6. 可追溯可审计：每个变更都有完整的生命周期记录

三阶段工作流

OpenSpec 的核心是三阶段工作流：

1
2
3
4
5
6
Stage 1: 创建变更        Stage 2: 实施变更        Stage 3: 归档变更
   ↓                        ↓                        ↓
/openspec:proposal      /openspec:apply         openspec archive
   ↓                        ↓                        ↓
生成提案文档             按序执行任务             合并到规范
人工审核确认             更新进度                 历史存档

这个流程的关键在于：提案审核是强制环节。在 AI 开始写代码之前，必须先生成结构化的提案，经过人工审核确认后，才能开始实施。

第四部分：产物与流程

产物目录结构

初始化 OpenSpec 后，项目会增加以下目录结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
openspec/
├── project.md         # 项目级上下文和约定
├── AGENTS.md          # AI 助手指令
├── specs/             # 当前真相（已实现的功能规范）
│   └── [capability]/
│       ├── spec.md    # 需求规范 (WHAT + WHY)
│       └── design.md  # 技术设计 (HOW, 可选)
└── changes/           # 变更提案
    ├── [change-name]/
    │   ├── proposal.md    # 为什么改、改什么、影响
    │   ├── tasks.md       # 实现任务清单
    │   ├── design.md      # 技术决策 (可选)
    │   └── specs/         # Delta 变更
    └── archive/           # 已完成归档

各产物的作用

project.md：定义项目整体信息，供 AI 理解项目背景。包括技术栈、代码规范、架构模式、测试策略等。

AGENTS.md：指导 AI 如何使用 OpenSpec，定义三阶段工作流，约束 AI 行为。

**specs/**：记录已实现功能的需求规范，是”当前真相”（Single Source of Truth）。

**changes/**：存放变更提案，包括提案说明、任务清单、技术设计和规范增量。

规范文件格式

spec.md 使用特定格式：

1
2
3
4
5
6
7
8
9
10
### Requirement: User Login
The system SHALL authenticate users with valid credentials.

#### Scenario: Successful login
- **WHEN** user submits correct credentials
- **THEN** system grants access

#### Scenario: Invalid password
- **WHEN** user submits wrong password
- **THEN** system displays error

格式要点：

  • ### Requirement: 定义需求（3 个 #）
  • #### Scenario: 定义场景（4 个 #）
  • 每个需求至少一个场景
  • 使用 SHALL/MUST 表示规范性要求

第五部分：示例演示

让我用一个实际例子来演示 OpenSpec 的完整流程。

场景：添加收藏功能

假设我们有一个电商项目，需要添加”用户收藏商品”功能。

Step 1: 初始化项目

1
2
cd my-ecommerce-project
openspec init

选择要配置的 AI 工具（如 Claude Code、CodeBuddy），系统会自动创建目录结构和配置文件。

然后填写 project.md，定义项目上下文。

Step 2: 创建提案

向 AI 描述需求：

我想让用户可以收藏商品，方便之后购买。用户可以在商品详情页点击收藏按钮，在个人中心可以看到收藏列表，也可以取消收藏。

执行 /openspec:proposal，AI 会生成：

proposal.md：

1
2
3
4
5
6
7
8
9
10
11
## Why
用户经常浏览商品但不立即购买，需要收藏功能方便后续查找。

## What Changes
- ADDED: 商品收藏功能
- ADDED: 收藏/取消收藏 API
- ADDED: 收藏列表页面

## Impact
- Affected specs: product-catalog
- Affected code: prisma/schema, src/api/favorites, src/pages/user

tasks.md：

1
2
3
4
5
6
7
8
9
10
11
## 1. Database Setup
- [ ] 1.1 Create Favorite model
- [ ] 1.2 Run migration

## 2. Backend API
- [ ] 2.1 Create FavoriteService
- [ ] 2.2 Implement API endpoints

## 3. Frontend
- [ ] 3.1 Create FavoriteButton component
- [ ] 3.2 Create FavoritesList page

spec delta：

1
2
3
4
5
6
7
8
9
10
11
12
## ADDED Requirements

### Requirement: Product Favorites
The system SHALL allow users to favorite products.

#### Scenario: Add to favorites
- **WHEN** user clicks favorite button
- **THEN** product is added to favorites

#### Scenario: Remove from favorites
- **WHEN** user clicks on favorited product
- **THEN** product is removed from favorites

Step 3: 人工审核

这一步非常关键。我需要检查：

  • Why 是否准确描述了需求背景？
  • What Changes 是否完整列出了变更？
  • Scenarios 是否覆盖了边界情况？

比如我发现少了一个场景：”商品下架后收藏列表如何处理？”

就让 AI 补充：

1
2
3
#### Scenario: View favorites with unavailable products
- **WHEN** user views favorites containing unavailable products
- **THEN** unavailable products are marked with "已下架"

确认无误后，告诉 AI：”提案已批准，可以开始实施”。

Step 4: 执行实施

执行 /openspec:apply add-product-favorites，AI 按 tasks.md 顺序执行任务：

  1. 创建数据库模型
  2. 实现 API 端点
  3. 创建前端组件
  4. 编写测试

每完成一项，tasks.md 中对应的 [ ] 会变成 [x]。

Step 5: 归档变更

所有任务完成后：

1
openspec archive add-product-favorites

系统会：

  1. 将 delta 合并到 specs/product-catalog/spec.md
  2. 将变更目录移动到 changes/archive/2025-01-15-add-product-favorites/

归档后，规范更新了，历史也保留了。

第六部分：OpenSpec 解决了哪些问题？

直接解决的 8 个问题

痛点 OpenSpec 方案
词不达意 结构化模板强制完整表达
意图偏离 提案审核机制对齐意图
范围蔓延 Goals/Non-Goals 明确边界 + 审核限制扩展
上下文断裂 project.md 持久化上下文
变更混乱 changes/ 完整追踪
重复劳动 规范复用，无需重复解释
场景遗漏 Scenario 格式强制覆盖
协作困难 specs/ 作为统一真相来源

间接缓解的 2 个问题

  • 不可预测：技术栈约束减少选择空间，但 AI 生成仍有随机性
  • 机械执行：澄清环节提供质疑机会，但不能保证 AI 一定会质疑

无法完全解决的问题

  • 代码质量仍依赖模型能力
  • 复杂业务逻辑需要人工验证
  • 安全漏洞需要专门工具检测

第七部分：优缺点与适用场景

优点

  1. 降低不确定性：从”赌运气”变成”有章可循”
  2. 知识沉淀复用：项目越用越”聪明”
  3. 变更可追溯：知道”改了什么”、”为什么改”
  4. 团队协作友好：消除信息不对称
  5. 工具无关性：支持 20+ AI 工具
  6. 轻量级实施：低成本引入，渐进式采用

缺点

  1. 增加前期工作量：写提案比直接写代码”慢”
  2. 学习成本：需要学习新的概念和流程
  3. 维护负担：需要持续维护规范文档
  4. 不保证代码质量：约束”做什么”，不保证”做得好”
  5. 小任务过重：简单任务走完整流程太繁琐

适用场景

适合使用：

  • 中大型功能开发（开发时间 > 2 小时）
  • 团队协作项目
  • 长期维护项目
  • 复杂业务逻辑

不适合使用：

  • 快速原型验证
  • 一次性脚本/工具
  • 简单修改/Bug 修复
  • 学习/实验项目

第八部分：实践中的问题与改进

在实际使用中，我发现了一些流程上的缺口：

问题 1：提案缺乏强制校验

提案生成后，可能有格式错误或决策问题，完全依赖人工审核。

改进：创建 /proposal-verify Skill，在提案完成后自动验证格式、检查决策、触发自我反思。

问题 2：实施缺乏对齐检查

实施完成后，没有自动检查代码是否符合提案、场景是否都实现了。

改进：创建 /apply-verify Skill，验证任务完成度、提案对齐、场景覆盖、副作用检测。

问题 3：归档缺乏规范约束

有时候会用 mv 命令直接移动目录，跳过了 delta 合并。

改进：创建 /archive-verify Skill，强制使用正确的归档命令，验证合并正确性。

改进后的流程

1
2
3
需求 → 提案 → [proposal-verify] → 实施 → [apply-verify] → 归档 → [archive-verify]
              ↑                          ↑                       ↑
           验证点                     验证点                   验证点

第九部分：最佳实践总结

何时需要提案？

1
2
3
4
5
6
新请求到来
├── Bug 修复？ → 直接修
├── 拼写格式？ → 直接修
├── 新功能？ → 要提案
├── 破坏性变更？ → 要提案
└── 不确定？ → 要提案（更安全）

推荐流程

  1. 初始化：openspec init，填写 project.md
  2. 提案：描述需求，执行 /openspec:proposal，审核确认
  3. 实施：执行 /openspec:apply，监督执行，更新进度
  4. 归档：openspec archive，合并规范，存档历史

核心原则

  • 提案是强制环节，不可跳过
  • 审核是人的责任，不可偷懒
  • 规范是团队共享的真相来源
  • 变更可追溯，决策有记录

总结

OpenSpec 的核心价值是什么？

在编码前对齐意图，通过结构化的表达、持久化的上下文、可追溯的变更记录，让人与 AI 的协作从”碰运气”变成”有章可循”。

它不是银弹，不能解决所有问题。但对于需要准确性和可维护性的场景——团队协作、长期维护、复杂业务——OpenSpec 可以显著降低 AI 编程的不确定性，提高一次性成功率。

如果你经常和 AI 反复拉扯，如果你在 AI 编程中遇到协作问题，不妨试试 OpenSpec。

1
2
npm install -g openspec
openspec init

感兴趣的话可以到项目主页查看更多信息：https://github.com/fission-ai/openspec