如果你还停留在“帮我把这个项目写出来”这种一句话需求阶段那你估计也遇到过类似的场面AI一口气吐了上千行代码看着挺完整一跑全是洞让它改个登录逻辑它顺手把你数据库表结构也重构了修好了A功能B功能开始原地摆烂。我在把AI编程导入真实项目之后很快被这些事情反复教育最终从vibe coding转向了SDD路线。SDD就是Specification-Driven Development基于规范驱动的开发核心说起来就一句话先把“要什么”“做成什么样子”写得明明白白再让AI照着施工。而OpenSpec和SuperPowers是我在Claude Code、OpenCode这类工具链上实际落地SDD时最依赖的两个工具箱一个负责把需求固化成结构化规范一个负责让AI执行时自带工程师的章法。这篇文章就把这套组合完整拆开从SDD分级思想和六步实践到OpenSpec和SuperPowers的用法最后串联出一条全栈项目从规范到交付的完整流水线希望给正在被AI随机性折磨的开发者一条能直接照抄的路子。1. 先理解SDD三级分类框架与六步实践指南很多人在第一次接触“规范驱动开发”时容易理解成“写文档”写一堆word或者markdown扔到仓库里吃灰。但SDD真正要解决的是AI编程里的失控问题而它的切入点非常朴素人的需求本来就是分层的一份规范根本装不下所有信息。1.1 SDD三级分类框架为什么一份规范永远不够“三级分类框架”这个提法来自ThoughtWorks的杰出工程师Birgitta Böckeler。她的核心洞察是需求信息如果只放在一层描述里就会陷入两难——写粗了AI不知道该用什么技术栈、什么接口、什么字段写细了前面还在做业务分析你的规范已经掉进了类名和方法签名的泥潭且需求一变底层的维护成本会直接失控。所以规范必须分三个层级各管各的事。我对这个框架的理解是这样的一张表说清楚层级名称回答的问题典型粒度主要读者L1业务目标规范为什么做这件事一个可验证的业务结果需求方、产品L2系统能力规范系统要做什么一个能力或业务模块架构师、开发负责人、AIL3任务规范具体怎么实现一次可提交的代码变更AI、执行开发者用登录功能举个例子。L1层面写的是“用户可以通过邮箱密码登录并在30秒内完成从输入信息到进入系统”它是一个业务结果不涉及任何技术名词。L2开始出现“登录表单”“验证码校验”“会话票据生成”这些能力描述以及每个能力的验收标准。L3才落到“用哪个库签发JWT”“用户表存哪些字段”“错误码怎么定义”这些实现细节。实践里最典型的翻车现场是跳过L1和L2直接让AI干L3的活。你让它“做一个用户登录页面”它理解不了“为什么这个系统需要登录”“登录失败锁定的业务规则是什么”于是它就自由发挥有的AI会用自增id当会话标识有的AI会把密码明文存进数据库还有的AI把前端、后端、数据库全给你创一遍。原因很简单——它压根不知道你在哪个层级给它下达的指令。三级分类这个框架存在的价值就是强迫你在动手前想清楚我现在到底在跟AI讨论哪个层级的事。1.2 SDD六步实践指南一个能反复转动的闭环分类框架解决的是“规范长什么样”但规范驱动开发真正难的是“规范怎么驱动”。Birgitta提出的方法论下面业内逐渐沉淀出了一套六步实践指南我实际在项目里跑下来觉得这套流程可以用在几乎所有AI编码场景中界定边界明确本次迭代做什么、不做什么。边界不是一句“优化系统”的形容词而是有明确范围的清单比如“本期只做注册登录不做密码找回”。编写规范把边界内的内容整理成L1和L2规范放仓库的spec目录下形成受版本控制的文件。审查校验规范也要做评审重点检查验收标准是否可测试、有没有歧义、需求之间有没有冲突。任务拆分从能力规范拆出独立的L3任务一个任务对应一次可提交、可验证的变更。执行编码AI按照任务规范写代码每完成一个任务就跑一次相关测试通过再进入下一个。验证与回流人工或自动化的验证后如果发现规范本身有问题要回到规范层修改重新执行。做这个流程的关键不在第5步编代码而在第1步到第4步。我在指导团队时经常说一句话SDD把原本在编码阶段才暴露的问题提前到了规范阶段解决。以前AI把代码写错了你要去改代码、改测试现在AI把代码写错了你先看它是不是理解偏了规范。如果是规范写得含糊那是流程要背锅不是AI的错。1.3 SDD为什么能改善AI编码质量三个底层机制为什么给AI加一份规范就能明显减少瞎写的情况我自己总结出三个原因。第一个是方向冻结。需求在规范层被写清楚并审查通过后AI在实现阶段只能做施工方不允许做设计方。它接收到的是“用Postgres存用户信息表的字段是xx、xx、xx”而不是“帮我搞定用户存储”。方向一旦被冻结AI的自由发挥空间就被压到合理区间。第二个是上下文裁剪。大模型最怕的是啥是上下文塞太多内容之后不知道该听谁的。如果项目里有一百个文件AI全部读一遍它很容易晕抓不住当前任务的重点。SDD的思路反过来了每个任务只关联一份L3规范外加必要的L2背景AI只需要在极小的上下文窗口里做决策准确率会高很多。这就像给一个新人工程师派活你不会把整个公司的所有需求丢给他而是给一张写着“本周做这个功能、验收标准是这些”的卡片。第三个是可追踪性。每一个代码变更都能对应到具体任务和规范条目出问题之后能倒查是需求理解错了、规范有漏洞还是实现有bug。这个能力在传统软件开发中叫“需求追踪”放到AI编码里同样重要只是很多被AI生产力震惊到的人根本没想起来要建。这三个机制其实就是把所谓“harness”的概念拉回来了。圈里常说从vibe coding到harness加SDD中文语境里你把它理解成“给AI戴上笼头”就行。SDD就是那个笼头用规则把AI的蛮力引导到正确的方向上而接下来要讲的OpenSpec和SuperPowers都是这个笼头的具体零件。2. OpenSpec实战把口头需求变成AI守得住的规范有了理论之后工具就是让理论落地的那双手。OpenSpec是我目前在用的、和SDD理念最契合的开源工具它既不是那种重型的项目管理平台也不是一个只会生成文档的模板生成器它定义了一套目录规范和工作流让“规范驱动开发”这件事在终端和代码仓库里真正转起来。2.1 OpenSpec是什么SDD在AI工作流里的落地格式OpenSpec面向的是AI原生开发工作流它的核心思路是“变化提案Change Proposal能力规范Capability Specification任务Tasks”的三元结构。你不需要在脑子里记着一堆需求也不需要在聊天窗口里跟AI来回拉扯所有需求都先变成一个proposal文件经过确认后再变成能力规范最后才拆成AI能执行的任务。它做的事情可以概括成三条规定目录结构规范和代码一样纳入版本管理每个能力有自己独立的目录。定义变更提案每次新需求是一份提案有标准字段描述背景、变更内容、影响范围。连接AI任务生成提案确定后再拆解成执行级的任务清单任务直接引用规范里的需求编号和验收条件。第一次用OpenSpec时我有一个很直接的感受它把“你需要在聊天里反复喂给AI的那些人话”全部变成了文件。当你跟AI说要改一个功能时你不再是重新描述一遍需求而是直接说“去看specs/proposals/current按上面的tasks执行”AI自己会去读规范。这省掉的不是一次两次复述的功夫而是让需求状态永远有唯一一种权威表达大家人和AI都向这份文件对齐。2.2 目录结构与一份规范到底怎么写OpenSpec推荐的目录结构类似这样specs/ ├── capabilities/ │ ├── user-auth/ │ │ ├── specifications.md │ │ └── tasks.md │ └── todo-mgmt/ │ ├── specifications.md │ └── tasks.md ├── proposals/ │ └── 2025-06-add-login/ │ ├── proposal.md │ └── tasks.md └── architecture/ └── decisions.md简单解释一下capabilities下面放的是系统已经具备或要具备的“能力”每个能力一个目录目录里的specifications.md就是L2级别的能力规范tasks.md是拆出来的常规任务。proposals下面放的是“新需求提案”是变更的起点等提案评审通过再把它合并进对应的能力目录。一份L2规范关键字段不需要多复杂但一定要有可验证的验收标准。我以登录能力为例列一个精简模板# User Auth - Login ## Overview 用户可以用邮箱和密码完成登录登录成功后获得有效期为30分钟的会话票据。 ## Requirements - REQ-001: 支持邮箱密码方式登录 - REQ-002: 连续输错密码5次账号锁定30分钟 - REQ-003: 登录成功返回会话票据和用户基础信息 ## Acceptance Criteria - AC-001: 正确凭证请求登录接口返回200且包含token字段 - AC-002: 错误凭证请求登录接口返回401且错误信息为中文可读文案 - AC-003: 锁定期间即使凭证正确也返回403提示信息为“账号已锁定”大家注意我写验收标准的方式全部都是可以在测试里断言的状态码和字段。千万别写“处理好异常情况”“确保系统安全”这类没法判定的模糊描述。AI对验收标准的遵循度完全取决于验收标准本身是不是有清晰判定逻辑。这就跟给外包提需求一样你写“做一个好看的按钮”跟“按钮为蓝色、圆角8px、点击后跳转首页”交付质量完全是两个量级。2.3 OpenSpec的执行链路plan、task与验证OpenSpec相对方便的一点是它提供了一套CLI能把上面的文件操作和任务流转串起来。常用命令大概类似# 安装 npm install -g openspec/cli # 初始化 openspec init # 新建一个变更提案 openspec new proposal add-login # 根据提案内容生成任务清单 openspec plan add-login # 让AI按任务执行 openspec run add-login --task 001实际使用中我和团队的流程是需求来了先openspec new proposal写清楚背景和目标然后编辑proposal里的specifications明确L1业务目标和L2能力要求接着openspec plan生成任务列表再逐条openspec run去执行。关键点在于“一次一个任务”不是让AI一口气把所有任务全干完。一次只处理一个taskAI才能在既定的上下文范围内专注完成跑完测试再进入下一个。我在这里踩过一个大坑提醒各位注意任务的粒度宁小勿大。我一开始图省事把一个完整的登录模块包括数据库表、后端接口、前端页面拆成一个大任务结果AI跑了十分钟后直接上下文溢出代码写到一半乱掉日志也看不明白是谁的问题。后来我把任务拆成“建表”“写登录接口”“写注册接口”“写前端页面”这种粒度每个都能在几分钟内完成并验证稳得多了。3. SuperPowers让AI手里有工具而不仅仅有嘴规范解决了“AI该干什么”的问题但还有一个问题它解决不了AI干活的姿势对不对。很多人应该见过那种情况给AI提出明确需求它也听懂了但写代码的方式完全没有章法——不写测试就堆实现、改完代码不跑回归、遇到报错自己脑补原因而不是先看日志。SuperPowers这个工具就是冲着这些问题来的。3.1 SuperPowers是什么把工程师的肌肉记忆变成AI默认行为SuperPowers本质上是一套面向编码代理的“技能包”可以装进Claude Code、OpenCode这类终端型AI编码工具里。它和普通prompt的最大差别在于它不是一条提示而是把一整套工程实践拆成了一个个独立的小技能每个技能都包含触发条件、执行步骤、操作清单和注意事项。相当于把TDD、代码审查、重构这类“工程师肌肉记忆”进行了系统化封装然后告诉AI干活的时候必须按这套动作来。举个例子在它体系的TDD技能里AI拿到一个任务后的流程是先理解需求再写失败测试然后跑测试确认失败Red接着写最小实现让测试通过Green最后做重构清理Refactor。这一整套循环下来代码质量的稳定性非常高。而如果没有这套技能的约束大多数AI的做法是先噼里啪啦把完整实现写出来然后告诉你“代码写好了如果测试挂了再看”顺序完全反了。SuperPowers还有一个特点是按角色组织技能。它区分了“开发人员”“产品负责人”“敏捷教练”等不同的技能集不同角色关注的事情不一样。这一点在与OpenSpec搭配时有很大价值OpenSpec里proposal阶段用的偏产品技能编码阶段用的偏开发技能切换任务时你甚至可以把对应角色技能同时激活让AI知道自己现在到底是产品经理还是工程师。3.2 安装与配置Claude Code和OpenCode都能上以Claude Code为例SuperPowers的安装大概是这样# 方式一通过插件市场安装推荐 claude plugin marketplace add workswarm/superpowers-marketplace /plugin install superpowersworkswarm/superpowers-marketplace # 方式二使用 npx 方式直接在项目里安装 npx workswarm/superpowers install如果是OpenCode过程也类似最终都是在自己的AI配置里多出一批可用的技能文件。安装完成后可以有几种方式查看和调用技能/superpowers list之类的方式查看已安装技能清单或者在对话里直接某个技能来触发它。不同版本在不同工具里的命令会有细微差异装之前花两分钟看一下仓库README是最稳妥的。配置时我有一个很实在的建议技能别全开全开等于没开。技能的本质是上下文每一个激活的技能都会占掉模型一部分注意力。你一口气开了30个技能模型反而不知道该优先遵循哪一个。我自己长期保持激活的技能大概在6到8个之间核心是TDD、任务执行、代码审查、重构安全网、文档同步这几个。这几个和SDD流程配合最紧密。3.3 和OpenSpec的分工规范在外技能在内用一句话概括OpenSpec和SuperPowers的关系OpenSpec管方向SuperPowers管动作。让我用一张分工表说明工具负责层面典型动作产出物OpenSpec规范层/方向层写提案、维护能力规范、拆分任务提案文件、规范文件、任务清单SuperPowers执行层/动作层TDD循环、代码审查、重构落地测试、重构后的代码、审查报告Claude Code/OpenCode承载层/运行层运行AI代理、调用工具、执行命令实际代码变更两者没有任何功能重叠是前后衔接的关系。OpenSpec把“做什么”变成一个一个任务SuperPowers让AI在执行每个任务时“知道怎么做才是规范的”。我在实际配置三件套时通常让Claude Code启动时同时加载OpenSpec的目录文件和SuperPowers的技能配置前者的规范内容会作为任务描述被引用后者的技能会在代码动作层面兜底。这个组合跑起来之后你会明显感觉到一个变化AI从一个“话特别多、写代码速度飞快但总需要你擦屁股的新人”变成一个“话说得不多、动手前先确认规则、写完还会自己跑测试的中级工程师”。当然它还不是老手但至少不再需要你全程盯着。4. 三件套实战Claude Code OpenSpec SuperPowers全栈项目配置理论讲得再多不如亲手跑一遍。这一节我拿一个最常见的小项目——“带登录功能的待办事项应用”为例把从空目录到全栈功能的完整过程走一遍。你可以直接照着操作这个流程对大多数中小型全栈项目都适用。4.1 环境准备从零初始化项目准备工作其实很简单前提是你已经装好了Node.js LTS版本和Claude Code CLI。OpenSpec和SuperPowers都依赖Node生态装好后进入一个新项目目录mkdir todo-app cd todo-app git init npm init -y openspec init初始化完OpenSpec后它会生成specs/目录。接下来做两件事第一安装SuperPowers插件到Claude Code第二在项目根目录创建或修改CLAUDE.md文件这个文件就是Claude Code的“开机自检准则”AI每次启动都会优先读它。我在里面写的内容除了项目背景最关键是这段本项目采用规范驱动开发方式。开始任何编码任务前 必须先读取 specs/capabilities/ 下相关的能力规范文件 并检查 specs/proposals/ 中是否有当前正在执行的变更提案。 不要在没有规范指引的情况下直接编写实现代码。这一段写进去作用巨大。它相当于给AI设置了一个“进门先看图纸”的习惯而不是进门就抡起锤子砸墙。4.2 完整流程提案 → 规范 → 任务 → 编码 → 验证第一步创建提案openspec new proposal todo-auth然后编辑proposal.md把L1业务目标写清楚。这里我给一个示例# 提案用户登录与待办管理 ## 背景 用户需要一个私人的待办事项管理工具所有操作必须基于登录身份。 ## 业务目标 - 用户能够注册、登录并维护自己的待办事项 - 未登录用户不可访问待办接口第二步把L2能力规范写进specs/capabilities/user-auth/specifications.md目录结构在上一节已经展示过。这张表里既有需求列表又有验收标准比如“注册时邮箱唯一”“登录令牌有效期30分钟”这些可测试的条件。第三步执行plan命令生成任务清单openspec plan todo-auth它会在提案目录或者能力目录下生成tasks.md大概长这样- task-001: 创建用户表和待办表字段见 REQ-001、REQ-004 - task-002: 实现注册接口满足 AC-001、AC-002 - task-003: 实现登录接口满足 AC-003、AC-004 - task-004: 实现待办事项增删改查接口满足 AC-005 至 AC-008 - task-005: 实现前端登录页和待办管理页第四步让AI真正开始干活openspec run todo-auth --task 001执行task-001时AI会读到建表规范然后调用SuperPowers里的任务执行和TDD技能先写一个判断表结构是否存在的测试再建表跑通验证。你不需要额外催它规范已经告诉它要做什么技能告诉它怎么做得不跑偏。第五步所有任务跑完后人工做一轮验收。重点不是看代码漂不漂亮而是逐条对照验收标准过一遍接口返回的状态码对不对、前端能不能正常登录、未登录访问会不会被拦截。验收中发现的问题如果属于规范遗漏就回头改规范文件然后重新执行对应任务。4.3 关键参数的选择模型、技能和任务粒度三件套跑得顺不顺有几个参数层面的选择很关键。首先是模型选择。OpenSpec和SuperPowers本质上是把任务标准化所以对模型的“基础代码能力”要求依然很高。我个人的经验是如果可以选该工具链里最强的那档模型来执行编码任务选中等模型来辅助编写规范和拆任务。这样成本上比较划算质量上也有保障。其次是技能激活数量。我前面已经提过建议控制在6到8个。下面这张表是我实际保持激活的组合技能作用时机价值TDD编码阶段保证先测试后实现防止裸奔任务执行Execute Task每个任务开始时按既有步骤落地不跑题代码审查一个功能完成时提前发现接口和边界问题重构安全网修改已有代码时保证重构不破坏现有行为文档同步编码结束后让规范文件跟着代码变化更新第三是任务粒度设计。参考的黄金标准是“让AI在不超过它上下文窗口的情况下能一次完成且能独立验证”。一个接口是一个理想粒度一个完整模块往往偏大而一个函数又太小、任务列表会爆炸。具体的权衡在第五章的常见问题里会细讲。4.4 换到OpenCode或者Codex上这套流程还成立吗这个问题被问得特别多。我的回答是成立但配合度有差别。Claude Code目前是这三者的组合里对SuperPowers支持最完整的因为插件和技能机制相对成熟。OpenCode是开源方案如果你习惯自己折腾配置文件它也完全可以装SuperPowers技能配合OpenSpec做规范驱动编码没有障碍。Codex接入OpenSpec的规范上下文也做得到但技能加载的灵活性不如前两者。建议不要本末倒置核心不是选哪个终端工具而是把“规范层OpenSpec”和“动作层SuperPowers”这两层界面建好底层工具只是承载它们的方式随时可以换。5. 真正运行之后你会踩到的坑问题速查与避坑心得三件套不是装上就能一劳永逸。我前前后后跑了几个项目踩坑踩到怀疑人生后来把所有坑汇总成一张速查表和几个心得团队内部看到问题直接查表效率提高很多。5.1 常见问题速查表现象根因有效解法AI写出来的功能和需求对不上规范太粗只有一句业务描述补齐L2能力规范和可断言的验收标准规范写了一大堆但AI不遵守规范没有注入AI上下文在CLAUDE.md写明读取顺序任务引用规范文件路径任务太大AI执行到一半就乱任务拆分过粗按接口或模块粒度拆task确保一次能完成并验证测试跑挂AI自己脑补原因没开TDD技能强制SuperPowers的TDD技能先红后绿再重构规范和代码很快不一致变更后没有回流更新spec养成“验证后改规范”的习惯先改文档再造码上下文爆掉AI丢三落四技能开太多挤爆上下文只保留6到8个核心技能其余按需激活AI改A功能时弄坏了B功能缺少回归验证每个任务完成后跑全量相关测试用测试兜底5.2 几条只有动手才能踩出来的心得第一条规范文件是给AI吃的不是给管理者欣赏的。写规范围绕的一个核心是“减少AI的猜测空间”。所以能列清单就不要写长段落能写明确的状态码和字段名就绝不写“友好提示”这种词。我自己整理过一个对照组用散文式规范和检查清单式规范分别跑同一个登录功能前者需要三轮返工后者一次通过。差别就是这么大。第二条一次只让AI读一个任务的上下文。不管项目多大都不建议同时把十个任务描述塞给AI让它自己挑着做。AI和人类新人一样多任务并发时容易出现“选择性遗忘”做着A任务突然蹦出B任务的思路。目前最稳的玩法就是把任务列表交给脚本脚本按顺序一个个喂给AI执行每个任务独立验证。OpenSpec的run命令本质上就是辅助你做这件事。第三条不要迷信“全自动流水线”。SDD这一套跑得最好、交付质量最稳定的用法目前仍然是人机协作人来界定边界、审查规范、验收结果AI负责在规范和技能的双重约束下算执行。SDD的价值不是取代人而是把人的判断力前置到了规范阶段。前置得越充分后面AI发挥的空间越安全。从成本账上看写规范花掉的时间通常会换回三倍起步的返工节省。最后补两句这套组合我跑了小半年最大的感受是难度不在工具而在“克制”。每次想省事少写一段规范、少拆一个任务、少更新一次文档最后都会在AI生成的烂代码里加倍还回来。OpenSpec帮我解决了需求表达混乱的问题SuperPowers帮我把执行质量拉到了及格线以上但真正让整套流程稳定运转的依然是那个愿意先把事情想清楚的人。如果你正被AI编程的随机性折磨不用一上来就全盘改造下个小项目试着只加一段规范、少让AI自由发挥一次你会很快感觉到变化。