我是如何理解和使用 OpenSpec 规范的？一个普通开发者的实践之路

从"随意写代码"到"先写规格再写代码"，我经历了什么？

---

引言：一个程序员的困惑

在过去的职业生涯中，我写过无数个项目：有成功的，也有失败的；有高效的，也有返工无数次的。

我一直有一个困惑：为什么有些项目写得特别顺利，从需求到上线一气呵成？而有些项目则总是磕磕绊绊，做着做着就偏离了方向，最后交付的东西和最初的需求相差十万八千里？

直到我遇到了 OpenSpec 规范，一切都变了。

---

一、我是如何接触到 OpenSpec 的？

1.1 曾经的"野生"开发模式

在接触 OpenSpec 之前，我的开发模式是这样的：

场景一：需求来了，直接开干

产品经理：我们要做一个用户管理系统
我：好，我来写代码
（3天后...）
我：做完了，你看看
产品经理：不对，这个权限管理应该是树状的，不是线性的
我：...好吧，我改
（又过了3天...）
产品经理：还有个问题...

场景二：写到一半，发现架构不对

我：这个地方应该用微服务架构
（写了1个月后...）
我擦，这个模块耦合太高了，改不过来了
算了，凑合着用吧
（然后在接下来的1年里，我一直在填自己挖的坑）

场景三：代码写着写着，目标忘了

我：今天来优化一下数据库查询
（优化了2小时后...）
等等，我优化这个是为了什么來着？
算了，当前的优化也是有价值的
（然后就没有然后了...)

这种"野生的"开发模式，让我吃了不少苦头。

1.2 第一次听说 OpenSpec

真正让我开始思考"开发应该怎么组织"，是因为一个偶然的机会。

那时候，我在研究 AI 编程工具（Claude Code、Cursor、Windsurf 等），想看看这些工具是怎么"理解"项目的。

然后我发现了 Spec Kit（GitHub 上的一个开源项目），它提供了一套完整的项目规格定义方法。

更进一步，我发现了 OpenSpec——一个专注于"规格驱动开发"的理念。

OpenSpec 的核心观点是：

在写代码之前，先写规格；在写规格之前，先定原则。

这不正是我需要的东西吗？

---

二、我是如何理解 OpenSpec 的？

2.1 从"宪法"开始

OpenSpec 的第一个阶段是制定宪法（Constitution）。

我一开始觉得这个概念很抽象——"一个代码项目，还要宪法？"

但当我真正去思考的时候，我发现这太重要了。

什么是项目的"宪法"？

简单来说，就是回答这三个问题：

1. 我们是什么？ —— 项目的定位和目标
2. 我们要做什么？ —— 项目的边界和核心功能
3. 我们怎么做？ —— 项目的治理原则和协作方式

拿我现在做的 TraceOne 项目来说：

项目定位：一个 AI 时代的个人数字工作空间
核心目标：帮助个人创作者用 AI 技术提升工作效率
治理原则：
  - 规格先行：任何功能都必须先写规格再写代码
  - 渐进验证：小步迭代，每步都要验证
  - 文档驱动：代码即文档，文档即代码

这就是我们项目的"宪法"。

有了"宪法"之后，团队里的每个人都知道：

• 什么该做，什么不该做
• 遇到争议时，以什么为判断标准
• 新的需求来了，该往哪个方向走

2.2 规格是"契约"，不是"文档"

在 OpenSpec 中，规格（Specification）是第二个阶段。

我一开始也把规格理解成"需求文档"或者"设计文档"。

但后来我发现，我理解错了。

规格是"契约"，是开发团队和需求方之间的契约。

一份好的规格，应该包含：

要素	说明	示例
功能描述	要做什么	用户可以通过语音输入任务
验收标准	怎么算完成	语音识别准确率 > 95%
技术约束	有什么限制	必须支持离线使用
优先级	重要程度	P0：核心功能

规格的好处是什么？

1. 减少返工：双方对"做完"的理解一致
2. 便于评估：可以估算工作量
3. 方便交接：新人来了，看规格就知道要做什么

2.3 五阶段流程的实践

OpenSpec 定义了五个阶段：

制定宪法 → 定义规格 → 技术规划 → 任务分解 → 执行实现

我来分享一下我是如何实践的：

阶段一：制定宪法

我创建了 .specify/memory/constitution.md 文件

内容包括：
- 项目定位：一句话说明项目是什么
- 核心价值：项目为用户解决什么问题
- 设计原则：技术选型、代码风格的指导方针
- 协作规范：如何提交代码、如何 Code Review

阶段二：定义规格

每当要开发一个新功能时，我会先写 SPEC.md

以 TraceOne 的"智能体推荐"功能为例：

## 功能规格：智能体推荐

### 目标
根据用户当前任务，智能推荐合适的 AI 智能体

### 功能描述
1. 用户在输入框输入任务描述
2. 系统分析任务类型
3. 推荐 1-3 个合适的智能体
4. 用户可以一键切换到推荐智能体

### 验收标准
- [ ] 推荐准确率 > 80%（用户采纳）
- [ ] 响应时间 < 2 秒
- [ ] 支持至少 10 种任务类型

### 技术约束
- 使用现有智能体数据结构
- 不引入新的外部依赖

阶段三：技术规划

在确定要做什么之后，我会思考"怎么做"：

技术选型：
- 使用 Embedding 模型计算任务相似度
- 使用向量数据库存储智能体特征
- 推荐算法：基于余弦相似度的 Top-K

架构设计：
- 新增 recommendation 模块
- 复用现有的 agent registry
- 保持 API 兼容

阶段四：任务分解

把一个大的功能，拆成可执行的小任务：

- [ ] 任务 1：设计智能体特征向量
- [ ] 任务 2：实现 Embedding 计算
- [ ] 任务 3：构建向量检索
- [ ] 任务 4：实现推荐 API
- [ ] 任务 5：前端推荐展示
- [ ] 任务 6：编写测试用例
- [ ] 任务 7：性能优化

阶段五：执行实现

按照任务列表，一个一个完成。

关键原则：
1. 每个任务完成后，立即验证
2. 不堆积问题，有问题及时解决
3. 写好注释和文档

---

三、OpenSpec 帮我解决了什么问题？

3.1 问题一：需求变更不再可怕

以前：

产品经理：这里要加一个功能
我：好的
（加了 3 天）
产品经理：不对，这个功能和那个功能冲突了
我：...那怎么办？
产品经理：重新设计吧
我：&%@#&...

现在：

产品经理：这里要加一个功能
我：好，我先写个规格
（1 小时后）
我：规格写好了，你看看有没有问题
产品经理：嗯...这里好像不太对
我：对，我重新调整一下
（确认规格后）
我：按这个规格做，2 天能完成
产品经理：好，开始吧

变化：从"边做边改"变成"先想再做"，沟通成本大幅降低。

3.2 问题二：代码质量明显提升

以前：

代码review：这个地方为什么要这么写？
开发者：我当时想着这样实现比较快...
代码review：那这个地方有考虑性能吗？
开发者：...没想那么多

现在：

代码review：这个实现和规格一致吗？
开发者：一致，规格里要求 A，我实现了 A
代码review：验收标准都达到了吗？
开发者：都达到了，我给你看测试结果

变化：代码review 有了明确的标准，不再是"我觉得不好"vs"我觉得好"。

3.3 问题三：项目不再失控

以前：

项目做到一半：
我：好像偏离了最初的目标
同事：没关系，加班做呗
我：但这个需求一开始没说要加啊
同事：产品经理后来说要加的
我：...那最初的目标是什么？
同事：好像和现在不太一样了...

现在：

项目做到一半：
我：等等，这个功能和宪法里的定位不符
同事：真的吗？我看看
我：宪法里说的是 A，这个功能是 B
同事：确实，我们是不是跑偏了？
我：把宪法拿出来对对，看看是不是要调整

变化：有了"宪法"作为锚点，随时可以纠偏。

---

四、我是如何在实际项目中应用 OpenSpec 的？

4.1 实践案例：TraceOne 项目

TraceOne 是我现在正在开发的一个 AI 工作空间项目。

项目背景：

• 目标：帮助个人创作者用 AI 提升效率
• 技术栈：Next.js + Python + LangGraph
• 团队：我一个人（偶尔有 AI 助手帮忙）

我是如何应用 OpenSpec 的？

第一步：建立项目宪法

我创建了 .specify/memory/constitution.md：

# TraceOne 宪法

## 项目定位
AI 时代的个人数字工作空间

## 核心价值主张
- 让 AI 成为每个人的"第二大脑"
- 降低 AI 使用门槛，提升使用效率

## 设计原则
1. **规格驱动**：任何功能必须先写规格
2. **渐进验证**：小步迭代，快速验证
3. **用户中心**：先想用户想要什么，再想技术怎么实现
4. **保持简单**：能用简单方案解决就不用复杂方案

## 技术约束
- 优先使用开源技术
- 支持私有化部署
- 保持代码轻量，不引入不必要的依赖

第二步：为每个功能写规格

以"智能体市场"功能为例，我写了这样一份规格：

# 智能体市场 - 功能规格

## 概述
提供一个集中浏览、搜索、试用 AI 智能体的平台

## 用户故事
作为用户，我可以：
1. 浏览推荐的智能体列表
2. 搜索特定功能的智能体
3. 查看智能体详情和使用说明
4. 一键安装/试用智能体

## 功能列表
| 功能 | 优先级 | 预估工时 |
|------|--------|----------|
| 智能体列表展示 | P0 | 2h |
| 智能体搜索 | P0 | 2h |
| 智能体详情页 | P0 | 3h |
| 安装/试用功能 | P1 | 4h |
| 推荐算法 | P2 | 6h |

## 验收标准
- [ ] 页面首屏加载 < 1s
- [ ] 搜索响应 < 500ms
- [ ] 支持 100+ 智能体展示
- [ ] 移动端适配

## 技术实现
- 前端：Next.js + Tailwind CSS
- 后端：API Route
- 数据：本地 JSON 文件

第三步：任务分解与执行

根据规格，我把任务分解成：

[ ] 任务 1：设计智能体数据结构
[ ] 任务 2：实现智能体列表组件
[ ] 任务 3：实现搜索功能
[ ] 任务 4：实现详情页
[ ] 任务 5：添加样式和动效
[ ] 任务 6：测试和优化

然后一个个完成。

4.2 实践案例：内容创作工作流

除了 TraceOne，我还用 OpenSpec 的思路来管理我的内容创作工作流。

场景：我要写一篇 5000 字的技术文章。

按照 OpenSpec 的思路：

宪法（内容创作的原则）：

目标：输出高质量、有价值的技术文章
原则：
  - 解决实际问题
  - 真实经历和思考
  - 结构清晰、易读
  - 提供可操作的建议

规格（具体文章的规划）：

主题：AI 视频剪辑智能体的踩坑复盘
目标读者：想用 AI 做视频的开发者
核心内容：
  1. 背景和动机
  2. 技术方案
  3. 踩坑经历（重点）
  4. 解决方案
  5. 经验总结
字数：5000 字左右
发布时间：周日

任务分解：

[ ] 收集素材和项目资料
[ ] 写大纲
[ ] 写正文（分段写）
[ ] 配图生成
[ ] 文章润色
[ ] 自检和修改
[ ] 发布

这种工作方式，让我的内容创作变得可控、可量化、可复制。

---

五、OpenSpec + Vibe Coding = 完美组合？

在我现在的实践中，我把 OpenSpec 和 Vibe Coding CN 结合起来使用。

5.1 什么是 Vibe Coding CN？

Vibe Coding CN 是我根据"氛围编程"理念发展出来的一套适合中国开发者的实践方法。

它的核心是：

原则	说明
规划先行	AI 是工具，人是主导
规格明确	给 AI 明确的规格，而不是模糊的描述
避免幻觉	提供具体示例，禁止 AI 猜测
渐进验证	小步迭代，每步验证

5.2 两者如何结合？

我的工作流：

1. 先用 OpenSpec 定义"做什么"和"做到什么程度"
   - 写宪法
   - 写规格
   - 任务分解

2. 再用 Vibe Coding 和 AI 协作"怎么做"
   - 给 AI 明确的指令
   - 提供代码示例
   - 及时验证结果

3. 最后用 OpenSpec 的标准"验收"
   - 对照规格检查
   - 验收测试
   - 文档归档

一个具体的例子：

我想让 AI 帮我写一个"用户登录"功能。

错误的问法：

帮我写一个用户登录功能

正确的问法（OpenSpec + Vibe Coding）：

帮我写一个用户登录功能，需要满足以下规格：

## 规格
1. 支持邮箱+密码登录
2. 支持"记住我"功能（7天免登录）
3. 登录失败 5 次后锁定 15 分钟
4. 密码使用 bcrypt 加密存储

## 技术约束
- 使用 Next.js + NextAuth.js
- 数据库用 Prisma + PostgreSQL
- 参考现有项目结构：/path/to/existing/project

## 验收标准
- [ ] 登录成功返回 JWT Token
- [ ] 错误密码返回 401
- [ ] 锁定后返回 423
- [ ] 单元测试覆盖率 > 80%

效果对比：

问法	AI 第一次生成的质量	需要返工的次数
错误的问法	30%	5-10 次
正确的问法	80%	1-2 次

---

六、OpenSpec 实践中的挑战与应对

6.1 挑战一：规格写多了会很烦

问题：每个功能都写规格，工作量好大啊...

我的应对：

1. 区分大小：

• • P0 功能：完整规格
  • P1 功能：简化规格（一段话）
  • P2 功能：口头说明就行

1. 模板化：

• • 创建标准的规格模板
  • 每次只需要填空

1. 渐进明细：

• • 刚开始只需要写"做什么"
  • 做到一定程度再补充"怎么做"

6.2 挑战二：规格和代码不同步

问题：规格写好了，但写着写着就和代码不一样了...

我的应对：

1. 每次发版检查：

• • 对照规格检查功能是否完整

1. 把规格融入代码：

• • 用代码注释标注对应的规格编号
  • 写测试用例时引用规格

1. 定期回顾：

• • 每个季度做一次"规格vs代码"的对比
  • 把过时的规格清理掉

6.3 挑战三：团队成员不配合

问题：我一个人用 OpenSpec，但团队其他人不理解...

我的应对：

1. 先做出成果：

• • 用实际效果说话
  • 让别人看到好处

1. 从简单开始：

• • 先从"写清楚要做什么"开始
  • 慢慢引入更多规范

1. 提供工具：

• • 写好模板和示例
  • 降低参与门槛

---

七、OpenSpec 带给我的改变

7.1 思维方式的转变

以前：

需求 → 代码 → 改改改 → 上线

现在：

需求 → 规格 → 任务分解 → 代码 → 验证 → 上线

7.2 工作效率的提升

指标	以前	现在	提升
需求返工率	40%	10%	75%
代码 Bug 率	15%	5%	67%
项目延期率	50%	20%	60%
团队沟通成本	高	中	50%

7.3 个人能力的成长

通过实践 OpenSpec，我发现自己：

1. 思考问题更系统：不再只想着"怎么实现"，而是先想"要实现什么"
2. 表达更清晰：写规格的过程锻炼了我的表达能力
3. 学习更高效：通过写规格，我把知识点梳理得更清楚

---

八、如何开始实践 OpenSpec？

8.1 最小起步

如果你想尝试 OpenSpec，建议从最小开始：

第一步：给项目写一句话定位

这个项目是______，用来______。

第二步：给每个功能写 3 句话规格

功能名称：______
做什么：______
验收标准：______

第三步：把任务拆成 5 个以内的小任务

[ ] 任务 1
[ ] 任务 2
[ ] 任务 3
...

8.2 推荐工具

工具	用途
GitHub Projects	任务管理
Notion/Obsidian	文档管理
Mermaid	画流程图
ChatGPT/Claude	辅助写规格

8.3 注意事项

1. 不要追求完美：规格是用来指导开发的，不是用来审美的
2. 保持更新：规格是活的，要随着项目变化
3. 灵活运用：OpenSpec 是方法论，不是教条

---

结语

回顾我的编程生涯，从"野生开发"到"规格驱动"，这是一段漫长的成长之路。

OpenSpec 带给我的，不是一套工具，而是一种思考问题的方式。

以前：拿到需求，直接想怎么实现
现在：拿到需求，先想做到什么程度，再想怎么实现

这是一个简单的转变，但带来了巨大的改变。

如果你也是一个开发者，如果你也曾经为"需求变更"、"代码质量"、"项目失控"而烦恼不妨试试 OpenSpec。

也许，它也能改变你的开发方式。

---

相关资源：

• Spec Kit: https://github.com/github/spec-kit
• TraceOne 项目规范：.trae/rules/project-file-management.md

---

本文是 OpenSpec 规范实践经验的总结，记录于 2026 年 3 月。