如果你让 AI 编程助手直接“帮我写一个全栈项目”大概率会经历这样的过程前几百行代码有模有样几百行之后开始自相矛盾再到后面连最初定的接口名都忘了改一个地方崩三个地方。这不是模型不够聪明而是工作方式错了。我的做法是把传统软件工程里的“规格先行”搬过来形成一套规格驱动spec-driven的打法用 OpenSpec 管“项目要什么”用 Superpowers 管“AI 怎么做”底层再配合 Claude Code 这类 agent 工具去执行。这套组合陪我跑通了从个人项目到小团队协作的不少需求今天把完整打法整理出来给正在折腾 AI 编程的朋友做个参考。1. 为什么“聊天式”AI 编程会在全栈项目上翻车1.1 三个致命伤失忆、跑偏、没法验收先说一个我反复踩过的场景。你打开对话窗口输入一段精心打磨的中文需求要求 AI 做一个带用户登录、数据列表和后台管理的全栈应用。前两三个文件它写得像模像样路由、数据库模型、接口返回值都规规矩矩。但聊到第 40 轮你想让它改一个字段校验它可能已经把最初的user_id换成了uid把 session 方案从 JWT 换成了 cookie而你根本不知道这是什么时候发生的。这就是聊天式编程的三个致命伤。第一失忆。对话式 prompt 的核心问题是上下文窗口永远有限。聊得越久早期约束越容易被后续内容冲淡模型只会优先服从最近几轮输入。你不可能指望一个记不清半小时前需求约定的大语言模型稳定交付一个几十个文件的项目。第二跑偏。自然语言需求天然是模糊的。你说“加个用户登录”在真实工程里至少涉及注册、登录、登出、会话保持、密码重置、权限中间件、登录状态前后端同步这还只是 MVP。AI 不会主动问清楚边界它会按自己的“平均理解”自由发挥。方向错了写得越快错得越远。第三没法验收。“写完了”到底怎么定义没有可校验的标准就只能靠人肉 review。但全栈项目几百个文件靠肉眼一行行看既低效又不可靠。最后你会陷入一个死循环AI 改一版你看一遍发现三个问题再让它改它又引入五个新问题。打个比方这就好比装修房子没有图纸。工人听你口头描述刷墙你描述一次他刷一次刷完你觉得颜色不对再让他改最后墙皮刷了八层钱和工期全浪费了。聊天式 AI 编程的问题本质上是“过程驱动”整个过程依赖随机对话结果完全不可预期。1.2 规格驱动把口头需求变成工程合同那怎么解决答案其实在传统软件工程里躺了几十年先出图纸再施工。在 AI 编程语境里图纸就是规格spec。规格驱动spec-driven不是让你写一堆没人看的文档而是把“项目要交付什么”“验收标准是什么”“本次改动触碰哪些文件”这些问题在动代码之前全部用结构化的 markdown 固定下来。这里的关键认知是规格不是给人看的文档而是给 AI 看的“源代码”。它会被 AI 逐字读取会被工具校验格式会在每次新会话里被反复引用。聊天记录是易失的规格文件是持久的聊天记录是概率性的规格文件是确定性的。我常用的类比是签合同。你和 AI 之间不是雇佣关系而是承包关系。一份工程合同必须写清楚工程范围、交付物、验收条件。AI 不再需要“猜”你要什么它只需要按合同执行。这套思路落到工具层面就是我接下来要重点讲的 OpenSpec 和 Superpowers。2. OpenSpec 和 Superpowers 分别管哪一段2.1 OpenSpec规格骨架、提案流程与校验闭环OpenSpec 是一套开源的、与具体模型无关的规格驱动开发框架。它解决的问题非常具体用什么格式写规格、变更范围怎么界定、验收标准怎么落地、做完之后怎么校验。它不绑定某个 AI 模型Claude、GPT 系、甚至本地的开源模型都能接只要按它的格式来。OpenSpec 的核心数据结构分两块。第一块是交付物规格deliverable spec放在specs/deliverables/目录下描述“系统应该长什么样”。第二块是变更提案change proposal放在specs/proposals/目录下描述“这次改动打算怎么做”。目录结构大概长这样specs/ ├── deliverables/ │ └── user-auth.md └── proposals/ └── add-user-auth/ ├── proposal.md └── tasks/交付物规格里最核心的是验收标准acceptance criteria。每条验收标准必须是可测试、可断言的行为描述比如“未登录访问 /dashboard 返回 302 到 /login”而不是“登录功能正常”。变更提案则是整个机制的灵魂。提案模板通常会要求写清楚要解决的痛点是什么、影响哪些交付物、具体要创建/修改/删除哪些文件、实施后的任务拆解、有哪些风险与假设、还有哪些开放问题。这个“文件改动清单”极其重要它是限制 AI 乱动代码的枷锁——提案里没列的文件原则上这次改动就不许碰。OpenSpec 配套的 CLI 提供了一组操作初始化项目骨架、校验规格格式、创建提案、归档已完成的提案。它本身不写代码只负责管流程。用我的话说OpenSpec 是“工程部”负责出图纸、定范围、做验收。2.2 Superpowers把专家工作流封装成技能包Superpowers 是另一条线上的工具。它是开源社区里针对 Claude Code 打造的一套技能插件集本质是一组高度结构化、可被 AI 调用的技能skill。这些技能把资深工程师的工作方法——需求澄清、写计划、测试驱动开发、根因分析、代码审查、Git 操作规范——全部封装成了 markdown 指令文件。每个技能就是一个SKILL.md文件里面有明确的步骤、提问清单、进行中必须遵守的约束。当 AI 启用某个技能时它不再自由发挥而是严格按照技能定义的流程推进。比如brainstorming技能会在你提出一个模糊想法后通过一连串问题逼你把需求边界、约束、验收方式全部想清楚tdd技能会强制它先写失败的测试再写实现最后重构而不是一头扎进代码里。我用一个粗俗但准确的比喻Superpowers 是给 AI 发的“SOP 手册”。同一个模型没有 SOP 时它可能凭感觉输出有了 SOP 它就按流程思考。它管的不是“项目要什么”而是“AI 怎么干活”。2.3 两者组合之后的工作流长什么样把 OpenSpec 和 Superpowers 放在一起整个规格驱动的闭环就完整了。上游用brainstorming技能把模糊需求梳理成清晰的验收标准中游把这些标准落到 OpenSpec 的交付物规格里再开一个变更提案把改动边界锁死下游让 AI 在tdd、implementing等技能的约束下按提案实现最后按验收标准逐条核对通过后归档提案。一句话总结分工Superpowers 管 AI 怎么做OpenSpec 管项目要什么。前者提供行为约束后者提供内容边界。两边对齐才叫真正的规格驱动。如果只用 SuperpowersAI 做事很有章法但做的可能不是你要的东西如果只用 OpenSpec规格写得再漂亮AI 执行时还是可能偷工减料。这俩是配套关系不是二选一。3. 从零到一安装落地与项目初始化3.1 安装 OpenSpec 并用 init 生成骨架OpenSpec 的安装方式在不同版本里略有差异建议以官方仓库的 README 为准。我这里以最常见的 npm 方式为例装完可以直接全局调用npm install -g openspec openspec --version如果你的网络环境或平台不支持 npm官方一般也会提供二进制发布包下载后放进 PATH 目录即可。安装完成后进入一个已有项目git 仓库会更合适执行初始化openspec initinit 会在项目根目录生成specs/目录骨架和模板文件里面预置了交付物模板、提案模板的 markdown 格式。这一步相当于给你的项目打上“规格驱动”的地基。第一次跑初始化时我犯过一个错在还没有 git 的项目里直接执行后面看变更历史时非常痛苦建议先把 git 初始化好再跑 openspec。初始化完可以顺手跑一次验证确认骨架没问题openspec validate如果输出报错多半是版本升级后模板格式有变化按提示修一下模板头部的字段就行不用紧张。3.2 在 Claude Code 里装好 Superpowers 插件Superpowers 目前最成熟的载体是 Claude Code通过插件市场安装。在 Claude Code 的会话里执行下面两行/plugin marketplace add obra/superpowers /plugin install superpowerssuperpowers装完之后可以输入/skill查看当前可用的技能列表。你至少会看到brainstorming、writing-plans、tdd、implementing、debugging、code-review这些核心技能。如果你用的不是 Claude Code而是 opencode 之类的其他 agent原理是一样的但需要按对应工具的插件机制去安装社区里也有现成的适配方案。这里有一个使用前提要提醒Superpowers 的技能流程大多是“多轮提问 多步规划 测试优先”对模型的指令遵循能力和上下文长度要求都不低。我自己实测下来至少要用 Claude Sonnet 4.5 这一档往上的模型否则技能流程经常执行到一半就开始简化步骤效果大打折扣。3.3 把规格模板写成团队能用的样子装完工具只是第一步真正决定上限的是你写规格的质量。先把默认模板改造成贴合自己项目的版本。我个人的习惯是交付物规格至少包含四个部分幂等标识、概述、验收标准、依赖关系。放在specs/deliverables/user-auth.md里大概是这种感觉--- id: user-auth title: 用户认证 status: active --- ## 概述 支持邮箱密码注册、登录、登出与会话管理 作为所有受保护路由的前置依赖。 ## 验收标准 - AC-1: 用户可以使用邮箱密码注册密码最低 8 位。 - AC-2: 注册成功后自动创建会话并跳转到 /dashboard。 - AC-3: 未登录访问 /dashboard 返回 302 到 /login。 - AC-4: 登录失败返回 401且不区分用户不存在或密码错误。 - AC-5: 登出后会话失效再次访问受保护路由需要重新登录。提案模板更要认真对待尤其是“文件改动清单”和“任务”这两块。我做过的提案大致长这样--- id: add-user-auth title: 新增用户认证模块 status: proposed author: 你的名字 date: 按实际日期填 --- ## 问题描述 当前系统没有任何身份认证机制受保护路由直接暴露。 ## 交付物变更 - 新增 deliverables/user-auth.md ## 文件改动清单 - 新增: prisma/schema.prismaUser、Session 模型 - 新增: src/routes/auth.ts注册/登录/登出接口 - 新增: src/middleware/session.ts会话校验中间件 - 修改: src/app.ts挂载 auth 路由 ## 任务 - [ ] 设计数据库模型 - [ ] 实现注册/登录/登出接口 - [ ] 实现会话中间件 - [ ] 编写迁移与测试 ## 风险与假设 - 假设MVP 阶段不引入第三方登录。 - 风险会话存储如果放内存重启会丢失。把提案填写到这个颗粒度AI 在实现阶段的自由度就被严格限制了。它知道该建哪些文件、该改哪些文件、不该碰哪些文件这个边界是规格驱动最值钱的部分。4. 实战全流程从一句话需求到验收归档4.1 用 brainstorming 把模糊需求问清楚假设现在你要给博客加一个用户登录功能。千万别直接让 AI“开始写”先调用 Superpowers 的brainstorming技能/skill brainstorming 我想给博客加一个用户登录支持邮箱和第三方登录帮忙理一下需求。接下来 AI 会像产品经理一样反过来连环问你MVP 范围到底包含哪些第三方登录打算接哪家服务商会话过期策略是什么要不要找回密码哪些页面需要登录才能访问这一轮问答通常要来回五六次你可能会觉得烦但前面问得越清楚后面返工越少。我实测的感受是这一步省掉的是后面至少两轮“AI 写了删、删了写”的灾难。这个技能的可贵之处在于它会把你的随口一句话逐步收敛成有边界的需求描述并在最后输出一份结构化的需求清单。这份清单就是下一步写规格的原材料。4.2 用 OpenSpec 写规格并开变更提案需求澄清之后把清单落成正式规格。根据需求清单创建交付物规格文件把上面那个user-auth.md的模板填实。然后创建变更提案openspec proposal new add-user-auth这条命令会在specs/proposals/add-user-auth/下生成提案模板你打开把问题描述、文件改动清单、任务逐项填好。填完后跑一遍openspec validate确认格式没问题。这里有一个值得强调的操作习惯在进入实现之前先把提案发给 AI让 AI 复述它对这个提案的理解明确“文件改动清单里没有列到的文件一律不许动”确认 AI 理解一致后再放它去写代码。这一步相当于施工前的技术交底能挡掉大量自作聪明的发挥。4.3 让 AI 在 TDD 循环里按提案实现接下来是真正动手的阶段。在 Claude Code 里输入类似这样的指令请读取 specs/proposals/add-user-auth/proposal.md 按提案里的任务清单用 tdd 技能开始实现。因为已经装好了 SuperpowersAI 会先加载tdd技能然后进入红绿重构循环先为注册接口写失败测试跑一遍确认红灯再实现代码跑通测试转绿灯最后重构。整个过程你观察下来会发现它的行为模式和“直接写代码”模式明显不同——每一步都有明确意图不会偷偷加需求外的功能。我在一次实战中遇到过特别典型的场景实现到一半AI 发现提案里没提到“用户表需要唯一索引”它停下来问我“是否允许在本次改动中为 User.email 增加 unique 约束”而不是自己默默加上。这就是提案文件改动清单起的作用。规格驱动真正的价值不是约束 AI而是让 AI 学会在边界内行动越界时主动请示。4.4 验收、回归与归档实现完之后按交付物规格里的验收标准逐条核对这是我和团队现在最常用的一步。比如 AC-3“未登录访问 /dashboard 返回 302 到 /login”直接让 AI 起服务跑一次请求就能断言。全部条目通过后跑一遍全量测试回归再跑一次openspec validate确认规格和实现没有脱节。确认没问题后归档提案openspec archive add-user-auth归档的意义在于specs/deliverables/永远只描述“系统当前应该长什么样”提案是历史记录代表一次改动的完整决策过程。下次开新会话AI 只需要读交付物规格就能了解系统现状不需要翻历史对话记录。5. 高频问题和排坑技巧实录5.1 AI 不读规格直接开干怎么办这是最常见的翻车现场规格写得漂漂亮亮但 AI 一开工还是凭自己理解写代码。根因通常是规格没有被系统性地注入上下文。解法是在CLAUDE.md里写清楚硬性规则# 项目规则 - 开始任何任务前先读取 specs/deliverables/ 下与本次任务相关的规格。 - 实现必须基于 specs/proposals/ 中对应的提案不得擅自扩大改动范围。 - 所有功能先写测试TDD测试通过后再提交。 - 修改前后都要跑 openspec validate。CLAUDE.md 会在每次会话启动时被自动加载相当于给 AI 设置了一个“开工前必须看图纸”的下马威。5.2 验收标准写得太虚AI 没法照做“登录功能正常”这种验收标准AI 看了等于没看。验收标准本质上就是测试用例的草稿必须写清楚输入、动作、期望输出。别写“性能要好”要写“在 1000 个并发用户下接口 P95 响应时间小于 500ms”。别写“登录要安全”要写“连续 5 次密码错误后该账号锁定 15 分钟”。写得越像测试用例AI 交付的代码越稳。5.3 上下文被长规格撑爆技能开始失灵规格文件太多太长时AI 读到后面会“忘记”前面的内容技能流程也跟着简化变形。我的对策是大需求拆小提案一次提案只做一个中等大小的模块控制在 500 行规格以内。规格是给 AI 读的不是给人凑页数的精炼永远比详尽更重要。5.4 技能与自定义规则打架如果CLAUDE.md里你自己写了一套完整工作流和 Superpowers 的流程叠加AI 会陷入左右互搏。我的建议是职责分离全局规则只保留底线约束比如“不要删除测试目录”“提交前必须跑测试”具体业务流程全权交给技能。用不到的技能也可以在插件配置里关掉减少选择干扰。5.5 一张速查表顺手解决问题现象根因解法AI 不看规格直接写代码规格未注入上下文CLAUDE.md 强制“先读 specs 再动手”验收标准形同虚设描述抽象无法断言改写成可测试的行为描述长规格导致后段失忆单次上下文超载拆小提案控制单次改动范围技能与自定义规则冲突职责重叠全局规则只管底线流程交给技能多轮提问 token 消耗大技能主动引导多步思考小改动不走完整流程大功能才启用最后提醒一下成本Superpowers 的完整技能流程会明显增加 token 消耗一个中等模块跑下来大概是直接写代码的 2 到 3 倍。但换来的是返工率大幅下降总体算下来反而更省。如果你只是改个文案这种小改动完全没必要上全套流程。6. 我的体感、边界与三个小建议规格驱动不是银弹。它最适合的是验收标准清晰、业务逻辑明确的工程型需求纯探索性的原型、玩法验证、一次性脚本用这么重的流程反而是负担。我自己的判断标准很简单这个需求后续会不会被反复修改会就上规格驱动不会就直接对话式写完拉倒。三个小建议都是我踩坑踩出来的。第一把“规格优先”四个字写进 CLAUDE.md 的第一行比任何花哨的技巧都管用。第二提案的文件改动清单至少要包含“新增”和“修改”两类如果一次提案里出现超过 15 个文件说明这个提案拆得不够细回头再拆。第三每个新会话开始时花 30 秒让 AI 复述一次它理解的规格和验收标准再让它动手。多花的这 30 秒经常能省下后面几小时的返工时间。这套组合从个人项目用到小团队协作给我最大的改变不是代码量上去了而是终于知道 AI 下一步大概率会干什么心里有底了。如果你也被聊天式 AI 编程的随机性折磨过建议先拿一个小功能跑通这个闭环再逐步铺到更大的项目上。