这两年只要你在折腾 AI 编程八成听过这几个关键词OpenSpec、Superpowers、规格驱动。尤其当你用 Claude Code、Codex 这类 agent 工具写过几个像样的项目之后大概率会遇到同一个坎小需求 AI 一把梭很爽一旦项目变复杂、功能变多AI 就开始精神分裂改 A 坏 B前面定好的设计后面全忘甚至自信满满地写出和需求完全相反的逻辑。问题不在模型不够聪明而是你缺少一套能管住 AI 的流程。OpenSpec 解决的是规格问题——强制 AI 在动手前把需求、现状、目标状态写成可验证的文档Superpowers 解决的是动作问题——把头脑风暴、写计划、执行计划这套工程流程变成 AI 能直接调用的技能。两个工具配合起来就是给 AI 编程装上规格驱动的完整打法。这篇我把自己实际跑通全栈项目的组合用法、目录结构、提示词模板、踩坑记录全整理出来适合正在用 agent 编程、又对交付稳定性不满意的人。1. 为什么 AI 编程总在半路翻车——失控根源先搞清楚1.1 AI 不是不聪明而是记性差还缺框架先说个扎心的结论现在的 coding agent 模型能力已经够强真正拖后腿的是工作方式。你让 Claude 单独实现一个函数它写得又快又好你让它从头到尾做一个包含数据库设计、API 层、前端页面、权限控制的全栈项目前半小时还挺正常一小时后就开始前后矛盾。根源有两条。第一条是上下文窗口的物理限制。Agent 每轮对话都要把历史记录塞进上下文项目一大几百个文件的概要、几十轮修改记录很快就会把窗口塞满。窗口一满早期的设计决策、约束条件就被挤出去了AI 只能靠猜。第二条是缺少一个外部的持久化记忆结构。人类开发有需求文档、有架构图、有代码评审记录AI 编程如果只靠对话流那一切都像写在沙子上潮水一冲就没了。我做过的项目里有个特别典型的案例让 AI 做一个包含用户注册、商品列表、购物车、订单结算的小商城。第一轮聊需求AI 信誓旦旦地说会用 JWT 做认证写到第三个模块时它突然改用 session理由是这样更简单。你问它为什么改它说根据我们之前讨论的。这就是典型的失忆——前面的决定根本没被记录或者说记录被上下文冲掉了。1.2 规格驱动的本质把需求-设计-实现重新拆开传统软件工程早就吃过这个亏。上世纪瀑布模型时代大家觉得先写完整需求文档再开发太慢、太僵化后来敏捷流行大家又觉得能跑的代码胜过完备的文档。但请注意敏捷从来不是说不要文档而是说要刚好够用的文档。AI 编程时代这个道理被放大了十倍。AI 的优势是执行速度极快、代码生成能力强弱项恰恰是全局规划、长程记忆、优先级判断。你让 AI 边想边写它就容易陷入局部最优——每个文件单独看都没问题合在一起就是一团乱麻。规格驱动spec-driven的核心就是强行把想清楚和写出来分成两个阶段先用人类可读、AI 可执行的规格文档把所有决策固定下来再让 AI 按规格实现。这里有个关键点规格不只是给人看的更是给 AI 看的。传统需求文档写系统要支持用户登录AI 看完还是不知道怎么做但如果你写成当前系统没有任何认证机制期望状态是用户可以通过邮箱 密码注册并登录登录后服务端签发 JWT前端将其存储在 HttpOnly Cookie 中所有 /api/private 下的请求必须携带有效 token那 AI 就不用设计了只需要翻译成代码。设计的风险由人脑承担实现的工作交给 AI这分工才是合理的。2. OpenSpec 和 Superpowers 分别是什么——两个工具的分工逻辑2.1 OpenSpec给 AI 编程加一层可变档案OpenSpec 是一个开源工具官方定位是spec-driven development for AI agents。它做的事情可以理解成在项目里建立一个 specs/ 目录把所有关于系统的规格描述、变更提案、验收标准都放进去并且用一套命令让 AI 能创建、更新、验证这些规格。它的核心概念叫 Change Proposal变更提案。每次你要加功能、改逻辑、重构模块不是直接让 AI 改代码而是先创建一份 proposal里面必须写清楚三件事Current State当前状态、Desired State期望状态、Implementation Plan实现计划。Current State 描述现状Desired State 描述改完之后的系统应该是什么样Implementation Plan 列出改造步骤。写完这三段AI 才被允许动代码。我特别喜欢它的地方在于OpenSpec 会把规格变成可回归的东西。每份 proposal 都对应一个 spec.md 文件里面有明确的功能要求和验收清单。项目后续迭代时AI 可以随时打开这份文件对照检查自己有没有把旧功能改坏。这相当于给 AI 编程加了个版本管理——不是管代码是管意图。而且 OpenSpec 有配套的 prompts放在 agents/ 目录下专门给 AI 用的。你用 Claude Code 时可以让它读取这些 promptAI 就知道哦这个项目是规格驱动的我改代码之前要先写变更提案。这个细节很重要——工具再强AI 不知道规则等于白搭。2.2 Superpowers把工程方法论变成 AI 的职业技能Superpowers 是 Jesse Vincent很多人叫它 obra做的一套 Claude Code skills。它的思路和 OpenSpec 不一样OpenSpec 管的是规格Superpowers 管的是流程——具体说是把软件工程里成熟的步骤拆解成 AI 可以一步步执行的小技能。Superpowers 最核心的三个技能是brainstorming头脑风暴、writing-plans写计划、executing-plans执行计划。听着像项目管理词汇其实每个都是一套严格的提示词剧本。以 brainstorming 为例它会让 AI 先问你一系列问题澄清需求边界、用户场景、非目标、风险点全部聊完才会进入下一步。这解决了一个大痛点很多人让 AI 写代码直接说帮我做一个博客系统AI 就闷头开写。Superpowers 会强迫 AI 先访谈你把模糊的需求理清再往下走。这也符合先规格、后实现的逻辑。writing-plans 更狠它会让 AI 把整个任务拆成一个一个互相关联的 plan 文件每个文件有目标、有步骤、有验证方法并且会主动把任务规模控制在一次只做一件事。执行的时候executing-plans 会让 AI 严格按顺序执行每完成一步就检查一次状态不会跳步也不会自己发挥加功能。2.3 组合的核心逻辑一个管存量一个管增量我摸索下来这两个工具是互补关系不是竞争关系。OpenSpec 更偏项目档案——它维护的是整个系统当前长什么样、要变成什么样、为什么这么变Superpowers 更偏工作流引擎——它维护的是 AI 在开发时按什么步骤走、用什么节奏推进。实际组合中有一个技巧你可以把 OpenSpec 作为 Superpowers 的外部命令集成进去。比如在 writing-plans 阶段让 AI 先调用 openspec 创建变更提案再把提案里的实现计划拆成 Superpowers 的 plan 文件。这样OpenSpec 的档案和 Superpowers 的动作就闭环了需求变更先被记录到规格库再被拆解成可执行的计划最后由 AI 按计划实现并回到规格库验证。简单说OpenSpec 管这个项目应该是什么样Superpowers 管怎么一步步把它做成这样。两个都装上才是完整打法。3. 组合落地我跑通全栈项目的完整实操流程3.1 环境准备Claude Code Superpowers OpenSpec 三件套先说环境。我主力用的是 Claude Code所以下面的命令以它为准。你如果用的是 Codex、OpenCode 这类支持 skills 的 agent 工具思路完全一样只是安装命令有差异。第一步安装 Claude Code。这个官方文档很清晰装完在项目目录下运行 claude 就能进入交互界面。第二步安装 Superpowers。在项目里建一个 .claude/skills 目录把 Superpowers 的仓库 clone 进来mkdir -p .claude/skills git clone https://github.com/obra/superpowers.git .claude/skills/superpowers装完检查一下目录结构应该能看到 .claude/skills/superpowers/skills/ 下面有一堆子技能比如 brainstorming、writing-plans、executing-plans。第三步安装 OpenSpec。它是以命令行工具的形式工作的npm install -g openspec/cli然后在项目根目录初始化openspec init初始化之后项目里会出现 specs/ 和 proposals/ 两个目录以及 agents/prompts/ 下面的一些 markdown 提示词文件。这两个目录就是后面所有规格工作的根据地。3.2 第一步用 brainstorming 把模糊需求聊清楚很多人装完工具就直接让 AI 写代码这是最大的浪费。我现在的习惯是任何新需求进来第一件事是让 AI 进入 brainstorming 模式。实际操作时我在 Claude Code 里输入类似这样的提示词请使用 Superpowers 的 brainstorming 技能和我一起澄清下面这个需求的细节 做一个团队任务管理工具支持成员管理、任务分配、进度跟踪。 在理清所有关键问题之前不要写任何代码。然后 AI 就会进入提问模式。它可能会问用户角色有哪些任务的状态流转是什么成员权限怎么划分需不需要通知功能移动端适配吗这个阶段看起来浪费时间其实是整个流程里性价比最高的环节。需求每清晰一分后面返工的概率就降十分。有个细节我提醒一下brainstorming 过程中AI 会根据你的回答生成一份需求简报文档存到项目的 plans 目录或者其他指定位置。这份简报别删它是后面写 OpenSpec 提案的素材。3.3 第二步用 OpenSpec 写 Change Proposal需求聊清楚之后进入规格阶段。这一步的工作是创建一个 Change Proposal把需求翻译成当前状态 期望状态 实现计划的格式。在命令行里执行openspec create proposal命令会交互式问你提案的标题、描述然后生成一个类似 proposals/2025-05-01-team-task-management/ 的目录里面有一个 proposal.md 文件。打开这个文件把 brainstorming 的结果填进去。以任务管理工具为例一份合格的 proposal 大概长这样当前状态系统没有任何任务管理能力只有基础的用户注册与登录功能。期望状态系统支持创建项目项目下有任务列表任务有关联负责人、截止日期、状态字段待处理/进行中/已完成项目管理员可以增删成员并分配任务。实现计划设计任务与项目的数据模型新增 projects、tasks、project_members 三张表实现项目 CRUD API加权限校验只有项目成员可访问实现任务 CRUD API支持按状态筛选与负责人筛选前端新增项目看板页面任务卡片支持拖拽更新状态补充自动化测试覆盖权限校验和任务状态流转。写完 proposal运行 openspec validate 校验格式再把提案提案通过状态更新一下。这时候 AI 的设计工作就完成了后续它只需要照单执行。我遇到过很多次写完这份提案之后AI 写代码的准确率明显上了一个台阶因为设计和实现混在一起时它容易偷懒一旦设计被明文固定它的角色就从决策者降级成了执行者反而更可靠。3.4 第三步用 Superpowers 的 writing-plans 拆解执行计划提案通过后不要急着让 AI 写代码。下一步是把提案里的实现计划进一步拆成 Superpowers 的 plan 文件。在 Claude Code 里输入请读取 proposals/2025-05-01-team-task-management/proposal.md然后使用 writing-plans 技能基于提案中的实现计划创建详细的执行计划。每个计划文件要包含目标、前置条件、具体步骤、验收方法。Superpowers 会生成一个 plans/ 目录下面按顺序排列几个 markdown 文件。拆分的粒度很关键。按照 Superpowers 的默认策略一个 plan 文件应该只做一件事。比如上面的实现计划拆成了五个 plan01-database-schema.md设计数据模型并生成迁移文件02-project-api.md实现项目 CRUD 与权限校验03-task-api.md实现任务 CRUD 与筛选逻辑04-frontend-board.md前端页面与交互05-tests-and-validation.md补测试并做全链路验证。每个 plan 文件里Superpowers 会写清楚当前状态目标状态执行步骤验证方式还会要求 AI 在执行时一次只做这个文件的事不要提前碰后面的文件。这正好和 OpenSpec 的提案形成呼应规格库负责回答做什么计划文件负责回答按什么顺序做。3.5 第四步executing-plans 执行与 OpenSpec 验收闭环计划写完了最后一步是执行。在 Claude Code 里输入请使用 executing-plans 技能按顺序执行 plans/ 目录下的所有计划文件。每个计划完成后对照计划文件中的验收标准做自检然后更新执行状态。全部完成后再对照 OpenSpec 提案的 Desired State 逐条验证。执行过程中有个细节值得注意Superpowers 要求 AI 每完成一个 plan就在文件里记录实际执行结果和偏差情况。这相当于过程文档——以后出了问题你可以追溯是哪个环节偏离了计划。全部执行完之后我还会手动做一轮 OpenSpec 验收。做法很简单让 AI 打开对应的 spec.md 或 proposal.md把 Desired State 里的每一条期望状态当成验收清单逐条检查实现。这一招治AI 自我感觉良好特别有效。比如提案里写任务列表支持按负责人筛选AI 可能只实现了按状态筛选它自己没意识到但你把 Desired State 贴在它面前它就能对照查漏。4. 关键细节这样写规格才不会被 AI 带偏4.1 规格写行为和约束不要写实现方案这是我最想强调的一点。刚用 OpenSpec 时我犯过一个低级错误在 Desired State 里写使用 Redis 缓存用户数据。结果 AI 真的去引入 Redis哪怕这只是个日活几百的小工具徒增运维成本。规格的正确写法是描述行为和约束而不是替 AI 决定技术选型。比如需要缓存你应该写热门任务列表的读取响应时间应低于 200ms且在高并发下不崩溃至于用 Redis 还是内存缓存还是数据库索引那是 AI 在实现阶段该权衡的事。有个简单的判断标准如果你在规格里写的内容是怎么办删掉如果写的是是什么、要什么样的行为、必须满足什么约束留着。规格越贴近验收标准AI 发挥和跑偏的空间就越小。4.2 一个 Change Proposal 只做一件事OpenSpec 的提案机制天然鼓励小步提交但很多人不习惯总想在一个提案里塞三四个功能。这在 AI 编程场景下是致命的——提案一大AI 的上下文里要维持的信息就多实现到后面前面的约束早忘了。我的经验是如果一个功能的变更涉及多个数据模型、多个模块的大改要么把它拆成多个 proposal要么在 proposal 里分成多个阶段。判断标准很简单想象你要给这个提案写验收清单如果你发现清单超过十条而且条目之间没有强关联就应该拆分。拆分之后还有个好处出 bug 时排查范围小。曾经有一次我同时改了用户认证和支付逻辑结果订单接口报错AI 花了十几轮才定位到是认证中间件改动引起的。如果当时拆成两个提案这个问题一眼就能看到。4.3 上下文管理的三个实用技巧规格驱动流程本身能缓解上下文压力但还不够。我在实践中还沉淀了三个小技巧技巧一历史文档勤归档。每一轮开发完成把已经完成的提案移动到 specs/ 目录并标记为已实现。AI 下次读取的时候只需要看 specs/ 目录下的索引不用把整个 proposals/ 历史都塞进上下文。技巧二关键约定放 README。把项目里最重要的规格约束、技术决策写进 README.md 的最前面。Claude Code 启动时默认会读 README这样 AI 第一眼就能看到本项目是规格驱动开发改代码前先看 specs/ 目录比任何提示词都管用。技巧三用文件状态代替长对话。执行计划时不要依赖对话里的记得我们之前说过而是让 AI 把每一步的状态写回 plan 文件。这样就算中间断了对话、甚至换了一个新会话AI 也能根据文件状态接续执行。我跑全栈项目时经常一个会话跨好几天全靠这个技巧保证连续性。5. 常见问题与实战排查5.1 AI 不按规格执行自己自由发挥怎么办这是我最常被问到的问题。症状是你明明在提案里写清了期望状态AI 实现时还是加了多余的功能或者改动了不该改的模块。我的排查思路分两步。第一步检查 AI 有没有真正读到规格文件。很多时候不是它故意不遵守而是它启动时没有加载相关文件根本不知道有规格存在。解决方法是把 OpenSpec 和 Superpowers 的提示词放进 Claude Code 的 CLAUDE.md 里让 AI 每次启动都先读规则。第二步检查规格本身是否可验证。如果 Desired State 写得太抽象比如系统性能更好AI 无从判断自己是否满足自然就按自己的想法来了。改法是把描述改成可测试的行为比如在 1000 个任务的数据量下看板页面的首次加载时间不超过 1 秒。有明确验收标准的规格AI 才不敢乱来。5.2 规格和代码不同步文档成了摆设这个问题在新人用规格驱动时特别常见。提案写归写后面 AI 改代码时直接改了实现但没人回来更新规格。几轮迭代之后specs/ 目录里的内容和真实系统完全对不上规格文件反而成了误导。我的习惯是把更新规格也纳入执行计划。在 writing-plans 阶段明确要求 AI 在完成代码实现后diff 一遍提案里的 Desired State把已实现、未实现、实现有偏差的部分都标出来。这个动作不花多少时间但能保证规格库始终反映真实系统。另外每次用 OpenSpec 创建新提案时先让 AI 读一遍 specs/ 目录下相关的旧规格避免新提案和旧规格冲突。5.3 流程太繁琐agent 干到一半卡住或超时规格驱动流程确实比直接让 AI 写代码多好几个步骤刚上手时会觉得慢。实际跑下来你会发现前期的慢换来的是后期少返工。如果 agent 在执行到一半时上下文耗尽或者卡住我有两个处理办法。第一个办法是从 plan 文件恢复。因为 Superpowers 要求每步都回写状态所以你只要让新会话继续执行对应编号的 plan 文件即可它知道哪些步骤做完了、哪些没做。第二个办法是手动缩小执行范围。卡住通常是因为一个 plan 文件里塞了太多事或者 AI 在某个环节过度探索。我会在提示词里加限制条件比如只实现 01-database-schema.md不要提前改动 API 层代码。把范围缩到最小AI 反而更容易顺畅完成。5.4 几个常见问题的速查表最近一些朋友试用后问我各种问题我把高频的几个整理成了速查表问题现象可能原因处理办法AI 没按规格实现启动时没读规格文件把规则写入 CLAUDE.md启动时自动加载规格文档和实际代码不一致没把更新规格纳入执行流程每个 plan 执行完强制 diff 规格内容执行到一半上下文爆掉计划粒度太粗单文件内容过多拆细 plan 文件用状态恢复新会话提案验收后仍有漏功能Desired State 写得太抽象改成可测试、可量化的行为描述AI 频繁自由发挥加功能规格缺少约束边界增加非目标清单明确不做什么小项目也走全套流程觉得重流程没有按场景适配MVP 阶段只用 OpenSpec 提案 人工验收写在最后的一些实在话这套组合打法我用了差不多三个月最大的感受不是AI 写出的代码变强了而是我终于能搞清楚 AI 在做什么了。规格文件就像开发过程的仪表盘它让你在任何一个节点都能回答三个问题系统现在是什么状态要变成什么状态距离目标还差几步光这三点就比黑箱式地信任 AI 要踏实得多。如果你正准备上手我的建议是别贪多。第一次用只装 OpenSpec把一个需求跑通第二次加 Superpowers 的 brainstorming 和 writing-plans熟悉之后再把 executing-plans 接进闭环。一步到位的结果大概率是你被流程搞烦然后弃用。工具只是帮你建立纪律的真正管用的是你愿意在 AI 动手前多花十分钟把事情想清楚——这个习惯放在任何时代都不亏。