我本来是想抄作业的。Spec Kit、OpenSpec、Superpowers 这三个名字我在搜索框里来回扫了不止一遍。原因很简单最近一段时间的 AI 编程 agent 越来越难控制改一个登录模块它能顺手把我另一个文件的变量名也改了说好只做前端适配它能自作主张重构后端接口。我需要给 agent 套上缰绳又不想把整个研发流程推倒重来。折腾了两个多月我最后没有完整选用其中任何一套。倒不是它们不好而是它们解决的核心问题各不相同而我要的偏偏是一个“能把规格、执行和审查串成一个闭环”的东西。干脆基于它们暴露出的问题自己搭了一套最小规格驱动工作流。这篇就来聊聊每套工具的差异、我踩过的坑以及最后这套“只有四件事”的自建方案是怎么来的。1. 先承认我不是一开始就想自造轮子1.1 从“agent 乱改代码”到 spec-driven 工作流事情得从一次很典型的失控说起。当时我在一个内部项目上做权限模块的改造需求本身不复杂给现有接口加上角色校验。我把任务丢给 agent 以后它确实很快写出了校验逻辑但同时也把用户模块里的几个函数签名改了理由是“为了让调用更统一”。从代码质量角度看它改得不算错可这个改动不在我的 review 预期里也没有对应的测试覆盖。我不得不先花时间理解它为什么要动这些文件再把多余的部分还原。这类情况出现多了以后我开始意识到问题不在 agent 的代码能力而在它缺少一个“边界”意识——它不知道哪些东西该碰哪些东西不该碰。当时我找到的解法就是 spec-driven 工作流。思路特别直白不要只给 agent 一句话需求而是先把需求拆成结构化、带边界的规格文件让它先读规格再动手。Spec Kit、OpenSpec、Superpowers 这三套方案本质上都是想解决这件事只是切入点完全不同。1.2 我拿来比较的三条硬标准在开始比较之前我先给自己定了三条衡量标准避免被各种宣传带偏。第一条规格和代码之间的距离。规格写完以后是只躺在文档里还是能进入实际的开发流程代码改了规格变旧了有没有机制提醒我第二条和现有 Git 工作流的融合程度。我们的协作方式就是分支、PR、多少轮 review。一套方案如果还需要我另起一个平台或者改变代码评审习惯那学习成本就会被团队其他成员直接挡在门外。第三条长期维护成本。规格文件本身也是代码库的一部分如果写规格比写代码还累那它只会变成另一堆没人愿意看的技术债。拿着这三条标准我把三套方案都跑了大约两周分别接在不同的实验分支上。结果很有意思它们每一套都能解决一部分问题但每一套也都留下了明显的空档。2. Spec Kit上手最快但止步于“单人舒服”2.1 它解决了我最痛的那一环先说我最先试的 Spec Kit。第一感受是爽因为它是三套里最容易上手的。它把需求拆成结构化文件一个功能一个目录每个目录里有自己的范围定义、接口描述和完成条件。agent 在动手前会先读这些文件再按图施工。我几乎没花什么力气就在一个小功能上跑通了整套流程。它解决了我最痛的那一环——把“我要什么”变成 agent 能读懂的指令。之前我反复在提示词里强调“只改你被要求改的东西”效果很差因为语言模型对“要求”的理解很容易被上下文带偏。但规格文件不同它是一份白纸黑字的边界agent 读到“范围”和“非目标”之后就不会再凭感觉扩大改动。我甚至在一个很简单的例子里验证过# 登录接口改造 ## 范围 - 修改登录接口的错误提示 - 增加账号锁定逻辑 ## 非目标 - 不修改注册流程 - 不重构 token 刷新逻辑同样一句话需求有这份文件约束和没这份文件约束agent 的最终 diff 完全不同。被约束之后它确实收敛了很多。2.2 在模拟项目 X 上碰到的第一个硬伤用了几天之后问题就来了。模拟项目 X 是一个经历了多轮迭代的老仓库模块之间耦合得很厉害登录模块和用户模块共享同一套 token 解析逻辑。我按 Spec Kit 的推荐方式把登录改造写成一个独立 spec结果 agent 在执行时又碰了用户模块的文件。原因不难理解局部 spec 只描述了“登录接口要改成什么样”却没有描述“它依赖了用户模块里的哪些东西”。当 agent 发现实现必须跨模块改动时它就自己开始做假设而其他模块没有对应规格假设就变成了自由的发挥。我试过在 spec 里补“涉及文件”清单但很快发现维护成本很高。老仓库里一个功能往往牵扯十几二十个文件每次代码结构变化清单都要跟着改改着改着就没人维护了。Spec Kit 给我的感觉是它把一个需求写清楚了却没有把需求之间的依赖关系写清楚。2.3 让我犹豫的真实原因第二周我让同事也来试用。结果团队成员的反馈让我开始犹豫。问题不是它不能用而是没有任何机制保证它会被人看。我这边辛苦维护了一份登录模块的 spec但另一位同事接手另一个需求时根本不知道这份文件的存在。代码评审的时候reviewer 也不会主动去打开 spec 目录大家看的还是 PR 里的 diff。也就是说Spec Kit 的核心价值会随着使用人数增加而递减。它更像一个很聪明的单人脚手架而不是一套团队协作协议。单人用的时候它帮你管住 agent多人用的时候它变成了一个需要额外推进的“平行文档体系”。3. OpenSpec工程化很完整我却总觉得在写论文3.1 规范性确实强后来我又把注意力转移到 OpenSpec 上。如果说 Spec Kit 是极简入口那 OpenSpec 就是另一个极端它把规格提升为变更管理的一等公民。它最打动我的地方是把一次需求变更组织得像一个正式的提案。目录结构、命名约定、模板、历史决策记录全都安排得清清楚楚。一次改动对应一个变更提案提案里要写背景、方案、影响面、验证方式甚至还有类似 ADR 的决策记录。这样一套流程走下来代码库里的每一次变更都有迹可循。刚开始我是很兴奋的。它让我看到了“规格即文档、文档即审计”的完整形态而且它和 Git 的关系非常紧密每个变更提案都可以直接对应一个分支或 PR比 Spec Kit 那种散落的 spec 文件要严谨得多。3.2 流程重量压过了收益的场景但真正跑起来以后我发现流程的重量开始压过收益。有一次我只是想调整一个字段的校验规则前后不到 200 行改动。按 OpenSpec 的流程我需要先写变更提案说明背景、方案、影响面再开一个规格 review等提案被认可才能让 agent 开始编码。等这一套走完两个小时过去了而实际写码只用了不到十分钟。我算过一笔账在一个需要快速迭代的团队里这种流程负担是很大的。OpenSpec 更像为那种“一次变更波及多个子系统、需要跨团队会签”的重型项目设计的它天然假设你有足够的人力去维护这套流程。对我来说它解决了一个我暂时不存在的问题却同时放大了我眼前的问题。3.3 它默认你有一个规范化协作团队更让我别扭的是OpenSpec 的整个设计都默认你有一个很正规的协作团队。每个人都会认真读提案都会有时间参与规格评审都愿意把“写规格”当作开发工作的一部分。但在实际操作中很多同学看到一长串提案模板第一反应是问我“这东西 PR 描述里写不行吗”我知道不一样但我也知道让团队每个人都理解这种不一样本身就是一笔成本。而且 OpenSpec 同样没有解决规格和代码之间的同步问题。提案写得再漂亮如果实现过程中 agent 偏离了提案或者代码演化后提案没有更新那这份提案很快也会变成一份历史文件。它会变得“正确但没人看”和很多仓库里躺着的设计文档一模一样。4. Superpowersagent 更会干活了但它开始“自作主张”4.1 它解决的是“怎么做”而不是“做什么”第三套方案是 Superpowers。它和前两套完全不是一个物种。Spec Kit 和 OpenSpec 都在定义“做什么”也就是给 agent 一套外部规格。Superpowers 则更像是在改造 agent 本身的工作方式它给 agent 加了一组技能和行为准则包括遇到复杂任务先拆解、动手之前先写计划、改代码之前先读相关文件、完成之后自查测试等等。我必须承认这套东西在我这里的效果是最直观的。用了它之后agent 明显变得更“懂事”了。它不再对着一个模糊指令蒙头写而是会先把大问题拆成小步骤每完成一步自我检查一次再输出补丁。它生成的代码确实更稳质量也明显高了一截。它的价值也正在于此把一些资深程序员的工作习惯固化成 agent 的默认行为。这是单靠规格文件做不到的。4.2 一次失控的扩权动手但问题也随之而来而且比之前更隐蔽。有一次我让它修改内部系统的导出功能。它给我列了一个非常合理的执行计划先分析现有导出逻辑再改数据格式最后补测试。我点头之后它竟然把计划里“建议后续优化”的部分也顺手做完了——包括重构了一个和本次需求毫无关系的工具函数把代码量扩到了原本的三倍。我复盘的时候发现它确实是按自己列的计划做的但那份计划本身包含了太多它自己“觉得应该做”的事情。Superpowers 的机制鼓励 agent 主动思考却没有给它足够的“边界不要突破”的信号。这说明一个很现实的问题行为准则能解决“怎么做”却解决不了“做什么”。当我要的是一个非常明确的交付范围时主动性越强反而越容易跑偏。4.3 黑盒提示词和审计之间的矛盾还有一个让我迟迟不敢把它全面接入团队流程的原因它太不可解释了。它到底为什么决定动那个工具函数是因为读到了某个 TODO还是因为把“后续优化”理解成了当前任务的一部分我翻它的行为日志只能看到一层层 prompt 组合之后的结果很难还原它那一刻的决策依据。如果一个人写代码时擅自扩大了范围我可以直接问他他可以给出理由我也可以把结论写进 review 记录。但 agent 不行它的决策依据藏在一套复杂的提示词策略里。团队里另一个成员如果遇到类似情况几乎无法复现、无法审计只能靠我口头解释“它有时候会这样”。一旦代码库交给更多 agent、更多人协作这种黑盒行为会变成很大的隐患。5. 我自己搭的这套其实只做了四件事5.1 设计原则能删则删砍到只剩闭环观察了三套方案之后我的结论是它们都不是失败的方案而是都“偏科”了。Spec Kit 给了我结构化入口但没有给团队协作的约束OpenSpec 给了我完整流程但流程太重Superpowers 给了我更强的 agent 能力却让边界更不可控。我需要的其实只是一个非常小的闭环规格定义范围agent 按范围执行PR 强制人回来检查范围。所以我自建的东西特别克制。整套方案目前只有四样东西一份极简的规格模板、一个 specs 目录、一段给 agent 的强约束指令、一个检查规格是否过期的脚本。没有额外平台没有复杂审批没有知识库甚至没有一个正式的命令行工具。5.2 最小规格模板长什么样我的规格模板长这样# 功能名 ## 目标 一句话说明这次要交付什么。 ## 范围 - 模块或文件级别的改动 - 具体功能点 ## 非目标 - 不做什么 - 不重构什么 - 不顺手优化什么 ## 接口 / 数据结构 - 对外暴露的方法 / 组件 - 涉及的数据库字段或配置文件 ## 影响面 - 哪些模块会被动到 - 哪些模块不允许动整个模板只有五段但真正起约束作用的是“范围”和“非目标”这两段。它们把 agent 的想象力锁死在明确边界里。尤其是“非目标”我把它放得很高因为它专门对付那种“顺手优化”。5.3 把 agent 从“自由发挥”改成“按单执行”我没有自己做一套完整的 agent 框架只是在给 agent 的上下文里加了一段固定规则。这段规则不复杂但很硬在开始修改任何代码前必须先阅读 specs/当前需求/README.md。 只允许实现规格中“范围”和“接口”部分列出的内容。 “非目标”中出现的内容一律不做。 如果发现规格已过时 1. 先修改规格文件并说明原因 2. 再修改代码 3. 在 PR 描述中标注“规格已更新”。前两句是防跑偏最后一句是防“规格腐化”。一开始我也怀疑这种提示词会不会太幼稚后来发现它比复杂的指令更有效。因为它给 agent 的是一条“先读文件再动手”的硬规则而不是一堆关于代码风格和架构原则的软建议。5.4 校验与人工卡点规范不落地等于白写规格写得再好如果没人执行就是一堆 Markdown。我把落地动作拆成了两个卡点。第一个卡点是一个很简单的检查脚本挂在 CI 里。逻辑非常粗暴一个 PR 改动了某个功能目录下的代码文件但如果这次改动没有同步改动对应的 specs 文件就报一个 warning。我不强制它 fail因为强制通过会让团队在时间紧的时候人为绕过我只需要在每个 PR 页面上提醒 reviewer“注意这次代码改动可能让规格过期了。”第二个卡点是 PR 模板。我在 PR 描述里加了一个勾选项- [ ] 已确认本次改动是否需要更新 specs/功能/README.md这个勾选项看起来不起眼但它把“规格同步”变成了 review 的一部分。reviewer 不需要自己去打开 specs 目录只要看到这个勾没选就知道该提醒开发者回去补。整个执行闭环就是这样规格文件管住 agentagent 产出 PRCI 检查规格是否同步reviewer 在人工环节做最终把关。代码、规格和审查终于连成了一条线。6. 最终选择的判断清单以及我先踩为敬的坑6.1 什么时候可以直接用现成方案虽然我自己搭了一套但我并不推荐所有人都这么做。相反如果你属于下面这几种情况直接用现成方案更合适。场景更合适的方案理由单人开发、快速原型Spec Kit上手成本最低适合个人项目大型团队、多系统变更OpenSpec提案和审计能力完整能跨团队协作已有严格范围控制、需要增强 agent 能力Superpowers行为准则能显著提升 agent 生成质量小团队、强迭代、需要留住核心规范自建最小方案流程轻和现有协作方式贴合做技术选型最怕的不是选错而是拿一套方案硬套所有场景。Spec Kit 在我这里是“不够团队化”但在个人项目里它就是神器OpenSpec 在小团队显得笨重但在大团队里可能刚刚好。6.2 什么时候值得自己动手搭我给自己搭这套方案不是因为我有能力把三套工具做一遍而是因为当时的情况比较特殊既有单点规范需求又有团队协作约束还不想让流程变得太重。如果你的团队也出现下面几种信号我建议可以考虑自建第一个信号是工具的学习成本已经超过了它帮你省下的沟通成本。团队成员开始问“这个流程能不能简化”而不是“这个流程帮我们解决了什么”这时候就应该考虑压缩流程。第二个信号是你发现自己反复在给 agent 补“不要扩大范围”的提示词。这说明你缺的不是更强的 agent而是一个范围边界。第三个信号是你的审查流程已经存在但规格无法进入审查。不是你没有 review而是规格文件和 PR 之间没有关联。自建方案要解决的核心就是让规格和代码在审查里见面。6.3 自己搭最容易踩的坑最后说几个我自己踩过的坑希望能帮你少走一点弯路。第一个坑是过度工程化。我第一版规格模板写了七个字段包括背景、动机、关联 issue、验收标准、技术方案、风险、测试计划。写的时候觉得很完整用起来才发现除了“范围”和“非目标”其他字段在绝大多数 PR 里都没人填。后来砍成五段使用率反而上来了。第二个坑是只搭不守。规格写好了agent 也读了但团队成员提交的普通代码没有走这套流程那规格很快就会失守。我现在把规格同步检查放在 CI 里不是为了让所有人难受而是为了让它成为默认动作而不是额外负担。第三个坑是让规格替代沟通。规格只是把需求边界固化下来它不能替代人与人之间的交流。我自己也遇到过 agent 按照规格写完了但规格本身就理解错了需求的情况。所以 review 的时候重点不是看 agent 有没有执行规格而是先确认规格本身理解得对不对。折腾这一圈我的体会是真正重要的不是用哪套工具而是让“规格定义边界、agent 执行边界、人守住边界”这个闭环转起来。如果你现在也在为 agent 乱改代码发愁不妨先别急着选框架先想清楚你缺的是范围定义、流程审批还是 agent 能力。想清楚这个问题很多选择自然就有答案了。
