这段时间我把 OpenSpec、Superpowers 和 SDD TDD 这套工作流真正跑起来之后才算把“让 AI 写代码”这件事从偶尔惊艳、经常翻车变成了过程可预期、结果可检查。这篇文章不是某个工具 README 的复述而是我从零开始搭建这套工作流的完整记录包括安装、目录设计、六步实操、测试先行怎么做以及我在真实项目里踩过的坑。适合已经用上 AI 编程工具但总觉得交付质量不够稳定的开发者参考。先说一个基本判断OpenSpec 解决的是“需求怎么被严格描述”的问题Superpowers 解决的是“AI 怎么按套路干活”的问题SDD 是把它们串起来的流程TDD 是这个流程里最硬的验收环节。单独用任何一个效果都有限组合起来才像一套完整的工程方法。1. 为什么这套工作流能治“AI 写代码不稳定”的毛病1.1 从“提示词工程”到“规格驱动”协作方式的根本变化以前我们让 AI 写一个功能通常是在对话框里甩一句话“帮我加一个用户注册功能。”然后就等着。AI 会自己脑补出一大堆细节要不要邮箱验证、密码规则是什么、注册成功跳哪里、重名怎么办。运气好它能猜对一半运气不好整个结构都跑偏。更麻烦的是这种对话是一次性的没有任何产物沉淀下来。下次想改需求只能再把整个历史对话甩给 AI让它从一堆文字里找上下文。SDD 的全称是 Specification-Driven Development规格驱动开发。它的核心思想是把“需求长什么样”这件事从对话里抽出来写成一份结构化的、放在代码仓库里的 markdown 文档。这份文档就是 AI 的施工图。AI 看图纸施工而不是靠猜。这个转变非常关键。对话是流式的看过了就没了而且越长越容易混乱。规格是持久化的它在仓库里可以被 review、被 diff、被回滚。你可以说“这次只做规格里的这些内容”AI 就不会自己加戏。这就像你给装修师傅一张平面图而不是发一段语音描述强调的是“少解释、看得见、改得动”。1.2 OpenSpec、Superpowers、SDD、TDD 到底各管什么很多人会把 OpenSpec 和 SDD 混为一谈其实它们是两层的概念。SDD 是一种开发方法论OpenSpec 是把方法论落地的工具。没有 OpenSpec你也可以在项目里手动建一个specs目录然后往里写 markdown但那样规格的创建、变更、状态管理、归档都得自己维护团队之间没有统一约定很快就乱了。Superpowers 又是另一个维度。如果说 OpenSpec 管“需求文件”那 Superpowers 管“AI 的能力”。它是给 AI 编程工具安装的一套技能包里面是一组结构化的操作技能比如“如何做计划”“如何写测试”“如何做代码审查”。每次干活的时候AI 会先从这套技能库里选取合适的流程来执行而不是靠自己的自由发挥。它们的关系我用一个表来说明角色类型解决的核心问题OpenSpec工具用文件系统管理规格让需求可审查、可追踪Superpowers技能包给 AI 提供标准化操作流程减少随机发挥SDD方法规定“先规格后代码”的先后顺序TDD方法规定“先测试后实现”的验证纪律这套组合里SDD 是为 AI 定边界TDD 是为代码定底线。OpenSpec 是容器Superpowers 是执行者。缺了哪一个另外几个都会变得难落到实处。2. 环境准备先把 OpenSpec 和 Superpowers 装好再谈流程2.1 OpenSpec 的安装、初始化与目录结构我先说安装。OpenSpec 通常以命令行工具的形式使用你需要一个能运行脚本的本地环境Node 和 Python 按需准备。不管你用哪种方式安装目标都是拿到一个openspec命令可以在项目根目录执行。如果你拿到的是仓库源码典型的做法是把项目拉下来把可执行文件所在目录添加进 PATH。我自己比较喜欢这种源码方式因为出问题的时候我可以直接读源码排查而不是对着一个黑盒猜原因。装好之后在项目根目录跑一下openspec --version能正常输出版本号说明环境没问题。然后执行初始化openspec init这会在项目里生成一个specs目录里面通常有需求、变更、归档、当前状态这几块结构。我用过的典型目录结构是这样的project/ ├── specs/ │ ├── requirements/ # 需求背景类文档 │ ├── changes/ # 待实施的变更规格 │ ├── current/ # 当前系统规格快照 │ └── archive/ # 已完成的规格归档 ├── .claude/ │ └── skills/ # Superpowers 技能放这里 └── src/这套目录的直觉是没有归档前改动都放在changes里每一份改动就是一个独立文件夹完成并验证后再合并进current或归档到archive。这样整个项目的规格演进像 git 一样有迹可循而不是所有需求堆在一份巨型文档里。2.2 Superpowers 的安装方式与技能目录Superpowers 的安装相对简单它本质上是把一组技能文件放进 AI 工具能识别的目录。以支持目录型技能的 AI 编程工具为例你可以把技能包克隆到项目的.claude/skills目录下或者在全局的配置目录里安装看你自己想让哪些项目使用。我建议先全局安装、验证有效后再下沉到具体项目。原因很简单全局安装只需要配一次项目里直接就能用如果你一开始就绑定单项目后来想换个项目用还得重新配比较麻烦。装完之后每个技能应该是一个独立的文件夹或 markdown 文件里面描述了这个技能的目标、适用场景和操作步骤。你可以直接打开看一眼看它是不是真的在引导 AI 按“规划、执行、检查”的顺序做事而不是简单的一两句话提示词。2.3 装完先别急着写代码做一次链路验证我见过太多人装完工具就直奔需求结果跑了两步发现 AI 根本没加载技能规格读不到测试包缺失整个流程像多米诺骨牌一样倒。所以安装完必须先做链路验证。第一步确认 AI 工具能访问specs目录。你可以在对话里问它“请列出 specs 目录下所有文件。”如果它能准确列出来说明文件访问正常。第二步确认 Superpowers 技能已加载。你直接问“你有哪些可用技能”看它能不能说出你安装的那几个技能名称。如果答不上来大概率是安装目录不对或者需要重启会话。第三步跑一个最小的端到端验证随便写一个一行规格让 AI 按规格生成一个函数同时写一个测试。全流程走通之后再开始真正的工作。这个验证只需要十几分钟但能避免后面连续踩坑很值得。3. SDD 六步实践把需求变成可以交付的规格3.1 前两步需求澄清与上下文收集拒绝“第一版就直接写”SDD 六步是我自己平时用的版本比官方流程更偏实践一些。第一步是需求澄清。你要让 AI 先别写代码而是把需求里的问题列出来。比如“给 Todo 应用加标签筛选”这个需求听起来很清楚但里面其实藏着不少问题是单选标签还是多选筛选条件要不要和现有“完成状态”筛选叠加没有匹配结果时显示什么标签数据从哪里来硬编码还是用户可维护这些如果不先问清楚AI 随便猜一个做出来的东西基本不是你要的。第二步是上下文收集。让 AI 读取项目里相关代码理解现有结构。我会明确要求它读取特定文件比如路由、数据模型、列表组件然后输出一个简短的“现状摘要”让我确认它没有理解偏。这两步的目的是让 AI 在写任何正式文档前先对齐一个共同的“现实基础”。这个阶段我通常用这样的提示词现在先不要写实现代码也不要写任何规格文档。 请按顺序完成 1. 列出你对这个需求的所有疑问 2. 读取 src/todos 下的相关文件输出当前数据模型和列表逻辑摘要 3. 等我确认之后再进入下一步。实测下来这个约束非常关键。一旦让 AI 直接跳进“写规格”或者“写代码”它很容易跳过问问题的步骤自作主张做决定。主动把它的动作卡住它才会真正执行。3.2 中间两步编写规格与评审验收标准必须可测试第三步是写规格。OpenSpec 里一份变更规格通常长这样背景、目标、范围、用户故事、验收标准。我强调一点验收标准必须写成“可以验证真假的句子”不要出现“更好的体验”“提升效率”这类形容词。什么是可验证的句子“用户选择标签后列表只显示包含该标签的 Todo。”这是可验证的。相反“用户能够方便地筛选标签”就是不可验证的因为“方便”没有标准。第四步是评审规格。评审者可以是人也可以让 AI 扮演评审者。我一般会让两个独立会话互相评审或者在一个会话里让 AI 先写完规格再换一个角色去挑毛病。比较实用的评审维度有三个每条验收标准是否真的可以被一个测试覆盖。有没有边界情况被遗漏比如空列表、超长文本、重复标签。范围是不是过大有没有把不该做的功能写进来。评审阶段发现问题改起来非常便宜就是改几个字。等代码写完再发现需求错了那就是重写成本完全不同。3.3 后两步拆解任务、实现与验证让 AI 照着规格干活第五步是拆任务。规格评审通过之后我不直接让 AI 写整个功能而是让它先根据验收标准列出实现任务每个任务对应一个或几个测试。这一步会把不可见的复杂度摊开比如“写数据库查询逻辑”“改列表渲染”“加空状态组件”。任务拆完AI 的工作路径就清晰了。第六步是实现与验证。实现必须严格按 TDD 顺序来先写测试看到测试失败再写实现最后让测试通过。一个任务一个任务地推进不要一次性把所有测试全部写出来然后再实现那样一旦整体跑不过来很难定位问题。全部实现完后还要做一层整体验证跑全量测试跑代码检查然后人工抽查关键路径。人工抽查很重要因为 AI 写的测试有可能和 AI 写的实现错得一致两边都错但相互匹配测试全绿功能却是坏的。我的习惯是在验收场景里手动操作一遍再决定是否关闭这个变更。4. 把 TDD 融进 SDD测试先行这件事到底怎么做4.1 行为级测试在前每条验收标准对应一条用例TDD 在 SDD 里的落点不是在功能写完后再补测试而是在规格评审通过后马上根据验收标准写行为级测试。这一步很多人会偷懒但我建议你宁可不写实现也要先把测试写好。所谓行为级测试就是站在用户视角写测试不管内部实现细节。比如“标签筛选”这个功能行为测试就是先创建几个带标签和不带标签的 Todo再点选一个标签断言列表里显示的条目标记。这里有一个技巧把规格里的每条验收标准翻译成测试用例的时候用表格来做映射。这样做的好处是任何一个验收标准丢了都能从测试用例里找出来不会出现“需求写着但测试根本没覆盖”的情况。验收标准对应测试用例测试层级选择标签后只显示相关条目创建混标签数据并断言列表内容集成测试无匹配项时显示空状态筛选一个没有任务的标签并断言 UI组件测试清除筛选后恢复完整列表筛选后点击清除并断言条数集成测试4.2 单元测试的 red-green-refactor 节奏行为级测试覆盖的是“功能是否正确”单元测试覆盖的是“内部逻辑是否健壮”。在 AI 协作场景下单元测试尤其重要因为 AI 在改内部实现的时候很容易破坏一些隐藏逻辑比如排序规则、时间格式、权限判断。没有单元测试兜底这些破坏往往要等很久才能被发现。单元测试要遵守 red-green-refactor 节奏先写一个当前必然失败的测试运行它确认失败且失败原因符合预期。写实现代码让这个测试变绿。重构代码保持测试全绿。这个节奏放在 AI 场景里有一个容易出错的地方AI 有时候会自动“跳过”失败步骤先把实现和测试一起写出来然后告诉你“测试通过了”。这时候你无法判断测试到底有没有测到逻辑因为测试目标一开始就通过了。所以我在提示词里会明确要求每完成一个任务必须先贴出“测试失败的输出”再贴出“测试通过的输出”。两次输出都在才算走完流程。4.3 规格变更时先改测试再改实现开发和需求有个永恒的矛盾需求一定会变。规格驱动的好处是需求变更时第一修改点很明确。但真正的纪律在于顺序先改规格再改测试最后改实现。这个顺序保证了每一步都有据可依。我举一个真实例子。原来规格写的是“支持单个标签筛选”后来产品说要支持多选。正确的流程是改规格文件里的范围描述和验收标准把“单个”改成“多个”。改测试用例新增“多个标签同时筛选”的场景。运行测试确认新用例失败。修改实现代码让所有测试通过。如果反过来写先改代码再改测试你很容易忘了更新某个验收标准最后测试虽然全绿但规格和实现已经不一致了。规格和实现的“漂移”就是从这个细小的顺序问题开始的。5. 实操记录从一条规格到全栈功能交付的全过程5.1 需求场景Todo 应用增加标签筛选这次实操我选了一个比较小的需求方便你完整看到流程如何走通给一个全栈 Todo 应用增加“标签筛选”功能。技术栈是前端 React 后端 FastAPI数据存在 SQLite 里。这个需求涉及前端组件、后端接口、数据查询三层足够演示 SDD 和 TDD 如何配合。需求描述只有一句话“用户可以根据标签筛选 Todo 列表。”如果直接让 AI 写它可能给你做单个标签筛选也可能做多个下拉框甚至可能顺便加一个标签管理页面。范围不清交付质量完全看运气。所以我决定走完整套流程。5.2 规格文件长什么样一个可直接抄的示例在specs/changes/add-tag-filter目录下我建了一份README.md。这是整个工作流的核心产物它定义了 AI 要做什么也定义了我如何验收。内容如下# 变更Todo 标签筛选 ## 背景 Todo 列表目前只能按完成状态筛选。用户希望按标签过滤 以便聚焦某类工作。 ## 目标 在列表页提供标签筛选功能。 ## 范围 - 支持单个标签筛选。 - 筛选结果与完成状态筛选可叠加。 - 不涉及标签管理功能。 ## 用户故事 作为 Todo 使用者 我希望选择标签后只看到相关联的任务 以便快速聚焦某类工作。 ## 验收标准 - 用户选择标签后列表只显示包含该标签的 Todo。 - 用户同时设置完成状态与标签时结果同时满足两个条件。 - 没有匹配的 Todo 时显示空状态文案暂无相关任务。 - 用户清除标签后列表恢复为完整任务列表。这份规格写得非常“窄”每条都能直接翻译成测试。没有“优雅”“快速”“用户友好”这类不可验证的词。评审时我重点看了范围这一节确认“不涉及标签管理”明确排除掉了 AI 给自己加需求的路。5.3 让 AI 按规格实现提示词与落地步骤规格文件写完并经过我自己审查后我开始把实现任务交给 AI。我的提示词是这样的请读取 specs/changes/add-tag-filter/README.md。 在动手之前先按 Superpowers 的 plan 技能给出实现计划 计划中要为每条验收标准列出对应的测试用例。 确认计划后按 TDD 顺序实施 先写失败测试再写实现再重构。 每完成一步请贴出对应测试的运行结果。这段话里有两个关键点。第一是“读取规格文件”不是把内容复制到提示词里而是让它去读文件。这样当规格更新时AI 下一次交互能看到最新内容。第二是“贴出测试运行结果”这是防止 AI 假装做了 TDD 的强约束。AI 给出的计划分了四步后端接口支持标签参数、前端请求参数联动、列表渲染按标签过滤、空状态组件。前两步是后端集成测试后两步是前端组件测试。计划没问题我就让它开始执行。5.4 验证、提交与规格关闭执行过程中有一个小插曲后端第一次实现时AI 只按标签过滤但没有跟“完成状态”叠加。原因是它在读规格时误把“筛选结果与完成状态筛选可叠加”理解为两个独立的接口。我让它重新读规格文件中的验收标准然后补了一个同时传两个参数的集成测试驱动它修正了实现。这个过程正好体现了 SDD 的价值分歧发生在规格层面而不是实现层面双方可以通过规格文件对账。最终所有测试通过。我手动打开页面创建了几条不同标签的任务验证了单选、叠加筛选、空状态、清除四个场景全部符合预期。提交的时候我保留了一个清晰的 git 提交顺序先规格再测试最后实现。git log --oneline # 8b1a2c3 docs(spec): add tag filter specification # 4e5f6a7 test(api): add tag filter integration tests # 9b8c7d6 feat(api): implement tag filter query # 1a2b3c4 test(frontend): add tag filter UI tests # 7d6e5f4 feat(frontend): implement tag filter UI最后一步是关闭规格把changes/add-tag-filter的内容合并到当前规格快照中并把这个目录移到archive。这样整个变更的生命周期完整闭环后续任何人查看项目历史都能知道这个功能是为什么做、按什么标准做的。6. 常见问题与排查技巧实录6.1 工作流起不来、包找不到先在 Python 环境里补依赖使用包含 Python 脚本的工作流时我最常遇到的报错是类似“请安装缺失的包以使用此工作流”的提示。这个信息看起来像是工具在指导你操作但很多时候你按提示装完包还是起不来。原因通常有两种装进了错误的 Python 环境或者项目依赖没有完整声明。我的排查顺序是这样的先确认当前用的是哪个 Python 解释器which python确保和项目虚拟环境一致。确认工作流脚本需要的依赖比如某个脚本开头 import 了openai、pydantic那就先pip show pydantic看装没装。用虚拟环境而不是全局环境安装避免污染系统环境。一个具体的踩坑记录有一回工作流要求装requests我全局环境里明明有但项目虚拟环境里没有脚本一跑就报错。我到虚拟环境里补装之后立刻正常。所以遇到这类报错第一反应不是怀疑包版本而是先确认“当前解释器是谁”。6.2 AI 不听规格指挥多半是规格写得不够“窄”如果你明确说了“读取规格文件”AI 还是自由发挥不要急着怪 AI。先回去看你的规格文件是不是写得太宽了。我见过太多人把规格写成需求描述“实现一个用户管理模块功能要完整。”这样的规格等于没说。范围不清晰AI 就只能靠猜。解决办法是把范围写“窄”。在规格里明确列出“不做”的内容是一个很有效的手段。前面那个标签筛选例子里的“不涉及标签管理功能”就是专门用来堵住 AI 加需求的。同理在对话提示词里也建议指定“只处理 specs/changes/xxx 范围内的内容”尽量不给自由发挥留空间。如果规格已经很窄AI 还是跑偏那可能是技能上下文被截断了。长会话里 AI 很容易忘掉早期的指令。我的做法是把规格路径重复写在每次提需求的末尾并定期开新会话让 AI 重新从规格文件读取上下文。6.3 团队协作中容易踩的坑规格评审、分支与归档单人使用时SDD 和 TDD 主要是改善个人效率。进入团队协作后还有几个坑值得提前注意。第一个坑是规格评审和代码评审的顺序反了。规格评审应该在实现之前做而不是等代码写完再反过来补一份规格。评审规格时发现问题成本只是改文字等实现完了再评审那基本等于返工。我会在团队约法三章没有通过规格评审的变更不允许进入编码阶段。第二个坑是规格文件放在功能分支上导致并发分支之间看不到彼此的规格变更。我的习惯是让specs目录跟着主干分支走每次都先从主干拉最新的规格再开始新变更。规格本身就应该像代码一样先 rebase 到最新避免多个 AI 会话基于不同的需求基准写代码。第三个坑是归档不及时。规格目录里如果堆满“已实现但没归档”的变更时间一长就分不清哪些是新需求、哪些是旧需求。建议每个变更完成后立即把对应目录从changes移到current或archive。这个动作虽然小但对维持项目长期可维护性非常重要。我个人在实际使用中最大的体会是这套组合拳最值钱的部分不是某个具体命令而是它逼着我把“需求”这个最容易马虎的环节变得可见、可审查、可回滚。AI 的能力只会越来越强但如果没有一个稳定的容器去承接需求能力越强越容易发挥到错误的方向上。最后分享一个小技巧把验收标准写在每份规格的最顶部实现过程中随时回看。当你发现 AI 开始偏离时把那份文件再甩给它通常比你说十句话都管用。