1. 从“氛围编程”到工程纪律为什么我们需要重新审视AI辅助开发的底层逻辑“氛围编程”这个词最近在开发者圈子里流传得越来越广它描述的是一种极其普遍的工作状态打开AI编程助手用自然语言描述一下想要什么然后看着代码一行行自动生成感觉对了就继续感觉不对就重新生成一版。整个过程行云流水像在跟一个懂你的搭档聊天效率感拉满。但问题恰恰出在这里——当“感觉”取代了“验证”当“看起来对”取代了“确实对”代码库就开始悄悄积累一种新型的技术债我把它叫做“氛围债”。这种债务的可怕之处在于它的隐蔽性。传统技术债你至少知道哪里欠了——没写测试、没做抽象、硬编码太多。但氛围债不一样它披着“AI生成”的外衣代码风格统一、注释齐全、甚至看起来逻辑自洽可一旦进入真实运行环境边界条件、并发场景、异常路径就开始集体暴雷。我见过一个项目三天内用AI辅助生成了近两万行代码功能演示完美通过结果上线第一天就因为一个空指针异常导致核心链路雪崩回滚都来不及。Superpowers技能框架、TDD契约驱动、AI工程纪律闭环——这三个词放在一起指向的正是同一个问题我们如何把AI从“代码生成器”变成“工程协作者”。Superpowers不是某个具体工具而是一套技能组织范式它把开发者的能力拆解成可组合、可验证、可复用的技能单元每个单元都有明确的输入输出契约。TDD契约驱动则是把测试从“事后验证”变成“事前约定”让AI在生成代码之前先理解“什么叫做对了”。而工程纪律闭环说白了就是一套让AI辅助开发不失控的流程约束——从需求拆解到代码生成从测试覆盖到集成验证每一步都有明确的准入门槛和退出标准。这套东西适合谁如果你只是用AI写个脚本、做个原型那确实不需要这么重。但如果你在维护一个长期迭代的项目团队里有多个开发者同时用AI辅助编码或者你正在构建对稳定性有要求的生产系统那这套框架就是刚需。它解决的核心问题是如何让AI的生成能力与工程的验证能力形成闭环而不是让AI的“自信输出”变成团队的“集体盲区”。我在这篇文章里会把这套框架拆开揉碎从设计思路到实操细节从工具选型到避坑经验尽量把每个环节的“为什么”讲清楚。不是因为它复杂而是因为太多人只看到了AI生成代码的爽感忽略了背后需要的工程约束。下面我们进入正题。2. Superpowers技能框架的核心设计与拆解思路2.1 为什么是“技能”而不是“提示词”大多数人用AI辅助编程的方式是写提示词——把需求描述清楚让AI生成代码。这种方式的问题在于提示词是一次性的、上下文相关的、难以复用的。你今天写了一个完美的提示词生成了用户认证模块明天换个项目想复用发现上下文变了、技术栈变了、业务规则变了提示词直接失效。Superpowers技能框架的核心洞察是把“提示词”升级为“技能”。技能和提示词的本质区别在于技能有明确的契约——输入是什么、输出是什么、依赖什么、保证什么。一个“生成RESTful接口”的技能它的输入是资源定义和数据模型输出是符合特定规范的控制器代码、路由配置和验证逻辑依赖是项目的基础框架和ORM层保证是生成的代码必须通过预设的契约测试。这种设计的好处是显而易见的。首先技能可以被版本化管理你可以像管理代码一样管理技能每次修改都有记录、可回滚。其次技能可以被组合一个“用户注册”技能可以调用“生成数据模型”技能、“生成接口”技能和“生成验证逻辑”技能形成技能树。最重要的是技能可以被验证——因为契约是明确的你可以自动检查AI的输出是否符合预期而不是靠人眼去review。我试过在一个中型项目里把常用的开发任务拆成二十多个技能从“生成数据库迁移脚本”到“生成单元测试骨架”每个技能都有对应的契约文件。结果是在后续三个月的迭代中AI辅助生成的代码首次通过率从不到四成提升到了七成以上代码review的时间成本下降了将近一半。2.2 技能框架的层次结构Superpowers技能框架通常分为三个层次原子技能、组合技能和领域技能。原子技能是最小的可执行单元比如“生成一个TypeScript接口定义”、“生成一个Python数据类”、“生成一个SQL查询语句”。这些技能的特点是输入输出极其明确几乎不需要上下文AI生成的准确率很高。原子技能的价值在于它们是构建更复杂技能的基础而且可以被独立测试和验证。组合技能是把多个原子技能按照特定顺序组合起来完成一个完整的开发任务。比如“生成一个CRUD模块”就是一个组合技能它内部会依次调用“生成数据模型”、“生成数据库迁移”、“生成接口定义”、“生成控制器逻辑”、“生成单元测试”等原子技能。组合技能的关键在于编排逻辑——什么顺序调用、什么条件下跳过、失败后如何回滚。领域技能是最高层次的技能它绑定特定的业务领域或技术栈。比如“生成电商订单处理逻辑”就是一个领域技能它内部不仅包含组合技能还包含领域特定的规则和约束——订单状态机怎么流转、库存扣减的并发怎么处理、支付回调的幂等怎么保证。领域技能通常需要团队根据自身业务特点定制很难直接复用。这种层次结构的设计思路是越底层的技能越通用、越稳定、越容易验证越高层的技能越具体、越需要定制、越依赖人工判断。在实际操作中我建议先把原子技能做扎实确保每个原子技能的契约测试都能稳定通过然后再往上构建组合技能和领域技能。跳过原子技能直接做领域技能结果往往是空中楼阁看起来很美但一碰就碎。2.3 技能契约的编写要点技能契约是Superpowers框架的核心它定义了“什么叫做对了”。一份好的技能契约应该包含以下几个部分输入规范明确描述技能需要哪些输入参数每个参数的类型、格式、约束条件。比如“生成数据模型”技能的输入可能包括模型名称字符串符合PascalCase命名规范、字段列表数组每个字段包含名称、类型、是否可空、默认值、索引定义可选数组。输出规范明确描述技能会产生哪些输出输出的格式和结构。对于代码生成类技能输出通常是文件路径和文件内容的映射。输出规范还应该包含代码风格约束——缩进用几个空格、是否使用分号、导入语句的排序规则等。前置条件技能执行前必须满足的条件。比如“生成数据库迁移”技能的前置条件可能是项目已经初始化了ORM框架、数据库连接配置已经存在、目标模型的数据类已经生成。后置条件技能执行后必须满足的条件。这是契约测试的核心依据。比如“生成接口”技能的后置条件可能是生成的控制器类必须包含指定的HTTP方法注解、必须调用指定的服务层方法、必须返回指定的响应类型。异常处理当输入不满足规范或前置条件不满足时技能应该如何处理。是抛出明确的错误信息还是尝试自动修复还是降级到某个默认行为。编写契约时最容易犯的错误是“过度约束”——把太多细节写进契约导致技能变得僵化稍微换个场景就无法使用。我的经验是契约应该约束“必须正确”的部分对于“可以灵活”的部分留出空间。比如代码的变量命名可以交给AI决定但函数的输入输出类型必须严格约束。2.4 技能框架与AI模型的协作模式Superpowers框架并不绑定特定的AI模型它更像是一层“协议层”把AI模型的生成能力封装成符合契约的技能。在实际操作中我通常会把技能契约作为系统提示词的一部分注入给AI模型然后在用户提示词中提供具体的输入参数。这种协作模式的关键在于“契约前置”——AI模型在生成代码之前必须先理解契约的要求。我试过两种方式一种是把契约放在系统提示词里让AI在每次生成时都参考另一种是把契约作为独立的验证步骤AI生成代码后再用契约去检查。实测下来第一种方式的首次通过率更高因为AI在生成时就有了明确的约束第二种方式更适合作为兜底防止AI在复杂场景下“忘记”契约。还有一个细节值得注意技能契约的粒度要适中。太粗的契约比如“生成一个完整的用户模块”会让AI有太多自由发挥的空间生成结果不可控太细的契约比如“生成一个变量声明”又会让技能数量爆炸维护成本太高。我的经验是一个技能对应一个“可独立测试的代码单元”比如一个类、一个函数、一个配置文件这样既保证了可控性又不会过于琐碎。3. TDD契约驱动的实操要点与核心环节实现3.1 从“测试后写”到“契约先行”的思维转变TDD本身不是新概念但在AI辅助开发的场景下它的意义被放大了。传统开发中测试后写虽然不好但至少开发者对代码逻辑是理解的补测试的时候还能发现一些问题。但在AI辅助开发中如果你不先写测试AI生成的代码你很可能只是“扫一眼”就过了因为代码看起来太合理了——命名规范、注释完整、结构清晰你很容易产生“应该没问题”的错觉。契约驱动的TDD把这个顺序彻底反过来先定义“什么叫做对了”再让AI去生成“可能对的代码”最后用契约去验证。这个顺序的调整带来的最大好处是你不再依赖对AI的“信任”而是依赖对契约的“验证”。具体操作上我通常会把一个开发任务拆成三步第一步用自然语言描述需求让AI帮我生成测试用例的骨架第二步人工review和补充测试用例确保覆盖了正常路径、边界条件和异常场景第三步把测试用例作为契约的一部分让AI生成实现代码然后运行测试验证。这个流程听起来比“直接让AI写代码”慢但实际算总账是快的。因为直接让AI写代码你省下的时间会在后续的debug、review和返工中加倍还回去。而契约驱动的流程虽然前期多花了时间定义测试但生成的代码首次通过率高返工少整体效率反而更高。3.2 契约测试的编写规范契约测试和普通单元测试的区别在于契约测试是“面向接口”的它不关心内部实现细节只关心输入输出是否符合约定。这种特性使得契约测试特别适合AI辅助开发场景——因为AI生成的代码内部实现可能每次都不一样但只要输入输出符合契约就是可接受的。编写契约测试时我遵循几个原则一个契约测试只验证一个行为。比如“用户注册”这个技能契约测试应该分别验证用户名重复时返回错误、密码强度不足时返回错误、邮箱格式不正确时返回错误、正常注册时返回用户ID。每个测试用例只关注一个行为这样当测试失败时你能快速定位是哪个契约被违反了。契约测试必须可独立运行。不依赖外部数据库、不依赖网络请求、不依赖其他测试的执行顺序。我通常会用内存数据库或mock对象来隔离外部依赖确保契约测试可以在任何环境下快速运行。契约测试的断言要具体。不要只断言“返回了错误”要断言“返回了错误码USERNAME_DUPLICATE”和“错误信息包含‘用户名已存在’”。具体的断言才能给AI提供明确的修正信号。下面是一个契约测试的示例结构以Python为例# 契约用户注册技能 # 输入用户名、密码、邮箱 # 输出成功时返回用户ID失败时返回错误码和错误信息 def test_register_duplicate_username(): # 前置条件用户名existing_user已存在 setup_existing_user(existing_user) # 执行 result register_user(existing_user, ValidPass123, testexample.com) # 断言 assert result.success False assert result.error_code USERNAME_DUPLICATE assert 用户名已存在 in result.error_message def test_register_weak_password(): result register_user(new_user, 123, testexample.com) assert result.success False assert result.error_code WEAK_PASSWORD assert 密码强度不足 in result.error_message def test_register_success(): result register_user(new_user, ValidPass123, testexample.com) assert result.success True assert result.user_id is not None assert isinstance(result.user_id, str)这种契约测试的写法AI模型很容易理解——它知道输入是什么、期望输出是什么、边界条件在哪里。在实际操作中我会把这些契约测试作为提示词的一部分提供给AI让它在生成实现代码时参考。3.3 契约驱动下的AI代码生成流程有了契约测试之后AI代码生成的流程就变得非常清晰了。我通常按照以下步骤操作第一步准备契约文件。把技能契约和契约测试整理成一个结构化的文档包括输入规范、输出规范、前置条件、后置条件和测试用例。这个文档不需要很正式但必须完整。第二步构造提示词。提示词的结构通常是系统提示词包含技能契约的摘要和代码风格约束用户提示词包含具体的输入参数和契约测试的完整内容。我试过把契约测试直接放在用户提示词里效果比放在系统提示词里更好因为AI在生成时会“看到”具体的测试用例更容易生成符合预期的代码。第三步生成代码并运行测试。AI生成代码后立即运行契约测试。如果测试通过进入人工review环节如果测试失败把失败信息反馈给AI让它修正。这里有个技巧不要一次性把所有失败信息都丢给AI而是按优先级逐个修复。先修复导致测试崩溃的错误再修复断言失败的错误最后处理代码风格问题。第四步人工review和补充。契约测试通过不代表代码就是完美的。人工review主要关注几个方面代码的可读性、是否有明显的性能问题、是否有安全漏洞、是否与现有代码风格一致。如果发现问题可以手动修改也可以把问题描述给AI让它重新生成。这个流程我用了大概半年最大的感受是AI生成的代码质量变得“可预测”了。以前是开盲盒现在是流水线——虽然偶尔还是会有意外但整体上可控性大大提升。3.4 契约的版本管理与演进契约不是一成不变的。随着业务需求的变化契约也需要演进。比如“用户注册”技能最初可能只要求用户名和密码后来增加了邮箱验证、手机号绑定、邀请码校验契约就需要相应扩展。契约演进的关键是“向后兼容”。每次修改契约时先问自己这个修改会不会破坏已有的测试用例如果会是应该修改测试用例来适应新契约还是应该保持旧契约不变、新增一个技能来处理新需求我的经验是尽量保持原子技能的契约稳定把变化放在组合技能或领域技能层面。比如“生成数据模型”这个原子技能它的契约应该只关心模型的结构定义不关心业务规则。业务规则的变化应该体现在组合技能层面通过编排不同的原子技能来实现。契约的版本管理我通常用Git来管理每个技能一个目录目录下包含契约文件、测试文件和示例代码。每次修改契约都提交一个commitcommit message里说明修改原因和影响范围。这样当某个技能出问题时可以快速回滚到之前的版本。还有一个细节契约测试的执行应该自动化。我通常会在CI流程里加入契约测试的执行步骤每次代码提交都自动运行所有技能的契约测试。如果某个技能的契约测试失败CI会阻止合并并通知相关开发者。这种自动化约束是工程纪律闭环的重要组成部分。4. AI工程纪律闭环的构建与常见问题排查4.1 工程纪律闭环的四个环节AI工程纪律闭环的核心是“不让未经验证的代码进入代码库”。这个闭环包含四个环节需求拆解、技能匹配、代码生成、验证集成。需求拆解环节的目标是把一个模糊的需求转化为明确的技能调用序列。比如“用户可以通过手机号注册”这个需求拆解后可能对应生成手机号验证技能、生成短信验证码技能、生成用户注册技能、生成注册接口技能。拆解的质量直接决定了后续环节的顺利程度——拆得太粗AI生成的结果不可控拆得太细技能数量爆炸维护成本高。技能匹配环节的目标是为每个拆解后的子任务找到对应的技能。如果现有技能库里有匹配的技能直接调用如果没有需要先创建新技能。创建新技能时先写契约测试再让AI生成实现最后把新技能加入技能库。代码生成环节就是前面说的契约驱动流程。这个环节的关键是“快速反馈”——AI生成代码后立即运行契约测试失败立即反馈不要让问题积累。验证集成环节的目标是确保新生成的代码与现有代码库兼容。这个环节包括运行全量测试套件、检查代码风格一致性、检查依赖冲突、检查性能影响。我通常会在CI流程里加入这些检查任何一项不通过都阻止合并。这四个环节形成一个闭环每次代码生成都会产生新的契约测试新的契约测试会加入技能库技能库的丰富又会提升后续需求拆解的效率和准确性。这个闭环运转得越好AI辅助开发的“失控感”就越低。4.2 常见问题与排查技巧实录在实际操作中我遇到过不少问题这里整理成速查表方便对照排查问题现象可能原因排查方法解决方案AI生成的代码首次测试通过率低契约描述不清晰或测试用例覆盖不足检查契约文件是否包含完整的输入输出规范检查测试用例是否覆盖边界条件补充契约细节增加边界测试用例把失败信息反馈给AI重新生成契约测试运行速度慢测试依赖了外部资源或测试用例过多检查测试是否使用了真实数据库或网络请求检查单个技能的测试用例数量用mock替换外部依赖拆分过大的技能把集成测试和契约测试分开技能之间互相冲突技能契约的输入输出定义不一致检查相关技能的契约文件看是否有类型不匹配或命名冲突统一技能契约的命名规范建立技能之间的依赖关系图避免循环依赖AI生成的代码风格不一致系统提示词中的风格约束不够具体检查系统提示词是否包含了缩进、命名、导入排序等细节在系统提示词中加入具体的代码风格示例或者用代码格式化工具自动处理契约演进导致旧测试失败契约修改没有考虑向后兼容检查契约修改是否影响了已有测试用例的断言尽量保持原子技能契约稳定把变化放在组合技能层面必要时为旧契约保留兼容层除了这些常见问题还有几个“踩过的坑”值得单独说第一个坑是“过度依赖AI生成测试”。我试过让AI根据需求描述直接生成契约测试结果生成的测试用例虽然能跑但覆盖的场景很有限边界条件基本没覆盖。后来我改成“AI生成测试骨架人工补充边界用例”效果好很多。第二个坑是“技能粒度过细”。一开始我把技能拆得很细比如“生成一个变量声明”、“生成一个if语句”结果技能数量爆炸维护成本极高而且AI在调用这些细粒度技能时经常“忘记”上下文。后来我把粒度调整到“一个可独立测试的代码单元”比如一个函数、一个类情况就好多了。第三个坑是“忽略代码风格约束”。AI生成的代码风格如果不一致虽然功能没问题但代码review时会很痛苦。后来我在系统提示词里加入了具体的代码风格示例并且在CI流程里加入了自动格式化步骤这个问题才解决。4.3 工程纪律闭环的度量与优化闭环建起来之后需要持续度量和优化。我通常关注几个指标契约测试通过率AI生成的代码首次运行契约测试的通过率。这个指标反映了契约描述的质量和AI模型的能力。通过率低于六成说明契约需要细化通过率高于八成说明契约和AI的协作已经比较成熟。返工率AI生成的代码需要人工修改的比例。这个指标反映了生成代码的可用性。返工率高的原因可能是契约不清晰、AI模型能力不足、或者需求本身模糊。技能复用率新需求中直接复用已有技能的比例。这个指标反映了技能库的积累效果。复用率越高说明技能库越丰富后续开发的效率越高。闭环周期时间从需求拆解到代码合并的平均时间。这个指标反映了整个闭环的效率。周期时间过长说明某个环节有瓶颈需要针对性优化。我自己的经验是闭环刚建起来的时候这些指标都不会太好看——契约测试通过率可能只有五成返工率可能超过三成。但随着技能库的积累和契约的细化指标会逐步改善。大概两三个月后契约测试通过率能稳定在七成以上返工率降到两成以下这时候整个流程就比较顺畅了。4.4 从工具到习惯工程纪律的落地心得最后说点务实的。Superpowers框架、TDD契约驱动、工程纪律闭环这些东西听起来很系统但落地的时候最大的挑战不是技术而是习惯。我见过不少团队工具都配齐了契约模板也有但开发者还是习惯直接让AI生成代码跳过契约测试。问原因回答是“太慢了”、“赶进度”、“先这样后面再补”。结果就是氛围编程的老路代码库越来越乱最后不得不花大力气重构。我的建议是不要试图一次性把整套框架落地。先从一个小项目开始选一个最常用的技能把契约测试写起来坚持两周。等习惯了“先写测试再生成代码”的节奏再逐步扩展到更多技能。等技能库有一定积累了再引入组合技能和领域技能。这个过程可能需要几个月但每一步都是扎实的。还有一个心得是契约测试不要追求完美。一开始写的契约测试可能覆盖不全、断言不够精确这都没关系。重要的是先跑起来然后在实践中逐步完善。我自己的技能库也是迭代了十几版才稳定下来的第一版现在回头看简直惨不忍睹。工程纪律的本质不是约束而是保护。它保护你不被AI的“自信输出”带偏保护你的代码库不被氛围债侵蚀保护你的团队不在深夜被线上故障叫醒。这套东西值得花时间去建而且越早建越好。 
长河君 · 2026/10/22 21:26:19 · 阅读 1.2k Superpowers技能框架与TDD契约驱动：构建AI辅助开发的工程纪律闭环
1. 从“氛围编程”到工程纪律为什么我们需要重新审视AI辅助开发的底层逻辑“氛围编程”这个词最近在开发者圈子里流传得越来越广它描述的是一种极其普遍的工作状态打开AI编程助手用自然语言描述一下想要什么然后看着代码一行行自动生成感觉对了就继续感觉不对就重新生成一版。整个过程行云流水像在跟一个懂你的搭档聊天效率感拉满。但问题恰恰出在这里——当“感觉”取代了“验证”当“看起来对”取代了“确实对”代码库就开始悄悄积累一种新型的技术债我把它叫做“氛围债”。这种债务的可怕之处在于它的隐蔽性。传统技术债你至少知道哪里欠了——没写测试、没做抽象、硬编码太多。但氛围债不一样它披着“AI生成”的外衣代码风格统一、注释齐全、甚至看起来逻辑自洽可一旦进入真实运行环境边界条件、并发场景、异常路径就开始集体暴雷。我见过一个项目三天内用AI辅助生成了近两万行代码功能演示完美通过结果上线第一天就因为一个空指针异常导致核心链路雪崩回滚都来不及。Superpowers技能框架、TDD契约驱动、AI工程纪律闭环——这三个词放在一起指向的正是同一个问题我们如何把AI从“代码生成器”变成“工程协作者”。Superpowers不是某个具体工具而是一套技能组织范式它把开发者的能力拆解成可组合、可验证、可复用的技能单元每个单元都有明确的输入输出契约。TDD契约驱动则是把测试从“事后验证”变成“事前约定”让AI在生成代码之前先理解“什么叫做对了”。而工程纪律闭环说白了就是一套让AI辅助开发不失控的流程约束——从需求拆解到代码生成从测试覆盖到集成验证每一步都有明确的准入门槛和退出标准。这套东西适合谁如果你只是用AI写个脚本、做个原型那确实不需要这么重。但如果你在维护一个长期迭代的项目团队里有多个开发者同时用AI辅助编码或者你正在构建对稳定性有要求的生产系统那这套框架就是刚需。它解决的核心问题是如何让AI的生成能力与工程的验证能力形成闭环而不是让AI的“自信输出”变成团队的“集体盲区”。我在这篇文章里会把这套框架拆开揉碎从设计思路到实操细节从工具选型到避坑经验尽量把每个环节的“为什么”讲清楚。不是因为它复杂而是因为太多人只看到了AI生成代码的爽感忽略了背后需要的工程约束。下面我们进入正题。2. Superpowers技能框架的核心设计与拆解思路2.1 为什么是“技能”而不是“提示词”大多数人用AI辅助编程的方式是写提示词——把需求描述清楚让AI生成代码。这种方式的问题在于提示词是一次性的、上下文相关的、难以复用的。你今天写了一个完美的提示词生成了用户认证模块明天换个项目想复用发现上下文变了、技术栈变了、业务规则变了提示词直接失效。Superpowers技能框架的核心洞察是把“提示词”升级为“技能”。技能和提示词的本质区别在于技能有明确的契约——输入是什么、输出是什么、依赖什么、保证什么。一个“生成RESTful接口”的技能它的输入是资源定义和数据模型输出是符合特定规范的控制器代码、路由配置和验证逻辑依赖是项目的基础框架和ORM层保证是生成的代码必须通过预设的契约测试。这种设计的好处是显而易见的。首先技能可以被版本化管理你可以像管理代码一样管理技能每次修改都有记录、可回滚。其次技能可以被组合一个“用户注册”技能可以调用“生成数据模型”技能、“生成接口”技能和“生成验证逻辑”技能形成技能树。最重要的是技能可以被验证——因为契约是明确的你可以自动检查AI的输出是否符合预期而不是靠人眼去review。我试过在一个中型项目里把常用的开发任务拆成二十多个技能从“生成数据库迁移脚本”到“生成单元测试骨架”每个技能都有对应的契约文件。结果是在后续三个月的迭代中AI辅助生成的代码首次通过率从不到四成提升到了七成以上代码review的时间成本下降了将近一半。2.2 技能框架的层次结构Superpowers技能框架通常分为三个层次原子技能、组合技能和领域技能。原子技能是最小的可执行单元比如“生成一个TypeScript接口定义”、“生成一个Python数据类”、“生成一个SQL查询语句”。这些技能的特点是输入输出极其明确几乎不需要上下文AI生成的准确率很高。原子技能的价值在于它们是构建更复杂技能的基础而且可以被独立测试和验证。组合技能是把多个原子技能按照特定顺序组合起来完成一个完整的开发任务。比如“生成一个CRUD模块”就是一个组合技能它内部会依次调用“生成数据模型”、“生成数据库迁移”、“生成接口定义”、“生成控制器逻辑”、“生成单元测试”等原子技能。组合技能的关键在于编排逻辑——什么顺序调用、什么条件下跳过、失败后如何回滚。领域技能是最高层次的技能它绑定特定的业务领域或技术栈。比如“生成电商订单处理逻辑”就是一个领域技能它内部不仅包含组合技能还包含领域特定的规则和约束——订单状态机怎么流转、库存扣减的并发怎么处理、支付回调的幂等怎么保证。领域技能通常需要团队根据自身业务特点定制很难直接复用。这种层次结构的设计思路是越底层的技能越通用、越稳定、越容易验证越高层的技能越具体、越需要定制、越依赖人工判断。在实际操作中我建议先把原子技能做扎实确保每个原子技能的契约测试都能稳定通过然后再往上构建组合技能和领域技能。跳过原子技能直接做领域技能结果往往是空中楼阁看起来很美但一碰就碎。2.3 技能契约的编写要点技能契约是Superpowers框架的核心它定义了“什么叫做对了”。一份好的技能契约应该包含以下几个部分输入规范明确描述技能需要哪些输入参数每个参数的类型、格式、约束条件。比如“生成数据模型”技能的输入可能包括模型名称字符串符合PascalCase命名规范、字段列表数组每个字段包含名称、类型、是否可空、默认值、索引定义可选数组。输出规范明确描述技能会产生哪些输出输出的格式和结构。对于代码生成类技能输出通常是文件路径和文件内容的映射。输出规范还应该包含代码风格约束——缩进用几个空格、是否使用分号、导入语句的排序规则等。前置条件技能执行前必须满足的条件。比如“生成数据库迁移”技能的前置条件可能是项目已经初始化了ORM框架、数据库连接配置已经存在、目标模型的数据类已经生成。后置条件技能执行后必须满足的条件。这是契约测试的核心依据。比如“生成接口”技能的后置条件可能是生成的控制器类必须包含指定的HTTP方法注解、必须调用指定的服务层方法、必须返回指定的响应类型。异常处理当输入不满足规范或前置条件不满足时技能应该如何处理。是抛出明确的错误信息还是尝试自动修复还是降级到某个默认行为。编写契约时最容易犯的错误是“过度约束”——把太多细节写进契约导致技能变得僵化稍微换个场景就无法使用。我的经验是契约应该约束“必须正确”的部分对于“可以灵活”的部分留出空间。比如代码的变量命名可以交给AI决定但函数的输入输出类型必须严格约束。2.4 技能框架与AI模型的协作模式Superpowers框架并不绑定特定的AI模型它更像是一层“协议层”把AI模型的生成能力封装成符合契约的技能。在实际操作中我通常会把技能契约作为系统提示词的一部分注入给AI模型然后在用户提示词中提供具体的输入参数。这种协作模式的关键在于“契约前置”——AI模型在生成代码之前必须先理解契约的要求。我试过两种方式一种是把契约放在系统提示词里让AI在每次生成时都参考另一种是把契约作为独立的验证步骤AI生成代码后再用契约去检查。实测下来第一种方式的首次通过率更高因为AI在生成时就有了明确的约束第二种方式更适合作为兜底防止AI在复杂场景下“忘记”契约。还有一个细节值得注意技能契约的粒度要适中。太粗的契约比如“生成一个完整的用户模块”会让AI有太多自由发挥的空间生成结果不可控太细的契约比如“生成一个变量声明”又会让技能数量爆炸维护成本太高。我的经验是一个技能对应一个“可独立测试的代码单元”比如一个类、一个函数、一个配置文件这样既保证了可控性又不会过于琐碎。3. TDD契约驱动的实操要点与核心环节实现3.1 从“测试后写”到“契约先行”的思维转变TDD本身不是新概念但在AI辅助开发的场景下它的意义被放大了。传统开发中测试后写虽然不好但至少开发者对代码逻辑是理解的补测试的时候还能发现一些问题。但在AI辅助开发中如果你不先写测试AI生成的代码你很可能只是“扫一眼”就过了因为代码看起来太合理了——命名规范、注释完整、结构清晰你很容易产生“应该没问题”的错觉。契约驱动的TDD把这个顺序彻底反过来先定义“什么叫做对了”再让AI去生成“可能对的代码”最后用契约去验证。这个顺序的调整带来的最大好处是你不再依赖对AI的“信任”而是依赖对契约的“验证”。具体操作上我通常会把一个开发任务拆成三步第一步用自然语言描述需求让AI帮我生成测试用例的骨架第二步人工review和补充测试用例确保覆盖了正常路径、边界条件和异常场景第三步把测试用例作为契约的一部分让AI生成实现代码然后运行测试验证。这个流程听起来比“直接让AI写代码”慢但实际算总账是快的。因为直接让AI写代码你省下的时间会在后续的debug、review和返工中加倍还回去。而契约驱动的流程虽然前期多花了时间定义测试但生成的代码首次通过率高返工少整体效率反而更高。3.2 契约测试的编写规范契约测试和普通单元测试的区别在于契约测试是“面向接口”的它不关心内部实现细节只关心输入输出是否符合约定。这种特性使得契约测试特别适合AI辅助开发场景——因为AI生成的代码内部实现可能每次都不一样但只要输入输出符合契约就是可接受的。编写契约测试时我遵循几个原则一个契约测试只验证一个行为。比如“用户注册”这个技能契约测试应该分别验证用户名重复时返回错误、密码强度不足时返回错误、邮箱格式不正确时返回错误、正常注册时返回用户ID。每个测试用例只关注一个行为这样当测试失败时你能快速定位是哪个契约被违反了。契约测试必须可独立运行。不依赖外部数据库、不依赖网络请求、不依赖其他测试的执行顺序。我通常会用内存数据库或mock对象来隔离外部依赖确保契约测试可以在任何环境下快速运行。契约测试的断言要具体。不要只断言“返回了错误”要断言“返回了错误码USERNAME_DUPLICATE”和“错误信息包含‘用户名已存在’”。具体的断言才能给AI提供明确的修正信号。下面是一个契约测试的示例结构以Python为例# 契约用户注册技能 # 输入用户名、密码、邮箱 # 输出成功时返回用户ID失败时返回错误码和错误信息 def test_register_duplicate_username(): # 前置条件用户名existing_user已存在 setup_existing_user(existing_user) # 执行 result register_user(existing_user, ValidPass123, testexample.com) # 断言 assert result.success False assert result.error_code USERNAME_DUPLICATE assert 用户名已存在 in result.error_message def test_register_weak_password(): result register_user(new_user, 123, testexample.com) assert result.success False assert result.error_code WEAK_PASSWORD assert 密码强度不足 in result.error_message def test_register_success(): result register_user(new_user, ValidPass123, testexample.com) assert result.success True assert result.user_id is not None assert isinstance(result.user_id, str)这种契约测试的写法AI模型很容易理解——它知道输入是什么、期望输出是什么、边界条件在哪里。在实际操作中我会把这些契约测试作为提示词的一部分提供给AI让它在生成实现代码时参考。3.3 契约驱动下的AI代码生成流程有了契约测试之后AI代码生成的流程就变得非常清晰了。我通常按照以下步骤操作第一步准备契约文件。把技能契约和契约测试整理成一个结构化的文档包括输入规范、输出规范、前置条件、后置条件和测试用例。这个文档不需要很正式但必须完整。第二步构造提示词。提示词的结构通常是系统提示词包含技能契约的摘要和代码风格约束用户提示词包含具体的输入参数和契约测试的完整内容。我试过把契约测试直接放在用户提示词里效果比放在系统提示词里更好因为AI在生成时会“看到”具体的测试用例更容易生成符合预期的代码。第三步生成代码并运行测试。AI生成代码后立即运行契约测试。如果测试通过进入人工review环节如果测试失败把失败信息反馈给AI让它修正。这里有个技巧不要一次性把所有失败信息都丢给AI而是按优先级逐个修复。先修复导致测试崩溃的错误再修复断言失败的错误最后处理代码风格问题。第四步人工review和补充。契约测试通过不代表代码就是完美的。人工review主要关注几个方面代码的可读性、是否有明显的性能问题、是否有安全漏洞、是否与现有代码风格一致。如果发现问题可以手动修改也可以把问题描述给AI让它重新生成。这个流程我用了大概半年最大的感受是AI生成的代码质量变得“可预测”了。以前是开盲盒现在是流水线——虽然偶尔还是会有意外但整体上可控性大大提升。3.4 契约的版本管理与演进契约不是一成不变的。随着业务需求的变化契约也需要演进。比如“用户注册”技能最初可能只要求用户名和密码后来增加了邮箱验证、手机号绑定、邀请码校验契约就需要相应扩展。契约演进的关键是“向后兼容”。每次修改契约时先问自己这个修改会不会破坏已有的测试用例如果会是应该修改测试用例来适应新契约还是应该保持旧契约不变、新增一个技能来处理新需求我的经验是尽量保持原子技能的契约稳定把变化放在组合技能或领域技能层面。比如“生成数据模型”这个原子技能它的契约应该只关心模型的结构定义不关心业务规则。业务规则的变化应该体现在组合技能层面通过编排不同的原子技能来实现。契约的版本管理我通常用Git来管理每个技能一个目录目录下包含契约文件、测试文件和示例代码。每次修改契约都提交一个commitcommit message里说明修改原因和影响范围。这样当某个技能出问题时可以快速回滚到之前的版本。还有一个细节契约测试的执行应该自动化。我通常会在CI流程里加入契约测试的执行步骤每次代码提交都自动运行所有技能的契约测试。如果某个技能的契约测试失败CI会阻止合并并通知相关开发者。这种自动化约束是工程纪律闭环的重要组成部分。4. AI工程纪律闭环的构建与常见问题排查4.1 工程纪律闭环的四个环节AI工程纪律闭环的核心是“不让未经验证的代码进入代码库”。这个闭环包含四个环节需求拆解、技能匹配、代码生成、验证集成。需求拆解环节的目标是把一个模糊的需求转化为明确的技能调用序列。比如“用户可以通过手机号注册”这个需求拆解后可能对应生成手机号验证技能、生成短信验证码技能、生成用户注册技能、生成注册接口技能。拆解的质量直接决定了后续环节的顺利程度——拆得太粗AI生成的结果不可控拆得太细技能数量爆炸维护成本高。技能匹配环节的目标是为每个拆解后的子任务找到对应的技能。如果现有技能库里有匹配的技能直接调用如果没有需要先创建新技能。创建新技能时先写契约测试再让AI生成实现最后把新技能加入技能库。代码生成环节就是前面说的契约驱动流程。这个环节的关键是“快速反馈”——AI生成代码后立即运行契约测试失败立即反馈不要让问题积累。验证集成环节的目标是确保新生成的代码与现有代码库兼容。这个环节包括运行全量测试套件、检查代码风格一致性、检查依赖冲突、检查性能影响。我通常会在CI流程里加入这些检查任何一项不通过都阻止合并。这四个环节形成一个闭环每次代码生成都会产生新的契约测试新的契约测试会加入技能库技能库的丰富又会提升后续需求拆解的效率和准确性。这个闭环运转得越好AI辅助开发的“失控感”就越低。4.2 常见问题与排查技巧实录在实际操作中我遇到过不少问题这里整理成速查表方便对照排查问题现象可能原因排查方法解决方案AI生成的代码首次测试通过率低契约描述不清晰或测试用例覆盖不足检查契约文件是否包含完整的输入输出规范检查测试用例是否覆盖边界条件补充契约细节增加边界测试用例把失败信息反馈给AI重新生成契约测试运行速度慢测试依赖了外部资源或测试用例过多检查测试是否使用了真实数据库或网络请求检查单个技能的测试用例数量用mock替换外部依赖拆分过大的技能把集成测试和契约测试分开技能之间互相冲突技能契约的输入输出定义不一致检查相关技能的契约文件看是否有类型不匹配或命名冲突统一技能契约的命名规范建立技能之间的依赖关系图避免循环依赖AI生成的代码风格不一致系统提示词中的风格约束不够具体检查系统提示词是否包含了缩进、命名、导入排序等细节在系统提示词中加入具体的代码风格示例或者用代码格式化工具自动处理契约演进导致旧测试失败契约修改没有考虑向后兼容检查契约修改是否影响了已有测试用例的断言尽量保持原子技能契约稳定把变化放在组合技能层面必要时为旧契约保留兼容层除了这些常见问题还有几个“踩过的坑”值得单独说第一个坑是“过度依赖AI生成测试”。我试过让AI根据需求描述直接生成契约测试结果生成的测试用例虽然能跑但覆盖的场景很有限边界条件基本没覆盖。后来我改成“AI生成测试骨架人工补充边界用例”效果好很多。第二个坑是“技能粒度过细”。一开始我把技能拆得很细比如“生成一个变量声明”、“生成一个if语句”结果技能数量爆炸维护成本极高而且AI在调用这些细粒度技能时经常“忘记”上下文。后来我把粒度调整到“一个可独立测试的代码单元”比如一个函数、一个类情况就好多了。第三个坑是“忽略代码风格约束”。AI生成的代码风格如果不一致虽然功能没问题但代码review时会很痛苦。后来我在系统提示词里加入了具体的代码风格示例并且在CI流程里加入了自动格式化步骤这个问题才解决。4.3 工程纪律闭环的度量与优化闭环建起来之后需要持续度量和优化。我通常关注几个指标契约测试通过率AI生成的代码首次运行契约测试的通过率。这个指标反映了契约描述的质量和AI模型的能力。通过率低于六成说明契约需要细化通过率高于八成说明契约和AI的协作已经比较成熟。返工率AI生成的代码需要人工修改的比例。这个指标反映了生成代码的可用性。返工率高的原因可能是契约不清晰、AI模型能力不足、或者需求本身模糊。技能复用率新需求中直接复用已有技能的比例。这个指标反映了技能库的积累效果。复用率越高说明技能库越丰富后续开发的效率越高。闭环周期时间从需求拆解到代码合并的平均时间。这个指标反映了整个闭环的效率。周期时间过长说明某个环节有瓶颈需要针对性优化。我自己的经验是闭环刚建起来的时候这些指标都不会太好看——契约测试通过率可能只有五成返工率可能超过三成。但随着技能库的积累和契约的细化指标会逐步改善。大概两三个月后契约测试通过率能稳定在七成以上返工率降到两成以下这时候整个流程就比较顺畅了。4.4 从工具到习惯工程纪律的落地心得最后说点务实的。Superpowers框架、TDD契约驱动、工程纪律闭环这些东西听起来很系统但落地的时候最大的挑战不是技术而是习惯。我见过不少团队工具都配齐了契约模板也有但开发者还是习惯直接让AI生成代码跳过契约测试。问原因回答是“太慢了”、“赶进度”、“先这样后面再补”。结果就是氛围编程的老路代码库越来越乱最后不得不花大力气重构。我的建议是不要试图一次性把整套框架落地。先从一个小项目开始选一个最常用的技能把契约测试写起来坚持两周。等习惯了“先写测试再生成代码”的节奏再逐步扩展到更多技能。等技能库有一定积累了再引入组合技能和领域技能。这个过程可能需要几个月但每一步都是扎实的。还有一个心得是契约测试不要追求完美。一开始写的契约测试可能覆盖不全、断言不够精确这都没关系。重要的是先跑起来然后在实践中逐步完善。我自己的技能库也是迭代了十几版才稳定下来的第一版现在回头看简直惨不忍睹。工程纪律的本质不是约束而是保护。它保护你不被AI的“自信输出”带偏保护你的代码库不被氛围债侵蚀保护你的团队不在深夜被线上故障叫醒。这套东西值得花时间去建而且越早建越好。