1. 为什么我彻底放弃了“直觉编程”
做了十几年的开发，我发现一个挺扎心的事实：大部分项目烂掉，不是程序员技术不行，而是大家从一开始就不知道自己在做什么。
我见过太多这类场面——需求文档写得很含糊，产品口头讲两句就开始动手，代码按开发者的“个人理解”推着走。前端觉得按钮该这么写，后端觉得接口该那么返回，测试拿着自己脑补出来的用例去验。结果投入使用后，产品说“这不是我要的”，业务说“逻辑不对”，运维说“这个我们没法部署”。然后开始改、返工、扯皮。
这种开发模式，我管它叫“直觉编程”。每个人都在用直觉猜需求，用直觉定规则，用直觉写实现。问题在于：十个人的直觉，十种结果。代码越写越厚，认知分歧越滚越大，最后只能靠加班来填坑。
直到我完整实践了一次OpenSpec 规范驱动开发（SDD），才意识到问题不在人，而是缺了一道“先统一认知，再动手写码”的工序。
OpenSpec 本质上是一个把软件需求转成机器可读规范、再由规范驱动编码实现的工具链。它解决的核心问题有三个：需求描述有歧义、实现结果无法验证、代码与文档脱节。换成大白话说，就是让团队在同一个认知基准上开发，把“我以为”变成“规范里写了”，把“我猜”变成“可校验”。
这篇文章既不是官方文档的翻译，也不是通稿式的工具介绍。我会直接讲清楚这套工作流怎么落地，从规范结构、PBL（基于包的开发）流程到实操参数和常见坑，全部基于我实际跑过的项目经验。适合正在被需求漂移和返工折磨的团队，也适合想给个人项目建立分工纪律的独立开发者。
追求敏捷和速度没有错，但如果这个“速度”是靠反复返工堆出来的，那不如慢一点，先让所有人朝同一个方向走。
2. 认识 OpenSpec：它不是文档工具，而是一条工作流
2.1 OpenSpec 到底做了什么
很多人第一次接触 OpenSpec，容易把它当成一种“更漂亮的文档格式”。这个理解会限制你的上手深度。
文档的特点是“记录”，它描述世界是什么样。规格（spec）的特点是“约束”，它定义系统应该是什么样。OpenSpec 的野心是后者——让规格成为开发流程的核心驱动力，编码只是规格的一种物理实现。
这套工具的工作方式可以拆成四层：
- 规格描述层：用结构化的 markdown 文件描述需求，按能力域（capability）组织。
- 变更管理层：每次需求变更都对应一个变更提案（change proposal），醒目标注改了什么、为什么改。
- 任务生成层：基于规格内容生成任务清单（task list），把“需求”转成“可执行动作”。
- 验证反馈层：通过内置的验证器（validator）检查规格与实现的偏差，输出修正建议。
我打一个比方。传统开发像是口头指挥装修师傅——“这里给我弄个柜子，那里弄个台子”，结果师傅做了个深柜，你想要的是挂衣区。OpenSpec 的方式是先在图纸上画出柜子的长宽高、层板数量、拉手位置，然后师傅严格按照图纸施工，每装一层板就对照图纸检验一次。
2.2 不是替代，而是收拢
这里要强调一个边界：OpenSpec 不替代你现有的框架、编程语言、数据库选型，也不替代你的 CI/CD 流水线。它做的是把“需求 → 设计 → 编码 → 验证”中最早、最模糊的那一环管住。
很多团队引入所谓的“文档驱动开发”，结果文档写完了，代码还是照着老思路写，文档就成了一件漂亮的摆设。OpenSpec 不太一样的地方在于它用了PBL（Package-Based Lifecycle）这种基于包的生命周期管理方式，让规格不是静态的纸面文件，而是跟着开发节奏持续生成的活资产。
PBL 把项目拆分成多个“包”（package），每个包对应一个可独立交付的能力切片。包不是按代码目录分的，而是按业务能力边界分的。举个例子，一个订单系统可以拆成“购物车包”“订单创建包”“库存锁定包”“支付回调包”。每个包都有完备的规格说明，独立演进、独立验证。
这样做最大的好处是：认知单元和交付单元对齐了。业务上解得开的问题，代码里就不会纠缠成一团。
3. 搭建 OpenSpec 规范驱动工作流
3.1 初始化一个 OpenSpec 项目
OpenSpec 基于 Node.js 生态，前置条件是本机已有可用的 Node.js 环境。我建议使用 Node 18 或更高版本，避免一些依赖兼容的小麻烦。安装工具链：
npm install -g @openspec/cli装好之后，进入你的项目目录，执行初始化命令：
openspec init这个命令会自动帮你创建几个目录和文件。正常情况下你会看到类似这样一棵目录树（版本不同的工具可能会有细微差异）：
openspec/ project.md # 项目级说明，描述整体目标和约束 capabilities/ # 能力域规格存放目录 changes/ # 变更提案存放目录 tasks/ # 任务清单输出目录 tmp/ # 临时运行目录初始化完成之后，可以跑一下自检命令，确保环境没问题：
openspec check这个命令会验证现有规格文件的结构是否合法。如果输出一切正常，说明工具链就绪，可以进入下一步。
3.2 规划能力域——别上来就写文件
这是新手最容易急的地方。工具装好了，目录建好了，恨不得马上写一堆规格出来。但在动手之前，有两件事必须先想清楚。
第一件事：你的项目有哪些能力边界。
能力域（capability）不是功能列表。功能是“用户能点这里、能看那里”，能力是“系统能承载什么”。一个最简单的区分方法：你描述的时候用词是“用户”还是“系统”。凡是说“用户要能……”的，大概率是功能；凡是说“系统应该保证……”的，才是能力。
我用一个内容发布系统举例子。
- 功能视角：用户要能上传封面图、用户要能编辑文章、用户要能发布内容。
- 能力视角：系统要管理媒体资源、系统要维护内容版本、系统要控制发布状态流转。
按功能拆分，很容易拆出一百条需求，互相之间还有重叠。按能力拆分，大概就是五个到八个相对稳定的域，这些域就是你的 capability 目录。
第二件事：每个能力域当前处在什么阶段。
OpenSpec 的规范不是一次写完的。一个能力域会经历三种状态：
- proposed：能力边界有雏形，细节还没定，先记录下来让团队对齐。
- active：正在开发实现，规格细节已明确到可指导编码。
- archived：能力已经稳定，代码实现跑通一段时间，规格进入归档状态。
在规划阶段，不要追求所有能力域一上来就到 active。先让团队对边界达成共识，再逐步深化。
3.3 用模板脚手架生成变更提案
能力域规划好之后，真正的日常开发循环就开始了。每一次需求变更，在 OpenSpec 里都是一个 change proposal。不管这个变更是修 bug、加功能还是重构，都走同一条流程。
生成一个变更提案的标准动作：
openspec proposal create <change-name>这个命令会为你生成一个标准模板文件，依次包含以下区块：变更动机、变更内容、需求描述、场景示例、任务拆解。模板的意义不只是让你按格式填，更重要的是它强制你想清楚“为什么做这个变更”和“成功标准是什么”。
我见过很多人跳过动机区块直接写细节，这是极大的浪费。动机写清楚，价值在哪里一目了然；动机写不清楚，大概率这个变更可做可不做。
提案写完之后，执行：
openspec proposal apply这个命令会把提案内容落定到能力域规格中，更新相关的规范文件版本，并生成任务清单。到这里，一个变更提案走完了一半流程，从“讨论”进入了“约束”。
4. 核心实操：需求转规格，到底转什么
4.1 需求描述中最大的坑——“看起来对，实际没定义”
很多人写需求时会写类似这样的话：“用户登录后应跳转到首页并展示个性化内容。”
这句话谁看都觉得没毛病，但没人能直接拿它写代码。三个问题立刻浮现：用户登录后，这个“后”是同步跳还是异步跳？首页是哪个路由？“个性化内容”的数据从哪里取，取不到怎么办？
OpenSpec 的规格写法要求把每一个模糊量词变成可验证的断言。上面那句话落到规格里大概会变成：
When: 用户完成登录认证 Then: 系统在 500ms 内返回 HTTP 302 到 /home And: 系统根据 user.profile.theme 字段渲染首页主题 And: 系统调用 recommendation API 拉取内容列表 And: 当 recommendation API 超时或返回空数组时，首页展示默认内容块每种描述都对应一个具体的断言，每条断言都是可测的。这就是规范驱动开发的精髓：你不是在把事情写得更啰嗦，而是在消灭“每个人理解都不一样”的空间。
4.2 场景示例怎么写才有价值
规格模板中有一个场景示例区块，很多团队把它理解成“举一个业务例子”。这个定位其实窄了。场景示例在 OpenSpec 里承担的作用是可执行验收标准的草稿。
一个合格的场景示例应该包含四要素：
- 前置状态：系统此刻处在什么状态。数据库里有几类数据，外部依赖是否可用。
- 操作动作：用户或外部系统做了什么操作。
- 预期结果：系统应该给出什么样的反馈。
- 边界情况：如果操作异常、参数缺失、并发冲突，系统该怎么办。
我在实际项目中总结的经验是：把场景示例当成“最小测试用例”来写。每条需求，至少配一个正常路径场景和一个异常路径场景。例如，还是登录那个需求，正常路径是“凭证有效，登录成功，返回首页”，异常路径就是“凭证过期，系统返回 401，前端跳转登录页并给出提示”。
有了这两个场景，开发人员不需要做“二次需求理解”，测试人员也不会觉得自己在凭空造用例。
4.3 规格文件变更记录与版本管理
一个能力域的规格不是铁板一块。它内部通常包含若干条需求指令，每条指令由若干场景结果支撑。当你对规格做了调整，OpenSpec 支持查看变更差异：
openspec capability diff <capability-name>这个命令可以帮你对比当前规格与上一个已接受变更之间的差异。我的习惯是，每次变更提案 apply 之前，先跑一次 diff，确认改动范围没有超出提案声明的范围。一旦发现改动了别人没批准的部分，就立刻撤回检查。
这个习惯用一句话总结就是：diff 守范围，apply 才落定。先看差异，再应用变更，顺序错了后面全是冲突。
5. 用任务清单驱动开发节奏
5.1 将规范拆成可执行任务
规格文件落定后，OpenSpec 会生成对应的任务清单。每个任务对应一个最小可交付单元，任务与任务之间是基于依赖关系而非时间顺序连接的。这个设计背后有它的道理：任务是规范在开发执行阶段的投射，任务的完成标准就是规范的验证标准。
看一下任务清单：
openspec task list正常情况下，你会看到类似这样结构化的输出，每一项任务含标题、关联需求 ID、状态。任务状态有三种：
- pending：还没开始。
- in_progress：正在实现。
- completed：已完成并通过规格验证。
开发的原则是：一个任务完成了，才标记 completed；标记完成的标准是代码实现满足对应规格描述中的全部断言。没有满足断言就标完成，算自欺欺人，后面验证阶段迟早暴露。
5.2 让规格参与代码评审
我强烈建议把规格文件纳入代码评审的必读材料中。评审人员不只看代码 diff，还要对照规格文件里的需求描述，确认实现确实吻合。
评审时大家关注三个问题：
- 代码是否实现了规格中描述的所有断言？
- 代码是否做了规格之外的事情？如果有，要么是规格漏了，要么是开发自作主张。
- 代码中是否存在与规格命名不一致的标识符，导致未来追踪困难？
这一条很朴素，但极少有团队真正执行。大多数评审会聚焦在实现质量和可维护性上，却忽略了最根本的一致性。你在评审里拦住一个“和规格不符但代码看起来没问题”的实现，远比事后修复省事得多。
6. 避坑指南：OpenSpec 实践的五大常见坑
6.1 把 OpenSpec 当文档系统用
有人习惯把 OpenSpec 的规格文件写完，然后继续回到老节奏拍脑袋写代码。这相当于拿了张地图，然后闭着眼睛开车。规格的生命力在于持续驱动开发，只有写出来但没有进入任务拆解和验证反馈闭环，这套流程等于白搭。
6.2 一开始就追求规格的“完备性”
还有一种相反的偏执，总觉得规格写得不够细、不够全，不敢进入编码阶段。这种行为会导致规格文档膨胀到几千行，没人看也没人维护，最终重新变成摆设。
合理的方式是先写 70% 的确定性，保证关键的边界、状态、异常覆盖到位，剩下 30% 交给验证阶段迭代。OpenSpec 的 PBL 模式本来就是支持“边开发边演进”的，不需要也不可能一次写到位。
6.3 忽略验证器输出
OpenSpec 自带验证器和错误检查器，执行校验的命令大致是：
openspec validate <change-name>这个命令会检查规格文件内部的引用完整性、场景断言是否遗漏、任务清单是否有未关联项。我实测下来的感受是，校验器输出的每一条提示都有实际意义。比如它会指出你某个场景只写了正常路径没有异常路径，或者某个需求指令没有对应的代码关联文件。忽略这些输出，等于放弃了这个工具一半的能力。
6.4 变更粒度失控
有的团队会把十几个需求塞进一个变更提案里，美其名曰“高效”。这往往招来的是灾难。变更范围过大，评审没法聚焦，冲突不断，验证时出了问题也无法定位是哪个需求导致的。
我的经验是：一个提案只解决一个问题。如果一个需求可以拆成多个独立的交付动作，那就拆成多个提案。提案越小，认知负担越低，被拒绝的风险也越小。
6.5 不把规范变化同步给非技术角色
OpenSpec 的文件是 markdown 格式，本质上人和机器都能读。有些人会把规范文件只留给开发团队看，产品和业务侧完全不接触。这样需求源头和实现层之间依然存在信息服务。
建议在需求评审阶段直接打开 capability 目录，让产品和业务一起看规格描述里的场景断言。他们看不懂代码，但看得懂“当……则……”的叙事结构。让非技术角色参与规格讨论，很多需求模糊地带在编码前就暴露了，这比事后再纠正省钱得多。
7. 验证与反馈：从“我觉得行”到“规格说了算”
OpenSpec 的验证环节是整套工作流里最值钱的部分，没有之一。
传统项目里，开发完一个功能，测试同学要么凭经验写用例，要么对着需求文档猜覆盖。OpenSpec 的验证思路完全反过来——验证目标不在“功能名单”里，而在规格断言里。代码写完，执行校验，校验器会读取规格描述，检查实现是否存在偏差。验证不通过，校验器给你反馈问题列表，你带着问题去改代码或改规格，形成闭环。
这里需要说明一下：OpenSpec 提供的验证器能力深度取决于项目集成的程度。简单场景下，它验证的是规格结构、任务状态和引用完整性；深入场景下，它可以通过接入自动化测试框架，把规格断言映射为可执行的测试用例。
实际项目中我建议分两步走：
- 第一步，先让规格驱动人为评审，保证方向正确。
- 第二步，再逐步引入自动化测试映射，保证回归可靠。
这套节奏不至于一上来就背上过多工具负担，也能快速看到效果。
我印象最深的一次实践，是某个支付状态机项目的重构。旧代码里状态流转的判断逻辑散落在七八个文件里，每次改动都要靠“人肉推理”。后来我们把状态流转规则全部写进规格，每个状态迁移配一条断言，任务拆到具体迁移路径。重构完那次上线前测试，没有靠人工能想到的用例挨个试，而是直接跑规格映射出来的状态迁移矩阵。一夜之间验证完所有路径，效率提升是传统方式完全没法比的。
8. 团队怎么平滑过渡到规范驱动开发
8.1 不要立刻推翻现有项目
我给团队的建议是：不要停下来把过去所有代码重构一遍，也不要试图把所有已有的隐性规则一次性写进规格。这种行为会在短期内消耗大量时间，且看不到收益。
正确姿势是：从下一个新需求或新模块开始。新需求走 OpenSpec 流程，旧代码维持现状。当旧模块因为迭代需要频繁变更时，再逐步把相关规则梳理进规格体系。渐进式迁移，比一刀切的改革稳妥得多。
8.2 从一两个能力域试点
选择一个业务稳定、边界清晰、变更频率适中的能力域作为试点。建议选择你们团队最熟悉、最常接触的模块，而不是选一个大家都在回避的遗留老代码。因为试点的目的是验证工作流本身的可行性，不是挑战最难的技术问题。
试点期间，至少跑完一个完整的变更循环——从提案到规格、从任务到实现、从验证到合入——让大家完整看到这套流程的全貌。有了成功示范，团队接受度会明显提高。
8.3 沟通成本是前期的主要成本
有人问，规范驱动开发会不会拖慢团队速度，增加前期工作量。如果单看第一个变更提案，确实会比传统模式多花一些时间。但请注意，这些时间大多花在沟通和认知对齐上，而这些成本本来就会在后期返工中支付。与其说规范驱动增加了成本，不如说它把成本提前支付了，买来的是后期更高的确定性。
这个交易是否划算，取决于你的团队是否经常因为需求理解偏差而返工。如果从不返工，每个人都默契十足，那这套流程可能确实没有必要；如果每次上线前都要大改一轮，那就值得试一试。
9. 一些个人的使用心得
分享几个我在具体实操过程中的经验总结。
第一，规格文件不要堆在根目录。严格按照工具默认的目录结构走。capabilities 按能力域拆文件，changes 按时间或主题组织提案，tasks 保持与规格映射。目录一旦混乱，这套执行约束就瓦解了。
第二，能力域的命名要偏名词，不要偏动词。命名风格暴露思维习惯。如果你的能力域目录里出现“下单流程优化”“增加支付方式”这类名字，说明你还是在按功能切模块，不是按能力切边界。能力域的命名应该是“订单管理”“支付结算”“库存调度”这类稳定名词。
第三，别用一个巨型提案包办一切。有些同学习惯攒一波需求再统一提变更，方便自己是省事了，但给评审和验证带来巨大成本。提案拆得够小，才能做到每次变更都有明确的一对一验证反馈。
第四，规格文件不是写一次就结束的东西。项目在演进，能力边界在变化，规格必须跟得上。每当你发现代码实现需要绕过规格描述才能落地时，不要硬改代码，而是要反问一句：是规格过时了，还是实现想偏了？多数时候答案都是后者。
以上这套实践方式，我已经在个人项目和团队项目里反复验证过。它的价值不在于瞬间改变代码质量，而在于让所有人都意识到：设计软件系统的第一对象不是机器，是人的认知。把人的认知先约束住了，机器的行为才能可控。OpenSpec 的价值说大也大，说小也小——它不过是一个让这些约束变得可操作的工具而已。但“可操作”这件事，恰恰是大部分团队最缺的。
如果看完这篇文章，你最大的感受是“原来开发前应该先把话说明白”，那就说明你已经理解了规范驱动开发的精髓。其他细节上的工具操作，都不难学。
