最近一段时间我几乎把所有精力都砸在同一个问题上怎么让 Claude Code 别在项目做到一半的时候突然“失忆”别在改了 A 模块之后把 B 模块的逻辑顺手打碎。说实话最开始我用 AI 写代码完全是聊天式编程需求往对话框里一丢它刷刷刷生成一大片代码我复制进项目跑通就完事。前期确实爽一个人能顶一个小组。但项目一复杂就露馅了——AI 经常顾头不顾尾、前后矛盾甚至一本正经地写出一段看起来没问题、实际根本没满足需求的核心逻辑。后来我把整套开发方式切换成了 OpenSpec Superpowers Claude Code 三件套流程也被我重新整理成了 SDDSpec-Driven Development规范驱动开发和 TDDTest-Driven Development测试驱动开发的组合。今天这篇就是搭建这套 SDDTDD 工作流的完整教学文档包括工具定位、目录结构、六步流程、提示词写法以及我踩过的各种坑。先说清楚这里的“工作流”指的是软件开发流程不是你在 ComfyUI、Coze、n8n 里拖拖拽拽画出来的那种可视化工作流。想让你手里的 AI 助手从“随缘交付”变成“稳定交付”的开发者都可以按这篇文档来落地这套工作流。1. 为什么要把“需求到代码”之间的空地填上SDD 和 TDD 的互补逻辑1.1 聊天式编程为什么会失控我先用一句话总结踩过的坑聊天式编程的失控不是发生在单次对话里而是发生在多次对话之间的“上下文断层”里。你让 AI 给项目加一个“用户注册”功能它会在当前对话里写出一份像模像样的代码但注册功能必然牵扯到密码存储规则、邮箱唯一性校验、数据库表变更、注册成功后的默认数据初始化甚至还有日志规范和异常处理。这些细节分散在项目各个角落AI 如果没有一个稳定、可读取的全局依据它每一次生成代码都像盲人摸象——这次摸到尾巴下次摸到耳朵前后能对上才怪。1.2 SDD 管“做什么”先给 AI 一张施工图SDD 的核心思路其实非常朴素在写任何代码之前先用结构化的 Markdown 文档把项目背景、模块职责、本次变更方案、验收标准全部写清楚。AI 不再是靠聊天记录去猜测上下文而是靠这些文档获得全局视角。你可以把 SDD 理解成建筑工程里的施工图——施工队技术再强也得先看图再砌墙而不是每次到工地上听人临时口头交代一句“这里垒个墙那里开个门”。没有施工图的 AI 写代码就像没有图纸的施工队干得越快返工越狠。1.3 TDD 管“做对没”让 AI 自己给自己设验收闸门TDD 大家应该都不陌生它的循环是红-绿-重构先写一个会失败的测试确认它确实是红的然后写最小实现让它变绿最后再做重构优化。放在 AI 身上这个节奏尤其重要因为 AI 有一个典型毛病——没有自证意识。它觉得自己写完了就是写完了至于对不对全推到运行时再说。TDD 强迫它先定义“正确”的样子再动手实现等于让 AI 自己给自己设了一道验收闸门每一段代码的交付都有一个明确的“通过/不通过”标准。1.4 分工OpenSpec 管规格Superpowers 管执行那 OpenSpec 和 Superpowers 在这套体系里各管什么我的理解是OpenSpec 是需求治理层负责把“需求”变成 AI 能读懂的规格文档Superpowers 是执行技能层负责给 AI 注入“怎么按 TDD 节奏干活”的纪律。OpenSpec 解决的是“AI 该做什么”的混乱Superpowers 解决的是“AI 怎么做才靠谱”的混乱。两件事捏在一起才是一个完整的稳定交付闭环。很多人在讨论 AI 编程时只盯着模型参数和能力但我在实际项目里的体感是模型决定上限流程决定下限。没有流程约束的强模型一样能把项目搞成一团乱麻。2. OpenSpec把散落在对话里的需求固化成可执行契约2.1 一套典型的 openspec 目录结构我第一次跑 OpenSpec 初始化时最直观的感受是它终于把“需求”这件事从人脑里搬到了文件系统里。用 OpenSpec 管理项目核心会形成这样一个目录骨架不同版本字段可能有差异但大概率是这三类内容openspec/ ├── project.md # 项目全局描述几百字讲清楚项目是什么 ├── specs/ # 已确认的规格定义相当于项目的“法律条文” │ ├── user-management.md │ └── ... └── changes/ # 待评审/进行中/已完成的变更提案 └── 2025-06-05-user-registration/ └── proposal.md # 一次变更的完整设计文档project.md 不用写太长重要的是让 AI 一眼就知道“这是什么项目、给谁用、核心能力是什么”它的作用相当于给 AI 装了一个稳定的项目大脑。specs 目录里放的是已经定下来的规格一旦确认后续所有 change 都要基于它展开。changes 目录则是每次需求从想法到落地的完整记录相当于项目的“变更流水账”。这套结构最大的价值是把原本只存在于人脑和聊天记录里的隐性知识全部变成了 AI 和人都能读取的显性文件。2.2 变更提案Change Proposal怎么起草在 OpenSpec 的工作流里change 是一等公民。每个新需求进来我不急着让 AI 写代码而是先让它起草一份变更提案。我习惯把提案文件命名为proposal.md放在openspec/changes/日期-标题/目录下。一份合格的提案通常包含以下内容变更背景为什么要做这件事当前系统缺什么、痛在哪里。变更范围会新增或修改哪些模块同时明确“这次不做哪些事”。规格变更对应 specs 目录下哪些文档需要更新旧逻辑如何迁移。测试计划准备新增哪些测试覆盖哪些关键场景。验收标准可逐条勾选的清单每条都必须能自动化验证。下面是我在项目里实际用过的一份精简模板可以直接抄走# Change Proposal: 用户注册校验增强 ## Background - 当前注册接口只做非空校验弱密码和重复邮箱会直接落库。 ## Specification Changes - 新增密码强度规则不少于8位需包含字母和数字。 - 邮箱必须唯一重复时返回 409 及明确提示文案。 - 注册成功时自动创建默认 workspace。 ## Test Plan - 新增 user_registration.spec.ts覆盖弱密码拒绝、 重复邮箱拒绝、成功注册自动创建默认空间。 ## Acceptance Criteria - [ ] 密码不满足强度时接口返回 422 且响应体说明缺失项。 - [ ] 重复邮箱注册时接口返回 409数据库无新增记录。 - [ ] 注册成功时用户表与 workspace 表各新增一条数据且关联关系正确。注意最后一个验收标准它明确写了“数据库无新增记录”和“关联关系正确”。这种颗粒度的验收项才是 AI 后续写测试时真正能翻译成断言的素材。2.3 验收标准是 OpenSpec 的隐藏王牌我发现很多人用 OpenSpec只把 change 当成一个需求描述文档来写验收标准随便糊弄两三行这等于放弃了整个工作流里最值钱的部分。验收标准本质上是“人与 AI 之间可执行的契约”它必须满足三个特点可观察、可勾选、可回归。可观察指的是结果能通过接口响应、日志、数据库状态等方式直接看到可勾选指的是每一条都硬到能毫不犹豫地打勾或打叉可回归指的是未来任何一次改动都能重新跑一遍这些验收点来确认没有破坏旧逻辑。“密码不能太弱”这种表述就是典型的无效验收AI 根本不知道“太弱”的边界在哪里。改成“密码长度小于 8 位或纯数字/纯字母时注册接口返回 422并在响应体里指出缺失项”AI 写测试时就能直接写出断言。验收标准写得越硬后面所有环节就越省心因为测试、实现、评审都可以拿它当尺子。2.4 先审提案再放行人在环路里最关键的5分钟OpenSpec 这套东西有个反直觉的地方它把人的角色从“盯着 AI 写代码”变成了“审 AI 写的规格”。我现在的节奏是AI 先生成完整的 change 提案我花 5 到 10 分钟审核重点看两件事变更范围是否最小化验收标准是否足够硬核。确认没问题后才放它进入 TDD 执行阶段。这一步省下的返工时间非常可观因为改文档的成本永远低于改代码的成本。万一 AI 一开始就理解偏了让它在这份错误理解上生成几百行代码那才是真正的灾难。先审规格再动手等于在最便宜的阶段把方向纠偏。3. Superpowers给 AI 装上 TDD 的执行肌肉3.1 Superpowers 是干什么的Superpowers 是 Claude Code 生态里的一套开源技能包GitHub 上能直接找到作者是 Jesse Vincent很多 Perl 老玩家应该认识他。简单说它把“如何系统性地完成开发任务”拆成了一堆可复用的技能比如 TDD、计划、bug 修复、代码评审等。这些技能不是普通的提示词而是加载到 Claude Code 工作区里的结构化指令包。AI 会在符合触发条件时自动调用对应技能并按照技能内置的步骤去执行任务。你可以把 Claude Code 想象成一台刚装好系统的主机Superpowers 则是给你备好的一整套“操作手感调教包”。没有这套技能包的时候AI 的行为更像自由发挥有了之后它会被一系列隐含的流程节点约束住至少在 TDD 这件事上不会再由着性子乱来。3.2 TDD 技能如何约束 AI 的每个动作Superpowers 里的 TDD 技能核心还是红-绿-重构三阶段但落到 AI 上有很多细节约束。以我观察到的 AI 行为为例技能会要求 AI 必须先写一个真实会失败的测试运行一遍确认它是红的然后才允许写实现代码实现写到测试变绿就立刻停下来不许顺手加需求绿了之后再停下来思考哪些地方需要重构。这跟普通模式下 AI 的习惯完全是两回事。没有技能约束时AI 特别喜欢“一步到位”地改五六个文件顺带解决一堆你没让它解决的问题结果测试一挂你根本定位不到是哪段代码引入的。有了 TDD 技能之后AI 会乖乖地在一个测试变红变绿之后停下来汇报进度那种失控感真的减轻了很多。我甚至觉得TDD 技能最大的价值不是“测试驱动”而是它强行把 AI 的工作切成了一小块一小块可检查、可回滚的单元。3.3 安装与生效自检Superpowers 的安装方式以官方 README 为准大致流程是把 superpowers 仓库克隆下来把里面的 skills 目录复制到 Claude Code 的配置目录比如~/.claude/skills/或者通过 Claude Code 的插件机制直接安装。装好之后我强烈建议先做一个生效验证新建一个空目录让 AI“用 TDD 方式实现一个把字符串反转的函数”然后观察它的行为。如果它上来就直接写实现代码说明技能没被加载你需要回头检查路径和配置如果它先写测试、先跑红、再写实现那就说明技能已经生效了。这个验证方法很简单但能帮你避免在真实项目里才发现技能没装好。3.4 顺带值得用的几个技能除了 TDDSuperpowers 还带了好几个实用技能。planning 技能会在动手之前先产出计划清单适合需求分析阶段bug-fixing 技能会按照系统性步骤去定位问题而不是瞎猜乱改code-review 技能会按结构化标准审查代码适合每次变更收尾时做自检。不过我建议不要一上来就把所有技能都堆给 AI先让 TDD 技能跑顺再慢慢加其他的。技能太多AI 有时候会不知道该优先调用哪一个反而影响效果。4. 六步实操从一份 Change 到一段可交付的代码4.1 环境准备把 OpenSpec 和 Superpowers 一次配齐在讲六步流程之前先把环境准备说清楚。我当时的准备步骤如下安装并登录 Claude Code确认基本对话功能正常。在项目目录执行git init建立版本管理基线。克隆 Superpowers 仓库把 skills 目录安装到 Claude Code 配置目录并做一次上节说的“反转函数”生效验证。在项目根目录执行 OpenSpec 的初始化命令生成openspec/目录骨架。具体命令以你安装到的版本帮助为准不同版本可能略有差别。编辑openspec/project.md写清项目一句话描述、核心用户、核心能力。在项目根目录的CLAUDE.md里加一行全局指令“本项目使用 OpenSpec Superpowers 工作流所有功能变更需先写 Change Proposal再用 TDD 实现。”最后一步特别重要。Claude Code 默认会读取项目里的CLAUDE.md作为全局行为约束写上这句话之后你每次开启新会话AI 都会知道这个项目不是随便聊聊天就能写的必须走规格驱动那套流程。4.2 第1步让 AI 起草 Change Proposal环境配好后进入六步流程的第一步。我在项目里建了一个.claude/commands/new-change.md文件把常用指令固化下来避免每次手打。内容参考如下请基于项目现状起草一份 Change Proposal需求是对用户注册接口增加强校验。 要求 1. 输出到 openspec/changes/ 目录文件名格式为 2025-06-05-user-registration-force-validation/ 2. 提案包含 background、specification changes、test plan、acceptance criteria 四个小节 3. 验收标准必须是可勾选、可自动化验证的表述 4. 先不要写任何实现代码这个阶段最需要注意的是严禁 AI 碰实现代码。OpenSpec 的流程要求先有设计文档再有代码顺序一旦颠倒提案就失去了约束力。AI 会去读取项目文档和相关 spec然后生成一份像样的提案。如果它写得不够细你可以直接让它补充直到验收标准里每一条都能被你翻译成测试断言。4.3 第2步人工审核把验收标准翻译成测试思路提案生成后我不会马上点同意而是花几分钟做人工审核。审核重点就三个问题需求有没有遗漏或理解偏差变更范围是不是最小化验收标准能不能逐条转化为测试断言审核通过后我会做一个小动作把提案里的验收标准逐条朗读一遍并在心里翻译成“测试应该怎么断言”。比如“重复邮箱注册时返回 409数据库无新增记录”翻译成测试就是“先请求一次注册接口再请求一次相同邮箱第二次响应状态码为 409查询数据库用户表记录数为 1”。这一步是提前帮 AI 铺好写测试的思路也能提前发现验收标准里写得模糊的地方。如果连我都翻译不出断言那这条验收标准就是无效的得打回去重写。4.4 第3步TDD 红灯先写会失败的测试提案确认后进入 TDD 执行阶段。我给 AI 的下一步指令是现在进入 TDD 实现阶段。请基于 Change Proposal: 2025-06-05-user-registration-force-validation 1. 先为验收标准中的场景编写测试禁止写实现代码 2. 运行测试确认这些测试当前是失败的红灯 3. 如果测试没有失败就继续了请立即停止并排查原因这一步是 SDD 和 TDD 的衔接点。验收标准定义“做什么”测试把“做什么”翻译成“可执行的断言”。我第一次跑这套流程时AI 生成的测试里有好几处断言过宽导致测试压根没有真正失败过。后来我强制要求“先红后绿”这毛病基本治好了。真正的红灯是很珍贵的它证明你的测试和实现之间存在真实的检测关系。4.5 第4步TDD 绿灯写最小实现红灯确认之后再给 AI 下绿灯指令2. 现在请用最小实现让上面这些测试通过不改动测试代码不额外添加需求 3. 运行全部相关测试确认全绿 4. 运行项目现有测试套件确认没有回归这里的关键词是“最小实现”。AI 极其容易在实现完需求后顺手“优化”一下别的模块这在 TDD 纪律里是不允许的。绿灯阶段只能做让测试通过的最简改动。如果它动了测试范围之外的代码我会直接打回先回滚非必要改动再重新跑测试。这样做是为了保持每次变更的可审计性——你永远知道这次改动是为了什么出问题也能快速定位。4.6 第5步重构 验收标准核对测试全绿后进入重构环节现在进入重构阶段。请在不改变测试结果的前提下 1. 检查实现代码是否有重复、命名是否有歧义 2. 应用重构建议保持代码整洁 3. 再次运行全部测试确认仍然全绿 4. 逐条核对 Change Proposal 里的 acceptance criteria 能打勾就打勾不能打勾的说明原因最后一条“逐条核对验收标准”是我后来特意加的。加了之后AI 自己就能发现漏掉的边界条件因为打勾这个动作逼着它回到需求层面重新做一次推导而不是只看测试颜色。有一次它甚至在核对时发现注册成功的用例没有检查默认 workspace 的权限字段这块测试没覆盖到于是主动补了一条测试。4.7 第6步更新规格沉淀项目记忆最后一步是把这个 change 的成果合并回 specs 目录变更已完成。请更新 openspec/specs/ 下相关规格文档 把本次变更后的行为固化为正式的规格说明 然后总结这次变更中的经验教训追加到 change 目录的 summary 文件里。这一步经常被人忽略但它才是 SDD 能“越用越顺”的关键。规格文档不是一次性垃圾而是项目的长期记忆。你把一次变更的结论沉淀进 specs下一次 AI 再起草新 change 时会带着这些历史经验做决策。团队对项目的理解也会越来越一致而不是各写各的、各改各的。这就像给一本操作手册持续做增补修订新同事上手时就不需要再从头踩一遍所有坑。4.8 一个端到端的最小示例为了让上面六步更形象我把“给用户注册接口增加强校验”这个 change 的产物串一下。提案里写了背景、范围、测试计划和三条验收标准。红灯阶段AI 生成了三组测试分别对应弱密码、重复邮箱、注册成功自动创建默认 workspace运行后确认失败。绿灯阶段AI 修改了注册接口的密码校验逻辑和邮箱唯一性检查跑通测试。重构阶段它把密码校验函数抽到了独立工具模块删掉了重复代码。收尾阶段它更新了specs/user-management.md把新的校验规则写进正式规格。整个过程下来每个阶段都有明确产物你随时能停下来检查这就是六步流程的底气。5. 这些坑我替你踩过了问题与排查实录5.1 “假测试”问题测试从头到尾没红过这是我在整套工作流里遇到最多的问题。现象是AI 写出来的测试看似覆盖了业务场景但你把实现代码故意改错测试依然能通过等于白测。根因通常是断言写得太宽比如只验证响应里有“error”字样而不验证具体错误码或者测试调用的函数和实际实现的函数压根不是同一个。对策有两个一是强制红灯要求测试必须先失败才能继续二是在审查测试时故意问 AI 一句“如果函数返回空字符串这条测试会失败吗”只要它犹豫就说明断言还需要加固。5.2 一个 change 塞了三个需求AI 上下文直接爆炸很多刚开始用 OpenSpec 的人包括我会忍不住把多个相关需求塞进同一个 change 提案。比如“注册校验增强”里又加密码找回再顺手改用户协议页面。提案写起来很爽但 AI 在 TDD 阶段就会逐渐逻辑混乱因为一次变更要追踪的点太多了上下文根本装不下。我的经验是每个 change 只做一件事可以是一个用户故事也可以是一组连续的小改动。如果一个 change 的验收标准超过 7 到 8 条就要警惕是不是塞得太满了。5.3 规格文档和实际代码漂移代码都改完了specs 文档里却还是旧逻辑这个问题我也踩过。根因很简单流程里没有把“更新规格文档”设为必做步骤AI 只要没人提醒就不会主动去做。我的解决办法是在收尾阶段的指令里强制要求 AI 更新 specs 并总结经验教训。另外每次 code review 时把 specs 和实现对照着看一遍也能防止漂移随时间积累成技术债。5.4 Superpowers 技能不生效怎么排查如果你发现 AI 根本没有按 TDD 节奏执行上来就写实现代码那就是技能没生效。排查路径我总结为四步第一检查 skills 目录位置是否被 Claude Code 扫描到路径对不对第二检查全局或项目级配置里有没有自定义拦截第三用一个最小示例比如反转字符串函数验证技能是否触发第四确认当前会话是否加载了新配置必要时重启 Claude Code。这套排查流程几乎能覆盖所有“技能失效”的情况。5.5 常见问题速查表现象最可能的根因优先处理方式测试全绿但需求没实现验收标准写得太虚测试断言过宽重写验收标准按可观察可勾选细化AI 在绿灯阶段顺手改别处缺少“最小实现”约束在提示词里强调禁止非必要改动规格更新老被跳过流程里没有把更新 specs 设为必做步骤在收尾阶段加一条专门指令TDD 技能不触发skills 没装好或路径不对先做反转函数最小验证再排查配置一个 change 太大导致失控需求拆解不到位拆成多个小 change验收标准控制在 7 条以内6. 跳出工具看本质这套工作流的底层逻辑6.1 三件套的分层执行引擎、需求契约、过程控制很多人在讨论 AI 编程时会陷入工具崇拜觉得只要装了最新、最酷的插件就能解决问题。但把 OpenSpec、Superpowers、Claude Code 放在一起看会发现它们的组合其实构成了一个非常清晰的分层架构Claude Code 是执行引擎负责实际读写代码OpenSpec 是需求契约层负责定义“做什么”Superpowers 是过程控制层负责约束“怎么做”。无论未来模型怎么换只要这个分层逻辑还在工作流就能继续跑。所以与其说是这三个工具绑定死了不如说这套方法论可以迁移到任何支持文件读写和技能定制的 AI 助手上。6.2 全栈项目中特别受益的三个场景这套工作流在三种场景下收益最大。第一种是长时间、多会话的大项目规格文档保证了每个新会话都能快速回到上下文AI 不会因为对话太长而忘记最初的目标。第二种是多人共用一个 AI 助手协作的项目change 提案让每次需求变更都可评审、可追溯不会出现“代码是谁改的、为什么这么改”这种无头悬案。第三种是需要交付质量审计的项目验收标准加测试全绿就是最直接的质量证据。当然这些收益都有一个前提你愿意花时间去写提案和审提案。6.3 反模式提醒不是所有代码都要走完整流程最后提醒一句这套工作流不是银弹。原型验证、一次性脚本、纯探索性编码硬套 SDDTDD 反而会拖慢速度。我个人会把工作分成两种模式探索模式和工作模式。探索模式随便聊、随便写代码不需要长期维护目标是快速验证想法工作模式则走完整工作流任何变更都有 change、测试、规格更新。关键是你得能分清当前任务属于哪一种别让流程变成束缚。啰嗦了不少最后再分享一个实际感受。以前我总觉得“让 AI 稳定交付”是个模型问题换个更强的模型就行。把 OpenSpec Superpowers 这套工作流真正跑起来之后我才意识到决定稳定性的关键是你有没有给 AI 一套必须遵守的流程以及你有没有一个能判断它对不对的基线。写规格、写测试、审提案这些步骤看上去确实增加了工作量但每省下来的一次返工都远超这些前期成本。如果你也正在被“AI 写得快、坑得也快”的问题折磨不妨先别急着换模型认真搭一套这样的 SDDTDD 工作流试试。我个人的经验是这套组合坚持用一个月之后你对 AI 的信任度会明显回升。