最近有好几个朋友在问我同一个问题:团队里引入AI辅助编码之后,代码生成速度确实上来了,但需求经常做偏,返工比手写还累,有没有什么办法能让AI和团队在同一个频道上干活?我的回答基本都是同一个:去试试规格驱动开发(SDD),配合OpenSpec这套工具链。这个组合是我近期实践下来,对付“需求理解偏差”和“AI生成不可控”最有效的一套打法。今天这篇就完整梳理一下我从了解到落地、再到在几个真实项目里跑通的全过程,希望能帮你少走点弯路。说实话,规格驱动开发不是什么新概念,但OpenSpec把这件事变得非常具体、非常好落地。它不是一个只能写在PPT里的方法论,而是一套有明确目录结构、有标准文件格式、有命令行工具、还能跟AI编码助手深度配合的完整工作流。这篇文章会从原理讲到实操,最后附上我踩过的坑和排查经验,读完你大概率能直接在自己的项目里开搞。1. 先搞清楚:规格驱动开发到底解决什么问题1.1 传统流程的需求传导链条为什么总是断做过几年项目的人基本都经历过这样的场景:产品经理口头讲了一个需求,你凭理解画了一版原型,开发照着原型去写,测试根据自己理解的场景去测,最后上线前发现产品经理想要的根本不是那回事。这个链条里最致命的不是某个人能力不行,而是信息在传递过程中不断失真。我把这个链条拆开看,通常的需求传导是这样:业务方有一个模糊的诉求,比如“做个优惠券功能”产品经理理解后,在文档里写下“支持满减券、折扣券”后端拿到需求,想的是一张券表怎么设计、状态机怎么流转前端拿到需求,想的是页面怎么展示、用户怎么交互测试拿到需求,想的是一堆用例和边界条件问题就出在这里:同一个功能,五个人脑子里有五份不同的“规格”。文档里只写了“满减券”三个字,但满减券是全场通用还是指定商品?能不能叠加?过期之后怎么处理?退款时券怎么退?这些问题没人说清楚,全靠开发“自由发挥”。传统流程里的需求文档往往又臭又长,写的人痛苦,看的人更痛苦。更麻烦的是,文档一旦写完就寿终正寝,代码实现了跟文档不一致,也没人发现。我见过太多项目,最后维护的时候,文档已经不是代码的影子了,而是代码的幻觉。1.2 规格驱动开发的核心思路:让规格成为唯一真相源规格驱动开发(Spec-Driven Development)的思路是反过来的:先把行为定义清楚,再写代码。它强调用结构化的、可校验的规格描述来描述系统“应该做什么”,然后让实现、测试、文档全部围绕这份规格展开。这种方法在国内被讨论得不多,但在API设计和微服务领域,契约优先(Contract-First)已经是很成熟的玩法了。OpenAPI规范就是典型的例子:先把接口契约定义好,前后端并行开发,基于同一个契约文档进行对接,而不是等一端写完了另一端才开工。规格驱动开发把这种“契约思维”从接口层面提升到了整个功能开发的层面。它不再只定义API长什么样,而是全面描述:这个功能解决什么问题系统行为在特定输入下应该给出什么输出有哪些业务规则和边界条件怎么确认这个功能做完了一旦这份规格被团队成员认可,它就是唯一的真相源(Single Source of Truth)。开发照着它写代码,测试照着它写用例,项目经理照着它排进度,AI照着它生成代码。所有人都对齐到同一份文件上,而不是对齐到某个人的口头上。1.3 为什么是OpenSpec而不是其他工具市面上做规格驱动的工具不算多,真正能开箱即用的更少。OpenSpec的核心优势在于它把整个流程工具化了。它不是让你在Word里写文档、在Excel里维护状态,而是给了一套标准的目录结构和文件格式,配套一个CLI工具,还会自动生成change proposal。你在OpenSpec里提出一个变更,它会让AI帮你想清楚这个变更涉及哪些文件、需要改哪些测试,后续还可以直接用命令行交互式的对变更进行review。这套完整的闭环,让“规格”从一个抽象理念变成了可落地的工作流。从2025年初我开始用OpenSpec,那时候它还比较小众,社区里讨论的人不多。现在已经有不少团队在推进,尤其是那些重度使用AI辅助编码的项目组,几乎把规格驱动当成标配。原因很简单:AI写代码快是快,但如果不给它一份明确的规格,它就是在猜。OpenSpec的价值恰恰在于,把“猜”变成“查”。提示:OpenSpec目前是开源项目,官网和GitHub上都有详细文档。如果你在评估它,建议先看官方仓库里的examples目录,里面有不少真实场景的规格示例,比读文档直观得多。2. 认识OpenSpec:规格文件究竟是长什么样的2.1 目录结构与变更集概念OpenSpec的核心抽象是“变更集(Change Set)”。在一个典型的OpenSpec仓库里,目录结构大致是这样的:openspec/ ├── project.md ├── spec/ │ ├── capabilities.md │ ├── orders.md │ └── users.md └── changes/ ├── 2025-02-18-add-coupon-system/ │ ├── proposal.md │ ├── tasks.md │ └── tests.md └── 2025-02-10-refactor-order-status/ ├── proposal.md ├── tasks.md └── tests.md我刚接触这个结构的时候也有点懵,觉得多此一举。用了一阵子才明白,这套设计非常讲究:capabilities文件描述系统当前应该具备的能力,changes目录下每增加一个子目录,就代表一次具体的功能变更。每个变更包含三份文件:proposal(提案)、tasks(任务清单)、tests(验收测试)。整个OpenSpec的逻辑本质上是把“开发一个功能”变成“提交一个提案,经过评审后实施”,很像开源社区的RFC流程,只是把它工程化了。你不再是人脑里装着需求直接写代码,而是先把变更描述清楚,再动手。2.2 规格文档里的四件套怎么配合一个完整的变更集通常包含四个方面,我分别说说它们的作用。Proposal描述“为什么”和“怎么做”。它解释当前方案想解决什么问题、有哪些可选方案、为什么选了现在这个方案。比如你要做优惠券系统,提案里要写清楚:业务背景、方案描述(券的类型、发放方式、使用规则)、影响面分析(涉及订单模块、支付模块、商品模块)。这份文件的价值是让所有人理解“我们在干什么,以及为什么这么干”。Tasks是把提案拆成可执行的开发任务。每完成一个功能点,就勾掉一个任务。这部分对AI辅助编码尤其重要,因为AI可以按照描述精确地定位需要修改的文件和逻辑,而不需要猜测重构范围。Tests是验收测试描述,而不是具体的测试代码。OpenSpec鼓励你用Given-When-Then结构描述行为,像这样:Given 用户有一张满100减20的优惠券 When 用户下单金额为150元 Then 订单金额显示为130元 And 优惠券状态变为已使用这套描述方式对测试工程师来说几乎是零门槛,而且高度结构化,可以直接转化成BDD测试代码。你也能提前把这些测试交给AI,让它生成对应的自动化测试用例。Project.md则是对整个项目的宏观描述,说明项目是干什么的、技术栈是什么。这个文件让AI(以及新加入的成员)快速了解项目全景,不至于一头扎进代码细节里。2.3 CLI与AI工作流是怎么串起来的OpenSpec最让我惊艳的是它内置的CLI工具和AI辅助能力。安装之后,常用两个命令:# 列出所有变更 openspec list # 查看变更详情 openspec show 2025-02-18-add-coupon-system # 生成新的变更提案 openspec proposal add-coupon-system --summary 新增优惠券系统OpenSpec甚至还提供了交互式CLI,可以直接用自然语言与CLI对话来生成最初version的proposal,它会结合你的工作区根目录里的内容自动生成proposal,比如你和它对话“帮我想想做优惠券系统需要考虑哪些边界情况”,它就会列出满减条件、过期处理、与其它优惠的叠加规则等,再通过交互继续确认细节,最终生成一份完整规格。这个环节打动我的点在于:它把“从零开始怎么写规格”的门槛降到了最低。以前写规格最难的其实是第一版,面对一张白纸无从下手,现在你只要把零散思路告诉AI,它会整理成结构化提案,你再逐项审核、修改、补充,很快就能得到一份像样的规格。这就算在实际使用中最重要的部分了。3. 实战演练:用一个优惠券功能走通全流程3.1 环境准备与初始化下面用一个真实案例来演示:给一个电商系统新增“优惠券”功能。这是一次规格驱动开发的全流程,包含从需求含糊到测试通过的完整闭环。首先安装OpenSpec并初始化项目:# 在项目根目录初始化 OpenSpec openspec init初始化之后,项目里会出现openspec文件夹。先编辑openspec/project.md,写清楚项目的基本信息:# 电商系统 ## 技术栈 - 后端:Python FastAPI PostgreSQL - 前端:React TypeScript - 部署:AWS ECS GitHub Actions ## 项目目标 提供一个支持商品管理、订单管理、支付结算的电商平台,面向中小商家。这一步别急着跳过。project.md虽然看起来简单,但它决定了后续AI和协作者对项目的整体理解。我在实际使用中发现,如果project.md写得太空,AI生成的提案质量会明显下降。你给它的上下文越充分,它输出的东西越靠谱。3.2 编写规格:把模糊需求变成可执行文档接下来创建一个变更提案。这里用交互模式写是最顺手的:openspec proposal add-coupon-system --summary 新增优惠券系统,支持满减券与折扣券这条命令会在openspec/changes/下创建一个日期开头的目录(比如2025-06-18-add-coupon-system),并生成proposal.md的骨架。然后用编辑器打开这个文件,开始补全。提案文件里的内容,核心是描述清楚“解决方案”。我的习惯是先写清用户故事,再列业务规则。这里贴一段我当时实写的片段:# 变更提案:新增优惠券系统 ## 摘要 新增优惠券模块,支持商家创建满减券和折扣券,用户在下单时可选择符合条件的优惠券进行抵扣。 ## 背景与动机 目前系统没有任何营销工具,商家无法进行促销活动。本期引入优惠券作为最小可行营销能力。 ## 解决方案 - 优惠券类型:满减券、折扣券 - 每种券有固定有效期,过期自动失效 - 每张券绑定一个用户,用户领券后进入“我的券包” - 下单时可选用一张可用券,券与商品级折扣互斥 - 订单创建成功后,锁定优惠券;订单取消时,解锁返还 ## 关键业务规则 1. 满减券的订单金额门槛以商品原价计算,不含运费 2. 折扣券最高抵扣不超过订单实付金额的50% 3. 优惠券不可叠加使用,每个订单只能使用一张 4. 退款后,优惠券不退回,仅退回用户实际支付金额 ## 影响范围 - 订单模块:创建订单、取消订单需要接入选券和锁券逻辑 - 新增优惠券模块:领券、券包列表、校验可用性 - 管理端:商家创建优惠券的接口这一段内容其实已经相当具体了,但我还想强调一点:业务规则的描述是核心中的核心。你不需要把代码方案写进去,比如用什么设计模式、建什么表,这些留给开发决定,但要尽可能把规则边界写清楚。第4条“退款后券不退回”是我在现实中踩过坑的教训。一开始没写这条,开发就按直觉实现了“退款退券”,结果造成用户刷退款薅羊毛的问题。后来把规则明确写进规格,才堵住了这个漏洞。3.3 评审变更提案:让该说话的人都在场提案写完后,别急着进开发。组织一次评审,拉上产品、后端、前端、测试、AI代表(其实就是把提案喂给AI过一次)开个短会。我自己的项目里,评审是这样的流程:先让提案作者过一遍背景和方案,然后逐条过业务规则,尤其是带数字、带条件的部分。上面那段规则里的“折扣券最高抵扣不超过50%”,当时就有争议,运营同学说有些大促想要100%抵扣(也就是0元购)。一番讨论后,决定按50%上限先上,后面如果要放开,单独走变更流程。这个细节恰好说明了规格驱动的价值:规则不是开发拍脑袋定的,而是在写代码之前就经过讨论,一字一句写进了文件里。评审结束后,把proposal状态标记为approved。这个状态转换很重要,相当于给团队一个信号:方案定了,下面进入施工阶段。3.4 根据规格拆解任务并生成测试接下来用CLI生成开发任务清单:openspec proposal tasks add-coupon-system --spec openspec/changes/2025-06-18-add-coupon-system/proposal.md这个命令会扫描proposal.md,结合当前代码库结构,自动生成一个tasks.md,内容包括创建数据库表、编写领券接口、校验接口、下单接入、状态管理等。生成之后逐条过一遍,改成符合项目习惯的描述,补充细节任务。我当时把生成的结果调整成了这么多:# 任务清单 ## 数据库与模型层 - [ ] 创建 coupon 表,字段包括id、type、value、threshold、expires_at、user_id、status - [ ] 创建 coupon_template 表,字段包括id、type、value、threshold、total_count、start_time、end_time ## 后端业务逻辑 - [ ] 实现创建优惠券模板接口(POST /api/admin/coupon-templates) - [ ] 实现领取优惠券接口(POST /api/user/coupons/:templateId/redeem) - [ ] 实现查询我的券包接口(GET /api/user/coupons) - [ ] 实现优惠券可用性校验(金额门槛、有效期、状态、互斥规则) - [ ] 订单创建时接入优惠券锁定逻辑 - [ ] 订单取消/超时未支付时释放优惠券 ## 前端页面 - [ ] 商家端:优惠券模板创建页 - [ ] 用户端:我的券包页面 - [ ] 用户端:下单页展示可选优惠券至于tests.md,本质上是把业务规则转成Given-When-Then描述。这一步能把验收标准说清楚,也能减少测试工程师跟开发之间的来回沟通。比如:# 验收测试 ## 满减券使用 - [ ] Given 用户有一张满100减20的满减券,When 下单金额为90元,Then 不能使用该券 - [ ] Given 用户有一张满100减20的满减券,When 下单金额为150元,Then 订单金额为130元 - [ ] Given 用户有一张满100减20的满减券,When 订单金额为150元且已使用,Then 订单金额显示原价150元 ## 折扣券使用 - [ ] Given 用户有一张8折券且最高抵扣50元,When 下单金额为1000元,Then 实际抵扣50元而非200元 ## 退款场景 - [ ] Given 用户使用优惠券后订单被退款,When 完成退款流程,Then 优惠券不退回用户这份文件既可以作为开发自测的清单,也可以直接交给测试同学写自动化用例。我在实操中是把这份描述直接复制给AI,让它按项目现有的测试框架生成参数化测试代码,基本一版就能跑通。3.5 实现代码与规格对齐进入编码阶段后,规格驱动开发最有意思的部分来了。我们把tasks.md和tests.md作为实现依据,交给AI编码工具来辅助实现。过早地让AI在没有任何规格的情况下直接生成优惠券功能,往往会出现“代码看起来正常,但规则实现错位”的局面。比如它可能会默认“退款退券”,而规格里明确写着退款不退券。有了规格文件,再把场景喂给AI,它就是基于规则推理而不是猜测。在实际操作中,AI生成的代码里仍然会有细节错漏,但整体正确率从“50%像猜的”提升到“80%以上直接可用”,剩下的20%你自己改起来也很快。过程中还有一个容易被忽略的动作:代码提交时,在commit信息里引用变更集目录,比如feat(coupon): implement coupon locking per openspec/2025-06-18-add-coupon-system。这样做的好处是,后人看git记录时能直接关联到完整上下文,而不是看一堆零散的commit message猜当时在干什么。注意:规格驱动开发最忌讳的是“写完规格就不管了”。项目做完全部落地后,要把这个变更集归档,否则功能后面继续演进,规格就静悄悄地过期了。归档的做法是把opened的变更全部通过审批、然后把已经合入代码的变更目录移到openspec/archive目录下。这步很简单,但能保证仓库里的规格始终是“活着”的。4. 常见问题与排查技巧实录4.1 规格写了一大堆,但代码实现总是对不上这是我看到的最常见现象。原因通常是:规格写得过于抽象,根本没到“可执行”的颗粒度。比如你写了“支持满减券”,但没写满减券的金额门槛怎么算、是否能与其他优惠共享、超时未下单是否失效等等。这些边界不写清楚,实现阶段必然靠猜。这不是OpenSpec的问题,而是从需求到规格的翻译能力不足。解决的办法是,在评审提案时逐条逼问“如果……会怎样”。专门做一次“找茬”演练:把规则里的每个动词、每个数字都过一遍,凡是出现“可以”“支持”“允许”这类模糊词,必须补上条件和限制。我上面的规则列表里有一条“折扣券最高抵扣不超过订单实付金额的50%”,这个数字就是通过一次找茬演练补出来的。没有这个数字,开发很可能就写成“最多减50元”了。4.2 规格和代码实现发生漂移怎么办规格驱动开发的理想状态是“规格即真理”,但现实中规格和代码一定会漂移。尤其是快速迭代的项目里,总是有小改动不经提案直接进入代码,导致规格文件慢慢过时。我的经验是,不要试图“禁止一切漂移”,而是要建立定期校准机制。每次迭代结束,花个把小时打开changes目录,看看哪些变更集已经合入代码,哪些还没结束,哪些proposal描述和实际实现有出入。有出入就直接改proposal,保持它跟代码同步。只要这个校准动作是常态化的,规格就不会烂尾。另外一个技巧是,把“规格文件更新”作为完成的定义的一部分,写进团队的Definition of Done。没有更新规格文件,就不算完成这个功能。听起来有点形式主义,但踩过几次坑之后就明白,这比事后花几天去核对代码和文档的偏差省多了。4.3 让AI参与提案生成时,怎么保证质量OpenSpec的AI辅助功能确实能大幅降低规格编写门槛,但AI生成的提案质量不稳定。最常见的两个坑是:内容空洞、套话多,或者规则描述太含糊。我的经验是,AI生成的提案一定要经过人工重写。具体做法是:先用交互式CLI跟AI对话,把核心需求同时讨论出来,它会生成一版proposal;然后从头到尾通读,把每一段用自己的话重新描述一遍。为了明确边界,也可以在对话中直接输入业务规则并要求逐条确认。通过这一轮重写,内容会扎实得多,因为AI提供的框架是完整的,而你的领域知识补上了血肉。还有一点,AI往往会遗漏“反规则”,也就是什么情况下不能做什么。这些规则恰恰是需求里最容易出现问题的部分。所以每次AI生成完,我都会专门问一遍:“哪些情况下这个功能应该被禁止或拒绝?”用这个问题去套它,能挖出不少遗漏。4.4 团队协作中的变更流程怎么运转规格驱动开发真正的难点,不在个人,而在团队。多个开发同时开工,每个人都在改产品代码,这时变更集之间的冲突就不可避免。我的团队实际操作中,规则简单粗暴:一个变更集尽量只改一个模块。如果一个变更影响了订单和优惠券两个模块,要么拆成两个变更集,要么明确指定这个变更集的owner,由他来统筹两边代码。实践中还有一个trick,每次动代码前都打开变更集对应的tests描述,看看你马上要改的地方是不是被某条场景管着。如果是,改完代码顺手把这条测试跑一遍,而不是等到提测时才去排查问题。提示:在多人协作时,建议给changes目录加一个README,约定变更集命名规则、评审流程、approve标准。OpenSpec本身不强制这些规范,但团队内如果没有约定,会陷入“格式混乱”的困境。4.5 写本文时发现的新玩法:变更集作为项目知识库规格驱动开发用久了,你会发现openspec目录本身变成了一部项目活历史。每次变更集都记录了“当时我们为什么要这么干”“中间讨论过哪些方案”“定下了什么边界条件”。这非常利于新成员加入时快速熟悉系统,也方便回溯问题。我经常在处理线上bug时,先去翻对应模块的规格文档,而不是直奔代码。因为规格文档记录了业务意图,而代码只能告诉你当前是什么样子,不能告诉你“为了什么才变成这样”。如果你把OpenSpec当成一个团队知识库来运营,那么它的长期价值会远超“规范开发流程”这么简单。这一点体会,越用得久越明显。5. 数字表格参考:几个可以帮你快速复制的最小模板下面提供几组可以直接复制着用的最小模板,覆盖新功能变更、缺陷修复、技术重构三类场景。这样你打开编辑器就能开写,不用每次从零搭骨架。5.1 最小变更集文档模板(新功能)# 变更提案:简要标题 ## 摘要 用三句话描述你要做什么。 ## 背景 这个需求是怎么来的?不做的代价是什么? ## 解决方案 分点描述系统和业务的相关变更,写明边界条件和限制。 ## 业务规则 1. 规则一 2. 规则二 3. 规则三 ## 影响范围 哪些已有模块会被改动?5.2 缺陷修复类模板# 变更提案:修复XX问题 ## 缺陷描述 用户实际看到的现象、复现步骤、影响范围。 ## 根因分析 代码层面的直接原因是什么?为什么会出现? ## 修复方案 改哪里、怎么改、是否有需要更新的规格描述。 ## 回归测试场景 - [ ] Given 复现场景,When 执行操作,Then 期望结果5.3 技术重构类模板# 变更提案:重构XX模块 ## 现状问题 当前结构的痛点是什么?例如耦合、性能、可维护性。 ## 目标状态 重构之后理想的结构是什么样?抽象出哪些新概念? ## 迁移方案 从当前状态到目标状态的过渡路径,是否分阶段? ## 兼容性要求 对外接口行为是否有变化?是否需要兼容旧数据?这三套模板覆盖了我日常开发中90%的规格编写需求。当你写了一段时间之后,自然会长出自己的一套描述偏好,但起步阶段直接套模板是最快的。6. 从规格驱动到更完整的工作流如果你已经用OpenSpec把“功能开发”纳入规格驱动,那可以进一步往前迈一步:把需求分析也纳入这个体系。我现在习惯的做法是,需求讨论阶段就打开一个空白提案文件,把零散的想法记进去,随着讨论深化逐步补全。等到需求评审时,提案已经是一份比较完整的规格初稿了。这样不但省掉“写完需求文档再转规格说明”的一道工序,而且能促使产品经理和开发从一开始就对齐。另外一个可以扩展的方向是:把规格文件跟自动化测试绑定。在CI/CD流水线里加一个阶段——规约测试阶段,目标是:每合并一个变更集,自动检查tests.md中的所有场景都有对应的自动化测试用例覆盖,或者直接运行由规格推导出的测试集。这样就能做到“规格驱动的自动化闭环”。不过我要提醒一句,这些进阶玩法一定要在自己团队已经习惯基础流程后再上。曾经有一天,我在会议上讲完这些规划后,一个同事问我是不是在“过度工程”。后来我仔细想了想,确实是。如果一个小团队连规格文件都还没养成习惯,就急着上自动化验收,只会让所有人觉得流程很重、很繁琐,然后整个体系被抛弃。所以,一步一步来,先把提案任务测试这个最小闭环跑顺,再谈扩展。7. 最后的几个小建议我根据自己的实际操作体验,整理几条过来人的经验:第一,规格文件不要追求一次写完美。初稿能把核心规则说清楚就行,评审过程本身就承担补充和修正的功能。你只要有“三幕结构”——背景、方案、规则,并且让相关人参与评审,消息就不会烂。第二,每次AI生成内容后,在接收之前给自己留一个必须核对的关键清单:规则是否完整、边界是否合理、影响面是否覆盖。千万别直接照单全收。这年头AI的能力是强了,但它最大的问题在于“过于自信地犯错”。它写出来的规格看起来头头是道,实际可能在某个关键逻辑上有隐患。第三,OpenSpec不是银弹。它解决的是开发过程规范化的问题,解决不了需求本身想不清楚的问题。如果业务目标本身是混乱的,再好的规格流程也救不了。这个流程最大的价值,是能把“想不清楚”这个问题提前暴露在写代码之前——项目早期发现需求模糊,总比上线那天发现做错了要好得多。从我个人的实践来看,规格驱动开发最大的变化不是流程上的,而是团队沟通方式的。以前大家讨论需求,各说各话,现在都围着规格文件说话——有争议先改文档,文档改好了再动手。光这一点,就让我在每个项目里省下了大量的时间,也少吃了很多“返工”的苦头。我真心建议你去试一次,哪怕先拿一个小功能练手,跑一遍完整的提案到测试闭环,你就能真正体会规格驱动开发带来的改变。