如果你最近半年和我一样重度依赖 AI 编码工具大概率会遇到同一个问题AI 写单点功能很顺但一碰跨模块变更它就像脱缰的野马。说好只改支付接口它顺手把订单状态机的命名也重构了说好沿用现有错误处理风格它给你引入一套全新的异常包装说好“保持最小改动”提交记录里却躺着十来个无关文件的 diff。代码能跑review 却比手写还痛苦。我试过各种 prompt 模板、编辑规则、约束清单效果都有限直到我把整个工作流从“对话驱动”切到“规格驱动”情况才真正好转。这次想聊的就是这个转变的核心工具OpenSpec以及它的Commands 命令体系。OpenSpec 不是又一个代码生成器它解决的是 AI 编码工作流里最容易被忽略的问题规范缺失。AI 编码工具本身没有长期记忆每次对话都是新上下文如果团队没有一个结构化的“契约”文件AI 就会在每次会话中随机发挥。OpenSpec 通过一套 CLI 命令把需求、设计、实现、验证这些环节固化成规范文件让 AI 始终在同一套事实基础上工作。这篇文章我会从核心模型讲到命令逐条拆解再聊接入现有工作流的实操细节适合正在重度使用 AI 编程助手、但觉得项目正在“慢慢腐烂”的团队和个人开发者。1. 先回答一个关键问题AI 编码为什么需要“规格驱动”1.1 自由发挥式编码表面高效账上全是隐性成本直接算一笔账让 AI 编码单次生成的“直接成本”确实低一段百行以内的函数它几十秒就能写完哪怕不满意重写一遍也就多花一两分钟。但真正的大头在隐性成本。我自己的项目里最典型的一个反例我让 AI 给用户中心加一个“退款申请”接口并强调“只动 payment 模块”。AI 确实只在 payment 模块加了接口但它顺手把 controller 层一个已有方法的命名从refund改成了applyRefund理由是“更符合语义”。这个改动在它的上下文里是合理的但对整个代码库来说这是一次没有评审的公共 API 变更——调用方全部要跟着改测试接口文档也要改而团队里只有我一个人知道这件事发生过。更隐蔽的问题是风格漂移。同一个 AI 助手今天生成的错误处理是try/catch 统一异常包装明天生成的可能是if err ! nil 直接返回因为它每次都是独立的上下文。代码库会逐渐变成“多人风格混写现场”只是这些“人”其实是同一个 AI 的随机状态。这种漂移在 review 时很难发现因为每一段代码单独看都“没毛病”放在一起看就是四种不同的处理风格。对话驱动的工作流还有一个结构性缺陷prompt 是易失的。人脑里关于“当初为什么这么设计”的背景在两周之后就模糊了AI 的上下文窗口关掉之后就彻底没了。代码只是最终产物它记录了“做了什么”但完全没有记录“为什么这样做、不做什么、边界在哪”。等到项目进入维护期新人无论是人还是 AI只能靠猜。1.2 规格驱动的本质把决策从对话里搬到文件里规格驱动开发Spec-Driven Development不是新概念传统软件工程里的设计文档、接口契约、验收标准本质上都是规格。只是过去这些文档和代码实现经常脱节写文档变成了“事后应付”于是大家觉得流程重、收益低。OpenSpec 的思路不一样它把规范文件直接放在代码仓库里跟代码一样走版本管理并且用命令来驱动它的生命周期。关键点在于规范不是给“过程”用的而是给“决策”用的——把关于“做什么、不做什么、边界在哪”的决策在编码开始之前就固化下来而不是让 AI 在编码过程中临时发挥。打个比方AI 编码很像请一支施工队装修。你要是只说“把厨房弄好看点”施工队自由发挥的结果大概率跟你想的不一样但你要是给一张图纸、一份材料清单、一个验收标准施工队反而能稳定交付。OpenSpec 就是给 AI 编码工作流补上“图纸”和“验收标准”的那套工具。这里有个反直觉的点写规格看起来是增加了前期时间但它真正省下的是返工时间。一个变更如果设计阶段错了返工成本是 1 倍如果编码阶段错了返工成本可能变成 3 倍如果上线之后才发现错了可能就是 10 倍。规格驱动不是要消灭不确定性而是把不确定性尽量集中在设计阶段解决别让它延后爆发。2. OpenSpec 的核心模型项目规范、变更提案和 Agent 规则2.1 一次变更从“想法”到“合并”的完整生命周期OpenSpec 把一个功能变更拆成了明确的阶段每个阶段都有对应的命令和状态。以“用户中心增加退款申请”为例完整旅程是这样的创建变更提案用openspec create生成一个变更提案文件记录背景、目标、非目标、影响范围。此时提案是draft状态。细化设计技术负责人或 AI 辅助完善提案明确“要做什么”和“明确不做什么”。通过评审后进入in-review或accepted。生成实现计划用openspec plan把提案转成一份 AI 可执行的分步计划相当于施工图纸。AI 执行编码AI 编码工具读取提案和计划一步步实现代码改动与提案文件绑定。人工审查与合并审查时对照提案逐条核对确认没有超出提案范围的改动合并分支。同步回主规范用openspec sync把这次变更中沉淀下来的约束、术语、模式同步到项目级规范里让规范随着项目一起生长。这六个阶段覆盖了一个想法从产生到沉淀为架构约束的全过程。注意一个细节在第 6 步之前changes/里的提案是临时性文档合并之后就可能“过时”而project.md是长期规范会不断吸收每次变更中值得固化的内容。区分清楚这两层后续才不会把规范文件写成一堆历史记录。2.2 三种规范文件的分工逻辑OpenSpec 目录的内部结构大致如下openspec/ ├── project.md # 项目级规范长期稳定 ├── agents/ │ └── coding.agent.md # Agent 规则指导 AI 的工作方式 ├── changes/ │ └── 2025-03-user-refund.md # 变更提案按时间/标题命名 └── specs/ # 同步后生成的全量规范视图其中三种文件的定位完全不同很多刚开始用 OpenSpec 的人会搞混把变更提案写成“流水账”或者把项目规范写成“百科全书”。我用一个表格来对照文件类型生命周期面向对象更新频率核心作用项目规范project.md长期所有开发者与 AI Agent低频merge 时同步记录架构约束、命名、技术选型变更提案changes/短期执行本次变更的 AI Agent高频单个变更期间明确“做什么、不做什么、验收标准”Agent 规则agents/长期每次编码会话中的 AI低频告诉 AI 先看什么、按什么顺序做这个分层非常关键。项目规范如果写得太细AI 每次读它都要消耗大量上下文 token而且高频修改会让规范失去权威性变更提案如果写得太粗AI 在实现时还是会陷入“没图施工”的状态。各管一摊各司其职才算用对了。2.3 Commands 到底是什么AI 工作流的状态管理器很多人以为 OpenSpec Commands 是“生成代码的魔法命令”其实不是。它更像一个状态管理器通过文件系统的规范文件让 AI 在不同会话之间保持同一个“事实版本”。AI 模型本身是无状态的你每次打开新会话它都不记得上次聊过什么。OpenSpec 的解题思路简单但有效AI 不记得文件记得。提案文件、计划文件、规范文件全部存在仓库里AI 每次开工前只需要被引导去读这些文件就能迅速恢复“上下文”。从本质上说OpenSpec Commands 管理的是规范的“状态转换”——create创建一份提案plan把它从想法变成计划sync把临时结论固化为长期规范。这和 git 管理代码版本是同一套思维只是一个管代码一个管规格。所以你在使用 OpenSpec 时心态要从“给 AI 写 prompt”切换成“给项目维护规格库”。命令只是工具真正的核心是那套规范文件。3. Commands 逐条拆解从初始化到提案落地的完整链路3.1 openspec init给仓库建立“游戏规则”在项目根目录执行openspec init执行后会生成上面那个openspec/目录骨架。这一步通常只需要做一次但它是整个体系的地基没有它后续所有命令都无处安放。以我目前使用的 0.x 版本 CLI 为例init的交互过程大致会确认几个信息项目名称、默认语言、是否自动生成 Agent 规则文件。生成完目录结构后第一件事不是急着建提案而是认真编辑openspec/project.md。这里写的是项目长久的“宪法”技术栈、目录分层、命名约定、错误处理策略、数据库设计规范、禁止事项。不用写得太长但每一条都应该是真实约束宁可少而准不要太而全。一个体验是project.md初版内容越克制越好。如果一上来就写一堆“应该”项AI Agent 会在每轮任务里都背着沉重的上下文token 消耗大而且约束之间容易冲突。我的做法是先只写“禁止”项和“硬性技术栈”因为“禁止什么”争议通常更小AI 执行起来也更明确。3.2 openspec create / explore让变更“有据可查”create是最常用的命令。为刚才的退款功能创建提案openspec create user-refund命令会生成一个带日期的提案文件比如openspec/changes/2025-03-user-refund.md模板大致包含这些字段背景为什么有这个需求当前流程的痛点是什么目标这次变更要交付什么用可验收的语句描述非目标明确哪些事情这次不做这是整个模板里最容易被忽略但最有价值的部分影响范围预计涉及哪些模块、哪些文件验收标准怎样算做完包含哪些测试和检查项填提案的时候“非目标”反而是最值钱的部分。AI 编码时最大的风险不是做得太少而是做得太多、越界发挥。把“不做什么、不改哪些文件”写清楚相当于提前给 AI 画了红色禁区。我的经验是非目标里至少写三条比如“不在本次变更中调整数据库表结构”“不重构订单模块的既有接口”“不新增第三方依赖”。explore则是另一个方向的命令当代码已经被改完了、但当初没有写任何规范时用它可以反向提取变更内容。它会扫描当前 git 分支相对主干的所有差异自动生成一份提案草稿。openspec explore这个过程相当于给“已经发生的变更”补一张“事后设计文档”。场景通常是团队里有人或者某个 AI已经改了一堆代码但没留下任何设计说明你接手 review 时一脸懵。explore能把 diff 里的关键变更点抽出来生成草稿再由人工补齐背景和验收标准。需要注意explore之前请把工作区里不相关的改动提交或 stash 掉否则它会把你临时调试产生的console.log、无关格式修改也扫进提案里。3.3 openspec plan生成 AI 可执行的实现计划提案有了下一步是生成实现计划。这是 OpenSpec 里我觉得最实际的一个命令openspec plan 2025-03-user-refund它会读取提案文件和项目规范输出一份分步实现计划。这个计划不是给人看的是给 AI Agent 执行的“施工任务书”所以它通常包含明确的步骤顺序、涉及文件路径、每步的完成标志。理想情况下计划长这样在payment/refund/下新增RefundRequestDTO字段与原型对齐修改PaymentService增加createRefund(request)复用已有支付回调逻辑在web/controller/PaymentController中暴露POST /payment/refund接口为退款拒绝分支补充测试用例覆盖超时与余额不足两种场景更新docs/api/payment.md接口文档注意第 5 步计划里一定要包含文档和测试否则 AI 默认只会写主流程代码。把“完成标志”写清楚AI 执行到哪一步可以自查有没有完成避免了它在中途“觉得自己做完了”就停下来。生成的计划文件同样存放在变更提案目录下之后把它连同提案一起作为上下文喂给 AI 编码工具。很多 AI 编程应用允许引用项目文件或指定 “Agent 指令”你可以把这些文件和指令关联起来让它每次开工前自动加载。一个实操提示plan 不需要一次生成完美。AI 在实现过程中大概率会发现计划里没考虑到的边界情况这时允许它修正计划但修正动作要体现在计划文件里不要悄悄改。这样最后 review 时可以清晰地看到“原计划是什么样的实际执行中为什么调整”。3.4 openspec update / validate / sync让规范和代码一起生长update用来修改已存在的提案。提案在评审阶段经常被推翻、补充openspec update 提案名会打开编辑器让你修改对应文件。这个命令的隐性价值在于它让“设计演进”这件事有了痕迹而不是在需求讨论群里来回发修改意见最终文档和实际实现完全对不上。validate是格式校验命令。OpenSpec 的提案文件是有 schema 的结构化 Markdown如果某个字段缺失或者标题层级不对AI Agent 在解析时可能会失败。openspec validate会检查所有提案和规范文件是否符合规范openspec validate我强烈建议把这个命令加入 CI 流程每个 Pull Request 都跑一遍校验不合格直接阻止合并。这样一来哪怕团队成员没有规范意识CI 也会逼着他们遵守——机器检查永远比人肉提醒可靠。sync则是把已合并的变更提案中的经验沉淀回项目规范。具体作用是把本次变更中讨论出的术语、约束、模式提取出来合并进project.md。比如这次退款变更之后团队统一了“所有支付金额字段一律用最小单位整数”的约定那就可以通过sync把这条约束固化到项目规范里之后所有 AI 会话都能读到。openspec sync 2025-03-user-refund这一步最容易被跳过但它是“规范随着项目生长”的核心。如果不做 sync长期积累的架构性约定就散落在各个变更提案里失去了长期规范的意义。我通常会在功能分支合并进主干后立即执行一次 sync并审查合并后的project.mddiff——这相当于给团队做一次自动化的经验归档。4. 接入现有 AI 编码工作流的实操路径4.1 分支策略与提案状态的映射OpenSpec 要跑顺分支策略必须跟提案一一对应。我的建议是每个变更提案对应一个分支命名直接用提案名change/2025-03-user-refund为什么要严格一一对应因为explore扫描的是分支 diff如果同一个分支里塞了三四个提案扫描结果会混在一起AI 生成的计划也会边界模糊。反过来一个提案跨多个分支则会让审查和 sync 变得困难。配合使用时提案状态与分支状态可以建立一个映射关系提案状态Git 分支状态对应操作draft尚未创建或新建分支openspec createin-review分支已推远程等待评审openspec plan 人工评审accepted评审通过开始编码AI Agent 按计划实现implemented编码完成等待合并openspec validate 测试merged分支已合并主干openspec sync这张映射表最好直接写进团队文档甚至写进agents/规则文件里让 AI Agent 在每个环节都知道自己处于哪个状态、下一步该做什么。4.2 与可视化工作流编排工具的联动如果你团队已经在用 Dify、Coze、扣子这类可视化工作流工具编排“需求收集—文档生成—AI 编码”的流程OpenSpec 完全可以作为其中一个环节接入。举个例子你可以在 Coze 或 Dify 里搭一个“提案生成助手”输入一段产品需求描述工作流调用 LLM 按 OpenSpec 提案模板生成结构化 Markdown再调用文件节点写入openspec/changes/目录。后续接上openspec plan再到 AI 编码工具里执行。这样整个链路就变成了“需求文本 → 结构化提案 → 实现计划 → 代码变更 → 校验合并”每一步都有文件留痕。我见过有人把“Markdown 转 Word 工作流”也接进去把已批准的提案转成正式设计文档供非技术人员审阅。这是个不错的拓展思路因为提案模板本身就是结构化 Markdown转格式成本很低。但这里要提醒一句可视化编排很容易把流程做得很长很炫但核心价值仍然是提案内容本身。如果你的 LLM 生成的提案文件连“非目标”都写不清楚下游花再多力气也是空中楼阁。工作流要服务于规范而不是反过来被工作流绑架。4.3 三个我实测中踩过的坑坑一规范文件越写越长AI 上下文被吃光。最初我用 OpenSpec 时总想把所有背景知识、业务细节都写进提案结果 AI 编码工具每次开工读上下文就占掉大半窗口真正写代码时注意力反而下降。后来我改成提案里只写“结论、边界、验收标准”背景细节放到外部文档或用链接引用。记住OpenSpec 文件是给 AI 的“施工图”不是“项目百科”。坑二中英文混用导致解析不稳定。AI Agent 读规范文件时字段名和标识符必须稳定。如果你在提案里写“目标支持用户退款”AI 能看懂但如果把它写成“goal让用户 refund 时候更丝滑”一些结构化解析流程会出问题。我的习惯是字段名、代码标识符、路径、命令统一用英文描述性内容可以保留中文但长句尽量拆短避免歧义。坑三sync 没进流程规范文件变成“死文档”。第一个月我经常忘记 sync等想起来时提案里的约定已经散落在十几个分支里。后来我把它固化进流程功能分支合并后第一件事就是openspec syncopenspec validate审核project.md的 diff。如果改动量太大说明这次变更的影响范围比预期大需要回到提案阶段重新审视“非目标”是否写得太窄。这个动作坚持一段时间后项目规范会越来越准确AI 被“误导”的概率会明显下降。5. 团队落地 OpenSpec 的评估与推进建议5.1 什么团队和项目适合它不是所有项目都值得上 OpenSpec。我判断的标准很简单三个条件只要命中两个就可以认真尝试代码库生命周期会超过三个月。一次性脚本、原型验证项目用不上这套体系。AI 编码工具参与度很高。如果大部分代码还是人写的OpenSpec 的收益会不明显AI 参与度越高规范约束的价值越大。多人协作或一人多账号多工具。需要让不同会话、不同 Agent 保持同一个架构认知。最适合的场景是 3-10 人的小团队做一个长期维护的业务系统且大家已经在用 AI 编码助手。这种团队里人的沟通成本低于大厂但 AI 引入的随机性却真实存在OpenSpec 这种轻量级规范工具刚好能补上缺口。5.2 推进顺序先个人、再试点、别全面铺开如果你打算在团队里推 OpenSpec我的建议是别搞“突然袭击”。第一步自己先在一个中等规模的项目上跑通完整链路init→create→plan→ 编码 →validate→sync。只有自己把坑踩一遍你才知道哪些地方同事会卡住。第二步拉一个重点项目试点只挑一个中等规模的变更走完整流程。试点时目标不是“所有变更都用 OpenSpec”而是“让团队体验一次‘带着图纸施工’和‘自由发挥’的差别”。一次成功体验胜过十次制度宣讲。第三步根据试点反馈简化流程。如果团队觉得模板字段太多就砍掉不常用的字段如果觉得 validate 卡得烦就只在合并主干时校验。工具是为人服务的别让流程变成新的负担。5.3 与现有工具链的配合建议OpenSpec 本身不替代任何编码工具它是胶水层把 AI 编码助手、Git 平台、CI/CD 串成一条规范链。在实际配置中我会把openspec validate加进 CI保证每个拉取请求都经过格式校验我会在 AI 编码工具的规则文件里写一条“开工前先读 openspec/project.md 和当前变更提案”让 Agent 自动加载规范我还会在代码 review 模板里加上一栏“本次改动是否超出提案范围”倒逼提案先行的习惯。最后分享一个小技巧在 Agent 规则里加一条“任何代码注释、提交说明、Pull Request 描述都必须带上提案 ID”。一开始你会觉得啰嗦但坚持两周后回头查历史你会发现每个改动都能追溯到最初的设计决策——这种“可追溯感”在维护期价值极大。排查线上问题时我能根据提交信息里的提案 ID 直接翻开当时的“非目标”那栏看到当初明确不做什么的理由省掉了大量考古式排查。对我自己来说OpenSpec Commands 最有价值的不是某条命令而是它把“编码前先想清楚”这件事变成了可执行、可检查、可沉淀的流程。AI 编码的大方向已经不可逆了谁能把规范框架搭好谁就能在效率和秩序之间找到平衡。