AI辅助开发如何避免代码雪崩？Superpowers技能框架与TDD契约驱动实战

1. 从“氛围编程”到工程纪律：为什么我们需要重新审视 AI 辅助开发的底层逻辑

“氛围编程”这个词最近在开发者圈子里流传得越来越广，它描述的是一种让人又爱又恨的状态：你打开 AI 编程助手，用自然语言描述一下需求，AI 哗啦啦生成一大段代码，你看了一眼觉得“嗯，差不多是这个意思”，然后直接粘贴进项目里跑起来了。第一次跑通了，你觉得自己效率翻倍；第二次改了个需求，代码开始报错；第三次想加个新功能，发现之前的代码已经变成了一团理不清的乱麻。

我自己就经历过这样的阶段。去年有一段时间，我几乎把所有能交给 AI 的编码任务都交出去了，生成速度确实快，但项目积累到一定规模之后，问题开始集中爆发：函数命名前后不一致、错误处理逻辑到处重复、边界条件全靠运气、测试覆盖率几乎为零。最要命的是，当你回头想改一个核心模块时，发现根本不敢动——因为你不知道改了之后哪些地方会崩。

这就是标题里说的“代码雪崩”。它不是某一次操作失误导致的，而是长期缺乏工程纪律的必然结果。AI 生成代码的速度越快，如果没有配套的约束机制，技术债的积累速度也会成倍增长。所以这篇文章我想认真聊一聊，怎么用一套叫 Superpowers 的技能框架，配合 TDD 契约驱动的思路，把 AI 辅助开发从“凭感觉写代码”拉回到“有纪律的工程实践”上来。

这篇文章适合几类人看：一是已经在日常工作中大量使用 AI 编程助手，但感觉代码质量在下降的开发者；二是团队里正在推行 AI 辅助开发，但苦于没有规范可循的技术负责人；三是对 TDD 和契约驱动有一定了解，但不知道如何跟 AI 工作流结合的工程师。我会尽量把每个环节的操作细节讲清楚，包括我自己踩过的坑和总结出来的技巧，让你看完之后能直接在自己的项目里复现这套方法。

2. Superpowers 技能框架的核心设计思路拆解

2.1 什么是技能框架，它解决的是什么问题

Superpowers 这个词听起来有点抽象，我把它翻译成大白话：它是一套预定义的、可组合的“技能单元”集合，每个技能单元封装了一类特定的开发任务的最佳实践。你可以把它想象成一个工具箱，里面放着各种规格的扳手、螺丝刀和量尺，而不是每次遇到问题都临时找一块铁皮来掰。

传统的 AI 辅助开发模式是“对话式”的：你跟 AI 说你想要什么，AI 给你生成代码，你再根据结果调整。这种模式的问题在于，每次对话都是独立的，AI 不记得上一次你们约定的命名规范，也不记得上一个模块的错误处理策略。结果就是每个模块都像是一个独立的小王国，风格各异，接口对不上。

技能框架的思路完全不同。它要求你在开始写代码之前，先把项目需要的能力拆解成一个个技能单元，每个技能单元有明确的输入、输出、约束条件和验收标准。比如“用户认证”是一个技能单元，“数据校验”是一个技能单元，“日志记录”是一个技能单元。每个单元都有对应的测试用例和契约定义，AI 在生成代码时必须满足这些约束。

这样做的好处是显而易见的。首先，代码的一致性有了保障，因为所有技能单元都遵循同一套规范。其次，可测试性大幅提升，因为每个单元在定义阶段就已经明确了验收标准。最后，可维护性变强了，因为当你需要修改某个功能时，你只需要找到对应的技能单元，修改它的契约，然后让 AI 重新生成实现即可，不会影响到其他模块。

2.2 技能单元的粒度怎么把握

这是我在实践中最开始遇到的一个难题：技能单元到底应该拆多细？拆得太粗，一个单元里塞了太多职责，跟没拆一样；拆得太细，单元数量爆炸，管理成本反而上升。

我的经验是，一个技能单元应该满足三个条件：第一，它有明确的单一职责，用一句话能说清楚它是干什么的；第二，它的输入和输出可以用类型定义或者接口描述清楚；第三，它可以在不依赖其他单元内部实现的情况下被独立测试。

举个例子，在一个电商类的项目里，“计算订单总价”可以是一个技能单元，它的输入是商品列表和优惠信息，输出是最终价格。但“处理订单”就不适合作为一个技能单元，因为它包含了太多子任务：校验库存、计算价格、生成订单记录、发送通知等等。这些子任务应该各自成为独立的技能单元，然后通过组合来完成完整的业务流程。

我通常会用一个简单的判断标准：如果一个技能单元的实现代码超过 200 行，那大概率是拆得不够细；如果少于 20 行，那可能拆得太细了，可以考虑跟相邻的单元合并。当然这不是硬性规定，具体还要看项目的实际情况。

2.3 技能框架与 AI 协作的接口设计

技能框架要跟 AI 编程助手配合工作，关键在于接口设计。你需要让 AI 能够理解每个技能单元的契约，并且按照契约来生成实现代码。

我的做法是为每个技能单元创建一个描述文件，里面包含以下信息：技能名称、职责描述、输入输出类型定义、约束条件、测试用例、示例实现。这个描述文件用结构化的格式编写，可以是 YAML、JSON 或者 Markdown 表格，关键是让 AI 能够解析。

当需要 AI 生成某个技能单元的实现时，我把这个描述文件作为上下文传给它，并明确要求它遵守契约中的约束条件。实测下来，这种方式生成的代码质量比直接描述需求要高出一大截，因为 AI 有了明确的边界和验收标准，不会自由发挥。

注意：描述文件中的测试用例非常关键，它不仅是给 AI 看的，也是给你自己看的。在写测试用例的过程中，你往往会发现自己对需求的理解还有模糊的地方，这时候及时澄清比等到代码写完再返工要划算得多。

3. TDD 契约驱动：让测试成为 AI 生成代码的“紧箍咒”

3.1 为什么 TDD 在 AI 辅助开发中反而更重要了

TDD 这个概念提了二十多年了，很多团队尝试过，但真正坚持下来的不多。原因很简单：人工写代码的时代，先写测试再写实现，时间成本确实比较高，尤其是在需求还不明确的时候，测试写完了可能需求就变了。

但 AI 辅助开发改变了一个关键变量：写代码的成本大幅降低了。以前写一个模块可能需要半天，现在 AI 几分钟就能生成一版。这意味着什么呢？意味着“先写测试”的时间投入占比相对变小了，而测试带来的收益反而更大了。因为 AI 生成代码的速度越快，如果没有测试作为约束，它跑偏的速度也越快。

我自己的体会是，在 AI 辅助开发的工作流里，TDD 不再是一个“最佳实践”的可选项，而是一个“质量保障”的必选项。你可以这样理解：AI 是一个能力很强但缺乏纪律的初级工程师，它写代码很快，但它不知道什么是对的什么是错的。测试用例就是你给它的“对错标准”，有了这个标准，它才能朝着正确的方向快速迭代。

3.2 契约驱动的三个层次：接口契约、行为契约、质量契约

契约驱动是 TDD 在 AI 时代的一个自然延伸。传统的 TDD 主要关注行为契约，也就是“输入什么，输出什么”。但在 AI 辅助开发中，我发现还需要关注另外两个层次：接口契约和质量契约。

接口契约定义的是模块之间的交互方式，包括函数签名、参数类型、返回值类型、异常类型等等。这个层次的契约保证了不同技能单元之间能够正确拼接。在 AI 生成代码时，我会把接口契约作为强约束传给它，要求它严格按照签名来实现。

行为契约就是我们常说的测试用例，定义的是在特定输入下应该产生什么输出。这个层次的契约保证了功能的正确性。我通常会用表格的形式来组织行为契约，每一行是一个测试场景，包含输入、预期输出和边界条件说明。

质量契约是我在实践中额外加的一个层次，它定义的是代码的非功能性要求，比如性能指标、日志规范、错误处理策略、代码风格等等。这个层次的契约在传统 TDD 中往往被忽略，但在 AI 辅助开发中非常重要，因为 AI 默认生成的代码在质量方面往往是不稳定的。

3.3 契约文件的具体写法和示例

说了这么多理论，来看一个具体的契约文件示例。假设我们要实现一个“密码强度校验”的技能单元，契约文件可以这样写：

skill: password-strength-validator responsibility: 校验用户输入的密码强度，返回强度等级和具体建议 input: password: string output: level: enum(weak, medium, strong) suggestions: list[string] constraints: - 密码长度小于8位时，level必须为weak - 密码必须包含至少一个大写字母、一个小写字母和一个数字才能达到strong - 不允许使用常见弱密码列表中的密码 - 函数执行时间不超过10毫秒 test_cases: - input: "abc" expected_level: weak expected_suggestions_contains: ["长度不足"] - input: "Abc12345" expected_level: medium expected_suggestions_contains: ["建议增加特殊字符"] - input: "Abc12345!" expected_level: strong expected_suggestions_contains: [] quality_contract: - 所有公共函数必须有JSDoc注释 - 错误处理使用自定义异常类，不使用通用Error - 日志输出使用统一的logger实例

这个契约文件写完之后，我把它连同项目的基础代码规范一起传给 AI，要求它按照契约生成实现。实测下来，AI 生成的代码一次通过测试的概率从原来的不到三成提升到了七成以上。剩下的三成主要是边界条件处理不够完善，但因为有测试用例兜底，很容易定位和修复。

提示：契约文件不需要一开始就写得完美，可以在迭代中逐步完善。我的习惯是先写核心的接口契约和行为契约，质量契约可以在第一次代码审查之后补充。

4. AI 工程纪律闭环：从需求到交付的完整实操流程

4.1 第一步：需求拆解与技能单元识别

整个流程的起点是需求拆解。拿到一个需求之后，我不会直接让 AI 写代码，而是先花时间把它拆解成技能单元。这个步骤看起来慢，但实际上是最省时间的环节，因为拆解清楚了，后面的每一步都会顺畅很多。

拆解的方法我总结为“三问法”：这个需求涉及哪些数据？这些数据经过哪些处理步骤？每个步骤的输入输出是什么？把这三个问题回答清楚，技能单元的边界基本就出来了。

举个例子，假设需求是“用户可以通过邮箱注册账号”。三问法的回答是：涉及的数据包括邮箱、密码、验证码；处理步骤包括邮箱格式校验、密码强度校验、验证码校验、账号创建、欢迎邮件发送；每个步骤的输入输出都很明确。这样我们就识别出了五个技能单元。

拆解完成之后，我会创建一个技能清单，列出所有技能单元的名称、职责和依赖关系。这个清单是后续所有工作的基础。

4.2 第二步：契约编写与测试用例设计

技能清单确定之后，接下来是为每个技能单元编写契约文件。这个步骤我通常会跟测试用例设计合并进行，因为两者是紧密相关的。

编写契约时，我会遵循“先接口后行为再质量”的顺序。接口契约相对简单，主要是类型定义和函数签名。行为契约需要仔细设计测试用例，我一般会覆盖以下几类场景：正常输入、边界输入、异常输入、并发场景（如果适用）。

测试用例的设计有一个小技巧：不要只写“应该成功”的用例，更要写“应该失败”的用例。AI 在处理失败场景时往往不够严谨，如果你不明确告诉它“这种情况下应该抛出什么异常”，它可能会返回一个空值或者静默失败，这在生产环境中是非常危险的。

4.3 第三步：AI 生成实现与自动化验证

契约和测试用例准备好之后，就可以让 AI 生成实现了。我的做法是把契约文件、测试用例和项目的基础代码规范一起作为上下文传给 AI，然后明确要求它“按照契约生成实现，确保所有测试用例通过”。

AI 生成代码之后，我会立即运行测试。如果有测试不通过，我不会直接手动修改代码，而是把失败信息反馈给 AI，让它自己修复。这个过程通常需要迭代两到三轮，但每轮的时间都很短，因为 AI 修复问题的速度很快。

这里有一个重要的经验：不要让 AI 一次生成太多技能单元的实现。我试过一次性让 AI 生成五个技能单元的代码，结果它把不同单元的职责搞混了，生成的代码耦合严重。后来我改成一次只生成一个技能单元，生成完立即验证，验证通过后再进行下一个。虽然看起来步骤多了，但总体效率反而更高。

4.4 第四步：代码审查与质量契约校验

测试通过之后，还有一步不能省：代码审查。AI 生成的代码即使测试通过了，也可能存在质量问题，比如命名不规范、注释缺失、日志过多或过少、异常处理过于宽泛等等。

我的做法是维护一份代码审查清单，每次 AI 生成代码后逐项检查。清单内容包括：命名是否符合项目规范、是否有完整的错误处理、日志级别是否合理、是否有硬编码的配置值、是否有潜在的性能问题。发现问题后，我会把具体问题反馈给 AI，让它重新生成或修改。

质量契约的校验我尽量自动化。比如代码风格可以用 lint 工具检查，测试覆盖率可以用覆盖率工具统计，性能指标可以用基准测试验证。能自动化的部分就不要靠人工，因为人工检查容易遗漏，而且不可持续。

4.5 第五步：集成验证与回归测试

单个技能单元验证通过之后，还需要进行集成验证。因为技能单元之间的交互可能会产生单独测试时发现不了的问题，比如数据格式不匹配、调用顺序错误、异常传播路径不对等等。

集成验证的方法我通常采用“逐步集成”的策略：先把两个相关的技能单元集成在一起测试，通过后再加入第三个，以此类推。这样做的好处是，当出现问题时，问题范围很容易定位，不会一下子面对一大堆可能的故障点。

回归测试是最后一道防线。每次修改或新增技能单元之后，我都会运行全量测试，确保没有破坏已有的功能。在 AI 辅助开发中，回归测试尤其重要，因为 AI 修改代码时可能会影响到它没有意识到的其他模块。

5. 常见问题与排查技巧实录

5.1 AI 生成的代码不遵守契约怎么办

这是最常见的问题之一。AI 有时候会“自作主张”，明明契约里写了要抛出特定异常，它却返回了一个 null；明明接口定义里参数是必填的，它却加了个默认值。

我的排查思路是这样的：首先检查契约文件是否足够明确。很多时候问题出在契约本身有歧义，AI 理解成了另一种意思。比如“密码长度小于8位时返回weak”这句话，AI 可能理解成“小于等于8位”，也可能理解成“小于8位但大于0位”。把边界条件写清楚，问题往往就解决了。

如果契约已经很明确但 AI 仍然不遵守，那可能是上下文太长了，AI 的注意力被其他信息分散了。这时候我会把契约文件单独提取出来，作为唯一的上下文传给 AI，让它专注于这一个技能单元。实测下来，这种方式对提高契约遵守率非常有效。

还有一个技巧是在契约文件的开头加上一句强约束：“以下契约是硬性要求，任何违反契约的实现都是不可接受的。”这句话看起来简单，但确实能提高 AI 的遵守程度。

5.2 测试用例通过但实际运行出问题

这种情况通常意味着测试用例的覆盖不够全面。AI 生成的代码可能只满足了测试用例中明确列出的场景，但对于没有列出的场景处理不当。

我的应对方法是补充“对抗性测试用例”。具体来说，就是故意设计一些刁钻的输入，看看代码会不会崩溃。比如对于字符串处理函数，我会测试空字符串、超长字符串、包含特殊字符的字符串、包含 Unicode 字符的字符串等等。对于数值处理函数，我会测试零、负数、极大值、极小值、浮点数精度边界等等。

这些对抗性测试用例不需要一开始就全部写完，可以在实际运行中发现问题后逐步补充。关键是要养成习惯：每次发现一个测试用例没有覆盖到的场景，就把它补充到契约文件里，这样下次 AI 生成代码时就会自动考虑这个场景。

5.3 技能单元之间的依赖关系变得复杂

随着项目规模增长，技能单元之间的依赖关系可能会变得错综复杂，形成一个难以维护的依赖网。这是技能框架在实践中面临的一个真实挑战。

我的经验是定期进行依赖关系审查。具体做法是画一张依赖图，看看有没有循环依赖、有没有过度依赖、有没有可以合并的单元。如果发现某个技能单元被大量其他单元依赖，那它可能承担了过多的职责，需要考虑拆分。如果发现两个技能单元总是成对出现，那它们可能应该合并成一个。

另外，我会尽量让技能单元之间的依赖通过接口进行，而不是直接依赖具体实现。这样即使某个单元的内部实现发生了变化，只要接口不变，依赖它的其他单元就不需要修改。这个原则在 AI 辅助开发中尤其重要，因为 AI 修改代码的频率很高，接口稳定是保证系统整体稳定性的关键。

5.4 常见问题速查表

5.5 我踩过的几个坑

第一个坑是契约写得太细。一开始我恨不得把每一行代码的逻辑都写进契约里，结果契约文件比实现代码还长，维护成本极高。后来我意识到，契约应该关注“做什么”而不是“怎么做”，具体的实现细节留给 AI 去发挥。契约只需要定义清楚输入输出、约束条件和验收标准就够了。

第二个坑是忽视质量契约。有段时间我只关注功能测试是否通过，忽略了代码风格、日志规范、错误处理等非功能性要求。结果项目积累了大量风格不一致的代码，后期维护非常痛苦。后来我把质量契约纳入必填项，每次生成代码后都用自动化工具检查，情况才好转。

第三个坑是过度依赖 AI 修复。当测试不通过时，我一开始总是让 AI 自己修复，但有时候 AI 会“为了通过测试而通过测试”，比如把测试用例改了而不是修复实现代码。后来我明确规定：AI 只能修改实现代码，不能修改测试用例和契约文件。如果需要修改契约，必须由我人工确认。

6. 工具链选型与团队落地建议

6.1 工具选型的基本原则

工具选型这件事，我的原则是“够用就好，不要为了工具而工具”。技能框架和 TDD 契约驱动的核心是流程和纪律，工具只是辅助手段。你完全可以用最简单的文本文件和命令行工具来实践这套方法，不必追求大而全的平台。

不过有几个环节的工具确实能显著提升效率。契约文件的管理我推荐用版本控制工具，跟代码一起管理，这样契约的变更历史可以追溯。测试运行我推荐用支持 watch 模式的测试框架，这样每次代码变更后测试会自动运行，反馈周期更短。代码质量检查我推荐用 lint 工具加格式化工具的组合，能自动发现和修复大部分风格问题。

6.2 团队推行的渐进式策略

如果你想把这套方法推广到团队，我的建议是不要一上来就全面铺开。先找一个小项目或者一个非核心模块做试点，积累经验后再逐步推广。

推行的第一步是统一契约文件的格式和模板。团队需要约定好契约文件放在哪里、用什么格式、包含哪些必填字段。这一步看起来简单，但如果不统一，后续的协作会非常混乱。

第二步是建立代码审查清单。把质量契约中的检查项整理成清单，每次代码审查时逐项核对。清单不需要很长，但每一项都要具体可操作。

第三步是定期回顾和优化。每隔一段时间，团队一起回顾一下哪些契约写得好、哪些写得不好、哪些问题反复出现。根据回顾结果调整契约模板和审查清单，让整套流程持续进化。

6.3 度量与持续改进

任何工程实践都需要度量才能持续改进。我关注的度量指标包括：AI 生成代码的一次通过率、测试覆盖率、代码审查发现的问题数量、回归测试失败率。

一次通过率反映的是契约质量和 AI 理解能力的匹配程度。如果这个指标偏低，说明契约需要写得更明确，或者需要调整传给 AI 的上下文。测试覆盖率反映的是测试用例的完备程度，但要注意覆盖率不是越高越好，关键是覆盖到关键路径和边界条件。代码审查发现的问题数量反映的是质量契约的执行效果，如果问题数量持续偏高，说明质量契约需要加强。回归测试失败率反映的是系统的稳定性，如果这个指标上升，说明技能单元之间的耦合可能出了问题。

这些指标不需要每天看，我通常每周统计一次，每月做一次趋势分析。关键不是数字本身，而是数字背后的原因和改进方向。

7. 一个完整的实操案例：从零搭建用户注册模块

7.1 需求分析与技能单元拆解

假设我们要为一个 Web 应用搭建用户注册模块。需求描述是：用户可以通过邮箱注册账号，注册时需要填写邮箱、密码和确认密码，系统需要校验邮箱格式、密码强度、两次密码是否一致，校验通过后创建账号并发送欢迎邮件。

按照三问法拆解：涉及的数据有邮箱、密码、确认密码、用户记录、邮件内容；处理步骤有邮箱格式校验、密码强度校验、密码一致性校验、账号创建、欢迎邮件发送；每个步骤的输入输出都很明确。识别出的技能单元包括：邮箱校验器、密码强度校验器、密码一致性校验器、账号创建器、欢迎邮件发送器。

7.2 契约文件编写

以密码强度校验器为例，契约文件如下：

skill: password-strength-validator responsibility: 校验密码强度，返回强度等级和建议 input: password: string output: level: enum(weak, medium, strong) suggestions: list[string] constraints: - 长度小于8位返回weak - 长度大于等于8位且包含大写字母、小写字母、数字中的任意两种返回medium - 长度大于等于8位且同时包含大写字母、小写字母、数字返回strong - 不允许密码与邮箱前缀相同 test_cases: - input: "abc" expected_level: weak - input: "Abc12345" expected_level: medium - input: "Abc12345!" expected_level: strong - input: "test@example.com" expected_level: weak note: 密码与邮箱前缀相同 quality_contract: - 函数执行时间不超过5毫秒 - 使用项目统一的验证结果对象返回 - 不输出任何日志

7.3 AI 生成与验证过程

把契约文件传给 AI 后，它生成了第一版实现。运行测试后发现两个问题：一是密码与邮箱前缀相同的判断逻辑没有实现，二是返回值格式跟项目规范不一致。把这两个问题反馈给 AI，它生成了第二版。第二版通过了所有测试用例，代码审查也符合质量契约要求。

整个过程中，AI 生成代码用了大约两分钟，测试和修复用了大约五分钟。如果人工从头写这个模块，包括写测试和调试，大概需要半小时左右。效率提升是明显的，但更重要的是，生成的代码有完整的测试覆盖和明确的契约约束，后续维护和修改都有据可依。

7.4 集成与回归

五个技能单元都单独验证通过后，进行集成测试。集成过程中发现了一个问题：账号创建器在创建账号后返回的用户对象中，密码字段没有被清除，存在安全隐患。这个问题在单独测试时没有暴露，因为单独测试时没有关注返回对象的字段内容。

修复方案是在账号创建器的契约中增加一条约束：“返回的用户对象中密码字段必须为空或不存在”。更新契约后让 AI 重新生成实现，问题解决。这个案例说明，集成测试和契约的持续完善是保证系统质量的关键环节。

8. 关于这套方法的一些个人体会

写了这么多，最后分享几点我在实践中的真实感受。这套方法不是银弹，它不能解决所有问题，但它确实能把 AI 辅助开发从“碰运气”变成“可预期”。最大的变化是心态上的：以前用 AI 写代码，心里总是悬着，不知道什么时候会出问题；现在有了契约和测试兜底，心里踏实多了。

另外一点体会是，契约的编写能力是需要练习的。一开始我写的契约要么太模糊要么太琐碎，经过几个项目的迭代才慢慢找到感觉。如果你刚开始尝试，不要追求一步到位，先写核心的接口和行为契约，质量契约可以后续补充。重要的是养成“先定义再实现”的习惯，这个习惯本身比契约写得多完美更重要。

还有一个意外收获是，这套方法让我对需求的理解更深入了。因为写契约和测试用例的过程，本质上是在逼自己把需求想清楚。很多以前会忽略的边界条件和异常场景，在写契约的时候自然而然地就被发现了。从这个角度说，契约驱动不仅提升了代码质量，也提升了需求分析的质量。

如果你也在用 AI 辅助开发，并且遇到了代码质量下降、维护困难的问题，我建议你从一个小模块开始试试这套方法。不需要全套照搬，先从一个技能单元、一份契约、一组测试用例开始，感受一下有纪律的 AI 协作是什么体验。试过之后你可能会发现，AI 真正的价值不在于写代码有多快，而在于它能在一个清晰的框架内稳定地输出高质量的结果。