OpenSpec 这个名字我第一次看见的时候，第一反应是“又一个把需求文档做成网页的工具”。因为团队里做过太多次“文档写得很漂亮，代码跑起来完全不是一回事”的脑力劳动，我对一切号称能管好“规格”的东西都保持警惕。但真正把 OpenSpec 用起来之后，我发现它解决的并不是“写文档”这件事，而是让规格变成一种“可评审、可追踪、可执行”的项目资产。这篇内容我会从设计思路、文件组织、实操流程到踩坑经验一次讲清楚，适合正在为需求反复变更、文档滞后、验收扯皮而头疼的团队，也适合想给个人项目建立轻量规格体系的朋友。
如果你还没听过 OpenSpec，可以把它理解成一套“把需求写成结构化文本，并且用 Git 管理起来”的规格规范。它不依赖重型平台，不需要额外部署服务，核心就是普通文件夹加 Markdown 文本，再加上简单的校验约定。听起来简单，但价值和门槛恰恰都藏在“简单”这两个字背后。
1. OpenSpec 到底解决什么问题
1.1 从一次变更事故说起
我之前参与过一个中台项目，需求从口头沟通到最终上线，中间经过微信语音、邮件、产品原型、线下评审会、技术方案文档五个环节。结果有一次业务方在评审会上说“这个字段要改成可空”，产品经理当场点头，技术同学记在笔记本上，但一周后联调时才发现，原型没改、接口文档没改、测试用例更没改。
问题并不在某个人的执行力，而是需求变更没有一个“单一的、可追溯的落点”。OpenSpec 的切入点就是补上这个落点：它把规格定义成仓库里的一等公民，和代码一样有目录、有版本、有 diff、有评审记录。谁在什么时间改了什么、为什么改，清晰可见。
1.2 它和 Wiki、需求文档的本质区别
传统需求文档的问题不在于写得不细，而在于“写”和“做”是两条线。Wiki 页面、Word 文档里的内容需要有人手动同步到代码、测试用例和验收标准里，一旦人手不够或流程紧张，同步就断掉了。
OpenSpec 的做法是把规格拆成小粒度的文本文件，每个文件之间通过命名和目录结构建立约定关系。它不要求你一次性写出“完美文档”，而是鼓励在每次需求变化时只改动对应的小文件。这个模式非常接近代码评审：改动集中、diff 清晰、责任明确。
我自己的体会是，OpenSpec 的真正价值不是“文档更好看”，而是把“改需求”这件事从口头承诺变成可回放的资产。它让每个人在任何时间点都能回答三个问题：当前要实现什么？这个修改是谁提出的？修改前后的差异在哪？
2. 规格的目录结构与核心概念
2.1 一份规格的最小骨架
用 OpenSpec 管理项目时，目录结构一般长这样：
spec/ README.md changes/ 2025-01-15-add-order-status/ proposal.md requirements.md tasks.md services/ order-service/ current.md requirements.md entities/ order.md user.md这套结构看起来不复杂，但每个部分承担的责任都很明确。README.md说明整个规格仓库的用途和阅读方式；changes目录放每批需求变更，一个变更一个文件夹；services目录描述系统中的服务职责；entities目录定义领域实体。
我建议从changes目录开始用，因为它是整个 OpenSpec 的入口。每次有新需求，就新建一个以“日期-简短描述”命名的文件夹，里面放三份文件：提案、需求、任务。这三份文件分别回答“为什么要做”“做成什么样”“怎么分解落地”。
2.2 服务、实体、需求：三大核心概念
这三个概念对应了三种不同的抽象层次。
- 服务（services）：描述系统中的业务能力边界，例如“订单服务”“支付服务”。OpenSpec 不限定服务粒度，可以是一个微服务，也可以是一个模块。
- 实体（entities）：描述服务处理的核心数据对象，例如“订单”“用户”“商品”。实体字段、状态流转、约束关系都写在这里。
- 需求（requirements）：每条需求都是可验证的行为描述，可以对应一条验收标准。
这种拆分的价值在于，当你需要修改订单实体的状态流转时，不再需要翻几十页文档，而是直接定位到entities/order.md。需要评估影响面时，也只需要检查引用这个实体的服务和需求文件。
2.3 为什么用纯文本而不用数据库
这里要解释一个关键选择。市面上很多需求管理工具都提供表单、看板、数据关联，功能强大但维护成本高——权限体系、部署、数据迁移、导出格式都是负担。OpenSpec 坚持用普通文本文件，理由和 Git 管理代码完全一致：文本容易 diff、容易 review、容易合并，也容易做自动化检查。
纯文本还有一个隐性好处：它消灭了“信息孤岛”。无论你用 Obsidian、VS Code、Typora 还是命令行里的 Vim，都能打开和编辑规格文件。不需要培训团队学习新平台，也不存在“账号没开通就没法看文档”的尴尬。
我见过不少团队花了很大力气搭建需求管理工具，最后数据死在老系统里导不出来。而 OpenSpec 这种“规格即文件”的方式，迁移成本几乎为零。就算以后不用 OpenSpec 的规范了，这些 Markdown 文件本身仍然是可读的项目资产。
3. OpenSpec 实操流程与落地案例
3.1 新建一个规格变更的标准流程
第一次上手时，最容易犯的错误是试图把整套体系一步到位。我建议按下面的节奏走：
- 在
changes/下创建变更目录，命名格式建议用2025-01-15-add-order-status，日期加简短描述。 - 在
proposal.md中写清楚背景、目标、影响范围，这部分是给评审者看的。 - 在
requirements.md中逐条列出可验证的需求，每条需求都有编号和验收标准。 - 在
tasks.md中拆解工作量，让开发同学能够估算和认领。 - 提交 MR 或者 PR，让所有人 review，合并之后需求变更正式生效。
这里有一个很重要的细节：changes里的文件是“提案”，等开发完成并验收通过后，应该把对应内容合并到services和entities中，作为当前系统状态的权威描述。如果不做这一步，changes 目录会越来越像“历史遗留仓库”，失去参考价值。
3.2 用一份真实需求演示
假设我们现在要给订单增加一个“取消”状态，需求描述大概是这样的：
## Change: Add order cancel status ### Background - 用户在支付前可以取消订单 - 取消后库存需要回滚 - 取消操作需记录操作人 ### Requirements - REQ-1: 当订单状态为 pending 时，用户可以发起取消请求 - 验收标准：调用取消接口后，订单状态变为 cancelled - REQ-2: 取消订单时必须记录操作人信息 - 验收标准：取消记录中操作人字段不可为空 - REQ-3: 取消订单成功后释放已锁定库存 - 验收标准：取消后库存数量恢复至下单前水平 ### Tasks - [ ] 后端增加取消接口 - [ ] 修改订单状态流转逻辑 - [ ] 库存服务增加回滚方法 - [ ] 前端增加取消按钮 - [ ] 补充自动化测试用例每条需求都对应一个明确的验收标准。这里的关键不是文档格式，而是“可验证性”。如果一条需求没法写清楚验收标准，那说明它还没有被想清楚，强行进入开发大概率会返工。
3.3 从提案到正式规格的合并策略
我强烈建议在合并的时候保留“提案变更”的追踪信息。具体做法是：在entities/order.md中更新订单状态列表，并且加上一行注释说明“cancelled 状态由 change-2025-01-15 引入”。这样做的价值在三个月后体现得尤其明显——当有人问“cancelled 状态是为什么加的”，你不用考古 Git 历史，一眼就能看到来源。
合并的频率也不要太低。理想节奏是“一次变更，一个 MR，合并即同步”。如果一个月才合并一次，中间产生的新变更会和旧变更纠缠在一起，review 成本暴涨。这个节奏和代码提交很类似，越频繁越安全。
3.4 团队协作中的角色分工
OpenSpec 不强制指定谁写什么，但根据我的实践，以下分工比较稳定：
- 产品经理：负责
proposal.md和requirements.md里“为什么做”和“做成什么样” - 技术负责人：负责补充“影响范围”与“技术约束”
- 开发人员：认领
tasks.md中的任务，并在开发过程中发现需求矛盾时回溯提案 - 测试人员：把
requirements.md中的验收标准转成测试用例，并标注覆盖率
这样分工的价值在于，每个角色都在同一个文件体系里工作，信息不会散落在个人聊天记录和私人笔记里。
4. OpenSpec 实施中的常见问题与排查技巧
4.1 团队不写规格、文档总是滞后怎么办
这可能是 OpenSpec 落地时最大的障碍。我见过一个团队，推行了两周后changes目录里空空如也，原因是大家认为“写规格是额外负担”。
应对方法不是靠考核，而是靠降低门槛。我在项目里只要求先写requirements.md，每条需求一句话加一个验收标准，proposal 可以先用三个关键词代替完整描述。先让流程转起来，再逐步补全。
另外一个非常有效的手段是把 OpenSpec 的变更检查接入 CI。哪怕只是做一个“新建目录必须包含 requirements.md”的脚本，规则就变成刚性约束，不再依赖个人自觉。从我实测来看，有自动化检查之后，规格文件的完整率能明显提升。
4.2 diff、评审、版本管理的实操细节
因为 OpenSpec 完全是文本格式，Git 的 diff 天然就能用来做规格评审。我在 review 时主要关注三类变化：
- 需求编号是否连续且不变：一旦对外发布过的需求编号，就不要复用或修改，新增需求用新编号。
- 验收标准是否可测：凡是出现“用户体验要好”“性能要好”这类描述，都要打回去重写。
- 状态变更是否同步到实体定义：如果需求里出现了新状态或新字段，实体文件里必须及时更新。
版本管理上，建议把 spec 目录和代码放在同一个仓库里。这样在做代码评审时，需求变更和技术实现能整体联动，评审者可以直观地看到“这个代码改动对应的是哪条规格”。
4.3 常见问题速查表
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
| changes 目录越来越乱 | 没有规定命名规范 | 统一使用日期加描述前缀 |
| 规格文件没人看 | 没有把评审纳入流程 | 在 MR 中加入“规格变更说明” |
| 需求验收标准写不清楚 | 对业务逻辑还没有理解透 | 先画数据流图再写需求 |
| 实体定义和实际代码不一致 | 合并流程缺失 | 开发完成后必须同步更新 entities |
| 一个变更包含太多需求 | 拆分粒度太大 | 按“一次上线一个能力”拆分 |
这张表不是标准答案，但里面每个问题我都真实遇到过。最典型的是“一个变更包含太多需求”，一开始总觉得分目录麻烦，后来发现一个大变更动辄几百行 diff，评审根本看不出门道，最后还是老老实实拆小。
4.4 顺手的小技巧
最后分享一个我一直在用的习惯：在README.md里维护一份“当前活跃变更”清单，列出还在进行中的changes目录、对应负责人和预计完成时间。这个文件维护成本不高，但能极大提升项目透明度，开会时不用再打开聊天记录找“上一版需求是哪个文件”。
还有一个经验是给每条需求加上稳定 ID。这个 ID 建议用REQ-001这种纯序号格式，不要带日期和功能名缩写，因为功能名经常变，日期在后续合并时会产生冗余信息。稳定 ID 能让测试用例、代码注释、Bug 描述都引用同一个编号，追问题的时候非常省力。
5. 从规格到代码：后续还可以怎么扩展
OpenSpec 本身是一套很轻的规范，但它留了足够的扩展面。我看到有的团队会在规范文件之上写脚本，自动生成测试用例清单，把requirements.md里的验收标准项转成 JUnit 或者 pytest 的注释骨架；也有人用 GitHub Actions 对规范文件做格式校验，确保每个变更目录都包含必要文档。
对我个人来说，最有价值的是它把“需求变化”这个原本只能靠记忆和聊天记录维持的信息，变成了可以像代码一样反复查验的对象。真正用了半年之后，我和产品经理之间的话风都变了。以前是“这个需求应该没问题吧”，现在变成“你把 REQ-102 的验收标准再补一句，我这边就能联调”。这在我看来，就是规格管理该有的样子。
