★ FEATURED ARTICLE 1. 为什么文档即代码喊了这么多年落地却一直这么难先说个我自己的真实经历。前两年带一个中大型项目团队十几个人需求文档分散在在线文档、本地 Word、聊天记录和几个老同事的脑子里。需求评审会上大家对着一个最新版文档聊得热火朝天结果开发到一半发现文档是一个月前的旧版本产品经理自己都忘了改过哪几处。那种想砸电脑又无处发泄的感觉做过大型项目的工程师应该都能共鸣。后来我们尝试过各种方案在线协作文档工具、专门的 Wiki 系统、甚至有人用数据库表单去管理需求。但问题始终没有真正解决——文档的变更过程不可追溯、不可 Review、不可回滚。就算工具再先进本质还是一个人写了大家看版本永远靠自觉。这就是 OpenSpec 切入的点。它不是又一个在线文档工具也不是什么重量级的 ALM 平台而是把软件规格说明彻底变成一种可以被 Git 管理、可以被 Code Review、可以进 CI 检查的工程产物。规格文档在你本地就是一串 Markdown 文件但整体运作起来它有了一套完整的生命周期创建、评审、合并、追溯、变更记录跟代码的协作体验完全对齐。这篇文章我会完整讲讲 OpenSpec 的核心设计逻辑然后给出一套从零到一的落地流程最后聊聊我在真实项目里踩过的坑。如果你也在为需求文档管理混乱前后端接口约定靠嘴传新成员看文档不知道看哪份这类问题头疼这篇应该能给你一个有点不一样的解法。2. OpenSpec 到底做了什么给 Markdown 文档装上开发流程OpenSpec 的价值很难用一句它是文档工具来概括。准确说它是一个规格文档的工程化管理框架把文档这件事从内容创作变成了规范变更。2.1 核心设计Markdown Git CLI仅此而已如果你把这个思路理解透就会发现 OpenSpec 其实没发明什么新东西它做的是把三样你已经很熟的工具组合起来专门服务规格文档这个场景组件作用为什么选它Markdown文档编写格式门槛极低、易读易写、Git 文本对比友好任何工程师都能直接上手Git版本控制、协作、评审分布式、有完整的权限模型、天然支持分支合并是当前工程协作的事实标准CLI脚手架、校验、流程工具把流程变成可强制执行的命令不必依赖人的自觉性核心思想特别朴实既然代码可以用分支做隔离、用 PR/MR 做评审、用 CI 做检查那规格文档为什么不能走同一套流程OpenSpec 要做的就是把规格文档的书写规范和组织方式固定下来再用一套 CLI 把这些开发心智落到操作层面。2.2 仓库结构为什么规格文件要这样摆我第一次接触 OpenSpec 时不太理解它的目录约束嫌管得太宽。后来用了两周才明白这种约束正是它价值所在。它把规格仓库组织成了一种可扫描、可校验、可编译的状态而不是一堆 Markdown 的乱葬岗。specs/ ├── openspec/ │ ├── project.md │ └── components/ ├── capabilities/ │ ├── user-authentication/ │ │ ├── specification.md │ │ └── requirements.md │ └── payment-service/ ├── changes/ │ ├── 2025-01-15-add-sso-login/ │ │ ├── proposal.md │ │ └── tasks.md │ └── 2025-01-20-refactor-payment/大致分三块openspec/放项目级元信息和组件说明相当于规格的目录首页。capabilities/描述系统当前具备的能力每个能力一个目录内部包含specification.md能力规格描述和requirements.md需求明细列表。changes/存放变更提案。每个待实现的需求或改动是一个目录内部有proposal.md变更说明和配套的任务拆解。这个划分的逻辑在于capabilities/反映的是系统的当前状态changes/反映的是通向新状态的待办过程。前者是稳态后者是流量两者分离才不会互相污染。2.3 一份规格文件到底长什么样说了半天理论直接看一个我常用的能力规格结构。以用户认证这个能力为例specification.md的骨架大概是# Capability: User Authentication ## 概述 系统通过邮箱 密码方式认证用户签发 JWT Token。 ## 核心场景 - SC-1: 用户使用正确凭据登录返回 access token 和 refresh token。 - SC-2: 用户使用错误密码登录返回统一的认证错误信息。 ## 对外依赖 - 依赖账号服务内部服务HTTP。 - 使用 Redis 存储 refresh token 状态。 ## 非功能要求 - token 有效期 30 分钟refresh token 有效期 7 天。 - 登录接口 p99 延迟 200ms。而requirements.md则是把场景拆成可追踪的需求条目## REQ-1: 密码登录 - 状态: 已实现 - 优先级: P0 - 场景: SC-1, SC-2 - 验收标准: 1. 输入正确邮箱和密码返回 200 及 token。 2. 输入错误密码三次后触发图形验证码。 ## REQ-2: Token 刷新 - 状态: 评审中 - 优先级: P1这里有个关键点需求条目必须可以对应到测试场景和验收标准而不是一句支持登录功能就完了。这种强制性的结构化逼着你把模糊想法说清楚这是 OpenSpec 帮团队提升文档质量的核心手段。3. 从零到一一套可以直接照抄的 OpenSpec 落地流程理论部分讲完了下面进入实操。我按一个内部项目的实际推进节奏分四步讲清楚每个人应该做什么、命令怎么敲、产物长什么样。3.1 初始化规格仓库为团队搭好文档主干道第一步是把规格仓库建起来。你完全可以新建一个独立仓库也可以把它放在主代码仓库的根目录下我推荐后者理由后面讲。# 如果在主仓库里先创建 specs 目录 mkdir specs cd specs # 初始化 OpenSpec伪代码以实际帮助为准 openspec initinit之后CLI 会生成一个最小的骨架仓库包括openspec/目录组织和一份 README说明这个仓库的用途和命名规范。做完这步把它提交推送到远端拉团队的负责人或者核心成员一起看一遍目录结构确认什么文件放哪里的约定。这个环节最容易犯的错误是先让每个人都装好环境再开工这完全本末倒置。先定结构再补工具。文档仓库本身不需要任何开发者本地环境支持编辑器 Git 就够用。3.2 把已有需求回填成能力规格先建立基线第一次引入 OpenSpec最忌讳的是以后新需求用这套老需求先不管。这样做的结果是仓库永远只有两三个新目录老需求还在线上文档里文档割裂的问题依旧存在。正确姿势是花一到两周时间把当前系统正在做的、稳定的核心功能按能力维度回填成规格文件。举个例子。假设你手头有个电商后台老需求散落各处。你可以这样梳理openspec create capability order-management openspec create capability inventory-service openspec create capability refund-flow每个命令生成一个能力目录然后你和产品、测试负责人一起把老需求拆成specification.md里的场景和requirements.md里的需求条目。回填过程不用追求百分之百覆盖把当前线上已实现的主要行为描述出来就够了重点是形成基线。回填完成后我把这个基线仓库发给团队要求所有人以后涉及现有功能变更先到capabilities/里找对应能力目录而不是新建一个 Word 文档。这一步做完文档割裂的问题基本解决了 80%。3.3 新需求的正确打开方式从一个变更提案开始基线建好后新的需求流程就顺畅多了。一次典型的新需求流转是这样的产品经理提出需求比如要新增微信扫码登录。用 CLI 创建变更提案openspec create change add-wechat-login此时会生成一个changes/2025-01-15-add-wechat-login/目录里面有proposal.md和tasks.md。在proposal.md里写清楚变更内容改了哪些能力、新增了哪些需求条目、废弃了哪些旧行为。如果涉及对现有能力规格的修改要把对应的改动描述写清楚而不是直接改capabilities/里的文件。这一步是理解 OpenSpec 的核心关键我多说两句。规格仓库的capabilities/是已经合入主干的代码changes/是等待合并的分支。需求评审通过前你只应该改changes/里的提案不应该动capabilities/的内容。团队评审这个变更提案Review 的对象是提案是否清晰地描述了系统行为的改变而不是文档格式漂不漂亮。通过评审后合入变更用 CLI 的一条命令把提案里的改动应用到capabilities/对应文件上让能力规格更新到新状态。同时 Git 提交信息完整记录这一次变更。这个流程走顺之后你会发现一个变化文档的变更节奏和代码开发节奏开始同频了。产品经理提交提案开发在提案的任务清单上领活测试根据提案里的验收标准写用例整个链路特别舒服。3.4 把 OpenSpec 接进 CI让文档检查成为合并门禁落地 OpenSpec 只靠团队自觉是不够的必须有强制手段。CLI 提供了校验命令如openspec validate或openspec check我强烈建议把它接入 CI作为合并请求的一个必检步骤。# GitHub Actions 示例 name: spec-check on: pull_request: paths: - specs/** jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Validate OpenSpec run: | cd specs openspec validate加了这个检查后即使团队里有人对目录结构、格式规范不熟悉CI 也会直接告诉他哪里有问题。我见过有不少团队把规则写在 wiki 里没人看但没有人在 CI 报错时敢随便跳过。这就是工程化带来的强制性。另外强调一个推荐做法规格仓库放在主代码仓库里而不是独立仓库。原因很简单当规格文件与代码在同一仓库时一个 PR 里能同时看到代码改动和对应的规格改动评审人不需要在两个仓库之间跳来跳去。那种代码在仓库 A、文档在仓库 B、两边版本还经常对不上的痛苦谁经历谁知道。4. 团队协作里最容易翻车的几个细节OpenSpec 这套东西逻辑上很顺但真用到团队协作里有几个坑是我实际踩过之后才反应过来的。写出来帮大家提前躲开。4.1 规格变更和代码变更的时序问题最常见的冲突场景是这样的开发拿到需求后在changes/里建了提案但业务方催得紧开发直接开始写代码了。等代码写完capabilities/里的规格还没更新提案也没合并。这会导致一个很尴尬的局面——代码已经上线规格还停留在过去时。虽然规范上要求先更新规格再写代码但现实里紧急需求总是有的。我的折中方案是明确两条线。紧急需求可以并行开发但合并代码分支时必须同时合并规格变更否则代码 PR 的 CI 直接不通过。也就是说规格的滞后可以是短时间的但不能被遗忘。把规格是否更新和代码是否可合并绑定在一起是解决这个问题的关键而不是单纯靠流程约束。4.2 Review 的粒度小步提交比憋大招好一万倍OpenSpec 的提案机制设计上鼓励小步快跑。一个提案最好只解决一个完整的需求点而不是把一个月的需求都堆在一个提案里慢慢写。我们来对比一下两种做法提案策略评审效果实际体验大提案一次提交 8 个需求点评审人看完前两个已经忘掉后六个只能草草通过提案写了三周Review 十分钟等于没评审小提案一个需求点一个提案评审人 10 分钟能完整理解上下文节奏流畅甚至可以在提案里直接讨论实现细节这一点和代码评审的道理一模一样。Review 效果取决于评审单元的大小提案拆得越小评审质量越高。我会在团队约定里写死一句话一个提案的描述必须能让另一个不在场的同事只看这份文档就能理解改动的全部内容。4.3 拒绝文档八股验收标准要有但要避免空洞有些团队把 OpenSpec 引入之后会走进一个误区要求每个需求条目都写满完整的验收标准每条标准都要对应一个测试用例结果文档写成了论文光维护验收标准就占了一半工作量。我的建议是验收标准按风险级别来决定详略。P0 需求涉及资金、安全、核心链路必须写可量化的验收标准最好能对应到自动化测试。P1 需求主流程但非关键路径写清楚正常路径和常见异常路径即可。P2 需求边缘优化类一段话说明行为即可不必刻意拆多条验收项。举个例子P0 的微信登录需求验收标准写使用有效微信授权码调用登录接口返回 200 及新用户 tokentoken 有效期与密码登录一致就足够没必要再写点击登录按钮后按钮文字变化这种 UI 细节。好的规格不是字数越多越好而是信息密度越高越好。4.4 谁来维护规格仓库这个问题得提前想明白OpenSpec 落地最容易被忽略的问题其实是所有权。如果团队里每个人都觉得规格仓库是公共的随手改一下没问题那用不了一个月仓库状态就会因为没人负责而腐烂。我建议每个能力目录指定一个明确的 Owner这个能力的规格变更必须由 Owner 评审后才能合入。这个 Owner 通常是该模块的技术负责人但注意——Owner 的角色是维护规格的一致性而不是写所有规格内容。他负责把关这份规格是否准确描述了当前系统行为具体内容还是由对应需求的开发或产品来写。有了明确的 OwnerCI 检查和提案评审才真正闭环。否则流程再完善最终也会因为查漏补缺的人是谁这个问题而卡住。5. OpenSpec 还能怎么玩一些超出文档管理的扩展用法用熟了之后OpenSpec 的价值不只是管文档它还能和一些工程环节衔接把规格文档变成更多自动化流程的输入源。5.1 把规格需求映射到开发任务tasks.md 的妙用每个变更提案目录下的tasks.md我建议按开发任务粒度写。比如微信扫码登录提案的任务清单## 任务清单 - [ ] 后端: 实现微信 OAuth 授权码换取用户信息接口 - [ ] 后端: 用户表新增 wechat_openid 字段并加唯一索引 - [ ] 前端: 登录页新增微信扫码入口按钮 - [ ] 联调: 与微信回调域名配置联调登录链路 - [ ] 测试: 补充微信登录自动化用例这些任务可直接对应到代码仓库的 issue 或看板。proposal.md描述为什么变、变成什么样tasks.md描述怎么落地。两者分离的好处是评审提案时可以专注于做什么而不被怎么做的细节干扰。5.2 从规格生成测试用例打通验证链路既然能力规格里有场景、需求条目有验收标准那从规格自动生成测试用例的存根就是水到渠成的事。OpenSpec 生态里有不少辅助工具支持这类扩展你可以按自己的实际需要集成解析requirements.md中每条需求的验收标准生成测试用例标题列表。将核心场景导出为 Markdown 表格供 QA 团队手工用例评审。在 CI 中比对需求条目状态和自动化测试状态找出规格里说已实现但测试未覆盖的需求。这条链路跑通之后规格文档就不再是写完就吃灰的静态文件它变成了研发流程里一个可被自动读取、可被追踪状态的动态资产。5.3 与架构决策记录ADR结合使用另一个让我觉得很好用的扩展场景是把 OpenSpec 的变更提案和架构决策记录结合起来。技术团队通常会用 ADR 记录重要架构选择的背景与取舍但 ADR 和需求规格经常脱节——架构决策了但对应的规格没变。我的做法很简单在proposal.md里加一个可选的架构影响章节如果这个需求涉及架构层面的选择比如引入新中间件、改变存储方案、调整接口协议就写清楚选择的理由和备选方案。这样一份变更提案同时具备了 ADR 的决策记录属性和需求规格属性评审的时候技术选型和需求准确性可以一起被审视。当然不要强行把这份文档做成四不像。对于大型架构决策我仍然会单独写一份完整的 ADR只是在提案里指明详见 ADR-xxx。关键是建立引用关系而不是试图把所有信息塞进一个文件里。6. 一些真实落地后的总结和补充最后聊聊我的真实体会。OpenSpec 不是那种装完就能立刻见效的工具它的价值曲线是前期平缓、中后期陡峭的。最开始的回填基线阶段最痛苦因为要把散落在各处的需求理解清楚并用结构化文档重新表达但是当能力规格的基线真正成型后后续每个新需求的流转效率提升是非常明显的。对于团队规模我的判断是4 人以下的小团队这套方案可能略显繁琐——几个人平时口头沟通就足够硬塞流程反而增加负担。但如果你的团队在 10 人以上、有多个职能角色协作、或者需求迭代节奏快那 OpenSpec 带来的文档即代码体验会明显超过传统文档工具。我实际踩过几个坑这里再补充几句不要一开始就做全量迁移。先把一个新的小需求走通整条流程让团队感受到原来文档评审可以这么顺再逐步回填老需求。一上来就搞大迁移大概率会收获一堆半成品和怨气。CLI 的校验命令要多用。本地提交前跑一遍validate比推到远端被 CI 打回要体面得多。这条没什么技术含量但能显著减少无谓的往返。规格文档不是写给老板看的汇报材料。它的读者是下一个接手的工程师、下个月来检查的测试、以及明年你自己。写的时候永远优先考虑信息是否准确和能否被准确执行而不是读起来是否顺滑。把我最后想说的浓缩成一句OpenSpec 本质上不是工具而是一套让团队在动手前先想清楚、在动手时能追踪、在动手后可追溯的协作纪律。工具只是把那套纪律固化成了流程真正让文档管理发生质变的是整个团队对这个纪律的认同和执行。如果你正在被需求文档混乱、接口约定靠嘴传的问题折磨拿一个小项目试试 OpenSpec 的提案流程跑通一个完整的需求闭环你会回来感谢自己这个决定的。
阅读完成 · 觉得有帮助？
