AI编程三重奏：Spec、契约与TDD实战指南-北京尧图网络

1. 为什么单靠让AI写代码总是翻车1.1 一个让我彻底改变认知的翻车现场去年有段时间我特别迷恋让AI直接生成代码觉得效率起飞。当时接了一个内部工具的需求功能不复杂读取一批结构化数据做清洗、聚合然后输出报表。我花了大概十分钟写了一段自认为描述得很清楚的提示词AI也很给力一口气吐了三百多行代码出来。跑了一下主流程居然通了我当时还挺得意。结果第二天测试同事过来找我说数据里有个字段是空的程序直接崩了。我回去一看AI写的清洗逻辑里默认所有字段都有值压根没考虑空值分支。我补了个判空再跑又发现聚合的时候对重复数据的处理跟我预期完全不一样——它按自己的理解做了去重而业务上那些重复记录是需要累加的。改完这个又冒出来一个边界问题当输入为空列表时它返回了一个空对象而不是空数组下游解析直接报错。一个下午我就在改一个bug、冒两个新bug的循环里打转。那天晚上我复盘了很久得出一个结论问题不在于AI写得不好而在于我给它的输入太模糊了。我脑子里有一套完整的预期但我只把其中一小部分翻译成了文字剩下的全靠AI猜。它猜对了是运气猜错了是必然。这个经历让我开始认真思考一件事怎么才能让AI编程从抽卡变成工程。后来我逐步摸索出一套方法核心就是三个东西的融合——Spec规格说明、契约Contract、TDD测试驱动开发。我把它们叫做AI编程的三重奏。这篇文章就把我踩过的坑、总结的方法、以及可以直接抄作业的模板全部摊开讲清楚。1.2 这三样东西到底各自解决什么问题先说Spec。Spec就是规格说明用自然语言把要做什么讲清楚。它的作用是消除需求层面的歧义。很多人以为Spec就是写个需求文档其实不是给AI看的Spec有它自己的写法后面我会详细拆。再说契约。契约是接口层面的约定规定输入什么、输出什么、出错怎么办。它比Spec更硬是可以用代码或者结构化格式固定下来的。契约解决的是模块之间、函数之间的边界问题让AI在实现细节上有自由但在接口上不能乱来。最后是TDD。测试驱动开发先写测试再写实现。在AI编程的场景下TDD的意义被放大了——因为测试用例本身就是最精确的Spec而且是可执行的Spec。你写一个测试AI就知道这个函数在什么输入下必须返回什么没有任何模糊空间。这三者的关系我打个比方Spec是设计图纸契约是承重墙的尺寸标准TDD是验收标准。图纸告诉你房子长什么样承重墙标准保证结构不会塌验收标准确保每个房间都符合要求。缺了任何一个房子都可能出问题。1.3 融合之后的效果到底有多大差别我拿同一个需求做过对比实验。需求是实现一个函数接收一个订单列表计算总金额支持折扣和优惠券。纯提示词方式我写了一段话描述需求AI生成了代码。跑测试的时候发现折扣和优惠券的叠加顺序它理解错了优惠券它默认在折扣前使用而业务要求先打折再用券。改了一轮又发现它对负数金额没有校验。总共来回改了四轮才基本可用。三重奏方式我先写Spec明确折扣和优惠券的计算顺序、边界条件、异常处理策略。然后定义契约规定输入输出的数据结构。最后写测试用例覆盖正常流程、边界情况、异常输入。把这三样一起给AI它一次生成的代码就通过了所有测试只有一处命名风格我不太满意手动改了一下。效率差距是肉眼可见的。更重要的是三重奏方式生成的代码我敢直接合并到主分支因为它的行为已经被测试锁死了。而纯提示词方式生成的代码我总得提心吊胆地再检查一遍。2. Spec怎么写才能让AI真正听懂2.1 给AI看的Spec和给人看的需求文档是两回事很多人写需求文档的习惯是高层概括关键点罗列因为读文档的是人人有常识、有上下文、能脑补。但AI不会脑补它只会严格按照你写的字面意思去理解。你写处理用户数据它可能理解成读取、可能理解成清洗、可能理解成加密全看它训练数据里哪种关联最强。所以给AI的Spec核心原则是消除一切可能的歧义。具体来说要做到三点第一每个术语都要有明确定义不能用行业黑话或者模糊词汇第二每个行为都要有明确的触发条件和预期结果第三边界情况和异常情况必须显式写出不能默认AI会合理处理。我举个例子。之前我写对数据进行去重AI给我按完全相同的记录去重。但实际上我的需求是按用户ID去重保留时间最新的一条。这就是典型的歧义。正确的Spec写法应该是输入是一个记录列表每条记录包含用户ID和时间戳。输出时对于同一个用户ID只保留时间戳最大的那条记录。如果时间戳相同保留列表中靠前的那条。2.2 一个可以直接套用的Spec模板经过多次迭代我总结了一个Spec模板基本上覆盖了AI编程需要的所有信息。这个模板分为六个部分第一部分功能概述。用一句话说清楚这个模块/函数要做什么。注意是一句话不要展开展开的内容放到后面。第二部分输入定义。列出所有输入参数每个参数说明类型、含义、取值范围、是否可为空。如果是复杂数据结构要给出结构定义。第三部分输出定义。说明返回值的类型和含义。如果有多种返回情况要分别说明。第四部分核心逻辑。按步骤描述处理流程。每一步都要说清楚在什么条件下做什么。第五部分边界与异常。列出所有已知的边界情况和异常情况以及期望的处理方式。第六部分示例。给出至少一组输入输出示例最好包含一组正常示例和一组边界示例。这个模板看起来有点繁琐但实际写起来很快。而且你写得越详细后面改bug的时间就越少总体是赚的。2.3 Spec里最容易踩的三个坑第一个坑是用抽象词汇。比如合理处理、优化性能、保证安全这些词对AI来说等于没说。什么叫合理优化到什么程度安全指哪些方面全部要具体化。第二个坑是遗漏隐式假设。你脑子里觉得这还用说吗的东西恰恰是AI最容易搞错的地方。比如你默认输入列表不会为空但AI可能会加一个空列表的处理逻辑然后这个逻辑跟你的下游代码不兼容。所以任何假设都要写出来。第三个坑是逻辑顺序不明确。多个操作之间有先后依赖关系的时候一定要明确写出顺序。比如先过滤再排序和先排序再过滤结果可能完全不同。AI不会自动帮你判断哪个顺序更合理它只会按你写的顺序来或者按它自己的理解来。我的经验是写完Spec之后自己先读一遍假装自己是一个完全不了解这个项目的新人看看有没有哪里会产生歧义。如果有就补清楚。这个自检动作花不了几分钟但能省下大量返工时间。3. 契约给AI划出不可逾越的边界3.1 契约的本质是什么契约这个词听起来很正式其实本质很简单它是调用方和实现方之间的一个约定。调用方说我按这个格式给你数据实现方说我按这个格式还你结果。双方都不关心对方内部怎么处理只关心接口对不对得上。在AI编程的场景下契约的作用是给AI划出一个明确的边界。边界之内AI可以自由发挥用什么算法、什么数据结构、什么代码风格都行。边界之外AI不能乱来输入输出的格式、异常的类型、副作用的范围都必须严格遵守契约。为什么契约这么重要因为AI生成的代码经常在内部实现上没问题但在接口行为上出问题。比如它可能把一个同步函数写成异步的可能把返回数组改成返回迭代器可能把抛异常改成返回错误码。这些改动在它看来是优化但对调用方来说是破坏性的。3.2 契约的三种表达形式契约可以用三种形式表达各有适用场景。第一种是类型签名。这是最轻量的契约用编程语言的类型系统来表达。比如在TypeScript里你可以定义一个接口类型明确输入输出的结构。AI看到这个类型定义就知道不能返回不符合类型的东西。第二种是接口文档。用结构化的文字描述每个接口的行为包括参数含义、返回值、异常情况。这种形式适合跨语言或者跨模块的场景。第三种是可执行的契约测试。这是最硬的契约直接写成测试代码任何违反契约的实现都会被测试拦住。在AI编程中我强烈推荐这种方式因为它把契约和TDD结合起来了。实际使用中我通常是三种一起上。先用类型签名定义数据结构再用接口文档补充行为说明最后用契约测试锁死关键行为。三层防护下来AI基本没有钻空子的空间。3.3 契约设计中的关键决策设计契约的时候有几个关键决策需要提前想清楚。第一个决策异常还是错误码这两种方式各有优劣。异常的好处是调用方不容易忽略错误坏处是控制流不直观。错误码的好处是显式坏处是容易被忽略。我的建议是对于可预期的业务错误用错误码或者Result类型对于不可预期的系统错误用异常。这个决策要在契约里明确写出来不能让AI自己选。第二个决策同步还是异步这个看似是技术细节实际上对调用方影响很大。如果契约里没写清楚AI可能会根据它自己的判断来选择。我的做法是在契约里明确标注每个函数的同步/异步属性。第三个决策副作用的范围。函数会不会修改传入的参数会不会写文件会不会发网络请求这些副作用必须在契约里说清楚。AI有时候会顺手加一些它认为合理的副作用比如加个日志、加个缓存这些如果不提前约定可能会引发意想不到的问题。我踩过的一个坑契约里没写清楚函数是否会修改输入参数AI生成的代码直接对输入列表做了原地排序。调用方后面还要用原始顺序的数据结果全乱了。后来我在契约里加了一条本函数不修改任何输入参数问题就再没出现过。4. TDD用测试把AI的行为锁死4.1 为什么TDD在AI编程中格外重要传统开发中TDD是一种可选的工程实践有人用有人不用。但在AI编程中我认为TDD几乎是必须的。原因很简单AI生成的代码你需要一种自动化的方式来验证它的行为是否符合预期。你不可能每次都逐行审查AI生成的代码那样效率还不如自己写。测试用例的本质是可执行的Spec。你写一个测试说输入A应该返回B这就是一条精确到不能再精确的规格说明。AI看到这个测试就知道它的实现必须让这个测试通过。没有任何模糊空间没有任何解释余地。而且测试还有一个好处它是回归防护。AI后面如果又生成了新的代码或者你让AI重构了某个模块跑一遍测试就知道有没有破坏原有行为。这在AI编程中特别重要因为AI重构代码的时候经常会顺手改变一些它认为不重要的行为。4.2 测试用例该怎么设计才能覆盖AI的盲区AI生成代码的盲区通常集中在几个地方边界条件、异常输入、并发场景、状态依赖。所以测试用例的设计要重点覆盖这些区域。边界条件包括空输入、单个元素、最大数量、临界值。比如一个分页函数要测试页码为0、页码为负数、页码超过总页数的情况。异常输入包括类型错误、格式错误、超出范围的值。比如一个接收邮箱地址的函数要测试空字符串、没有符号的字符串、有多个符号的字符串。并发场景包括多个调用同时修改共享状态、竞态条件。这个在AI编程中容易被忽略因为AI生成的代码往往没有考虑线程安全。状态依赖包括函数的行为是否依赖于之前的调用、是否有隐藏的状态。AI有时候会引入一些它自己都没意识到的状态依赖。我的做法是对于每个核心函数至少写四组测试一组正常流程、一组边界条件、一组异常输入、一组状态相关。这四组下来基本能覆盖大部分AI容易出问题的地方。4.3 测试先行的具体操作流程TDD的标准流程是红-绿-重构先写一个失败的测试然后写实现让测试通过最后重构代码。在AI编程中这个流程可以调整为第一步我来写测试。根据Spec和契约我把测试用例写好。这一步我不让AI参与因为测试用例是我表达预期的方式必须由我来控制。第二步AI来写实现。我把测试用例、Spec、契约一起给AI让它生成实现代码。第三步跑测试。如果测试全过进入下一步。如果有失败把失败信息反馈给AI让它修正。第四步我审查测试通过后的代码。重点看代码风格、可读性、是否有明显的性能问题。如果有问题让AI调整但调整后必须重新跑测试。第五步补充测试。如果我在审查过程中发现了测试没覆盖到的情况补上测试然后回到第二步。这个流程的关键在于测试是我写的实现是AI写的。这样就形成了一种制衡。AI不能通过修改测试来作弊因为测试不在它的控制范围内。5. 三重奏的完整实操从零实现一个数据处理模块5.1 需求背景与整体设计为了把前面的理论讲透我拿一个实际做过的模块来完整演示一遍。需求是这样的实现一个日志分析模块接收一批日志条目做过滤、聚合、统计输出分析报告。日志条目的结构是时间戳、日志级别、来源模块、消息内容。分析报告需要包含总条目数、各日志级别的数量分布、各来源模块的数量分布、时间范围、以及错误级别日志的样本列表。这个需求看起来不复杂但涉及多个处理步骤、多种边界情况非常适合用来演示三重奏的完整流程。整体设计上我把它拆成三个函数filterLogs负责过滤aggregateLogs负责聚合统计generateReport负责组装报告。三个函数之间通过契约连接每个函数都有独立的Spec和测试。5.2 第一步写Spec我先写filterLogs的Spec功能概述从日志列表中过滤出符合条件的日志条目。输入定义logs日志条目数组每个条目包含timestamp数字毫秒时间戳、level字符串取值为debug、info、warn、error之一、module字符串非空、message字符串。options过滤选项对象包含minLevel可选字符串默认debug、modules可选字符串数组默认空表示不过滤、startTime可选数字默认0、endTime可选数字默认Infinity。输出定义返回过滤后的日志条目数组保持原有顺序。核心逻辑遍历logs中的每个条目。如果options.minLevel存在过滤掉级别低于minLevel的条目。级别高低顺序为debug info warn error。如果options.modules非空只保留module在列表中的条目。如果options.startTime存在过滤掉timestamp小于startTime的条目。如果options.endTime存在过滤掉timestamp大于endTime的条目。返回所有条件都满足的条目。边界与异常如果logs为空数组返回空数组。如果logs为null或undefined抛出TypeError。如果某个条目的level不在允许的取值范围内抛出Error。如果options为null或undefined使用默认值。示例输入logs [{timestamp: 1000, level: info, module: A, message: test}]options {minLevel: warn}。输出[]。这个Spec写下来大概花了五分钟但它把所有的歧义都消除了。AI拿到这个Spec基本不可能理解错。5.3 第二步定义契约Spec是自然语言契约是结构化的。我用TypeScript的类型定义来表达契约interface LogEntry { timestamp: number; level: debug | info | warn | error; module: string; message: string; } interface FilterOptions { minLevel?: debug | info | warn | error; modules?: string[]; startTime?: number; endTime?: number; } function filterLogs(logs: LogEntry[], options?: FilterOptions): LogEntry[];这个类型定义就是契约。它规定了输入输出的结构AI生成的实现必须符合这个签名。如果AI返回了不符合LogEntry结构的东西TypeScript编译器会直接报错。契约里还隐含了一些约定函数不修改输入参数因为参数没有标记为可变、函数是同步的没有返回Promise、函数不抛出业务异常异常情况在Spec里单独说明了。5.4 第三步写测试测试是整个流程的核心。我针对filterLogs写了以下测试用例describe(filterLogs, () { const sampleLogs [ { timestamp: 1000, level: debug, module: A, message: d1 }, { timestamp: 2000, level: info, module: B, message: i1 }, { timestamp: 3000, level: warn, module: A, message: w1 }, { timestamp: 4000, level: error, module: C, message: e1 }, ]; test(空数组返回空数组, () { expect(filterLogs([])).toEqual([]); }); test(null输入抛出TypeError, () { expect(() filterLogs(null as any)).toThrow(TypeError); }); test(默认返回所有日志, () { expect(filterLogs(sampleLogs)).toEqual(sampleLogs); }); test(按minLevel过滤, () { const result filterLogs(sampleLogs, { minLevel: warn }); expect(result).toHaveLength(2); expect(result.map(l l.level)).toEqual([warn, error]); }); test(按modules过滤, () { const result filterLogs(sampleLogs, { modules: [A] }); expect(result).toHaveLength(2); expect(result.every(l l.module A)).toBe(true); }); test(按时间范围过滤, () { const result filterLogs(sampleLogs, { startTime: 2000, endTime: 3000 }); expect(result).toHaveLength(2); }); test(多条件组合过滤, () { const result filterLogs(sampleLogs, { minLevel: info, modules: [A, C], startTime: 2500, }); expect(result).toHaveLength(2); }); test(不修改输入数组, () { const original [...sampleLogs]; filterLogs(sampleLogs, { minLevel: error }); expect(sampleLogs).toEqual(original); }); test(非法level抛出Error, () { const badLogs [{ timestamp: 1000, level: invalid, module: A, message: x }]; expect(() filterLogs(badLogs as any)).toThrow(Error); }); });这九个测试用例覆盖了正常流程、边界条件、异常输入、副作用检查。写完之后我把Spec、契约、测试一起发给AI让它生成实现。5.5 第四步AI生成实现与验证AI生成的实现大致是这样的function filterLogs(logs: LogEntry[], options?: FilterOptions): LogEntry[] { if (logs null || logs undefined) { throw new TypeError(logs cannot be null or undefined); } const opts options || {}; const minLevel opts.minLevel || debug; const modules opts.modules || []; const startTime opts.startTime ! undefined ? opts.startTime : 0; const endTime opts.endTime ! undefined ? opts.endTime : Infinity; const levelOrder { debug: 0, info: 1, warn: 2, error: 3 }; const minLevelValue levelOrder[minLevel]; return logs.filter(log { if (!(log.level in levelOrder)) { throw new Error(Invalid log level: ${log.level}); } if (levelOrder[log.level] minLevelValue) return false; if (modules.length 0 !modules.includes(log.module)) return false; if (log.timestamp startTime) return false; if (log.timestamp endTime) return false; return true; }); }跑测试九个全过。我审查了一下代码逻辑清晰没有明显的性能问题。唯一想调整的是levelOrder对象可以提取到函数外面避免重复创建但这是微优化不影响功能。我让AI做了这个调整重新跑测试依然全过。整个过程从写Spec到实现通过测试大概花了二十分钟。如果不用三重奏纯靠提示词来回改我估计至少要一个小时而且质量还没这么有保障。5.6 另外两个函数的处理aggregateLogs和generateReport我用了同样的流程。每个函数都是先写Spec再定义契约再写测试最后让AI生成实现。aggregateLogs的测试重点覆盖了空输入、单元素、多元素、以及各种分组统计的准确性。generateReport的测试重点覆盖了报告结构的完整性、各字段的计算正确性、以及错误日志样本的截取逻辑。三个函数全部完成后我又写了一层集成测试验证三个函数串联起来的行为。集成测试也是我先写然后让AI调整实现来通过。最终整个模块的测试覆盖率达到了95%以上我对代码质量非常有信心。6. 常见问题与排查技巧实录6.1 AI生成的代码测试不过怎么办这是最常见的情况。我的处理流程是先看失败信息判断是测试写错了还是实现写错了。如果是测试写错了修正测试。如果是实现写错了把失败信息、Spec、契约、测试一起发给AI让它修正。这里有个技巧不要只发失败信息要把完整的上下文一起发。因为AI在修正的时候可能会为了通过当前测试而破坏其他测试。把完整的测试套件一起给它它就会考虑所有测试的约束。如果AI改了两三轮还是过不了我会停下来自己看看。有时候是Spec本身有矛盾有时候是测试用例之间有冲突。这种情况下需要先解决Spec和测试的问题再让AI继续。6.2 AI自作主张添加了契约之外的行为这种情况也很常见。比如契约里没写函数会打日志但AI生成的代码里加了一堆console.log。或者契约里没写函数会缓存结果但AI加了一个缓存层。我的处理方式是在契约里显式写出禁止项。比如加一条本函数不产生任何副作用包括但不限于日志输出、文件写入、网络请求、全局状态修改。这样AI就知道哪些事情不能做。如果AI还是加了那就在审查阶段删掉。删掉之后重新跑测试确保没有破坏功能。6.3 测试用例写得太细导致AI实现受限有时候我把测试写得太具体比如断言了内部函数的调用次数或者断言了具体的实现细节。这会导致AI的实现被过度约束它可能写出很别扭的代码来满足测试。解决方法是测试只断言行为不断言实现。测试应该关注输入什么、输出什么而不是内部怎么实现的。比如不要断言某个辅助函数被调用了多少次而是断言最终结果是否正确。6.4 常见问题速查表问题现象可能原因排查思路解决方法测试全过但功能不对测试用例覆盖不足检查是否遗漏边界和异常场景补充测试用例重新生成实现AI反复改都过不了Spec有矛盾或测试有冲突逐条检查Spec和测试的一致性修正Spec或测试再让AI实现实现通过了但代码很丑测试只约束了行为没约束风格审查代码风格让AI按指定风格重构重构后重跑测试AI添加了额外副作用契约没写禁止项检查契约是否完整在契约中显式禁止副作用集成测试失败但单元测试全过函数之间的契约不匹配检查各函数的输入输出定义统一契约定义补充集成测试6.5 几个让我省了很多时间的实操技巧技巧一把Spec、契约、测试放在同一个文件里。这样发给AI的时候不用来回切换AI也能看到完整的上下文。我通常会在文件顶部写Spec注释中间写类型定义下面写测试最后留一个空位给实现。技巧二用AI生成测试的骨架但自己填充断言。测试的结构describe、test的嵌套可以让AI生成但具体的断言必须自己写。因为断言是你表达预期的方式不能让AI代劳。技巧三每次只让AI实现一个函数。不要一次性让AI实现整个模块那样出问题的时候很难定位。一个函数一个函数地来每个函数都通过测试之后再进入下一个。技巧四保留每次生成的版本。AI生成的代码即使通过了测试也可能在后续重构中被改坏。保留版本历史出问题的时候可以快速回滚。技巧五定期让AI解释它生成的代码。有时候AI生成的代码能通过测试但逻辑很绕。让它解释一遍你能发现一些潜在的问题也能加深自己对代码的理解。这套三重奏的方法我从去年开始用到现在大概做了十几个项目。最大的感受是前期多花二十分钟写Spec和测试后期能省下几个小时的调试和返工。而且代码质量有保障合并到主分支的时候心里踏实。如果你也在用AI编程强烈建议试试这个流程。一开始可能会觉得繁琐但用顺了之后你会发现这才是AI编程的正确打开方式。

AI编程三重奏：Spec、契约与TDD实战指南

相关推荐

Claude Code 精通：命令行AI编程助手实战指南

身体调理手法怎么选？从技术原理到鉴别流程的实用指南

Ponytail插件：轻量级前端交互技能单元实战指南

更多资讯

AMLL Vue 绑定包演进实录：从 0.4 到 0.5 的架构重构、歌词组模型与关键修复解读

无铜点击葡聚糖：DBCO-Dextran DBCO-葡聚糖DBCO-Dex

开源AI助手WorkBuddy企业化改造：私有化部署与协作升级

易语言恒云雨驱动控制模块：用户态与内核态通信实战指南

WebSphere MQ入门拆解：队列管理器、通道与系统管理实战

从零搭建多角色博弈模拟系统：多智能体强化学习实战与调优

今日更新

小波包能量谱原理与MATLAB实现：从频带分解到故障特征提取

基于LSTM的网易云音乐评论情感分析：数据清洗与模型调优实战

Alpha-Beta剪枝与极大极小值算法：博弈树搜索原理与实战优化

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？