1. 从“氛围编程”到工程纪律为什么我们需要重新审视 AI 协作模式“氛围编程”这个词最近在开发者圈子里流传得很快它描述的是一种状态你坐在编辑器前对着 AI 助手敲下几句模糊的需求描述然后看着它哗啦啦吐出一大段代码感觉一切都很顺畅氛围到了代码就出来了。这种体验确实很爽尤其是在原型验证阶段几分钟就能跑通一个之前要写半天的功能。但爽完之后呢我见过太多项目在“氛围编程”的狂欢之后陷入了一种诡异的困境代码能跑但没人敢改功能实现了但边界条件全是坑测试覆盖率看着还行但全是 AI 生成的“自证式”测试根本抓不住真正的逻辑漏洞。这就是我所说的“代码雪崩”——表面上看是 AI 帮你写了代码实际上你欠下了一笔巨大的技术债这笔债会在后续迭代中以指数级的速度膨胀。你让 AI 改一个函数它顺手重构了三个模块你让它修一个 bug它引入了两个新的边界问题。每一次交互都在增加系统的熵直到某一天你发现整个项目已经变成了一团无法维护的乱麻而你对它的理解还停留在最初那几句模糊的需求描述上。这篇文章要聊的就是怎么从这种状态里走出来。核心思路是三个东西的组合Superpowers 技能框架、TDD 契约驱动、以及AI 工程纪律闭环。这三个词听起来有点抽象但拆开来看每一个都对应着非常具体的实操方法。Superpowers 技能框架解决的是“AI 到底该会什么、不该会什么”的问题TDD 契约驱动解决的是“怎么让 AI 写出的代码有可验证的边界”的问题工程纪律闭环解决的是“怎么让这套流程持续运转而不退化”的问题。适合谁来读如果你已经在用 AI 辅助写代码但感觉越写越乱、越改越怕那这篇内容就是为你准备的。如果你还没开始用 AI 写代码但想从一开始就建立一套靠谱的协作模式那更好你可以直接跳过那些坑。全文会围绕这三个核心概念展开穿插具体的操作步骤、参数配置、排查技巧以及我在实际项目中踩过的坑和总结出来的经验。不堆砌术语尽量说人话目标是让你看完之后能直接在自己的项目里落地一套可运行的流程。2. Superpowers 技能框架给 AI 划清能力边界2.1 什么是 Superpowers 技能框架为什么需要它Superpowers 技能框架本质上是一套对 AI 助手能力进行结构化封装和约束的机制。你可以把它理解成给 AI 写的一份“岗位说明书”哪些事情它能做、哪些事情它不能做、做某件事的时候必须遵循什么流程、产出物必须满足什么格式。没有这套框架的时候你和 AI 的交互是随机的、发散的AI 会根据你每一句话的上下文去“猜”你想要什么猜对了是运气猜错了是常态。我最初用 AI 写代码的时候就是典型的“氛围编程”打开对话框输入“帮我写一个用户登录的接口”然后看着它生成一堆代码复制粘贴跑一下报错了再问它“这里报错了怎么办”它再给一版修改。整个过程没有任何结构完全靠对话的惯性在推进。结果就是同一个项目里登录接口的写法和其他接口完全不一样错误处理的方式五花八门命名风格更是随机。后来我意识到问题不在于 AI 写得不好而在于我从来没有告诉它“在这个项目里什么叫做得好”。Superpowers 技能框架的核心思想就是把“什么叫做得好”这件事从你的脑子里、从每一次临时的对话里提取出来变成一份显式的、可复用的、可版本管理的技能定义。这份定义里包含几个关键要素技能的名称和触发条件、输入输出的格式约定、必须遵循的步骤序列、以及验收标准。当你把这份定义交给 AI 的时候它就不再是在“猜”你的意图而是在“执行”一个明确的技能。2.2 技能定义的结构从模糊需求到可执行契约一个完整的 Superpowers 技能定义通常包含以下几个部分。我拿一个实际项目里的“新增 API 端点”技能来举例说明。技能名称与触发条件名称要具体比如“新增 RESTful API 端点”而不是“写接口”。触发条件要明确比如“当用户要求新增一个 HTTP 接口且该接口需要访问数据库时触发”。这样做的目的是让 AI 能够准确判断什么时候该调用这个技能而不是把所有请求都往一个模糊的“写代码”技能里塞。输入契约明确这个技能需要哪些输入参数。比如端点路径、HTTP 方法、请求体结构、响应体结构、涉及的数据库表、权限要求。每一个参数都要有类型和约束条件。比如“端点路径必须符合/api/v1/{resource}的格式”“HTTP 方法必须是 GET、POST、PUT、DELETE 之一”。这些约束不是摆设它们会在 AI 生成代码之前就进行一次校验避免它生成一个路径里带空格的接口。步骤序列这是技能框架的核心。它规定了 AI 在执行这个技能时必须按照什么顺序做什么事。比如第一步根据输入契约生成接口的 OpenAPI 描述文件第二步根据 OpenAPI 描述生成路由层代码第三步生成服务层代码并确保服务层不直接依赖 HTTP 上下文第四步生成数据访问层代码并确保所有查询都使用参数化查询第五步生成单元测试测试必须覆盖正常路径和至少两个异常路径。这个步骤序列是强制的AI 不能跳步也不能改变顺序。输出契约规定产出物的格式和内容。比如必须生成一个包含路由、服务、数据访问三个文件的变更集每个文件必须包含文件头注释说明该文件的职责和依赖关系必须生成一个测试文件测试文件的命名必须遵循{resource}_test.{ext}的格式。输出契约的作用是让产出物可预测你知道每次执行这个技能你会得到什么而不是每次都要去翻 AI 到底生成了哪些文件。验收标准这是最后一道关卡。验收标准必须是可自动化的比如“所有单元测试必须通过”、“代码必须通过静态检查工具的检查”、“接口的响应时间在本地环境下必须小于 200 毫秒”。如果验收不通过AI 必须回到步骤序列里重新执行直到通过为止。这一步是很多“氛围编程”流程里缺失的大家往往看到代码生成了就以为完事了实际上真正的验证才刚刚开始。2.3 技能框架的落地从文档到自动化把技能定义写出来只是第一步更重要的是让它真正运转起来。我的做法是把技能定义写成一个结构化的配置文件放在项目的.ai/skills/目录下每个技能一个文件用 YAML 或 JSON 格式。然后写一个简单的脚本在每次和 AI 交互之前把这个配置文件的内容作为系统提示的一部分注入进去。这样 AI 在每次对话开始时就已经知道了当前项目里有哪些技能可用、每个技能的契约是什么。更进一步的做法是把技能定义和 CI 流程打通。比如当 AI 生成代码之后自动触发一个流水线先跑静态检查再跑单元测试再跑集成测试最后跑验收标准里定义的那些检查。如果任何一步失败就把失败信息反馈给 AI让它根据反馈重新生成。这个循环可以自动跑也可以半自动跑取决于你对风险的容忍度。我个人的习惯是对于核心模块的变更一定要人工确认之后再合并对于边缘模块或者工具类的变更可以让它自动跑完整个循环。这里有一个关键点技能定义本身也是需要版本管理的。当你发现某个技能的定义有问题比如步骤序列里少了一个必要的检查或者验收标准太宽松导致 AI 经常生成有问题的代码你就应该去修改技能定义而不是在每次对话里临时打补丁。这样你的技能库会随着项目一起进化越来越贴合实际需求。2.4 实操心得技能框架的常见坑与规避方法第一个坑是技能定义过于宽泛。我一开始写了一个叫“写代码”的技能结果 AI 把所有请求都往这个技能里塞生成的东西完全没有结构。后来我把技能拆细了拆成了“新增 API 端点”、“修改现有端点逻辑”、“新增数据库迁移”、“修复 bug”等十几个具体技能每个技能都有明确的触发条件和契约效果立刻好了很多。技能定义的粒度应该和你在代码评审时关注的粒度一致。如果你在评审时会说“这个接口的权限检查没做”那你的技能定义里就应该有一条“必须包含权限检查”的步骤。第二个坑是验收标准不可执行。我见过有人写“代码必须优雅”作为验收标准这种标准 AI 根本没法判断最后只能靠它自己“感觉”优雅不优雅。验收标准必须是机器可判断的比如“圈复杂度不超过 10”、“没有重复代码块超过 5 行”、“所有公共函数都有文档注释”。这些标准可以用工具自动检查AI 也能根据检查结果去修正。第三个坑是技能定义和实际代码脱节。技能定义写得很漂亮但实际项目里的代码根本不遵循这套定义导致 AI 生成的新代码和旧代码风格完全不一致。解决方法是在引入技能框架的初期先花时间把现有代码按照技能定义的要求重构一遍或者至少让新代码严格遵循定义旧代码逐步迁移。不要指望 AI 能自动理解你项目里的“潜规则”那些规则必须被显式地写出来。3. TDD 契约驱动让 AI 写出的代码有可验证的边界3.1 TDD 在 AI 协作场景下的特殊意义测试驱动开发TDD本身不是一个新概念但在 AI 协作的场景下它的意义被放大了。原因很简单AI 生成代码的速度太快了快到你的大脑根本来不及对每一行代码进行逻辑审查。如果你还是用传统的方式等 AI 把代码写完再去写测试那测试往往就变成了“验证 AI 写的代码能跑”而不是“验证需求是否被正确实现”。这两者之间的差别在项目规模变大之后会变得非常致命。TDD 契约驱动的核心是先写测试再写实现而且测试必须由人来定义契约AI 来填充实现。这里的“契约”指的是接口的行为约定输入什么、输出什么、在什么情况下报错、报什么错。契约一旦确定测试就是契约的可执行表达。AI 的任务是让测试通过而不是“写一段看起来合理的代码”。这个顺序的颠倒是很多 AI 协作流程失败的根本原因。我举个具体的例子。假设你要新增一个“用户积分兑换”的功能。在“氛围编程”模式下你可能会对 AI 说“帮我写一个积分兑换的功能”然后它生成了一堆代码你看着觉得差不多就合并了。但在 TDD 契约驱动模式下你会先定义契约兑换时积分必须大于等于所需积分否则返回“积分不足”错误兑换成功后用户积分减少兑换记录增加兑换操作必须是幂等的同一个请求 ID 重复提交不会重复扣减积分。然后你把这些契约写成测试用例再让 AI 去实现。这样AI 写出来的代码天然就满足了这些边界条件而不是等你上线之后才发现幂等性没做。3.2 契约的定义从需求到可执行测试定义契约的过程本质上就是把模糊的需求翻译成精确的、可验证的断言。这个过程需要你对业务逻辑有清晰的理解不能含糊。我通常会用“给定-当-那么”的格式来写契约这个格式强迫你把前置条件、触发动作、预期结果都写清楚。还是拿积分兑换举例。一个完整的契约可能包含以下几条给定用户当前积分为 100当用户请求兑换 50 积分时那么兑换成功用户积分变为 50兑换记录增加一条。给定用户当前积分为 30当用户请求兑换 50 积分时那么兑换失败返回“积分不足”错误用户积分不变。给定用户当前积分为 100当用户使用同一个请求 ID 连续请求兑换 50 积分两次时那么第一次兑换成功第二次返回“重复请求”错误用户积分只扣减一次。给定用户当前积分为 0当用户请求兑换 0 积分时那么兑换失败返回“兑换积分必须大于零”错误。每一条契约都可以直接翻译成一个测试用例。这些测试用例就是 AI 实现功能的“靶子”。AI 的任务不是“写一个积分兑换功能”而是“让这些测试全部通过”。这个目标的转变让 AI 的产出变得可衡量、可验证。这里有一个关键的操作细节测试用例必须由人来写或者至少由人来审核。如果你让 AI 自己写测试再自己实现它很可能会写出一些“自证式”的测试——测试的逻辑和实现的逻辑完全一样测试通过了但需求可能根本没被满足。比如AI 可能会写一个测试断言“兑换后的积分等于兑换前的积分减去兑换积分”这个断言看起来没问题但如果实现里把“减去”写成了“加上”测试也会通过因为测试和实现用的是同一套错误的逻辑。人写测试的价值在于人是从需求出发的而不是从实现出发的。3.3 红绿重构循环在 AI 协作中的变体传统的 TDD 循环是“红-绿-重构”先写一个失败的测试红然后写最少的代码让测试通过绿最后重构代码消除重复、改善设计。在 AI 协作的场景下这个循环可以变得更高效但也需要一些调整。红阶段你写好测试用例运行确认测试失败。这一步不能省。我见过有人直接让 AI 写实现然后补测试结果测试从来没失败过因为测试是根据实现写的。确认测试失败是确认测试本身有效性的关键步骤。如果测试没失败要么是测试写错了要么是功能已经存在了。绿阶段把失败的测试和相关的技能定义一起交给 AI让它生成实现代码。这里的关键是一次只让 AI 处理一个失败的测试。不要一次性把十个失败的测试都丢给它那样它会试图一次性满足所有条件生成的代码往往会过度设计或者在某些测试之间做出奇怪的妥协。一个测试一个测试地来每次只关注让当前这个测试通过代码会简洁很多。重构阶段当所有测试都通过之后再让 AI 或者你自己来重构代码。重构的目标是消除重复、改善命名、提取公共逻辑。重构之后必须重新运行所有测试确保没有破坏任何契约。这个阶段是很多 AI 协作流程里被忽略的大家往往测试一通过就完事了结果代码里充满了重复和坏味道下一次修改的时候又得推倒重来。在 AI 协作的场景下我通常会把重构也交给 AI但会给出明确的约束比如“提取重复的积分校验逻辑到一个独立的函数中”、“把错误码定义成枚举而不是魔法数字”。这些约束可以写在技能定义里作为“修改现有代码”技能的一部分。3.4 契约驱动的边界什么该测什么不该测TDD 契约驱动不是要你为每一行代码都写测试。那样的话测试本身就会变成巨大的维护负担。契约驱动的核心是测试行为而不是测试实现。行为是接口对外表现出来的可观察结果实现是达成这个结果的具体步骤。测试应该关注行为因为行为是稳定的实现是易变的。举个例子一个“发送邮件”的功能它的行为是“调用邮件服务商的 API传入正确的收件人、主题、正文”。它的实现可能是用 HTTP 客户端直接调用也可能是用某个 SDK。如果你测试的是“调用了 HTTP 客户端的 post 方法”那当实现从 HTTP 客户端换成 SDK 的时候测试就挂了但功能其实没变。如果你测试的是“邮件服务商收到了正确的请求”那不管实现怎么换测试都能通过。在 AI 协作的场景下测试行为还有一个额外的好处AI 在实现行为的时候有更大的自由度它可以选择它认为最合适的方式而不是被你预设的实现细节束缚住。你只需要告诉它“这个函数在收到无效输入时应该抛出一个特定类型的异常”它可以选择用 if 判断、用断言、用装饰器都无所谓只要行为正确就行。那么什么该测我的经验是所有跨边界的交互都该测。跨边界指的是函数与函数之间的调用、模块与模块之间的调用、服务与服务之间的调用、系统与外部依赖之间的交互。这些边界是 bug 最容易藏身的地方也是契约最需要明确的地方。至于边界内部的纯逻辑比如一个计算折扣的函数如果它足够简单可以测但不必强求。如果它足够复杂那它本身就构成了一个边界应该被单独测试。4. AI 工程纪律闭环让流程持续运转而不退化4.1 闭环的四个环节定义、执行、验证、反馈AI 工程纪律闭环指的是把前面说的技能框架和 TDD 契约驱动串起来形成一个持续运转的循环。这个循环包含四个环节定义、执行、验证、反馈。每个环节都有明确的输入和输出环节之间通过自动化的方式衔接减少人工干预的环节同时保留关键的人工决策点。定义环节在这个环节里你定义技能和契约。技能定义告诉 AI“怎么做”契约告诉 AI“做到什么程度算好”。这个环节的产出是一组结构化的配置文件放在项目的.ai/目录下和代码一起版本管理。定义环节是人工主导的因为技能和契约的质量直接决定了后续环节的效果。执行环节AI 根据技能定义和契约生成代码或修改代码。这个环节可以完全自动化也可以半自动化。自动化的方式是通过一个脚本把技能定义、契约、以及当前代码库的状态一起打包发送给 AI接收 AI 的产出然后自动应用到代码库中。半自动化的方式是AI 生成代码之后由人工确认再应用。我通常对核心模块采用半自动化对边缘模块采用自动化。验证环节代码应用之后自动触发验证流程。验证流程包括静态检查、单元测试、集成测试、验收标准检查。这些检查的结果会被收集起来形成一个验证报告。如果任何一项检查失败验证报告会包含失败的具体信息比如哪个测试失败了、失败的原因是什么、相关的代码片段是什么。反馈环节验证报告会被反馈给 AIAI 根据反馈修正代码然后重新进入执行环节。这个循环会一直持续直到所有检查都通过。反馈环节的关键是反馈信息的质量。如果反馈信息只是“测试失败了”AI 很难知道该怎么改。如果反馈信息是“测试test_exchange_insufficient_points失败了期望返回错误码INSUFFICIENT_POINTS实际返回了null相关代码在exchange_service.py的第 42 行”AI 就能很快定位问题并修正。4.2 自动化流水线的搭建从本地脚本到 CI 集成搭建这个闭环的自动化流水线不需要很复杂的工具。我的做法是先用一个本地脚本把整个流程串起来跑通了之后再考虑集成到 CI 里。本地脚本用 Python 或 Node.js 写都可以核心逻辑就是读取技能定义和契约文件调用 AI 接口应用产出运行验证收集反馈循环。这里有一个具体的脚本结构示例用 Python 写的import subprocess import json from pathlib import Path def load_skills(skills_dir): skills {} for skill_file in Path(skills_dir).glob(*.yaml): with open(skill_file) as f: skill yaml.safe_load(f) skills[skill[name]] skill return skills def run_verification(): results {} results[lint] subprocess.run( [pylint, src/], capture_outputTrue, textTrue ) results[unit_test] subprocess.run( [pytest, tests/unit/], capture_outputTrue, textTrue ) results[integration_test] subprocess.run( [pytest, tests/integration/], capture_outputTrue, textTrue ) return results def build_feedback(results): feedback [] for name, result in results.items(): if result.returncode ! 0: feedback.append(f[{name}] failed:\n{result.stdout}\n{result.stderr}) return \n.join(feedback) def main(): skills load_skills(.ai/skills/) contracts load_contracts(.ai/contracts/) max_iterations 5 for i in range(max_iterations): ai_output call_ai(skills, contracts) apply_changes(ai_output) results run_verification() feedback build_feedback(results) if not feedback: print(fAll checks passed after {i1} iterations.) break contracts[feedback] feedback else: print(Max iterations reached. Manual intervention required.)这个脚本的核心逻辑很清晰加载技能和契约调用 AI应用变更运行验证如果有失败就把失败信息加入契约再次调用 AI。最多循环五次如果五次之后还有失败就停下来让人工介入。这个“最大迭代次数”的设定很重要防止 AI 陷入无限循环也防止你在一个问题上消耗太多时间。集成到 CI 之后这个流程可以在每次提交时自动触发。但要注意CI 环境里调用 AI 接口可能需要额外的配置比如 API 密钥的管理、网络访问的权限等。另外CI 环境里的验证应该比本地更严格比如可以加上代码覆盖率检查、安全扫描等。4.3 人工介入的时机什么时候该停下来自动化闭环虽然高效但不是什么情况下都应该让它自动跑。有几种情况必须人工介入契约本身有歧义或错误如果 AI 反复无法让某个测试通过而且反馈信息显示它尝试了多种方式都不行那很可能是契约本身有问题。比如契约里写“兑换积分必须大于零”但实际业务里可能允许兑换零积分比如作为一种记录操作。这种情况下你需要回到定义环节修改契约而不是让 AI 继续瞎试。涉及核心业务逻辑的变更如果变更涉及到资金、权限、数据一致性等核心逻辑即使自动化验证通过了也应该人工审查一遍。自动化验证只能验证你写出来的契约不能验证你没写出来的隐含假设。人工审查可以发现那些“测试没覆盖到但很重要”的问题。AI 的产出超出了预期范围有时候 AI 会“顺手”修改一些不相关的代码或者引入新的依赖。这种情况下即使测试通过了也应该人工确认这些额外的变更是否合理。我遇到过 AI 在实现一个简单功能时顺手把整个项目的日志框架换掉了虽然测试都通过了但这种变更的风险很高必须人工评估。连续多次迭代失败如果 AI 在同一个问题上连续失败超过三次继续让它试下去大概率是浪费时间。这时候应该停下来人工分析一下问题到底出在哪里。可能是技能定义不够具体可能是契约有遗漏也可能是 AI 对某个技术栈的理解有偏差。4.4 纪律闭环的长期维护防止退化闭环搭建起来之后最大的挑战是防止它退化。退化通常表现为几种形式技能定义越来越臃肿契约越来越宽松验证越来越形式化反馈越来越敷衍。这些退化往往是渐进的不容易察觉但积累到一定程度之后整个闭环就名存实亡了。防止退化的关键是定期回顾和清理。我个人的习惯是每个迭代周期结束时花半个小时回顾一下这个周期里 AI 协作的情况哪些技能被频繁使用哪些技能几乎没用过哪些契约经常失败哪些验证步骤经常被跳过。根据回顾的结果该合并的技能合并该删除的技能删除该收紧的契约收紧该加强的验证加强。另一个关键是保持技能定义和契约的可读性。如果技能定义写得像天书一样没人愿意去维护它它就会慢慢腐烂。我的做法是每个技能定义都配一个简短的说明文档用自然语言解释这个技能是干什么的、什么时候用、有什么注意事项。契约也用注释的方式解释每一条的业务含义。这样即使过了几个月再回来看也能快速理解。还有一个容易被忽略的点是技能和契约的测试。技能定义和契约本身也是代码也应该被测试。比如你可以写一个测试验证每个技能定义都包含必需的字段验证每个契约都至少有一个对应的测试用例。这些元测试可以防止技能和契约在修改过程中出现低级错误。5. 常见问题与排查技巧实录5.1 AI 生成的代码总是偏离预期怎么排查这是最常见的问题。AI 生成的代码偏离预期通常有三个原因技能定义不够具体、契约不够明确、或者上下文信息不足。排查的第一步是检查技能定义。看看技能定义里有没有明确说明“不要做什么”。比如如果你不希望 AI 在实现 API 端点时直接操作数据库那技能定义里就应该有一条“服务层不得直接依赖数据库连接必须通过数据访问层”。很多偏离预期的情况是因为技能定义只说了“要做什么”没说“不要做什么”。第二步是检查契约的粒度。如果契约太粗比如只写了“兑换成功”没写“兑换成功后积分记录和兑换记录必须在同一个事务里”那 AI 可能会把两个操作分开执行导致数据不一致。契约的粒度应该细到你能想象出具体的测试断言。第三步是检查上下文信息。AI 在生成代码时会参考你提供的上下文。如果你只给了技能定义和契约没给现有的代码结构、命名规范、依赖库版本那 AI 只能靠猜。我的做法是在每次调用 AI 时都把项目的目录结构、关键文件的摘要、以及依赖清单一起传过去。这样 AI 生成的代码会更贴合项目的实际情况。5.2 测试通过但功能不对问题出在哪里这种情况通常是因为测试写得太“实现导向”了。比如你写了一个测试断言“调用了deduct_points函数”但实际需求是“用户积分被扣减”。如果实现里把deduct_points改成了subtract_points测试就挂了但功能其实是对的。反过来如果实现里deduct_points函数被调用了但函数内部有 bug积分没被正确扣减测试也会通过因为测试只检查了函数被调用没检查积分是否真的变了。解决方法是测试行为而不是测试实现。测试应该断言“用户积分从 100 变成了 50”而不是“deduct_points被调用了”。行为测试更稳定也更能抓住真正的 bug。另一个可能的原因是测试和实现用了同一套错误的逻辑。比如测试里计算期望值时用了和实现一样的公式如果公式本身是错的测试和实现会一起错测试通过但功能不对。避免这种情况的方法是测试里的期望值应该来自独立的来源比如手工计算的、来自需求文档的、或者来自另一个独立实现的。5.3 技能定义越来越臃肿怎么精简技能定义臃肿通常是因为你把太多细节写进了技能定义里。比如一个“新增 API 端点”的技能定义里包含了所有可能的参数校验规则、所有可能的错误码、所有可能的数据库操作。这样的技能定义会变得非常长而且很难维护。精简的方法是分层。把技能定义分成基础技能和组合技能。基础技能是原子操作比如“生成路由层代码”、“生成服务层代码”、“生成数据访问层代码”。组合技能是把基础技能按特定顺序组合起来比如“新增 API 端点”就是“生成路由层 生成服务层 生成数据访问层 生成测试”。这样基础技能可以复用组合技能只需要描述顺序和参数映射不需要重复细节。另一个方法是把细节移到契约里。技能定义只描述“做什么”契约描述“做到什么程度”。比如技能定义里写“生成参数校验逻辑”契约里写“参数points必须是大于零的整数否则返回INVALID_POINTS错误”。这样技能定义保持简洁细节都在契约里修改契约不影响技能定义。5.4 常见问题速查表问题现象可能原因排查方法解决措施AI 生成的代码风格不一致技能定义缺少风格约束检查技能定义是否有命名、格式、注释的约束在技能定义中加入风格检查步骤或引入格式化工具自动处理测试通过但功能不对测试实现导向或逻辑同源审查测试断言是否关注行为而非实现重写测试断言可观察的行为结果期望值来自独立来源AI 反复无法通过某个测试契约有歧义或技能定义不完整人工审查契约和技能定义确认是否有遗漏或矛盾修改契约或技能定义必要时拆分为更小的步骤验证流程经常被跳过验证太慢或太麻烦检查验证脚本的执行时间和配置复杂度优化验证脚本只保留关键检查或把验证拆成快速和完整两档技能定义和实际代码脱节技能定义未随项目演进更新定期对比技能定义和实际代码的差异建立技能定义的版本管理每次代码规范变更时同步更新AI 引入不相关的变更技能定义缺少范围约束检查技能定义是否明确了修改范围在技能定义中加入“只修改指定文件”的约束并在验证环节检查变更范围5.5 独家避坑技巧第一个技巧是给 AI 的反馈要具体到行。不要只说“测试失败了”要说“测试test_xxx在第 15 行断言失败期望200实际500相关代码在handler.py第 23 行”。具体的反馈能让 AI 更快定位问题减少来回次数。第二个技巧是保留每次迭代的产出。不要覆盖上一次的产出而是把每次 AI 生成的代码都保存下来打上时间戳和迭代编号。这样当出现问题时你可以回溯到之前的版本看看是哪一次变更引入了问题。这个习惯在排查复杂问题时特别有用。第三个技巧是定期用“反向测试”验证契约的有效性。反向测试是指故意修改实现代码引入一个 bug然后看测试是否能抓住这个 bug。如果测试没抓住说明测试的覆盖不够或者断言太弱。这个技巧可以帮助你发现那些“看起来在测但实际没测到”的测试。第四个技巧是把 AI 的“解释”也纳入验证范围。AI 在生成代码时通常会附带一段解释说明它为什么这么写。这段解释有时候会暴露它的理解偏差。比如它可能会说“我在这里加了缓存因为我觉得这样更快”但你的需求里根本没提缓存。这种情况下即使代码通过了测试也应该人工审查一下这个额外的缓存是否合理。6. 从工具到习惯把工程纪律内化成团队共识这套流程跑通之后最大的挑战其实不是技术层面的而是习惯层面的。我见过不少团队工具搭得很漂亮技能定义写得很完整契约也很详细但用了两周之后就慢慢荒废了。原因很简单当项目进度紧张的时候大家会本能地回到“氛围编程”的模式因为那样“更快”。但那种“快”是假象它只是把成本推迟到了未来。要让这套流程真正持续下去需要把它从“工具”变成“习惯”再从“习惯”变成“团队共识”。工具是外在的习惯是个人的共识是团队的。只有当成团队里所有人都认同“先写契约再写实现”是默认做法而不是“额外步骤”的时候这套流程才算真正落地了。我个人的经验是从一个小模块开始试点跑通整个闭环积累一些成功案例然后再逐步推广到其他模块。不要一上来就全项目铺开那样阻力会很大。试点的时候选一个边界清晰、依赖少、变更频率适中的模块这样容易看到效果也容易在出问题的时候回滚。另外不要追求完美。技能定义不需要一开始就写得很完整契约也不需要覆盖所有边界。先跑起来然后在实践中逐步完善。我最初写的技能定义只有三行契约也只有两条但就是这三行和两条让我第一次感受到了“有结构的 AI 协作”和“氛围编程”之间的巨大差别。后面的一切都是在这个基础上慢慢长出来的。最后再分享一个小技巧把每次 AI 协作的“翻车”案例记录下来形成一个内部的“避坑手册”。这些案例比任何理论都更有说服力也更能帮助团队理解为什么需要这套纪律。当新成员加入的时候让他们先读这本手册比让他们读一堆规范文档有效得多。