做了这么多期“CleanCode AI编程标准代码生成器”的系列实践，我最深的一个感受是：问题的核心从来不是AI能不能写代码，而是AI写完的那一坨东西，三个月之后还改不改得动。市面上各种AI编程软件越来越强大，Codex、Copilot这些工具，随便一个需求扔过去，几十秒就能给你吐出一段能跑的代码。但“能跑”和“值得留”之间，隔着整整一条技术债的河。这一弹我要聊的就是那架桥：怎么让代码生成器输出“生成即规范”的结果，在源头就把技术债拦下来，而不是等代码堆成山之后再去还。
先说这东西能解决什么问题。你正在用AI编程工具写功能，生成倒是快了，但命名全是process、data、temp，一个函数二百行，异常处理要么全吞要么全不写，测试根本无从下手——这种情况我以前在团队里见得太多了，几乎每个刚把AI编程引入日常开发的组都会经历一轮“爽三个月，痛一整年”的循环。这套“标准代码生成器”的思路，就是给AI编程装上一套净水器：在生成阶段强制约束，在产出之后自动校验，让代码从诞生那一刻就符合一套可维护、可调测、低技术债的标准。这篇文章适合谁？适合正在使用AI编程软件的个人开发者，也适合想把AI辅助开发真正落地到团队流程里的技术负责人。读完你能直接带走一套四步落地的方案和几组能抄作业的配置。
1. 为什么AI编程最大的坑，是“技术债批发”
1.1 AI编程的“三快三乱”困境
先说一个真相：现在的AI编程软件，优化目标基本都是“生成速度”和“通过率”。你给它一个需求，它最关心的是赶紧产出一段看起来完整、能跑通的代码，而不是这段代码在真实项目里活不活得下去。于是你会看到一种非常典型的“三快三乱”现象。
快是真的快。写一个函数快、堆一个模块快、出一个Demo快，过去要两小时的CRUD页面，现在十分钟就完了。但乱也是真的乱。命名混乱，函数叫doSomething、变量叫tmp、常量散落各处；依赖混乱，一个工具函数被复制进五个模块，谁也不引用谁的；异常路径混乱，要么except Exception一把梭全吞掉，要么压根没有try，一崩到底。
我举一个特别常见的例子。有次让AI写一个订单取消接口，它生成的核心逻辑大概是这样的：一个函数里干了四件事——校验订单状态、计算退款金额、记录操作日志、调用外部支付接口退款。看着都能跑，但等你要写单元测试的时候就傻眼了：这个函数副作用太多，根本没法单独测试；等产品说“取消订单要支持只退部分金额”，你得在一大坨代码里小心翼翼地找“退款计算”到底在哪一行。这就是典型的技术债批发：AI把问题从“写代码难”转移成了“改代码难”，而且这个难是批量复制的，一次生成几个文件，就攒了几份债。
1.2 技术债不能靠“事后还”，要在“源头断”
常规的应对思路是什么呢？很多团队的做法是“AI生成代码，人工做代码评审，Review发现问题再改”。听起来没问题，但落地过你就知道，这种方式有巨大的两个Bug。
第一，AI的“坏习惯”是稳定的。你这次Review发现了5个问题，改完提交了；下次你换个需求再让它生成，它大概率又重新写出了同样风格的代码。因为AI的学习上下文是你的项目代码库和提示词，你只在Review阶段拦截，而没有在生成阶段约束，那每一次新代码都在用同样的错误方式重来一遍。第二，人工Review本身就是资源瓶颈。你让高级工程师盯每一段AI生成代码，盯着盯着就变成了人肉审码机，成本比直接自己写还高。
所以“标准代码生成器”的核心思路，是把规范前移，做四件事：
- 把CleanCode规范拆成机器能判断的规则，写进配置文件；
- 把规范配置挂载到AI编程工具的上下文里，让它生成时就被约束；
- 用静态检查工具加AI自审做自动校验收口；
- 用技术债指标做持续度量，谁欠债谁负责。
一句话总结：以前是“AI写，人改”，现在改成了“规矩写，AI照着写，机器验”。这样的话，技术债就不是“事后还”而是“源头断”。
1.3 “第三十五弹”意味着什么：从Prompt到体系
有朋友可能会问，一个系列更到第三十五弹，怎么还有东西写？我觉得恰恰是前三十四期的积累，才让这一篇文章有底气去讲“体系”而不是“技巧”。
早期我做AI编程辅助，跟大部分人一样，全靠在提示词里拼命叮嘱：请你写出干净的代码、请加上注释、请保持命名清晰。说实话，效果不稳定，偶尔运气好能生成不错的代码，更多时候AI会阳奉阴违——开头一段代码规规矩矩，写到后面就开始放飞。后来我开始把规范沉淀成项目里的CONVENTIONS.md文件，再后来加入了静态检查、技术债指标、代码骨架模板，一步一步把“靠运气”变成了“靠系统”。第三十五弹能聊的，正是这套沉淀下来的体系化方案，不是某个灵光一现的提示词，而是可以复制到任何AI编程软件上的一套标准层。如果你愿意，也可以把它理解成：给AI编程套上了一个“带规范的脚手架”。
2. 标准代码生成器的核心设计：让AI“戴着镣铐跳舞”
2.1 把CleanCode从口号拆成可检查的规则
“代码整洁之道”这四个字听起来特别玄学，什么叫干净什么不干净，每个人理解都不一样。但落到标准代码生成器这个场景里，就必须把它变成机器能理解和执行的硬性约束。我在实践过程中，把CleanCode拆成了下面这些可量化、可判断的规则：
- 命名规则：函数名必须包含动词，能表达行为意图；变量名必须是名词或名词短语，不允许出现
a、b、tmp这类单字母和无语义命名； - 函数规则：单个函数不超过30行，超过必须拆分；函数参数不超过4个，超过必须用配置对象或数据类；
- 复杂度规则：圈复杂度不超过10，函数内嵌套不超过3层，超过必须提取子函数；
- 异常规则：不允许空
except，不允许吞异常；出错的路径必须显式抛出或返回结果，且必须记录日志； - 职责规则：一个函数只做一件事；禁止在业务逻辑层直接操作数据库连接；
- 注释规则：注释只解释“为什么”，不解释“是什么”；代码本身必须能自解释。
这些规则一旦确定，就可以同时干两件事：一是作为配置给AI编程软件的提示词上下文，让它生成代码时主动避雷；二是作为静态检查和代码评审清单，自动去校验AI生成的产物。CleanCode就从一种审美偏好，变成了可以批量执行的工程标准。
2.2 生成器的三层结构：模板层、规则层、验收层
我搭的标准代码生成器，在实际使用中分成了三层，每层解决不同的问题，缺一不可。
第一层是模板层。这是最容易被忽视的部分。很多AI编程项目失败，是因为让AI从零开始写一个完整模块，AI自由发挥的空间太大了。我的做法是先准备好领域骨架：比如新增一个业务接口，先给定标准的文件结构（入口文件、领域服务、仓储接口、DTO定义、异常定义），让AI只能在模板的空隙里填逻辑。模板层解决的是“结构统一”的问题，AI再怎么生成，产物的骨架永远是标准化的。
第二层是规则层。这一层把上面拆出来的CleanCode规则变成两部分：一部分是项目根目录的CONVENTIONS.md，这是给人看的，也是AI编程工具能读取的项目记忆；另一部分是“生成时提示词”里内置的硬性约束，比如“不要生成超过30行的函数”“不允许使用裸except”这类命令。规则层解决的是“生成即合规”的问题。
第三层是验收层。这一层负责兜底，因为不管规则写得多细，AI总有钻空子的时候。验收层由三件套组成：静态检查工具（ESLint、Pylint这类）、自动化测试、以及一个“AI自审”环节——让AI自己解释生成的代码是如何满足CleanCode规则的，越解释越容易暴露问题。验收层解决的是“违规有代价”的问题。
2.3 接入主流AI编程软件的具体姿势
很多朋友问，这套东西是不是要自己开发一个代码生成器？其实不用。现在主流AI编程软件，像Codex、Copilot这类产品，都已经支持自定义指令、项目记忆、多文件上下文等功能。你要做的事情，就是把三层结构挂载进去。
我的标准做法是这样：
- 在项目根目录放两份关键文件：
AGENTS.md（给AI编程软件看的全局规范）和CONVENTIONS.md（详细代码约定）； - 在AI编程软件的设置里，把
AGENTS.md设为项目级指令，确保每次对话都自动加载； - 遇到新需求，不是直接说“帮我写一个订单模块”，而是说“根据模板层结构，按照公约规范，生成订单模块，遵守三层代码约定”；
- 每次生成完，先跑一遍规则层的静态检查，再让AI做自审，最后才提交代码。
这套接入方式的好处是：不用换工具就能见效，而且团队的代码规范越完善，AI生成的合规率就越高。我用了一段时间之后，AI生成的代码需要人工修改的比例，从最初的差不多一半，降到了不到两成。
3. 实操：从普通生成到规范生成的四步落地
3.1 第一步：写一份团队能执行的CONVENTIONS.md
不管你的AI编程软件是哪个，第一步永远是同一个：先把规范变成白纸黑字的文件。只有写下来的规则，AI才知道要遵守；也只有写下来的规则，评审人才有依据去挑毛病。
我在这里放一份精简版模板，你可以直接改成自己团队的版本：
# 项目代码公约（CONVENTIONS.md） ## 命名 - 函数名：动词开头，表达意图，如 getUserById，严禁 process、handle 这类万能动词 - 变量名：名词或名词短语，如 userList，严禁 tmp、data、res 这类无语义命名 - 布尔变量：以 is/has/should 开头，如 isActive ## 函数 - 单个函数不超过30行，超过必须拆分 - 参数不超过4个，超过使用参数对象 - 圈复杂度不超过10，嵌套不超过3层 ## 异常 - 禁止空 except 与空 catch - 禁止吞异常；必须抛错或返回结果，且记录日志 - 受检异常的转换策略要显式声明 ## 模块 - 每层代码职责单一：控制器只做参数校验和路由，领域服务只做业务规则，仓储只做数据访问 - 禁止在业务逻辑里直接拼接 SQL ## 测试 - 新增功能必须包含正向、反向、边界三条用例 - 测试命名使用 方法_场景_预期结果 格式 ## 注释 - 只解释“为什么”，不解释“是什么” - 代码本身能说清楚的，不要加注释这份文件写完，放进项目根目录，同时复制一份到AI编程软件的自定义指令/项目记忆里。你接下来会发现，AI生成代码的规范程度会有一个肉眼可见的提升，因为它的“角色设定”变了。
3.2 第二步：设计“标准生成提示词”，让AI输出即规范
配置文件是底座，提示词是扳机。就算AI记住了规范，如果你给的指令太笼统，它依然会朝着“尽快跑通”的方向使劲。所以我准备了一套可以直接抄走的标准生成提示词模板，每次新生成代码时都会带上。
请作为本项目的高级工程师，按照项目根目录 AGENTS.md 和 CONVENTIONS.md 中的全部规范， 完成以下任务。 需求描述： [在这里填写具体需求] 输出要求： 1. 先生成代码结构说明，列出涉及的文件清单和各文件职责，不超过10行； 2. 然后生成代码文件，文件之间通过明确的接口互相调用； 3. 每个函数必须单一职责，行数不得超出约定上限； 4. 禁止生成裸异常捕获，所有错误路径必须显式处理； 5. 核心业务路径必须包含可测试的纯函数； 6. 代码中只有“为什么型”注释，禁止冗余逐行注释。 生成完成后，请另行说明： - 每个函数的功能和复杂度是否合规（一句话即可） - 潜在技术债点（如果有） - 建议的人工Review关注点这套提示词有几个隐蔽但很关键的细节。第一，它要求AI先输出结构说明再写代码，这相当于强迫AI在动手前做一次设计，而不是边写边编。第二，它要求AI在最后自我说明合规性和潜在技术债点，这能明显减少AI“理直气壮地写出烂代码”的概率。第三，“建议人工Review关注点”这一条尤其有用，它把AI从“生成者”变成了“配合评审者”，后续你检查代码时会有更明确的方向。
3.3 第三步：生成之后，用“机器+AI+人”三重校验关
生成完代码，不等于可以直接提交。我的习惯是做三道校验。
第一道是机器校验。跑的静态检查工具取决于项目语言，Python用Pylint加flake8，JavaScript用ESLint，Java可以用Checkstyle。关键在于你必须在配置文件里把严格等级拉满，把“函数过长”“圈复杂度过高”“未使用变量”这些规则调成error级别。AI生成的代码通常会在这道关被拦下一批。
第二道是AI自审。把生成完的代码重新交给AI编程软件，让它做一次独立Code Review，要求它挑问题而不是夸自己。实操中我发现一个小技巧：让AI用“如果这是接手的遗留代码，你会怎么吐槽”的视角来审，效果比平铺直叙的“请检查代码质量”好得多。大多数AI会老老实实指出自己刚生成的代码中的一堆坏味道。
第三道才是人工评审。人工只看AI标记过的风险和静态检查的高危项，做的是“减法”而不是“通读”。因为有前两道关卡打底，人工评审的压力会小很多，重点只需要放在业务正确性上。
3.4 第四步：用技术债指标验证“源头杜绝”效果
规范这东西，不度量就没有说服力。我在团队里长期追踪四个技术债指标，每个指标都有清晰的指向意义：
- 代码重复率：衡量模块复用程度，AI最擅长复制粘贴，这个指标异常敏感；
- 圈复杂度均值：衡量逻辑复杂度，越高越难测试和修改；
- 注释密度与行内注释占比：衡量代码自解释程度，自解释代码才是低维护成本的代码；
- 新增代码评审意见数量：衡量生成质量的直接反馈。
早期我们让AI随便生成的时候，统计到的数据大概是这样的：
| 指标 | 普通AI生成产物 | 规范生成器产物 |
|---|---|---|
| 代码重复率 | 12%~15% | 3%以下 |
| 圈复杂度均值 | 9~12 | 5~7 |
| 人工评审平均意见数/百行 | 4~6条 | 1~2条 |
| 单测覆盖关键路径 | 常在30%以下 | 强制80%以上 |
这里我注明一下，数据范围来自我们团队自己的对比实验，不同项目会有浮动，但趋势是一致的。我见过最夸张的一次差异，是一个老项目里的重复代码率从14%降到2%，原因很简单：AI不再各写各的工具函数了，所有公共方法都走我们模板层定义好的工具库。技术债从源头就被制度拦住了，而不是靠后期一次次重构去追债。
4. 易调测、易维护的底层逻辑：规范不是好看，是便宜
4.1 调试省力的根源在于“职责单一”和“语义化命名”
一个很容易被忽略的事实是：规范代码调试省力，不是玄学，是工程代价前移。你在普通AI生成的代码里调试，时间花在哪？花在“看懂这段代码到底想干什么”。一个叫processData的200行函数，你打个断点，根本不知道该看哪一行，只能一行行读完，读完发现它对数据库做了写入、对外部接口做了调用、还偷偷改了一个全局缓存。这时候调试根本不是调试，是在考古。
规范代码则完全不一样。首先，语义化命名让你的断点位置一目了然，想查退款金额计算，你直接去calculateRefundAmount()，连Search都不用。其次，职责单一让Bug的定位范围大幅缩小，问题只会出在某一个小函数内部，而不是一个巨型函数里的某几行。我在实际项目里统计过，同样一个Bug，在规范代码里的定位时间基本是普通AI代码的三分之一以内。这不是我手快，是结构化优势。
4.2 维护成本低的核心在于“依赖最小化”和“接口稳定”
代码维护最痛苦的时候，不是写新功能，而是改老功能。普通AI生成代码最可怕的地方在于，它非常喜欢把辅助逻辑揉进调用方。你改一个订单状态，就担心会不会影响旁边那个日志记录模块，因为它的日志逻辑就被AI顺手写在了同一个函数里，跟核心业务耦合得死死的。
标准代码生成器的三层结构，从机制上就堵住了这个隐患。模板层强制了模块边界，控制器只管路由、领域服务只管业务、仓储只管数据；规则层的“单一职责”约束又保证了一个函数很难蚕食另一个函数的领地。这样当你需要调整业务规则时，接口是稳定的，你只需要改领域服务内部的一段逻辑，调用方基本不受影响。维护成本低，说白了就是“改一处，只影响一处”，规范代码向这个目标靠近了一大截。
4.3 规范会让生成速度变慢吗？长期看反而更快
这是我被问得最多的问题：“加了这么多约束，AI生成代码会不会变得很慢？”实际体验是：单个模块的生成时间确实会比“裸生成”多十几秒到几十秒，因为AI需要先读规范、先生成结构说明。但把时间拉到一个需求周期来看，总时间是缩短的。
原因很简单：裸生成省下的那半分钟，后面要用几小时来补。以前生成完代码要人工改命名、拆函数、补异常处理、补测试，这些时间都是隐性的，但每一分钟都真实发生。规范生成器看起来做题慢，但它交出来的卷子不用怎么改就能提交。我把这套流程跑了三个迭代之后，团队整体的功能交付周期不升反降，核心原因就是返工变少了。这本质上是一种“磨刀不误砍柴工”的账，只是很多团队只看第一刀，没看后面的累计工效。
5. 常见问题与排查技巧实录
5.1 现象：AI生成的代码能跑，但你还是想重写
这种情况在刚开始用规范生成器时特别常见，AI写出了一段“符合语法但不符合灵魂”的代码。排查下来，八成是因为CONVENTIONS.md写得不够死。比如你只写了“函数要单一职责”，AI会认为一个处理订单的函数也算单一职责；但你改成“一个函数只允许处理一个业务动作，禁止同时进行状态校验、数据变更和外部调用”，它理解的误差就会小得多。规范文件里每一条原则，都需要配上具体的反例和正例，只讲抽象道理是约束不住AI的。
5.2 现象：提示词明明写了规范，AI还是放飞自我
这个问题我也踩过不少次。根因往往是上下文丢失，AI编程软件在长对话中会慢慢遗忘对话早期的指令，尤其是那些放在对话里而没有放在项目指令里的规范。我的处理方式是把重要规范同时写进三个地方：项目根目录的AGENTS.md、AI编程软件的系统指令设置、以及生成提示词里再次强调，三处冗余并不可耻，关键约束就是需要重复到位。
另外一个管用的小技巧是：在提示词里加“负向禁止”，比如明确写“禁止使用process/handle/tmp作为标识符”，正向要求不如负向禁止来得直接。AI编程软件对“不要做什么”的理解力，普遍好于“要做什么”。
5.3 现象：AI开始“过度设计”，简单的功能生成一堆抽象
规范约束得太死，AI又容易走向另一个极端：生硬地应用设计模式。你只是让它写一个读取配置文件的函数，它给你建了一个抽象工厂加策略模式再加依赖注入容器。这种“过度设计”在工程上同样是技术债，只是长得比较体面。
我的应对是在验收层的AI自审环节加一条特殊要求：检查是否存在“用不上的抽象”，任何当前没有第二调用方的接口，都先按普通函数实现，等出现第二个调用点时再考虑抽象。这个原则其实就是工程界常说的YAGNI，用在AI编程审计里效果极好，它能止住AI那种“多写一点显得专业”的冲动。
5.4 常见问题速查表
| 问题现象 | 最可能的原因 | 对应解法 |
|---|---|---|
| 代码能跑但不可读 | 规范公约未写入AI上下文 | 建立CONVENTIONS.md并挂载到项目指令 |
| 提示词指令被忽略 | 长对话上下文丢失 | 关键规范三处冗余：项目指令、系统设置、提示词 |
| 函数被迫拆成奇怪的小碎块 | 行数限制与职责约束冲突 | 规则改为“按职责拆”，不机械限制行数 |
| 公共逻辑被反复复制 | 模板层缺少工具库 | 先在模板层沉淀公共方法，再让AI调用 |
| 生成代码过度使用设计模式 | 缺少YAGNI约束 | AI自审环节强制检查无意义抽象 |
| 静态检查一堆历史遗留告警 | 旧代码与AI新代码混跑 | 先对存量代码做一次扫描，新代码必须零新增高优先级告警 |
这套速查表是我自己在三十多期迭代里反复踩坑攒出来的，每次碰到问题我都会先回来对照一遍，大多数情况都能快速定位到最省力的解法。
我个人在实际操作中的体会是：所谓“生成即规范”，说到底是把“规则”摆在“生成”前面，让AI编程软件在动手之前先看清边界。你投入在规范文件、提示词模板、校验流程上的每一分钟，都会在后面若干个需求里成倍地省回来。下一期的迭代，我打算把这套规则推进成自动化的评审插件，让机器直接拦截不合格代码，减少对人工评审的依赖。最后分享一个小技巧：每次让AI生成代码前，先问自己一句“如果这段代码三个月没人动，我还能不能一眼看懂并直接修改？”如果你自己都觉得悬，那AI大概率会写得让你更悬。规范，从来不是给别人看的装饰，是给未来的自己留的路。
