开场别再让AI自由发挥给它一张能执行的地图做开发这些年我有个越来越强烈的感受身边用 AI 编程的人分成了两类。一类让 AI帮我写个登录功能然后看着它写出一个能跑但到处是坑的版本再花两小时修 bug另一类会让 AI 按照一份清晰的规格说明逐步实现测试先行、小步提交代码质量甚至比自己手写还稳。差别在哪不在模型而在工作流。我最近把整个开发流程切到了OpenSpec Superpowers把SDDSpec-Driven Development规格驱动开发和TDDTest-Driven Development测试驱动开发串成了一条完整的链路。这套组合解决了一个困扰我很久的问题AI 写代码时上下文太散、目标太模糊、验证太晚。用了两个月最直观的体感是返工少了需求变更时可追踪了代码审查也轻松了不少。这篇文章我就把整套搭建过程、核心原理和踩过的坑完整写出来适合正在用 Claude Code、Codex CLI 或其他 AI 编程工具、想让 AI 输出更可控的开发者参考。内容不炫技全是实操。1. 先想清楚为什么是 SDD为什么是 TDD1.1 从需求满天飞到规格先行传统开发流程里需求和实现之间隔着一道巨大的鸿沟。产品经理口头描述一个需求你理解一遍写代码时又理解一遍AI 接手时再理解第三遍。每一遍都可能失真等代码写完才发现这根本不是要的东西于是推倒重来。SSD 的核心思路很朴素在写代码之前先把要做什么、为什么做、怎么验收写成一份结构化的规格文档。这份规格不是流水账式的 PRD而是可以直接喂给 AI、可以提交 git 审查、可以逐条追踪的契约。每一次需求变更对应一份独立的变更提案change proposal提案里写清楚背景、需求描述、任务拆解和验收标准。代码实现只是去满足这份契约的过程。我最早接触 OpenSpec 时其实有点怀疑——这不就是写文档吗但真正跑起来才发现差别OpenSpec 把规格文档变成了一种可执行的状态。它能校验格式、能归档历史、能根据验收标准自动生成任务清单AI 拿到这份清单后不会再天马行空地自由发挥。1.2 TDD 不是老古董而是 AI 时代的基础设施很多人在 AI 编程时跳过测试觉得让 AI 写测试还不如让它多写点功能。这个想法在纯人工时代还能争论在 AI 时代基本上行不通。原因很简单AI 最大的问题不是不会写代码而是会一本正经地写出看起来对但实际不对的代码。没有测试兜底你根本不知道它是不是在自嗨。TDD 的价值在这里被放大了——它不是测试方法论而是给 AI 装了一个自我校验回路先写一个会失败的测试Red再写最简实现让它通过Green最后重构Refactor。每走完一圈AI 就拿到一次明确的反馈信号。把 SDD 和 TDD 接在一起后整个逻辑链就很顺了SDD 负责回答做什么、为什么做TDD 负责回答怎么证明做完了。没有前者TDD 容易陷入为测试而测试没有后者SDD 的验收标准只是纸上谈兵。2. 工具拆解OpenSpec 和 Superpowers 各自解决什么问题2.1 OpenSpec用 Markdown 写规格让改需求变成可追踪的操作OpenSpec 是一个规格驱动开发的开源工具它把整个变更管理流程做成了 CLI 操作。它定义了一套目录结构和文件规范核心要素有这几个specs/当前项目最新的规格文档集合代表现在系统应该是什么样changes/待实施或正在实施的变更提案每次需求改动都开一个新的 change每份 change 包含change.md背景与需求说明、tasks.md任务拆解清单、acceptance.md验收标准实际使用中最舒服的一点是它和 git 是天然配合的。每次变更提案都走 git 分支规格文档和代码一起 review、一起合并归档后自动更新到specs/。这等于把需求变更这个原本让人头大的事情变成了和写代码一样标准化、可追踪的工程动作。为什么用 Markdown因为它是人和 AI 都能高效读写的最低成本格式。你不需要学一套新的标记语法不需要打开任何重型工具IDE 里直接改命令行里直接提交AI 也能无缝读取。你甚至可以给团队里不写代码的产品同学一份模板让他们直接提交需求变更这是传统 PRD 流程很难做到的。2.2 Superpowers一组技能包把 AI 从问答变成团队成员Superpowers 是近期社区里热度很高的一组 AI 编程技能集skills可以运行在 Claude Code、Codex CLI 一类支持 skill 协议的 AI 编程工具上。它内置了大量经过验证的开发技能比如头脑风暴、需求澄清、编写计划、TDD 循环、代码审查、调试、修复 bug、提交信息生成等等。Skill 机制可以理解成给 AI 挂载专业路径。裸调 Claude Code你问一句它答一句上下文一长就开始忘记你半小时前提过的约束。而挂载了 Superpowers 之后AI 在开始 TDD 会先加载对应的操作手册按照里面定义的步骤、约束和思考顺序来执行每一步都有明确的输入输出要求不再自由发挥。它的很多 skill 还内置了关键思考环节让 AI 在动手前先把问题想清楚。顺着这个思路你可以自己推测OpenSpec 管做什么Superpowers 管怎么做好。一个是骨架一个是肌肉。两者没有强绑定关系但合在一起才能跑出 SDDTDD 的完整闭环。维度OpenSpecSuperpowers核心职责需求建模、变更管理、规格归档执行方法论如 TDD、代码审查、调试工作产物规格文档、任务清单、验收标准代码实现、测试用例、审查输出操作方式CLI 初始化、创建 change在对话中触发对应 skill配合方式交给 AI 的输入材料AI 执行时的操作方法3. 搭建过程从零配置到跑通第一个需求3.1 环境准备OpenSpec 与 Superpowers 的安装先说环境。我目前的主力组合是 Claude Code 加 Codex CLIOpenSpec 可以直接在命令行里初始化。以 macOS 和 Linux 环境为例核心几步是这样# 安装 OpenSpec CLI具体方式以官方仓库说明为准 npm install -g openspec # 在项目根目录初始化 cd your-project openspec init初始化后项目下会出现.openspec/相关配置和specs/、changes/目录。如果你是接现有项目建议先把核心模块的现状规格补一份不用追求面面俱到至少让 AI 对系统有一个结构化认知。Superpowers 的安装稍微有点讲究。它本质上是一组 skill 文件需要安装到 AI 编程工具能读取的目录。多数支持 skill 协议的工具会读取项目本地或用户全局的.claude/skills/、.codex/skills/这类路径。常见做法是 clone 到对应目录# 以 Claude Code 为例把 skills 放进项目本地目录 git clone https://github.com/your-superpowers-repo .claude/skills/装完之后在对话中触发对应 skill比如触发 TDDAI 会读取 skill 内部的 SKILL.md 说明来约束行为。配置过程中最容易踩的坑有两处一是 skills 目录放错位置AI 完全感知不到这些技能二是权限设置不全skill 里定义的一些文件操作、命令执行被工具拦截。建议装完后先用一个简单 prompt 测试一下 AI 是否明确认领了这个 skill。3.2 核心设计一份 change 提案如何贯穿 SDD 和 TDD安装只是开始真正重要的是怎么设计 change 提案让它能丝滑衔接 TDD。我建议团队统一使用 OpenSpec 规范的模板每次新需求先跑openspec new change-name创建目录然后填充三个核心文件。先看change.md的骨架# 变更提案为购物车增加优惠券功能 ## 背景 当前购物车只支持直接结算缺少营销工具支持。 用户在下单前无法使用优惠券导致客单价提升乏力。 ## 需求说明 - 用户在购物车页面可以输入优惠券码 - 系统校验优惠券的有效性未过期、适用商品范围匹配 - 校验通过后结算总价自动扣减 - 同一订单只能使用一张优惠券 ## 影响范围 - 购物车结算流程 - 订单价格计算 - 优惠券服务DNS / 存储 / 校验逻辑然后tasks.md把实现拆成小块。注意这里的粒度要足够小最好每个 task 对应一轮 TDD 循环## 任务清单 - [ ] 1. 优惠券校验服务输入优惠券码和商品列表输出是否可用和折扣金额 - [ ] 2. 购物车结算接口接收优惠券码参数校验后返回最新总价 - [ ] 3. 前端购物车页面增加优惠券输入框和验证券交互最后是acceptance.md这部分是最关键的。验收标准不能写价格正确这种废话要写成可测试的、可交给 AI 去写测试用例的描述## 验收标准 1. 给定一个已过期的优惠券码结算接口返回错误信息 优惠券已过期 2. 给定一个正常可用的优惠券码结算总价等于原价减去折扣金额 3. 给定一个超出适用范围的优惠券码结算接口返回错误信息 该优惠券不适用于当前商品 4. 同一订单使用同一优惠券码重复提交时仅第一次生效这三份文件一就位SDD 阶段就完成了。接下来 AI 的所有动作都应该围绕这三份文件展开。这不是简单写几行需求描述而是把验收前置到了动手写码之前——这就是 SDD 最核心的杠杆。4. 实战体验用这套工作流做完一个小功能4.1 开始一个 change从规格到测试用例理论说再多不如走一遍流程。我以实际做过的优惠券功能为例演示完整的运行过程。创建 change 后我在 Claude Code 里直接给出指令让 AI 基于 change 文件开始 TDD请查看 changes/add-coupon/ 下的 change.md、tasks.md 和 acceptance.md。 按照 Superpowers 的 TDD skill 执行从 task 1 开始先写测试用例。AI 读取文件后开始为优惠券校验服务编写测试用例。由于验收标准里已经定义了具体的输入输出和错误信息测试用例的编写非常顺滑。它会先写一个失败的测试比如测试过期优惠券场景def test_expired_coupon_returns_error(): coupon_service CouponService() result coupon_service.validate(EXPIRED_CODE, [item-1]) assert result[valid] is False assert result[error] 优惠券已过期这个测试运行后必然失败——因为服务还没实现。接下来 AI 自动进入 Green 阶段写最小实现让测试通过。整个过程它会不断运行测试、观察结果、调整代码。最终 task 1 的两个测试全绿后它停下来等我确认再进入 task 2。在这个过程里我从头到尾没有手写过一行业务代码做的最多的事情是确认和观察。听起来很爽但有一个前提验收标准必须足够清晰。如果你写的验收标准是校验优惠券有效性AI 一定会给你一个模糊的实现测试也会模糊整个流水线就会开始摆烂。4.2 让 Superpowers 跑起来TDD 过程的实际指令流很多人装上 Superpowers 后发现 AI 并没有按预期工作原因是它没有被正确触发。TDD 不是一种随时生效的全局状态它需要你在对话中明确请求。我实践下来的标准指令流是激活 TDD skill使用 TDD 工作流完成当前 change 的剩余任务。 从第一个待办 task 开始严格遵循 Red-Green-Refactor 循环。触发后AI 会按 TDD skill 内部定义的流程行事大致步骤如下读取当前 change 的规格文件定位当前要处理的任务为这个任务写至少一个失败测试Red运行测试确认失败原因是功能未实现而不是其他问题用最简代码实现目标行为Green运行全量相关测试确保无回归进入重构阶段优化实现逻辑保持测试全绿更新 tasks.md 勾选已完成任务进入下一个 task这套流程的关键价值在于每一步 AI 都有明确的工作目标和完成定义而不是凭感觉写一段代码然后告诉你写完了。我在实际使用中观察到挂载 TDD skill 之后AI 写测试的频率和质量都有明显提升尤其是它会主动思考边界条件和异常输入这是裸调用时几乎不会出现的。4.3 没有 OpenSpec 时 vs 有 OpenSpec 时的差异社区里有人专门问过这个问题在没有 OpenSpec 的时候和有 OpenSpec 的时候有什么不同我自己的体验对比非常强烈。没有 OpenSpec 时AI 编程就像让一个外包团队干活但不给需求文档。你在对话里描述需求AI 边猜边写遇到模糊处就自行发挥。代码写完你觉得不对再告诉它这里不是这样它又改一遍越改越乱。需求一多上下文窗口越来越挤AI 甚至会忘记项目已有的架构约定。最后的结果是局部正确、整体混乱。有 OpenSpec 后AI 每次动手前都能读取结构化的规格文件明确自己的任务边界。需求变更时不直接改代码而是先改 change 提案再让 AI 对照新验收标准去改实现和测试。同样一个功能返工次数明显减少因为 AI 出错时你能快速定位是规格写错了还是实现跑偏了而不是稀里糊涂地来回拉扯。我自己的体感是没有 OpenSpec 时大约 30% 的 AI 产出需要返工而有了规格约束之后返工率降到 10% 左右。更重要的是心态变了——你不再担心 AI乱来因为它的每一步都有据可查。5. 打磨细节目录规范、上下文管理与 AI 角色分工5.1 项目背景下如何安排目录结构与文档状态很多人在使用 OpenSpec 时会忽略目录状态的重要性。你要清楚changes/目录下有两种东西进行中的 change 和已归档的 change。进行中的 change 是计划中的状态已归档的 change 才是已经发生的规格变更。我建议项目长期维护一个约定specs/目录是唯一事实来源你向 AI 描述系统现状时只基于它changes/目录里的进行中提案是待办事项AI 的编码任务都从这些待办里取。这样 AI 不会把历史需求和未来需求混淆起来。一个实用的目录结构示例project/ ├── specs/ │ ├── checkout.md # 购物车结算规格 │ └── coupon.md # 优惠券规格 ├── changes/ │ └── add-coupon/ │ ├── change.md │ ├── tasks.md │ └── acceptance.md └── src/状态流转也很关键需求完成并测试通过后执行 openspec 的归档操作把 change 中的规格合并到specs/对应文件中然后 change 目录就从进行中变成已归档。这个动作往往被忽略但它保证了规格文档不会腐烂。5.2 上下文管理从尽力塞到按需取AI 编程工具最大的瓶颈是上下文窗口。小型项目还好项目一大把全部代码塞进上下文的方案基本不可行。我以前试过一次把整个仓库让小模型读完再写码效果极差——无关文件反而干扰了判断。OpenSpec 的规格和任务清单天然解决了这个问题。因为它把任务拆成了颗粒度足够小的单元每次只把当前 change 的三份文件和相关模块的代码片段喂给 AI不需要它理解整个系统。比如做优惠券功能时我只让它读specs/checkout.md、changes/add-coupon/和购物车服务的源码。它在宏观上有规格指引微观上有测试用例约束两者一夹输出就很稳定。这个模式也改变了我和 AI 的协作关系。以前是帮我写代码的指令式协作现在更像是按这份规格把任务做完的工程式协作。AI 不是替我想需求而是替我把规格变成高质量的代码。5.3 厘清 AI 能力边界哪些环节适合留给人工再怎么强调 SDD、TDD也要承认 AI 不是万能的。在我这套工作流里有几个环节我不会完全交给 AI一是需求描述本身的业务判断比如优惠券的折扣规则到底怎么定这需要产品决策二是验收标准的合理性AI 可能帮你提出一些测试场景但最终要人工确认没有漏掉核心路径三是跨模块的大型架构调整这种任务拆成多个 change 分步走更稳妥。另外一个很实用的技巧是让 AI 先写验收标准你只需要做审查员。你可以在创建 change 时只提供背景和需求说明然后让 AI 根据需求补充验收标准和任务拆解你再逐条确认。这个过程既省时间又利用 AI 的覆盖面补足自己容易忽略的边界场景。审查、补漏、确认——这就是人在这个工作流里最该投入精力的地方。6. 常见问题与排查技巧实录6.1 典型问题速查表实际跑这套工作流的过程中多多少少会遇到配置、流程、协作方面的问题。我把自己遇到的问题和排查思路整理成了表格按优先级排序方便你对照排查现象可能原因排查与解决方法AI 完全感知不到 Superpowers skillskills 目录路径不对或工具未启用本地 skill 权限确认目录是否位于 AI 工具读取范围内查看工具文档确认权限设置用简单指令测试技能触发AI 频繁偏离规格文件中的验收标准上下文里没有明确指定要读取的 change 文件路径或验收标准描述太模糊开头就把文件路径写进提示词把验收标准细化成可验证的给定/当/则句式测试跑太久TDD 节奏太慢任务拆得太大一个 task 里塞了过多功能点把任务继续拆小每个 task 只围绕一个行为点测试尽量聚焦单元测试而非集成测试规格文档和代码实现逐渐脱节change 完成后没有归档或归档时修改过代码但没同步规格每次 change 合并后立即执行归档代码 review 时把规格也纳入检查范围多个 change 同时进行时互相干扰在同一个分支上同时开发多个功能一个 change 一个分支按分支管理开发与测试合并顺序按依赖关系排优先级skill 里的命令被工具拦截AI 工具的权限配置限制文件写入、终端执行等检查工具的权限策略按需授权但别图省事直接全放行AI 写的测试质量低、覆盖不到核心逻辑只让 AI写测试没有让它遵循具体方法论显式触发 TDD skill要求严格走 Red-Green-Refactor 流程并说明覆盖的具体边界场景6.2 几个看了能少走弯路的避坑经验第一不要把 OpenSpec 当作万能模板。它是一套方法论加工具不是说你初始化了就能自动化一切。它真正起作用的前提是团队认可规格先行的价值观并且愿意在 change 提案阶段投入时间。如果你只管让 AI 建模型而不写规格这套流程会变成纯粹的形式主义。第二TDD 的红绿循环千万别省红这一步。如果你让 AI 直接写实现然后顺手补测试那这个工作流的价值就损失一半。真正有价值的反馈信号来自先看到测试失败、再通过实现让它变绿这个过程。它保证了测试不是实现的自说自话。第三给 Superpowers 里的 skill 做减法。它内置了大量能力但不是每个项目都需要全部启用。尤其是团队里多人协同时技能范围越小行为越可控。我一般只启用 brainstorming、TDD、code-review、debugging 这几个核心 skill其他的按需临时开启。第四代码审查时不要只审代码还要审规格和测试的一致性。我遇到过几次代码实现正确、测试也通过但实现的功能和验收标准不是一回事的情况——因为 AI 在某个环节偷偷简化了需求。把验收标准、测试用例、实现代码三者对齐检查是保证这套工作流不跑偏的最后一道防线。7. 写在最后的一些体会这套 OpenSpec Superpowers 的 SDDTDD 工作流是我目前用过的 AI 编程方案里最接近工程化的一套。它没有发明什么新概念——规格驱动、测试驱动都是几十年的老方法论了——但它用现代工具把这些方法论变成了一线开发者真正愿意用的日常流程。好处显而易见需求可追踪规格不腐烂AI 的输出质量稳定团队协作时至少有一个共同的事实基础。代价也有一些前期需要花时间维护规格文档、把需求拆细、把验收标准写好这些都不是能完全甩给 AI 的事情。我个人在实际操作中的体会是这套流程最大的价值不是让 AI 写代码更快而是让写错代码的概率变低了。开发本来就是一场和复杂度的对抗规格和测试是两端最可靠的锚点。如果你最近也在为 AI 编程不可控而头疼可以按这篇文章搭一套试试。最开始会有一点不适感跑完两个完整 change 之后大概率就再也回不到之前裸调 AI 的状态了。