AI编程工程纪律闭环：Superpowers技能框架与TDD契约驱动实践

1. 从“氛围编程”到工程纪律：为什么我们需要重新审视 AI 协作方式

“氛围编程”这个词最近在开发者圈子里流传得越来越广，它描述的是一种让人又爱又恨的状态：你打开 AI 编程助手，用自然语言描述一个需求，AI 噼里啪啦生成一大段代码，你看了一眼觉得“嗯，差不多是这个意思”，然后直接粘贴进项目里。整个过程行云流水，充满了一种“凭感觉写代码”的松弛感。短期来看，效率确实高得惊人，一个下午就能堆出一个能跑的原型。但问题往往在几天甚至几周后集中爆发——代码逻辑前后矛盾、边界条件完全没处理、改了一个函数导致三个模块崩溃，最终演变成一场不折不扣的“代码雪崩”。

我自己就经历过这样的场景。早前用 AI 辅助做一个数据处理模块，当时觉得生成速度飞快，两天就完成了原本预估一周的工作量。结果到了联调阶段，发现 AI 生成的工具函数在不同文件里竟然有三套不同的参数约定，异常处理有的地方吞掉了错误，有的地方直接抛出未捕获的异常。排查这些问题花掉的时间，远远超过了当初“省下来”的那几天。这件事让我意识到，AI 编程的核心矛盾不在于生成能力，而在于工程纪律的缺失。

这也是为什么“Superpowers 技能框架”和“TDD 契约驱动”这两个概念开始进入我的视野。简单来说，Superpowers 技能框架是一套用于组织和管理 AI 协作流程的结构化方法，它把零散的提示词和生成结果纳入一个可复用、可验证的技能体系中；而 TDD 契约驱动则是把测试先行的理念从“人写测试”扩展到“人与 AI 共同遵守的接口契约”。两者结合，目标就是构建一个AI 工程纪律闭环——让 AI 的每一次输出都有约束、有验证、有反馈。

这篇文章适合所有正在或准备将 AI 编程助手引入日常工作流的开发者。无论你是刚接触 AI 辅助编程的新手，还是已经踩过不少坑的老手，我都会从框架设计、契约定义、实操流程到问题排查，把这条闭环路径拆解清楚。你不需要有很深的架构经验，但需要对基本的软件开发流程有概念，这样才能理解为什么某些步骤看似繁琐，实则是避免雪崩的关键。

2. Superpowers 技能框架的核心设计与选型逻辑

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

第一次听到“Superpowers 技能框架”这个名字，很容易联想到某种超能力工具包。实际上，它的核心思想非常朴素：把 AI 编程助手需要完成的任务，按照技能的维度进行拆分和封装。每个技能对应一类明确的能力，比如“生成数据库访问层代码”“编写单元测试”“重构指定函数”“生成 API 文档”等。每个技能内部包含提示词模板、输入输出规范、验证规则和示例库。

为什么需要这样做？因为直接跟 AI 对话时，每次都要重新描述上下文、重新交代约束条件，不仅效率低，而且一致性极差。今天你让它写一个“带重试的 HTTP 请求函数”，明天换个说法让它写“网络请求工具”，生成出来的代码风格、错误处理方式可能完全不同。技能框架的作用就是把这种“一次性对话”变成“可重复调用的能力单元”。

我自己的做法是，先梳理出项目中高频出现的任务类型，然后为每一类任务定义一个技能。比如在一个 Web 后端项目里，我定义了这些基础技能：数据模型定义、路由处理函数生成、中间件编写、单元测试生成、错误码映射。每个技能都有固定的输入格式（比如 JSON Schema 描述的参数）和输出格式（比如符合项目规范的代码文件），以及一组必须通过的验证检查。

2.2 技能框架的选型考量与对比

市面上并不是只有一种方式来组织 AI 协作流程。常见的还有“提示词链”“Agent 工作流”“多轮对话模板”等。我对比过几种方案，最终选择技能框架作为核心，主要基于这几个维度的考量。

技能框架最大的优势在于一致性。因为每个技能都绑定了固定的验证规则，AI 生成的结果如果不满足规则，就会被自动拦截或要求重新生成。这就像给 AI 戴上了一副“工程手套”，让它不能随意发挥。另一个优势是可积累。每当你发现一个新的边界情况，只需要更新对应技能的验证规则，所有后续调用都会自动受益。

当然，技能框架也有代价。前期需要投入时间定义技能、编写验证规则、维护示例库。如果项目本身变化极快，技能定义可能很快就过时了。所以我的建议是，先从最稳定、最高频的任务开始，逐步扩展，不要一上来就试图覆盖所有场景。

2.3 技能定义的关键要素与实操模板

一个完整的技能定义通常包含五个部分：技能名称与描述、输入参数规范、输出格式要求、验证规则集、参考示例。下面我用一个“生成数据访问层代码”的技能作为例子，展示具体的定义方式。

skill_name: generate_repository_layer description: 根据数据模型定义生成对应的数据访问层代码 input_schema: model_name: string fields: - name: string type: string nullable: boolean primary_key: string output_format: python_module validation_rules: - 必须包含 CRUD 四个基础方法 - 所有数据库操作必须使用参数化查询 - 异常必须捕获并转换为项目统一错误类型 - 每个方法必须有类型注解 examples: - input: 用户模型，字段包括 id、name、email output: 对应的 UserRepository 类代码

这个定义看起来简单，但每一条验证规则背后都是踩过的坑。比如“必须使用参数化查询”这条，就是因为早期 AI 生成过拼接 SQL 字符串的代码，虽然功能上没问题，但存在严重的安全隐患。把它写成硬性规则后，类似问题再也没有出现过。

注意：验证规则不要写得太模糊，比如“代码质量要好”这种无法自动检查的规则没有意义。每一条规则都应该能对应到一个具体的检查动作，比如正则匹配、AST 解析、或者运行测试用例。

3. TDD 契约驱动：让测试成为人与 AI 的共同语言

3.1 契约驱动的核心思想

TDD 本身不是新概念，测试先行的理念已经推广了很多年。但在 AI 协作场景下，TDD 被赋予了新的意义。传统 TDD 中，测试是人写的，用来约束人写的代码。而在 AI 协作中，测试变成了人与 AI 之间的契约——人通过测试定义“什么算正确”，AI 则负责生成满足这些测试的代码。

这个转变看似微小，实则关键。因为 AI 并不真正理解业务意图，它只能根据模式匹配生成“看起来合理”的代码。如果你只给它一段自然语言描述，它可能会生成一个功能上大致正确、但边界处理完全不符合预期的实现。而如果你给它一组明确的测试用例，它就获得了一个可验证的目标：让这些测试通过。

我通常把契约分为三个层次。第一层是接口契约，定义函数签名、参数类型、返回值结构。第二层是行为契约，定义正常情况下的输入输出对应关系。第三层是边界契约，定义异常情况、空值、极值时的处理方式。三层契约合在一起，就构成了一个完整的规格说明。

3.2 契约的编写规范与常见误区

编写契约时最容易犯的错误是“测试写得太松”。比如只测试了正常路径，没有测试空输入、超长输入、类型错误等情况。AI 在生成代码时，如果契约里没有覆盖这些情况，它就会按照自己的“理解”来处理，结果往往和你的预期不一致。

另一个常见误区是“测试依赖具体实现”。比如你写了一个测试，断言某个内部函数的调用次数。这种测试在人工编写代码时可能没问题，但在 AI 生成代码时，它会限制 AI 的实现自由度，导致生成的代码虽然通过了测试，但结构非常别扭。更好的做法是测试行为而不是实现，只关心输入和输出，不关心中间过程。

我自己的经验是，契约的粒度要适中。太粗了，AI 不知道具体要做什么；太细了，AI 被限制得太死，反而容易生成冗余代码。一般来说，一个契约对应一个公开函数或一个 API 端点比较合适。内部辅助函数不需要单独写契约，让 AI 在实现主函数时自行决定即可。

3.3 从契约到验证的自动化闭环

契约写完之后，下一步是把它接入自动化验证流程。我的做法是，在技能框架中增加一个“契约验证”环节。当 AI 生成代码后，自动运行对应的测试用例。如果全部通过，代码进入待审查队列；如果有失败，把失败信息反馈给 AI，要求它重新生成或修正。

这个闭环的关键在于反馈的质量。如果只是告诉 AI“测试失败了”，它很难定位问题。更好的做法是把失败的测试名称、期望值、实际值、错误堆栈都整理成结构化信息，作为下一轮生成的输入。我实测下来，有了详细反馈之后，AI 修正的成功率能从不到三成提升到七成以上。

# 契约验证的简化流程示意 def validate_contract(generated_code, contract_tests): results = run_tests(generated_code, contract_tests) if results.all_passed: return {"status": "pass", "code": generated_code} else: feedback = format_failures(results.failures) return {"status": "retry", "feedback": feedback}

这个流程看起来简单，但实际运行时需要处理不少细节。比如测试运行超时怎么办、生成的代码有语法错误导致测试无法运行怎么办、多次重试仍然失败怎么办。这些都需要在框架层面做好兜底策略。

4. 构建 AI 工程纪律闭环的完整实操流程

4.1 环境准备与基础工具链搭建

在开始之前，需要先准备好基础环境。我假设你使用的是 Python 技术栈，其他语言也可以参考类似的思路。核心工具包括：一个 AI 编程助手（可以是 IDE 插件或命令行工具）、一个测试框架（pytest 或 unittest）、一个代码质量检查工具（ruff 或 flake8）、以及一个版本控制工具。

第一步是建立项目的基础目录结构。我通常会把技能定义、契约文件、生成代码、验证脚本分开放置，避免混在一起。比如：

project/ skills/ # 技能定义文件 contracts/ # 契约测试文件 generated/ # AI 生成的代码 src/ # 人工编写的核心代码 validation/ # 验证脚本

这样的结构让每个环节的职责非常清晰。技能定义是“输入规格”，契约是“验收标准”，生成代码是“待检品”，验证脚本是“质检员”。当出现问题时，可以快速定位是哪个环节出了偏差。

第二步是配置 AI 助手的系统提示词。这一步很关键，因为系统提示词会贯穿整个会话，影响 AI 的所有输出。我的系统提示词通常包含这些内容：项目使用的语言和框架版本、代码风格要求（比如必须使用类型注解、必须写文档字符串）、禁止事项（比如禁止使用某些不安全的函数）、以及技能框架的调用方式说明。

提示：系统提示词不要写得太长，否则会占用大量上下文窗口，影响 AI 对具体任务的理解。把详细规范放在技能定义里，系统提示词只保留最核心的约束。

4.2 技能定义与契约编写的具体步骤

环境准备好之后，开始定义第一个技能。我建议从最简单的任务开始，比如“生成一个数据类的定义”。这个任务足够简单，容易验证，适合用来跑通整个流程。

第一步，编写技能定义文件。按照前面提到的五要素格式，把输入参数、输出格式、验证规则都写清楚。验证规则可以先从两三条开始，比如“必须包含类型注解”“必须包含文档字符串”“字段命名必须使用蛇形命名法”。

第二步，编写契约测试。针对这个数据类，测试内容包括：实例化时所有字段都能正确赋值、默认值符合预期、类型错误时抛出异常、序列化和反序列化结果一致。每个测试用例都应该是独立的，不依赖其他测试的执行结果。

第三步，调用 AI 生成代码。把技能定义和契约测试一起作为输入，让 AI 生成满足条件的代码。这里有个小技巧：在提示词中明确告诉 AI“你需要让以下测试全部通过”，并把测试代码附上。这样 AI 在生成时就会主动考虑测试的要求，而不是生成完再被动修改。

第四步，运行验证。如果测试全部通过，把生成的代码放入generated/目录，然后人工审查一遍。审查的重点不是功能正确性（测试已经验证了），而是代码的可读性、是否有冗余、是否和项目其他部分风格一致。如果测试失败，把失败信息整理后反馈给 AI，要求重新生成。

4.3 闭环运行中的参数调优与经验总结

跑通基本流程后，接下来是调优。我总结几个关键参数和经验值。

重试次数：建议设置为 3 次。第一次生成后如果失败，第二次带上失败反馈重新生成，第三次再失败的话，大概率是契约本身有问题或者任务太复杂，需要人工介入拆分。超过 3 次的重试通常是在浪费时间和 token。

契约覆盖率：不要追求 100% 覆盖。我的经验是，核心路径和主要边界情况覆盖到 80% 左右就足够了。剩下的边缘情况可以在人工审查时补充，或者等实际运行中发现问题再补测试。追求完美覆盖会导致前期投入过大，反而拖慢整体进度。

技能粒度：一个技能对应一个明确的交付物。比如“生成一个完整的 API 端点”就比“生成 API 相关代码”要好得多。粒度太粗会导致 AI 输出不稳定，粒度太细会导致技能数量爆炸，维护成本过高。

反馈信息格式：我试过几种反馈格式，最终发现“测试名称 + 期望值 + 实际值 + 错误位置”这种结构化的格式效果最好。纯文本的报错信息 AI 理解起来容易偏差，结构化信息则能准确传达问题所在。

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

5.1 生成代码通过测试但不符合项目规范

这是最常见的问题之一。AI 生成的代码功能上没问题，测试也全过了，但风格和项目其他部分格格不入。比如项目里用的是snake_case，它生成了camelCase；项目里用自定义异常，它用了内置异常。

排查思路：首先检查技能定义中的验证规则是否覆盖了这些规范。如果没覆盖，补充规则。如果覆盖了但没生效，检查规则的具体实现是否有漏洞。比如用正则检查命名风格时，要确保正则本身是正确的。

解决技巧：我通常会在技能定义中增加一个“风格检查”环节，用代码质量工具自动检查生成代码的风格。ruff 和 flake8 都支持自定义规则，可以把项目特有的规范写成配置。这样风格问题就能在验证阶段被自动拦截，不需要人工反复提醒。

另一个技巧是在系统提示词中放一个“正面示例”和“反面示例”。正面示例展示符合规范的代码片段，反面示例展示常见的不符合规范的写法。AI 对示例的敏感度远高于纯文字描述，这个方法实测能显著降低风格偏差。

5.2 契约测试本身存在缺陷导致误判

有时候问题不在 AI 生成的代码，而在契约测试本身。比如测试写得太严格，把一些合理的实现方式也判为失败；或者测试有 bug，导致正确的代码无法通过。

排查思路：当 AI 多次重试仍然无法通过测试时，先人工检查测试本身是否正确。可以手动写一个满足契约的实现，看看能否通过测试。如果手动实现也无法通过，说明测试有问题。

解决技巧：契约测试也要遵循“测试行为而非实现”的原则。避免断言内部函数的调用细节，只关注输入输出。另外，测试用例之间要相互独立，不要有执行顺序依赖。我踩过的坑是，早期写了一个测试依赖前一个测试创建的数据库记录，结果单独运行这个测试时总是失败，排查了很久才发现是测试设计问题。

注意：每次修改契约测试后，都要用已知正确的实现验证一遍，确保测试本身没有引入新的问题。这个步骤看似多余，但能避免很多无效的重试循环。

5.3 AI 生成代码的上下文丢失问题

当项目变大、技能变多时，AI 可能会“忘记”之前的约定。比如前面定义的错误码规范，在后面生成新模块时没有遵守。这是因为 AI 的上下文窗口有限，无法同时容纳所有历史信息。

排查思路：检查当前会话的上下文长度。如果接近上限，AI 的输出质量通常会明显下降。另外，检查技能定义是否被正确加载。有时候技能文件路径配置错误，导致 AI 根本没有读取到定义。

解决技巧：把长期约定写入系统提示词或项目级配置文件，而不是依赖会话历史。每次生成新模块时，只加载与该模块相关的技能定义和契约，避免无关信息占用上下文。如果项目特别大，可以考虑按模块拆分技能库，不同模块使用不同的技能集合。

我自己的做法是维护一个“核心约束”文件，里面只放最关键的几条规则，比如错误处理方式、日志格式、安全要求。这个文件的内容会注入到每次请求中，确保 AI 始终记得这些底线。其他细节规范则放在具体技能定义里，按需加载。

5.4 闭环流程运行效率低下的优化

完整跑一遍“定义技能→写契约→生成代码→验证→反馈→重试”的流程，如果每个环节都手动操作，效率可能比直接写代码还低。所以自动化是必须的。

优化方向主要有三个。第一是批量处理，把多个相似任务合并成一批，一次性生成和验证。比如需要生成五个数据访问层类，可以一次性提交五个技能调用，而不是一个一个来。第二是缓存机制，对于已经验证通过的技能输出，缓存起来，下次遇到相同输入时直接复用，不需要重新生成。第三是并行验证，多个契约测试可以并行运行，缩短等待时间。

我实测下来，经过优化后的闭环流程，完成一个中等复杂度模块（约 300 行代码）的时间可以控制在 15 分钟以内，其中包括人工审查时间。相比纯手工编写，效率提升大约在 2 到 3 倍。虽然不如“氛围编程”那种即兴生成快，但考虑到后期调试和修复的时间，整体效率反而更高。

6. 技能框架的扩展与长期维护策略

6.1 技能库的版本管理与团队协作

当技能框架从个人使用扩展到团队协作时，版本管理就变得很重要。每个技能定义都应该像代码一样纳入版本控制，每次修改都有记录，可以追溯和回滚。我通常会把技能定义放在独立的 Git 仓库里，或者放在主项目的skills/目录下，和代码一起管理。

团队协作时，需要约定技能定义的修改流程。比如新增技能需要经过评审，修改验证规则需要通知所有使用者，废弃技能需要提前标记。这些流程不需要很正式，但要有基本的共识，否则容易出现“你改了一个规则，我的生成结果全挂了”的情况。

另一个实践是给技能定义打标签，比如stable、beta、deprecated。使用者可以根据标签选择使用哪些技能。新技能先以beta状态运行一段时间，验证稳定后再升级为stable。这样可以在保证稳定性的同时，持续引入新的能力。

6.2 从单点技能到技能组合的演进

单个技能解决的是单点问题，但实际开发中往往需要多个技能配合。比如“新增一个 API 端点”这个任务，可能涉及数据模型定义、数据访问层生成、路由处理函数生成、单元测试生成等多个技能。这时候就需要技能组合的能力。

我的做法是定义一个“工作流”概念，把多个技能按顺序编排起来。工作流定义中指定每个步骤使用哪个技能、输入输出如何传递、失败时如何处理。这样就把单点能力串联成了端到端的自动化流程。

工作流的编排可以用简单的 YAML 文件描述，也可以用更复杂的编排引擎。对于大多数项目来说，YAML 文件加上一个执行脚本就足够了。关键是要把步骤之间的依赖关系和数据传递定义清楚，避免出现“上一步的输出格式和下一步的输入格式不匹配”这种低级问题。

6.3 长期维护中的经验沉淀与迭代节奏

技能框架不是一次建好就一劳永逸的。随着项目演进，新的模式会出现，旧的规则可能过时。所以需要建立定期回顾的机制。我通常每个月花半天时间，回顾过去一个月遇到的问题，看看哪些可以转化为新的验证规则或新的技能。

迭代节奏上，我建议“小步快跑”。每次只改一两个技能，改完后立即在实际任务中验证效果。不要一次性大改，否则出了问题很难定位是哪个改动导致的。另外，每次修改都要更新对应的示例库，确保示例和规则保持一致。

经验沉淀方面，我习惯把每次踩坑的记录整理成简短的笔记，附在对应技能定义的注释里。比如“2024-06 发现 AI 生成的时间处理代码没有考虑时区，增加了时区检查规则”。这样后来者看到这条规则时，能理解为什么会有这条规则，而不是觉得“这条规则好多余”。

7. 一些实操心得与最后的建议

这套闭环流程我用了大半年，最大的体会是：AI 编程的效率提升不在于生成速度，而在于减少返工。“氛围编程”之所以诱人，是因为它把反馈周期压缩到了极致，你刚说完需求，代码就出来了。但这种即时满足感掩盖了一个事实：没有约束的生成，后期修复成本极高。技能框架和契约驱动看起来增加了前期工作量，但它们把问题暴露在了生成阶段，而不是等到集成或上线时才爆发。

另一个心得是，不要试图让 AI 做它不擅长的事。AI 擅长的是模式化的代码生成、重复性的重构、根据明确规格实现功能。它不擅长的是需求分析、架构决策、模糊场景下的权衡。把这两类任务分开，让 AI 专注于它擅长的部分，人专注于判断和决策，整体效率才是最高的。

如果你准备开始尝试这套方法，我的建议是从一个小模块开始，不要一上来就全面铺开。选一个你熟悉的、边界清晰的模块，定义两三个技能，写五六条契约测试，跑通整个流程。感受一下每个环节的耗时和产出，然后再决定是否扩展到其他模块。这个过程可能需要一两天，但一旦跑通，后续的收益是持续的。

最后分享一个小技巧：在技能定义中留一个“备注”字段，记录这个技能的特殊注意事项。比如“这个技能生成的代码需要手动添加数据库索引”“这个技能不处理并发场景”。这些备注不会影响自动验证，但能在人工审查时提醒你关注特定方面。我靠这个字段避免了好几次“测试全过但上线出问题”的情况。