规格驱动AI编程实战：OpenSpec+Superpowers打造工程化流水线

自从我开始认真用 AI 编程写真实项目而不是停留在“帮我写个冒泡排序”的玩具阶段一个非常现实的问题就摆在了面前AI 生成代码越来越强但它太容易“断片”了。上一轮聊得好好的架构设计等它开始动手改文件的时候早就忘得一干二净。对话一长它就开始自由发挥经常把核心逻辑改得面目全非。我一度以为是模型不够聪明后来才发现问题出在我的工作流程上——我一直在用“聊天”的方式指挥 AI而不是用“规格”驱动 AI。直到我把 OpenSpec 和 Superpowers 集成进 Claude Code 的工作流之后整个局面才彻底改观。这两个工具解决的是完全不同层次的问题OpenSpec 负责把“需求”变成“结构化规格”Superpowers 负责把“规格”变成“可执行的施工步骤”。合在一起它俩形成了一条从需求到交付的工程化流水线。这篇东西我不打算写成工具文档的翻译稿而是想结合我这段时间的实战经验聊聊这套组合拳到底是怎么打出来的、每一步背后的设计逻辑是什么以及你会踩到哪些我替你踩过的坑。不管你是刚接触 Cursor、Codex、OpenCode 这类 AI 编程工具的入门者还是已经在用但总觉得“AI 写的东西不靠谱”的进阶用户这篇文章应该都能给你一些新的思路。1. 整体设计思路为什么「规格驱动」才是 AI 编程的正解先说一个很多 AI 编程新手最容易犯的错误把 AI 当成一个记忆力超群的结对程序员。实际上哪怕上下文窗口再大AI 在长对话中的注意力衰减和“立场漂移”都是不可避免的。你会发现它在第 10 轮还在坚持你最初的方案第 25 轮就开始“灵活变通”更可怕的是当它同时操作多个文件时经常会出现某个文件里还留着旧逻辑、另一个文件里已经改成新逻辑的情况。这不是模型不够聪明而是人的管理方式没有跟上。1.1 传统提示词模式的核心缺陷传统的“提示词编程”本质上是把所有信息都塞进对话上下文里。你需要在聊天框里反复粘贴文件内容、提醒 AI 之前定下的规则、纠正它跑偏的思路。这些操作消耗的 token 是小事真正致命的是上下文不可追溯——AI 在某一轮生成的决策和推理在下一轮就可能被新的信息覆盖。你问它“你之前为什么这么设计”它能给出一个听起来合理但完全不是当初理由的解释。这就是我常说的“AI 式失忆”。我早期用 Cursor 做一个小型全栈项目时就吃过这个亏。当时我在对话框里跟 AI 反复确认了数据库表结构它自己也答应得很好结果分三次生成代码之后第一次生成的 model 和第三次生成的 migration 里字段名全对不上。我当时第一反应是“AI 不行”后来复盘发现问题就出在没有一个持久化的规格文件来锁定这些决定。1.2 规格文件就是 AI 的「最小记忆单元」OpenSpec 解决的就是这个问题。它把每一次需求变更拆解成一份独立的 specification固化在项目仓库的特定目录里。AI 在动手写代码之前先读这些规格文件再按规格里写明的方案去改代码。规格文件不是设计文档那么简单它更像是可执行的需求契约里面不仅写“要做什么”还写“为什么做”“怎么做”“怎么验证”。这样一来即使对话上下文清空了AI 只要还能读到 spec 目录它就能无缝接续工作。这相当于给 AI 装上了一个外部硬盘不再依赖“内存”。换句话说规格文件就是 AI 编程的最小记忆单元——一次决策、一份任务、一个验收标准。把记忆从人的脑子里、对话历史中转移到文件系统里这件事本身就是 AI 编程走向工程化的分水岭。1.3 Superpowers 解决的是「怎么施工」的最后一公里但有了规格还不够。AI 编程的另一个痛点是算法模型本身没有“先计划后行动”的自控力。你让它“实现这个功能”它会跳过设计直接写代码你让它“写测试”它会挑简单的写你让它“重构”它可能顺手把别的功能也改了。这些行为模式不是靠改提示词能立竿见影的而是需要一个行为规范级的约束层。Superpowers 扮演的正是这个角色。它本质上是一个可复用的技能库通过向 AI 注入一套结构化的“技能定义”让 AI 在执行任务时按照预设的步骤行事比如“先分析现有代码→再写测试→再实现功能→再重构”。听起来像什么像敏捷开发里的纪律。只不过这套纪律以前靠人盯着现在靠工具注入。所以在我的工作流里OpenSpec 和 Superpowers 是天然的互补关系一个管“做什么”一个管“怎么做”。两者配合起来AI 才真正像一支有章法的施工队而不是一个灵感忽高忽低的自由画师。2. OpenSpec 实操拆解用「提案 → 任务 → 实现」锁定每一次变更OpenSpec 说起来并不复杂核心就是一套约定优于配置的目录结构和文件模板。你可以在任何项目里初始化它它会创建一个openspec/目录里面存放所有规格文档。这套设计的一个关键优势是不依赖特定 AI 工具——你用手写编辑也能用跟 Cursor、Claude Code、Codex 等都能配合。2.1 初始化与提案Proposal流程OpenSpec 的核心单元叫作“变更提案”Change Proposal每一个提案对应一次完整的功能变更或修复。初始化时它会创建一个标准结构大致如下openspec/ ├── project.md ├── standards/ │ └── ... # 项目级强制规范AI 每次都要读 ├── specs/ │ └── 2025-06-XX-slug/ │ ├── proposal.md # 需求背景、目标、非目标 │ ├── tasks.md # 按顺序拆分的实施任务 │ ├── design.md # 技术方案、接口定义 │ └── test-plans.md # 验收测试计划 └── archive/提案的第一步永远是写proposal.md这个文件的职责是回答“为什么做这件事”。我发现一个特别实用的小技巧让 AI 先只写 proposal不许碰代码。很多人在用 AI 编程时习惯催着它一步到位结果它把设计、实现、测试混在一起出了错都不知道是设计错还是编码错。强制先写提案等于把“思考”和“行动”分离了。提案写完之后你需要人工审一遍。别觉得这一步是多余的——AI 对需求的理解经常在“字面正确”和“实际可行”之间有一条巨大的鸿沟。比如我见过 AI 写了一个提案说要重构支付模块但对“兼容旧订单数据”只字不提。这种问题靠 AI 自查是发现不了的只有人在提案阶段把它拦住才能避免后面返工。2.2 任务拆解与 TDD 的天然映射当提案通过审核下一步是拆解tasks.md。OpenSpec 的任务拆解粒度很有讲究它提倡把工作拆成一个个“可独立验证的、原子化的”子任务并且每个任务都对应明确的验收标准。这种拆法跟测试驱动开发TDD是完美对应的任务类型验收标准示例对应的 TDD 阶段后端模型定义模型字段与设计文档一致迁移可运行红灯写失败测试API 接口实现接口返回结构与 spec 一致绿灯让测试通过前端组件接入数据绑定后 UI 渲染正常绿灯扩展异常处理补充错误场景可被捕获且日志完整重构阶段我通常会让 AI 根据tasks.md的顺序逐个任务执行 TDD 循环。每个任务完成前都必须先更新test-plans.md里的测试计划确保测试代码是有据可依的。这个过程真正把“AI 生成测试”从“装饰品”变成了“验收工具”。2.3 共享存储为什么规格必须写进文件而不是聊天框OpenSpec 有一个设计很聪明的点就是提供“共享存储”能力——把 AI 在工作过程中产生的关键结论、设计决策、注意事项自动归档到openspec/standards/目录中。这解决了一个非常真实的痛点AI 在长任务中会忘记自己之前的决策。比如它刚刚写过“用户头像上传统一走 OSS不存本地”但如果这个结论没有落盘10 分钟后它可能在另一个模块里又开始写本地存储逻辑。共享存储本质上就是一个外部记忆系统它把 AI 的“工作记忆”落盘成“长期记忆”。这种机制的意义不在于存了多少东西而在于每次 AI 开始新任务时能够主动读取这些记忆。所以我会在项目的 CLAUDE.md 或者 skill 配置里强令 AI 每次动工前先扫一眼openspec/standards/。这样哪怕跨会话、跨分支、甚至跨机器AI 的状态都是连续的。3. Superpowers 安装与核心技能给 AI 装上一套工程化「行为准则」如果说 OpenSpec 是一套管理“需求变更”的制度那 Superpowers 就是一套管理“代码施工”的工艺规范。我最早接触它是因为看到有人讨论“让 AI 自动写测试然后重构”的 skill 机制后来才发现它远远不止测试这么简单而是一整套基于文件系统的技能包。3.1 Superpowers 到底是什么简单说Superpowers 是一个技能库你可以把它安装到 Claude Code 或类似工具的能力目录中。安装过程不复杂核心是把技能定义以文件夹形式放到指定目录AI 会在特定任务场景下自动读取这些技能描述并遵循其中的步骤执行。这里要纠正一个常见误解Superpowers 不是“提示词合集”不是那种“你粘贴这段话 AI 就会变聪明”的咒语。它更像一套可解析的工程手册。每个技能文件夹里的SKILL.md定义了触发条件、执行步骤、产出物和注意事项。AI 读取它之后会按照里面的流程执行。这就像给基层员工发了一本 SOP 手册他不需要每次遇到情况都请示你但也不会擅自跑到流程之外。3.2 常用技能解析我实际用下来最有价值的是这三个技能方向Brainstorming头脑风暴在动手前强制 AI 和我进行多轮发散和收敛梳理清楚约束条件、风险和取舍。别小看这一步它把很多“我以为 AI 懂了其实没有”的问题消灭在摇篮里。Writing Plans编写计划在明确方案之后把实施路径拆解成带验证环节的计划。这一步非常像软考里的系统设计但颗粒度比我手工写要细得多。它能明确到“修改哪个文件的哪个函数”。TDD 工作流写测试、跑测试、实现、重构这是我最常用的一组技能。Superpowers 的 TDD skill 不是简单说“要写测试”而是规定了一套循环先确认测试是失败的再写实现使其通过最后做重构。它会在每一步问我是否继续等于强行让 AI 保持“小步快跑”的节奏。3.3 OpenSpec 与 Superpowers 如何配合很多人会困惑这两个工具是不是重复了。我的理解是两者处于不同的抽象层次。OpenSpec 管的是“需求级别的生命周期”它有提案、有审批、有归档是偏项目管理的Superpowers 管的是“任务级别的执行纪律”它告诉 AI 在拿到一个任务后用什么顺序、什么方法来完成实现是偏软件工程的。举个例子OpenSpec 的tasks.md里有一个任务说“实现用户注册接口”Superpowers 的 TDD skill 会指导 AI 去写失败测试、实现接口、重构代码。前者回答“做什么”后者回答“怎么做”。在我实际的 triage 流程里OpenSpec 负责生成任务清单Superpowers 负责确保每个任务都被高质量地执行。两者合体之后AI 编程的产出不确定性和不可控性都会显著下降。4. 三件套实战拆解从一句话需求到完整交付的全流程演示接下来我把这套三件套Claude Code OpenSpec Superpowers在真实项目中的操作流程完整拆开给你看。我以“开发一个带用户登录和信息展示面板的简易全栈应用”为例走一遍流程。这个例子足够直观又能展示规格驱动各个环节的作用。4.1 启动与澄清Brainstorming OpenSpec 初始化第一步我不会直接让 AI“开始干活”而是先启动 Superpowers 的 brainstorming 技能。它会用提问的方式引导我把需求的边界逐步明确。比如它会问“用户登录用什么方式”“信息展示需要支持几个角色”“数据从哪里来”。这些问题看起来很简单但 AI 能主动想到问比人自己遗漏要靠谱得多。需求聊清楚之后再初始化 OpenSpec。运行初始化命令后项目里会生成openspec/目录。这个动作相当于给项目打上“规格驱动”的基座。接下来 AI 会依据 brainstorm 的结论生成一张proposal.md内容包含背景、目标、非目标、风险。我只需要做一件事审阅。4.2 生成 Spec 与任务拆解提案通过后AI 会进入 Writing Plans 阶段。它会基于提案把端到端的功能拆解成一份design.md内容包括技术栈选择、接口定义、数据结构。然后拆tasks.md形成一棵非常细化的任务树- 01-初始化项目骨架 - 01.1 创建后端工程 - 01.2 创建前端工程 - 02-用户注册与登录 - 02.1 实现 JWT 签发 - 02.2 实现注册接口 - 02.3 实现登录接口 - 03-信息展示 - 03.1 后端返回用户信息 - 03.2 前端拉取并渲染这一步的关键在于每个任务都必须带有“可验证标准”。AI 在生成 tasks 的时候我会检查是否有不可验证的任务比如“优化性能”这种没人知道何时算完成的描述必须改成“接口响应时间低于 200ms”这种可量化的标准。4.3 实施环节子代理驱动的并行施工传统方式是让主代理一口气把任务做完但实践多了之后我发现更好的方式是让主代理扮演项目经理每次只领一个子任务交给子代理subagent去执行。这一步里Superpowers 的角色就非常关键了它为子任务注入对应的 skill。比如“实现注册接口”这个任务子代理会自动加载 TDD 技能先写测试再写实现。我最喜欢这个模式的一点是主对话上下文不会持续膨胀。每一次子任务都是一次全新的会话子代理只关心当前任务和它需要读取的规格文件。当它完成任务后会留下更新过的代码和测试报告主代理只需要汇总、继续分配下一个任务。整个流程就像 Scrum 里的迭代每个子任务是独立的 sprint规格文件是 product backlogAI 在点子项时不再犯迷糊。4.4 审查与复盘规格不是写了就完事在所有任务完成后我还会留一道“审查”工序。套用 OpenSpec 的归档机制把已经完成的提案移动进 archive 目录但在此之前我会让 AI 基于测试结果和实现差异生成一份简短的变更说明。这一步我收获很大AI 经常在审查时发现自己实现和设计文档的偏差比如某个接口的参数命名不一致、某个异常处理比设计时多写了一层。这种偏差靠人肉 review 文件差异也能发现但效率极低AI 根据规格自查几秒钟就给你列出来了。审查之后我喜欢把standards/目录再更新一遍。凡是这次开发中暴露出来的规则比如“用户模块的校验统一使用 validation 库”“接口返回格式统一为 code/message/data”都追加进 standards。这样下一次任务开始时AI 不用你重复叮嘱它自己就会读这些标准。规格驱动工作流的价值在这个环节体现得淋漓尽致它在不断自我进化。5. 常见问题与排查技巧实录我把踩过的坑都给你列出来了任何工具链都不是银弹OpenSpec Superpowers 也一样。我在实际使用中踩过不少坑有些是工具本身的机制局限有些是工作流习惯带来的问题。下面按问题频次排序整理一个速查表后面再挑几个典型展开说。问题现象根本原因排查与解决办法AI 跑偏改了很多无关代码任务拆得太粗或子代理没读到规格缩小任务粒度确认子代理工作目录包含 spec测试总是绿但代码有 bug测试只是“为了通过而写”没覆盖关键路径在 test-plans 中强制列出核心业务断言子代理不记得之前的决策决策只存在于主对话中没写进 standards每次有重要决策立刻追加到 standards规格更新了但 AI 还在按旧规格写子代理没有重新读 spec开始新任务时强制执行一次 spec 读取动作OpenSpec 提案阶段太耗时需求太琐碎不适用完整流程小改动直接用 issues不进提案流程5.1 问题一任务拆得够细但子代理还是乱来这个问题的根源往往不在 Superpowers而在任务描述本身。我检查过几次 AI 子代理乱来的日志发现是父代理在转交任务时把任务内容做了“压缩”——它没有把规格里的关键约束原样传递而是自己“理解”了一个简化版。结果子代理拿到的上下文里只有任务名称没有具体验收标准。解决方案是在父代理分配任务前明确要求它引用具体的 spec 文件路径和任务 ID而不是自说自话。说得再直白一点“把原话贴过去不要总结。”5.2 问题二测试质量太差形同虚设AI 写测试有个通病只测成功路径不测异常路径断言只检查“没报错”不检查“结果对不对”。我在 test-plans 里专门加了一节“负面场景”要求 AI 至少写出三条异常路径的测试比如“重复注册”“无效 token”“请求参数缺字段”。这一招立竿见影比任何提示词都管用。因为规格中明确做了要求AI 在执行 TDD 时就会把这些场景纳入实现考虑而不是测试环节硬凑。5.3 问题三OpenSpec 加进了 workflow但团队里其他成员不习惯如果你不是单打独斗而是带团队用这套流程阻力比较大的环节通常是“提案审核”。很多程序员觉得写 proposal 是浪费时间会绕过去直接让 AI 改代码。我的经验是没必要对微小改动也上完整流程。我给团队定的规矩是改动涉及文件超过 3 个或者会影响公共接口的必须走提案其他琐碎修复直接提 issue 就行。这样既保留了规格驱动的严谨又不至于让流程成为负担。5.4 关于国内使用 AI 编程模型的一点补充不少朋友会问这套工作流能否用在非 Claude 或非 OpenAI 的国内模型上。我的实际体会是规格驱动和技能注入的核心思想不绑定具体模型。OpenSpec 本身就是一套文件结构任何能读文件、写文件的模型都能适应Superpowers 的 skill 机制本质上不过是把行为规范写在文件里让模型按文件执行。所以只要你用的编程工具支持自定义技能目录或系统提示词这种方式就能迁移过去。区别只在于不同模型对长文档的理解能力和指令遵循能力效果会有高低但流程本身的优势依然成立。6. 这套组合还能怎么玩进阶扩展思路如果你已经能熟练跑通基本流程可以试试下面这几个方向我觉得潜力都很大。6.1 把历史规格变成团队的「隐式文档」openspec/archive/目录会随项目迭代越积越厚这些东西是绝佳的团队知识库。新同事接手项目时不用再去翻聊天记录直接按时间顺序读 archived proposals就能理解项目的演化脉络。我甚至试过让 AI 基于历史提案自动生成一份项目演进报告效果出乎意料地好。6.2 规格优先的多模型评测同一份规格文件可以同时喂给不同模型实现然后对比它们的代码风格、测试覆盖率和 bug 率。因为这个过程把“输入”完全标准化了输出对比就变得非常有意义。哪怕你平时主力模型是 Claude拿几个候选模型跑一遍同一套规格也能很直观地看出各家水平差距到底在哪。6.3 让规格本身也纳入自动化检查OpenSpec 的目录是纯文本结构完全可以接入 CI。你可以在 CI 里加一个步骤检查每个提案是否包含 proposal、tasks、test-plans 三件套校验 tasks 是否按顺序编号。这样即使有人偷懒没写规格流水线也会拦下来。规格驱动的工程化程度又上了一个台阶。最后再分享一个我个人的心得这套组合真正改变我的不是效率提升多少倍而是我终于敢让 AI 参与大型重构了。以前我总担心 AI 在一顿操作之后破坏掉我精心维护的架构有了规格文件给它划边界、有了测试给它兜底、有了子代理给它隔离风险这种失控感基本消失了。当然工具始终是辅助真正的判断力还得靠自己把握。希望这篇文章能让你在 AI 编程的路上少走一些弯路早点享受到规格驱动带来的踏实感。