先交代一个背景我用 AI 编程也有两年多了从最早拿 GPT 写点脚本到后来让 Claude、Codex 这类工具直接上手全栈项目。市面上的提示词技巧、Agent 框架、各种 MCP 服务我基本都试过一圈。如果你现在问我过去一年里对 AI 编程产出稳定性提升最大的一件事是什么我的答案不是某个更聪明的模型也不是更长的上下文窗口而是把“规格驱动”这套方法论真正落地到 AI 编程工作流里。最近这段时间我在自己的项目里把 OpenSpec 和 Superpowers 组合到一起配合 Claude Code 使用效果比我预想的要好不少。以前让 AI 做一个功能经常是“第一版能用改着改着就散架”现在基本上可以做到“需求拆清楚、任务列明白、改动可验收”。这篇文章我就把自己这套完整打法拆开讲包括 OpenSpec 和 Superpowers 各自解决什么问题、怎么安装配置、怎么配合提示词用以及我踩过的那些坑。这篇文章适合谁如果你已经用 Claude Code、Codex、OpenCode 这类 AI 编程工具写过不少代码但总感觉结果不稳定或者项目一复杂 AI 就开始乱改文件、丢失上下文那你很值得看下去。纯新手也能看不过建议你先跑通过一个简单的 AI 编程例子再回来接触规格驱动。1. 为什么“规格驱动”开始成为 AI 编程的主线1.1 直接甩需求给 AI为什么总是翻车很多人刚开始用 AI 编程时习惯是打开对话框敲一句类似“帮我写一个带用户登录和订单管理的全栈应用”然后把生成的一堆代码复制进项目run 一下。看着它跑起来的那一刻你会觉得 AI 编程简直是人类之光。但接下来改第二个需求时问题就来了AI 不记得自己之前生成的代码结构经常重新生成一套不一样的方案或者把原本能跑的功能改坏。我见过太多人卡在这一步包括我自己早期也一样。核心原因很简单大模型本质上是个概率生成器你给它的指令越模糊它的自由发挥空间就越大。一次性的小脚本自由发挥没关系反正是从头生成但到了多文件、多模块的全栈项目代码之间的依赖关系变多AI 每一步都自由发挥的话整个项目很快就会变成一锅粥。还有一个更隐蔽的问题直接对话式生成AI 的“记忆”是扁平的。你问它上次是怎么设计数据模型的它可能只能从当前上下文里猜或者干脆胡编一个。项目一旦跨越多个会话上下文窗口里的内容不断被压缩和丢弃AI 对项目的理解就越来越失真最终表现为开发者要反复盯着 AI 改错比自己写还累。1.2 规格不是文档而是给 Agent 的“施工图纸”要解决上面的问题我的思路是不要让 AI 去猜需求也不要让它凭记忆去还原项目全貌而是把需求、设计、任务拆成结构化的“规格文件”让 AI 每一步都对着规格干活。规格驱动的意思不是说要做一堆瀑布流文档而是把本来在人类团队里用的 PRD、技术设计、任务拆分改造成 Agent 能直接读取和执行的工件。有个很贴切的类比你找装修队刷墙如果只说“把房子弄好看点”工人只能自由发挥结果大概率不是你要的。但你给一张施工图标清楚哪里刷什么颜色、用什么漆、什么时候完工、怎么验收工人按图施工最后你按图验收。OpenSpec 的角色就是这张施工图Superpowers 则更像是老师傅的工艺手册告诉 AI 在具体施工的时候该用什么手法。这套方法论最核心的变化是把“一次性对话”改成了“工作流”需求规格 → 设计评审 → 任务分解 → 逐步执行 → 验收测试。每一步都有产物每一步都能被检查和回滚。这样 AI 编程从“碰运气生成”变成了“按流程交付”。2. 先看清两件武器OpenSpec 与 Superpowers 分别解决什么2.1 OpenSpec把需求整理成可检查的规格库先说 OpenSpec。它本质上是一套围绕“规格”组织的开源项目约定和工作流工具。它会规定你的仓库里有一个 specs 目录下面每个功能模块都有对应的规格文件包括需求条目、验收条件、设计说明、任务列表。它还会提供一些命令行工具帮助你在创建规格、修改规格、变更状态、展示任务进度这些环节上标准化。我最早看到 OpenSpec 时第一反应是“这不就是把需求文档放进 git 吗”但实际用下来发现不止如此。它真正有价值的地方是把“需求”拆成了机器可读、可检查的条目。每个需求不是一段含糊的话而是一组带编号的条目每条都对应可验证的验收条件。比如“用户能登录”这种描述是不合格的合格的写法是“当用户提交正确的邮箱和密码后系统在 2 秒内返回登录成功并在响应头中设置会话 Cookie”。OpenSpec 的另一个设计是“一次一个变更”。它鼓励你把每个项目目标拆成独立的变更请求每个变更先写规格再进行设计然后拆任务最后实施。这样做的好处是AI 的上下文窗口不会被整个项目的历史塞满它只需要关注当前这个变更的相关规格。对于动辄几十万行代码的仓库来说这几乎是让 AI 保持可靠性的唯一现实方案。2.2 Superpowers把常见编码操作封装成技能卡再来看 Superpowers。它是一个提供给 AI 编程 Agent 使用的技能集合用类似“技能卡”的方式来组织。每张技能卡描述一种能力比如头脑风暴、制定计划、写测试、做代码审查、重构、写提交信息等。这些技能不是简单的提示词模板而是结构化的指导文件告诉 Agent 在接到某类任务时应该按什么步骤来思考、产生什么中间产物、遵循什么标准。打个比方OpenSpec 是项目的“施工蓝图”Superpowers 则像是工程手册。蓝图告诉你这个楼要盖成什么样、有哪些验收点工程手册教工人怎么安全地砌墙、怎么检测混凝土强度。对于 AI 来说Superpowers 就是在它开始写代码之前强制它经历一个“想清楚再动手”的过程。实际使用中Superpowers 里最常用的技能有几个一个是头脑风暴用于把模糊的需求变成多个可选方案一个是计划制定用于生成分步骤的任务清单还有一个是执行计划真正去改代码再有是测试驱动开发相关的技能鼓励先写失败测试再写实现。每个技能在 Agent 的环境里可以被显式调用也可以在系统提示中配置为自动决策链的一环。2.3 两者组合的分工逻辑OpenSpec 和 Superpowers 能不能单独用能。单独用 OpenSpec你就有一套规格管理工作流但 AI 执行起来还是容易自己“加戏”因为规格文件并不直接约束 AI 的思考顺序。单独用 SuperpowersAI 确实会更有条理地做任务但任务本身从哪来、怎么验收、怎么对齐需求没有一套系统去承载。所以真正的价值出在组合上。OpenSpec 提供“做什么”和“怎么算做完”Superpowers 提供“怎么做”和“怎么保证质量”。组合起来的流水线大致是先用 OpenSpec 创建变更规格生成需求、设计和任务清单然后让 Superpowers 中的 Brainstorm 技能对规格进行质疑和补全接着让 Plan 技能把任务拆成更细的可执行步骤再交给 Execute 技能去写代码最后用测试和审查技能验证交付物是否符合验收条件。我在实际项目中体会最深的一点是这套组合解决了 AI 编程最常见的“偏航”问题。以前 AI 写着写着就忘了原始需求现在每个环节都有规格文件作为锚点Agent 即使中途跑了回到规格一对照就能发现偏离。所以这套打法真正的核心不是工具本身而是“用规格把每次对话都拉回到同一条轨道上”的工程化思路。3. 搭一套“规格驱动”工作流OpenSpec 安装与项目初始化3.1 初始化 OpenSpec 目录结构先走一遍最基础的环境搭建。OpenSpec 的安装方式类似大多数命令行工具可以从 GitHub 仓库拉取发布版本也可以通过包管理器安装。我通常会在项目的根目录下执行初始化命令它会自动创建一个 specs 目录里面预置了标准的结构一般包括变更目录、模板目录、状态目录等。初始化完成后推荐先在 specs 目录的模板文件里把团队或自己的验收标准写清楚。这个动作很值得做因为你后续每个规格文件都会继承这个模板相当于项目里的“质量标准基线”。我在自己项目里会给需求条目加几个字段描述、优先级、依赖项、验收条件、风险。这样 AI 生成规格时会有足够的信息去理解边界条件。目录结构创建好之后建议立刻把 specs 目录纳入 git 管理。这不仅是版本追踪更重要的是让 AI 在修改规格时能够用 git diff 看到变更差异。我遇到过一种情况AI 写着写着把需求悄悄改了如果不看 diff你可能根本发现不了。把规格文件纳入 git 之后这个风险就小很多所有规格变更都清清楚楚。3.2 一份规范的 OpenSpec 规格文件长什么样以我最近做的“数据看板筛选功能”为例初始化完成后的第一个动作是创建一个变更。执行 openspec 的相关命令后会在 specs/ 下生成一个新的目录结构命名一般像 “add-filter-panel”、 “support-saved-views” 这种。每个变更下面会包含若干核心文件requirements.md、design.md、tasks.md甚至还有一个 status.md 用来跟踪当前变更状态。requirements.md 是把自然语言需求拆成条目。比如“看板需要支持按时间范围筛选”我会写成## 需求 1时间范围筛选 - 描述用户可在看板顶部的筛选栏选择时间范围。 - 优先级P0 - 验收条件 - 当用户选择“近7天”时看板图表数据在 3 秒内刷新。 - 筛选条件应持久化到 URL 参数刷新页面后仍保留。 - 若接口请求失败页面展示错误提示不产生白屏。这些验收条件不是写给人看的空话AI 在执行时会拿它们当作自测清单。tasks.md 则是把实现步骤拆开每一条都要比需求更具体。比如“创建 FilterBar 组件”“编写 useDateRange 钩子”“为看板查询接口增加 timeRange 参数”“补充组件测试”。拆完之后Agent 的工作就变成一边查规格、一边照着任务清单做勾选整个过程变得非常可控。要特别提醒的是规格文件里的需求条目一定要控制在“一次变更能完成”的范围。OpenSpec 的设计哲学就是小而美的变更别做一个规格文件塞二十个需求。规格文件太大AI 的注意力会被稀释后期验收也会很痛苦。我自己的经验是一条规格对应一个完整可交付的功能最多不超过十个需求条目。3.3 把 Superpowers 安装到 Agent 工程环境Superpowers 的安装某种程度上更像是给 AI 编程工具“装技能包”。你需要把它下载到本地某个目录比如 .superpowers/ 或者项目的 .claude/skills/ 里然后在你的 AI 编程工具Claude Code、Codex、OpenCode 都支持类似机制中配置技能加载路径。配置好之后Agent 在对话里就能感知到这些技能文件。它会在需要时主动去读取“头脑风暴”技能卡或者在开始写代码前参考“计划制定”技能卡。你需要做的只是在系统提示或者项目规则里写一句类似于“主任务开始前必须先调用规划技能分解任务”的话。剩下的Agent 会自己按技能卡里的指引走。安装路径有一点要特别注意不同 Agent 工具对技能的加载方式有差异有的要求技能文件放在固定目录有的支持通过显式命令调用。我最开始使用 Superpowers 时以为装好路径就完事了结果发现 Agent 并没有真正读取技能卡排查了半天发现是配置文件里的目录权限问题。如果你把技能包放在项目目录里确保 Agent 的工作目录对它可读最好用一个 Makefile 或 init 脚本把初始化过程固定下来避免每次新 clone 项目后还要手动配置。4. 实操案例给数据看板加一个“动态筛选面板”4.1 从一句话需求到规格文件用我最近做的一个真实案例完整走一遍这套流程。当时的需求一句话给数据看板加一个筛选面板支持按时间范围和状态筛选。如果按我以前的做法可能直接把这句话丢给 AI 让它生成代码但这次我按照 OpenSpec 的流程来。我先创建了一个变更规格然后花大概半小时把“一句话需求”拆成结构化的规格条目。时间范围筛选、状态多选筛选、筛选条件反映到 URL、空数据状态展示总共拆了五条需求。每条需求下面都写了验收条件。这个动作看起来是在做多此一举的文档工作但它带来的好处是AI 不再需要从我那句模糊的话里去推理“筛选面板”到底包含哪些行为它只需要对着验收条件逐条实现。接着我写了初步设计说明描述前端组件结构、状态管理方案、API 接口的变化。设计部分不需要很细重点是让 AI 理解实现的大方向。最后在 tasks.md 里拆了十几个任务包括前端组件、API 层、状态持久化、测试和样式调整。完成之后这个变更规格就成了后续所有 Agent 会话的锚点。4.2 让 Agent 先做规划再做实现在真正让 Agent 动手之前我用 Superpowers 的“规划技能”要求它先输出一份执行计划。你可以把下面这类提示词作为项目规则固定下来 系统规则开始执行任务前必须阅读规格文件 tasks.md先输出整体实施计划和先后顺序确认计划后再写代码。不得跳过规划直接修改代码。加了这一条之后Agent 的行为立刻发生了质变。它不再是第一行代码直接动手而是会先列出“先实现 API 参数、再搭组件结构、再接入状态管理、再写测试”这种逻辑顺序。如果有不合理的地方我在它动手前就能拦截而不是等它写了一百行代码再返工。实际执行时我让 Agent 按 tasks.md 的顺序逐条处理每完成一个任务就更新任务状态并在对话中输出一句简短的完成说明。这样做的好处是一旦某一步出现问题我能立刻定位是哪个任务出了问题而不用把所有改动都混在一起看。这个习惯对 Agent 协作来说特别重要因为大模型改代码时经常会“越改越多”没有任务级别的隔离出问题就难以回退。4.3 用验收条件做多轮迭代的校准最关键的环节是“验收”。我的习惯是Agent 完成任务后不急着继续下一个功能而是把验收条件当作测试用例让它自己执行。在上面这个看板案例里我要求 Agent 逐条检查验收条件“当用户选择近7天时看板图表数据在 3 秒内刷新”“筛选条件持久化到 URL 参数刷新页面后仍保留”。Agent 会自己启动开发服务器模拟用户操作然后向你报告哪些通过、哪些失败。这个过程看起来慢实际上反而省时。因为如果验收失败Agent 会基于当前的代码上下文立刻继续修复而不是把问题留到你手动测试时才发现。你随手点一下界面可能就发现一个筛选条件没生效再回到对话里让 AI 修来回浪费好几轮。让 AI 自测一遍至少能挡掉 80% 的低级失误。这里有一个非常实用的建议把验收条件用“是否式”的清单表达避免模糊描述。AI 最怕的是“界面要好看”“体验要流畅”这种主观标准它无法判断自己是否完成了。与其那样写不如写“当筛选结果为空时展示数据空状态插图和‘暂无数据’文案”。越具体验收越顺利。5. 提示词与 Agent 协作的关键细节5.1 写提示词的三个原则情境、工件、约束规格驱动工作流跑起来之后提示词的作用并没有消失只是从“让 AI 写一切”变成了“让 AI 在规格框架里做决策”。我写提示词时几乎只遵循三个原则给情境、指工件、提约束。给情境的意思是告诉 Agent 当前在项目里的定位比如“你正在维护一个数据看板应用我们刚刚完成了筛选面板的功能规格”。指工件是告诉它去读哪个规格文件比如“请优先阅读 specs/2024-05-add-filter-panel/requirements.md然后按照 tasks.md 继续实施”。提约束则是明说边界比如“不要修改 auth 模块”“不要引入新的 UI 依赖”“所有新增组件必须有测试”。这三个原则看起来很朴素但在 Agent 协作里非常有效。原因是它们把 AI 的注意力限制在了可控范围内。AI 在长任务中最大的问题是发散而这三个原则恰恰给了一个“聚焦框架”。5.2 控制上下文别让 Agent 一口气读完整项目很多人用 AI 编程时喜欢把整个项目代码塞给 Agent觉得信息越多越准确但实际上这是错误的。模型在上下文窗口里的注意力是有限的塞太多无关代码反而会稀释它对当前任务的关注度。规格驱动模式下我基本只在当前阶段所需的规格文件、相关源码文件之间切换。Claude Code 这类工具一般都有文件读取的能力Agent 可以按需检索代码。我通常在提示词里限定它“先读取哪些文件”而不是让它自己扫描全库。比如新增一个前端组件我只需要它读取相关页面文件、API 客户端、样式文件最多再加一个测试文件的现有写法作为参考。其他无关代码坚决不读。上下文管理做得好不好直接决定了多轮会话后的稳定性。我实测过一个功能做到第 40 轮对话时如果 Agent 一直只读必要文件它的表现和最开始几乎一致如果中间让 Agent 浏览了整个项目它反而会开始“忘记”之前的决策甚至提出前后矛盾的设计。这是很值得养成的好习惯。5.3 一套可以直接抄走的提示词模板按照我的经验下面这套提示词结构在很多项目里都能直接用你可以根据自己的情况调整项目背景这是一个基于 XXX 框架的 XXX 系统当前处于 XXX 阶段。 当前任务请完成 spec 中的第 3 号任务task title。 规格路径specs/2024-05-add-filter-panel/requirements.md 设计参考specs/2024-05-add-filter-panel/design.md 约束条件 - 只修改与当前任务相关的文件 - 新增组件必须附带单元测试 - 不修改现有 API 的返回结构如需扩展请先说明 完成标准完成第 3 号任务后请运行相关测试并按照验收条件核验输出一份简短的自测报告。这套模板的核心在于“始终指出规格路径和任务编号”。它让 Agent 每次都能回到规格文件而不是依靠上下文记忆中越来越模糊的对话记录。你可能会觉得这样多写了几个字但换来的是少改好多次 bug这笔账很划算。还有一个小技巧在项目里放一个 AGENTS.md 或者 CLAUDE.md 文件把团队规范写进去让 Agent 在会话启动时自动加载。我会在里面写“所有新功能必须经过规格流程”“提交信息格式要求”“禁用某个不稳定的依赖包”等约定。这样每次新建会话Agent 都能自动知道规则不需要你重复提醒。如果你在使用 Claude Code 或 Codex这类项目级规则文件基本都是标准能力强烈推荐配置起来。6. 实战里最常踩的坑和排查方法6.1 Agent 过度自信与“幻觉代码”说到坑第一个要吐槽的就是 Agent 的过度自信。你用了几十轮对话它能做到“表面上有条不紊实际上暗自造出一些不存在的 API”。最典型的场景是Agent 调用一个接口函数这个函数在规格设计里根本没设计过代码里也不存在但 Agent 就是理直气壮地写了而且运行时报错它还会编一个理由说“可能是环境问题”。排查这个问题的思路其实很简单让 Agent 在完成任务后列出所有新增或改动的文件并且给出你自己不会去直接看大段代码的审查方式。我的做法是让 Agent 为所有新增的核心函数都写一个简单的 smoke test至少保证可执行。另外一个更笨但有效的办法是凡是用到外部依赖、不存在的 API 时要求 Agent 在提示词里给出链接或文档来源。如果它给不出来大概率就是在幻觉。6.2 规格文件与实现的漂移另一个高频问题是规格文件写好了但 Agent 在实现到一半时开始“自我发挥”悄悄偏离了原始设计。这在多轮对话里尤其常见因为随着代码越来越多Agent 对规格的记忆会被后续上下文稀释。它可能觉得“这里稍微绕开规格更省事”于是在某个角落埋了一个设计之外的实现方案。怎么防止这个漂移我习惯于把规格复核做成一个固定节点每完成三到四个任务就让 Agent 暂停重新打开 requirements.md逐条对照当前实现输出一个“符合/偏离”清单。一旦发现有偏离就立即定位是在哪个任务里引入了偏离再由 Agent 给出修正方案。这个过程不费多少时间但对项目稳定性的帮助极大。它相当于给 Agent 装上了一个校准器每次走歪都能拉回来。6.3 多人协作与多会话时的状态同步如果你自己一个人用这套流程状态同步倒不是大问题。但如果是几个人同时用一个项目或者你每天在不同会话里切换就需要额外注意变更状态的管理。OpenSpec 的变更目录里有个 status 文件会记录这个变更当前是 draft、in-progress 还是 done。我养成的习惯是每次会话开始前先看一眼当前变更的状态确认没有处于半完成的变更再开启新任务。另外如果你同时运行多个变更注意不要让它们的改动落在同一批文件上否则 Agent 之间会互相踩。我的经验是同时最多并行两个变更并且尽量分布在不同的模块目录下。如果碰到一个变更阻塞了宁愿先把它标记为 blocked也不要直接开新的变更去动同一个区域。等到这个变更解决后再继续推进。还有一个多会话场景的痛点AI 在下一个会话里“不认识”你上一个会话里改的代码。这个问题即使有规格文件也未必完全避免但规格文件至少能让新会话快速了解现状。我会在规格的 status 里补充一小段“当前进度摘要”写上哪些任务已完成、哪些卡住了、下一步要做什么。这样新会话启动后Agent 不需要从头阅读几十轮对话记录读一下进度摘要就能无缝接上。6.4 一个快速排查清单最后分享一个我经常用的排查清单当 Agent 行为异常时可以照着看症状可能原因排查方法AI 反复改同一处代码无法收敛规格验收条件不明确补充更具体、可自动验证的验收条件AI 忘记前几轮的决策上下文被压缩或注入无关文件重开会话让 AI 重新读取规格和进度摘要AI 生成了不存在的 API缺少约束或基础文档在提示词中明确“只允许使用代码中已验证的接口”AI 改动了不该改的文件任务范围没定义清楚检查 tasks.md约束只修改相关文件AI 自认为完成但功能失效没有让 AI 执行验证步骤强制要求 AI 运行测试和验收条件自检这张表不需要当成教条但每次遇到 Agent 行为诡异时按表排查一般都能找到根源。最核心的心法就是凡是你觉得“AI 怎么这么不靠谱”的时刻大概率不是模型变笨了而是你没有给它足够清晰的结构和验收标准。我自己的真实感受是OpenSpec 加 Superpowers 这套组合带来的最大改变不是代码写得多了而是“返工”变少了。以前花两三个小时和 AI 来回拉扯解决一个模糊功能现在很多顺序都在动手前就定好了Agent 更像是一个执行部门而不是一个幻想合伙人。这套打法的前期投入是沉没成本比较高的写规格、拆任务、定验收看起来都要额外花时间但做到第三四个功能之后你会发现整体效率不但没有下降反而大幅超过“一句提示词走天下”的状态。如果你现在正被 AI 编程的不稳定性困扰我的建议是先别去追最新的模型或者炫酷的 Agent 框架静下心来把规格驱动的工作流搭起来。哪怕只是从一个小项目开始把 OpenSpec 的目录结构建起来把第一份验收条件写好你也会明显感觉到AI 编程从“开盲盒”变成了“按图施工”。