每次AI编程工具升级我都会拿同一个内部项目去测。这几十个版本的实测里我最大的感触是AI生成代码的能力确实在变强但随之而来的技术债也在同步膨胀。一版功能跑通很快可等到提测、联调、上线之后接手的同事开始在群里疯狂艾特你的时候问题才真正浮出水面。这就是我坚持做CleanCode AI编程标准代码生成器这套实践的原因也是这第三十三弹想重点跟你聊透的东西——AI编程不是让AI放飞自我当写手而是要给它一套标准、规则和契约让代码生成的那一刻就是规范的而不是事后靠人肉Review去擦屁股。技术债这个东西最狠的不是还的时候有多累而是你根本不知道自己欠了多少直到某次重构把你彻底埋掉。这弹内容我不打算讲什么玄乎的架构理念就说清楚三件事为什么AI生成的代码容易埋债、我是怎么通过一套标准化的提示词模板做到生成即规范的、以及这套东西在实际项目里落地后到底改了什么。适合正在用各类AI编程软件做实际项目、又苦于代码质量不可控的团队和个人开发者尤其是那些已经从试试看进入真刀真枪干活阶段的人。1. AI写代码的本能动作恰恰是技术债的加速器先说一个可能让不少人不太舒服的结论AI默认的写代码方式天然倾向于制造技术债。不是模型本身写得烂而是它的生成逻辑决定了它不会替你考虑明天这个代码要承受什么。1.1 AI的单选快答模式与局部最优陷阱你用AI写代码的时候它本质上在做的事情是根据你给出的上下文预测最可能的下一段代码是什么。这个预测机制决定了两件事。第一它倾向于选择见过的、常见的、概率高的写法而不是适合你项目的、符合你们规范的写法。第二它只关注你问的这个局部问题不会主动去对齐你整个项目的架构边界。打个比方你让AI写一个订单状态更新的接口它大概率会给你一个能跑的CRUD实现——REST规范可能有参数校验可能有但状态机的流转权限在哪控制、事件要不要发、并发重复提交怎么处理、表结构变更会不会有锁问题这些它基本不会管。这就很像一个经验尚浅的实习生你给他一个明确任务他能做出来但你看完代码总得自己动手改一堆地方。区别在于实习生你会下意识去教AI的产出你往往会直接拿去用——因为看起来挺完整。我见过最典型的场景团队里用AI辅助开发三个月一开始效率确实翻倍了但到第四个版本迭代时所有人开始频繁踩自己之前生成的代码的坑。改一个字段要翻四五个文件因为每个文件都有一套自己的命名和风格加一个新接口得复制粘贴一大段已有代码然后再改最崩溃的是出Bug时根本追不动日志和错误处理风格完全不统一。1.2 无法AI复审的隐性债务一致性、边界与命名漂移技术债里最难还的那部分往往不是逻辑错误而是一致性问题。我这里有一个之前整理过的对照表是AI默认生成代码和标准代码之间的典型差异维度AI默认生成的常见状态标准代码的要求命名风格混合有时resource_id有时resourceId取决于训练数据中出现频率全项目统一命名映射表、命名词典兜底错误处理有的地方抛异常有的地方返回null有的地方直接吞掉统一遵循编队规则同类错误走同一路径边界条件核心链路覆盖多异常分支经常缺失参数边界、并发边界、缓存穿透边界显式声明日志输出随缘打点有的用print有的用logger级别混乱结构化日志必有上下文ID便于链路追踪依赖使用能直接用第三方库就绝不手写不考虑体积和License依赖灰度准入最小化引入上下文适配很少主动适配项目现有基座代码以项目骨架为上下文起点先对齐再扩展这些问题单个拎出来都不致命但它们叠加在一起之后你的项目就变成了一个能跑但谁也啃不动的黑箱。我当时做CleanCode标准代码生成器这套实践最根本的出发点就是既然AI最大的问题是无标准地回答任何问题那我们就用一套标准强迫它。不是靠碰运气而是靠规则把AI的输出框在一个合法的范围内。2. 标准代码生成器的第一层把提示词模板改造成规则引擎很多人的提示词还停留在帮我写一个xx接口帮我实现一个xx模块这种对话式用法。这种用法不能说错但它不算是工程化的方式。我做的这套东西核心是把提示词变成一份可复用、可版本管理的规则文件——我把这种文件称为规则引擎。2.1 三段式提示词结构情境、契约、输出格式我在第三十二弹里提到过提示词三段式这次展开说一下。标准代码生成器的提示词结构我长期稳定在三段第一段叫情境锚定也就是告诉AI它此刻扮演的角色和所在的项目背景。但这里的关键不是写你是一个资深工程师这种废话而是要把项目的技术栈特征、已有的目录结构、依赖约束、审计要求写进去而且最好是机器可感知的。第二段叫变更契约对应到具体需求时不要说实现订单取消功能要说订单取消功能的定义、边界条件、依赖服务、返回契约、异常出口分别为xxx。AI在契约明确的情况下生成的代码和没有契约时生成的代码质量差距极其明显。第三段叫输出格式约束比如目录归属、文件命名、函数粒度、注释规范、日志埋点位置。这一步最关键的是强制AI在输出代码的同时输出一份生成说明解释它为什么这样设计便于你快速审查。我直接放一份我现在在用的简化模板你感受一下模式# 角色情境 你是本项目的后端主程。项目采用Spring Boot 3 MyBatis-Plus代码规范见/quality/checkstyle.xml。 所有接口通过/controller/service/mapper三层编写禁止在Controller中出现业务逻辑。 统一返回结构为ResponseModel错误码定义见/enums/ErrorCode.java。 # 变更契约 需求实现订单取消接口 cancelOrder(orderId, operatorId, cancelReason) 契约 - 仅待支付/已支付订单可取消已发货/已完成订单不可取消 - 取消后写入订单状态变更流水表 order_status_log - 若该订单存在进行中的售后单则拒绝取消 - 接口返回订单取消结果及当前订单状态 - 涉及并发修改时使用分布式锁key为 order:cancel:{orderId} # 输出格式 1. 按Controller→Service→Mapper分层输出完整代码禁止省略关键逻辑 2. 每个public方法必须携带javadoc说明入参、出参、异常情况 3. 日志必须通过Slf4j并包含traceId上下文 4. 额外输出一段生成说明说明你如何处理状态边界和并发锁用这份模板生成的代码和帮我实现订单取消功能生成的代码多出来的不是具体某一行而是项目的一致性。因为你每次都在用同一份契约结构去约束它它在不同项目中产出的代码风格会逐步收敛到同一套框架内。2.2 让规则随需求变化而不崩塌不过这里有一个很现实的坑提示词维护成本。需求是天天变的你不可能每次改需求都去改一遍长提示词。我的做法是把提示词做成三段拆片项目基础规范切片、需求契约切片、临时指令切片。项目基础规范切片是长期不变的比如技术栈、代码风格、错误码规范需求契约切片是每次新建需求时填写的内容临时指令切片就是当次对话中追加的调整比如这个接口不要走缓存。这样做的好处有两个。第一基础规范可以被固定成团队共享的模板新人来了直接引用不用自己造。第二当AI产出不符合预期时你可以精准定位是切片里的哪一部分出了问题——大多数时候是契约这一片写得不够精确而不是AI本身不行。我在团队里落地这套方式之后代码审查的时间平均降了一半左右。原因很简单AI产出的代码在结构上已经被框住了Reviewer需要关注的是业务逻辑边界而不是命名、分层、日志这些重复性的格式问题。3. 第二层把CleanCode规则翻译成AI能执行的代码契约有了提示词的结构只是第一步真正的难点在于你怎么把CleanCode那堆抽象原则变成AI能一条条对照执行的规则。Robert C. Martin的《Clean Code》讲的是理念但AI不是人它不能领悟函数要短小职责要单一这种话背后的模糊判断——你必须把理念翻译成可执行的检查项。3.1 从原则到检查项一个命名规则的落地案例拿最简单也最要命的命名来说。命名要清晰表意这种话对AI毫无约束力。我踩过很多次坑之后把命名规则翻译成了一份负向检查清单直接写进提示词里所有布尔变量必须以is、has、can开头禁止使用flag、status这类模糊词禁止在变量名中出现类型前缀strName、intCount这种匈牙利命名残留同一个业务实体在两个类中必须使用相同的命名例如订单状态一律用orderStatus禁止一个地方叫orderState一个地方叫status方法名必须以动词开头且不允许出现两个语义重叠的动词例如getAndFetch、updateAndModify这种命名禁止将表名字段名直接用作Java属性名而不做风格转换所有列转驼峰必须在映射层完成这些规则都储存在基础规范切片里。AI每次生成代码之前这些规则都在它上下文中所以它产出的代码从第一行起就是按照这套命名体系走的。这带来的实际收益是像之前那种resourceId写了三处风格的问题直接从生成源头消失了。3.2 分层边界、依赖方向与禁止连招的约束表达命名只是最表面的一层。我写CleanCode标准生成器真正花力气的地方在分层边界和依赖方向上。一个很常见的AI出码事故是你让它增加一个查询接口它顺手就在Controller里写了一堆业务判断甚至直接查了数据库。这段代码能跑但Service层的意义就没了后续要复用的逻辑被焊死在接口层里改都改不动。我后来在规范切片里加了一些硬性的禁止项让AI在生成时就规避这类结构问题。例如Controller层禁止调用Mapper与Dao禁止出现任何SQL或ORM语句Service层禁止直接操作HttpServletRequest/Response业务方法与Web层无关Mapper映射文件中禁止出现重复的条件片段公共SQL必须抽成可复用sql片段禁止在循环内调用远程服务或数据库查询需要批量处理时先做批量接口设计禁止为单一分支逻辑提前建表字段归并必须在设计评审后进行这些禁止项本质上是在告诉AI你生成的代码要能够被团队的架构约束校验参考Checkstyle与ArchUnit规则执行在模板里加入它们并用它检测AI的输出。这样做了一段时间之后我意识到CleanCode生成器这套东西其实是在做一件非常朴素的事把人的经验判断沉淀成机的执行规则。人做一个月的项目能形成对团队规范的直觉那份直觉很难量化但AI需要的是量化之后的规则它才能不跑偏。3.3 工程化的Code Style校验双轨制所以我在落地这套实践的时候并没有把全部希望寄托在AI自觉上。我采用了两条轨道第一轨是生成前的规则注入。上文说的那些规范、禁止项、命名词典全部在提示词阶段就塞给AI。第二轨是生成后的自动化校验。AI生成的代码进入代码库之前先过我这边搭的一套自动化检查包含Checkstyle查风格、SpotBugs查缺陷隐患、ArchUnit查架构边界任何一项不过就自动打回并附上具体违规说明。我的经验是在最初几周打回率确实很高常见的是命名不规范或分层边界越界但那段矫正期过去之后AI产出的代码质量会出现一个明显的台阶式上升。因为大模型的上下文记忆是存在的你反复修正同一个地方它在这个项目中的输出会越来越贴你的规范。如果你问我这套东西最值钱的部分是哪个我会说是那个生成说明。让AI每次出完代码必须解释它的设计决策看似多了一步成本极低却能让你在三分钟内判断它是否真的理解了需求还是只是在拼模板——这种判断力在代码生成量越来越大的今天就是最稀缺的能力。4. 第三层测试、日志与可观测性从生成阶段一次性注入CleanCode不光是代码风格干净还包括一个更实用的维度这套代码好不好测好不好调。技术在演进过程中最需要的恰恰是这个——代码不是写完就完而是要经得起联调、排错、线上追踪。4.1 可调测性为什么必须在生成时解决过去我们写代码测试和日志往往是在代码完成之后补的更常见的现实是——压根没补。用AI编程这个事情变得更夸张AI能快速生成实现代码但如果你不额外约束它它大概率不会主动给你写配套的单元测试和日志链路。这不是模型傻而是你的提示词里根本没要求它做这件事它当然选择最小化输出。可调测性这个属性必须前置到生成阶段而不是事后后悔。原因在于事后补日志你得先看懂逻辑走向事后补测试你得先理解边界条件。这两件事的成本在任何项目里都比一次性写要高得多。我的做法是把日志规范和测试要求一起塞进规范切片。具体落地的效果是每一次AI生成的业务方法都会自动带有一套标准的日志埋点——方法入口记录入参关键信息和traceId分支决策点记录决策结果异常出口记录完整的堆栈和上下文。4.2 结构化日志与链路追踪的埋点标准这里有一个实际场景可以分享。我以前处理过一个线上问题订单支付回调偶发失败报错日志里能看到异常信息但完全不知道是哪个订单、哪个步骤、哪一次回调出的问题。排查起来只能去翻网关日志和数据库流水一个Bug查了大半天。用标准代码生成器改了生成规范之后同一个问题再出现时日志长这样// 在支付回调处理入口 log.info(payment callback received, traceId{}, orderId{}, payload{}, TraceContext.getTraceId(), req.getOrderId(), sanitizePayload(req)); // 在回调结果落地 log.info(payment callback handled, traceId{}, orderId{}, result{}, currentStatus{}, TraceContext.getTraceId(), req.getOrderId(), result.getCode(), order.getStatus()); // 在异常出口 log.error(payment callback failed, traceId{}, orderId{}, stepUPDATE_STATUS, err{}, TraceContext.getTraceId(), req.getOrderId(), e.getMessage(), e);排查问题的时候只需要按traceId把日志串起来整个请求链路一目了然。这就是生成即规范的一个非常直观的体现——代码生成的那一刻就嵌入了可观测性的基因而不是后期靠人肉补救。4.3 单元测试的标配化生成策略测试也是同一个思路。我在提示词里明确要求所有新增的Service方法必须同时生成对应的单元测试代码并且给出测试用例设计提纲。AI生成的测试可能做不到你团队里资深测试设计专家的水平但它能覆盖最核心的几条路径正常路径、参数异常路径、依赖异常路径、边界值路径。不要小看这四条路径的价值。我粗略统计过先前线上Bug中大概有70%都落在正常路径以外的分支没有覆盖这一块。AI在生成时就被要求把这四条路径写进测试等于把最常出问题的区域提前锁死。给AI的测试契约长这样# 测试契约 对上述Service实现补齐单元测试要求 1. 使用JUnit 5 Mockito不依赖真实数据库 2. 必须覆盖四个场景正常取消成功、订单状态不允许取消、存在未完结售后单拒绝取消、分布式锁获取失败抛出异常 3. 禁止用verify(service, times(1))这类无意义断言充数必须校验返回值或抛出的异常类型 4. 每个测试方法使用中文注释说明场景定位别小看中文注释说明场景定位这条——当测试用例数量增长之后新接手的人能不能快速理解每条用例在测什么直接决定测试代码是否会被维护还是被人偷偷skip掉。5. 生成之后的维护防线代码审查清单与人肉兜底在强调生成即规范的同时我必须诚实地告诉你一个边界标准代码生成器再完善也不可能完全替代审查和人的判断。它可以消灭低层次的一致性问题和结构问题但业务语义正确性、隐藏的交互影响、以及设计层面的取舍仍然需要人来决策。5.1 用生成说明当审查抓手我最推荐的审查方式是围绕生成说明来展开而不是从头到尾逐行读代码。实现上我在提示词中要求AI每次输出代码后附上一段生成说明说明设计决策、对边界条件的处理、以及采取的异常策略。审查时先重点读这段说明用业务预期去对照它的设计决策是否合理再针对说明中含糊或跳过的点去查对应代码。这个方式的效率提升非常明显。一次标准的代码审查从过去逐行阅读可能要半小时压到了先看说明花几分钟再有针对性地看关键代码几分钟。如果你发现AI生成说明里对状态边界一句带过那基本可以预判这码十有八九在并发场景下会出问题你重点查这里就够了。5.2 我实际在用的审查清单我把标准代码生成器的规则和审查清单联动起来使用。AI产出代码之后我用下面这份清单做快速核对命名是否符合团队命名词典分层边界是否有越层调用异常处理路径是否统一日志是否覆盖入口、出口、异常三个点位边界条件是否有显式处理有没有循环内远程调用测试用例是否覆盖四条核心路径有没有引入未在依赖白名单内的新依赖这套清单与提示词中的规范切片一一对应确保审查时心里有数。有一件事值得反复强调规则注入得越多AI产出的规范性确实越高但越过某条线之后AI的自由度会被压缩得很厉害——你会发现它开始用大量重复的模式凑厚度生成的代码做出特别刻意的结构来满足规范。所以规范切片的条目要基于真实发生的坏味道来维护而不是看到什么规范书上的原则就往里塞。5.3 技术债发生之后的应急处理哪怕规则完善了也总有漏网之鱼。AI用了某个被废弃的API、引入了某个有安全漏洞的依赖版本、或者生成的逻辑在特定数据量下出现性能问题这些你都不能完全指望生成阶段规避。我的建议是在技术债发生之后别急着还区分一下腐烂的代码和欠下的债。前者是指已经腐化、牵一发动全身、重构成本极高、甚至影响功能迭代的部分该处理就得处理越拖越贵。后者是指结构上还健康、只是暂时落后于新规范的部分比如命名风格不一致这个债挨个文件清理改起来风险不大排期慢慢还即可。再加上一条底线原则对于任何AI生成的代码禁止不经过检查直接合并。就算生成器做得再完美这一点也不能松。可以在CI流水线里做卡点确保没有绑定配置文件之外的新依赖、没有命中危险API黑名单用它压缩低级问题进入主干的机会。6. 落地这套实践后真实项目的三项变化如果你能看到这里我想你应该已经理解标准代码生成器本质上不是某个提示词技巧而是一整套将规范、规则、校验嵌入到AI编程工作流里的工程方法。整套落地之后具体到项目上的变化我说几个真实的感受。第一个变化是测试阶段的噩梦变短了。过去新功能提测的头两天群消息基本都是联调对不上、环境问题、日志找不到这类问题。现在因为日志链路和错误返回契约在生成阶段就统一联调时接口报错直接看traceId拉日志大概率一次就能定位是前端传参问题还是后端逻辑问题。第二个变化是代码交接的描述成本大幅下降。以前从一个模块转到另一个模块新人要先适应各种不同的编码风格全靠一张嘴讲。现在所有代码都长一个样——不是夸大的说法是真的几乎一个样新人看着生成说明就能上手改老同事也不用反复讲那些潜规则了。第三个变化最微妙是审查保护的隐形防线。CI流水线里挂了Checkstyle、SpotBugs和ArchUnit检查之后很多以前靠人盯的低级问题现在被机器直接拦住测试和审查阶段遇到的非业务类问题肉眼可见地变少了。这套东西的价值不能光从写了多少行代码来算。它更像是在项目里铺了一根底线——AI生成的速度再快也不会把项目的结构带崩。至于后续还能怎么玩我自己在计划的是把规范切片和代码库的实时状态联动起来AI在生成代码前先扫描现有代码结构动态生成上下文而不是每次都塞一套静态规范。这应该是下一弹要折腾的事了。
