AI编码项目实战：从生成到治理的二十五万行代码经验

1. 项目概述：从零到二十五万行代码的实战记录

这个项目是我半年前启动的一个内部业务系统，从第一行代码到二十五万行，几乎全部由AI编码工具生成。我负责架构设计与代码评审，AI负责把架构翻译成具体实现。严格来说，这不是一个“全自动开发”的项目，而是一个“人类定义边界、AI填充细节”的协作项目。

在启动之前，我最大的顾虑并不是“AI写不出代码”，而是“AI写出来的代码能不能用、好不好维护”。事实证明，这个顾虑完全正确。AI生成代码的速度快到令人咋舌——一个中等复杂度的微服务，人工写需要三到五天，AI配合合适的提示词，三个小时就能跑通主流程。但当代码量堆积到十万行以上时，真正的问题浮出水面：模块之间职责不清、命名混乱、重复逻辑遍布各处、上下文割裂导致同一个功能在多处实现。二十五万行代码里，AI生成的占比超过95%，而治理这些代码所花费的时间，占到了整个项目周期的60%以上。

这个项目的核心价值在于回答一个问题：当AI承担了绝大部分编码工作后，人的价值在哪里？我的答案是——治理。这里说的治理不是简单的代码规范检查，而是从架构约束、上下文管理、质量守门、依赖管控、技术债清理等多个维度构建的一套完整体系。下面我把这套体系拆开来讲，包括具体方案、踩过的坑、以及一些只能靠实践才能总结出来的经验。

1.1 为什么说“生成”是最不重要的部分

很多刚开始接触AI编码的人，会把注意力集中在“怎么让AI写出更长的代码”“怎么绕过限制”“哪个工具生成更快”这类问题上。这些关注点其实都偏了。以这个项目为例，AI生成代码的单次成功率大概在40%左右，如果算上“生成后能够直接通过编译+单测”的比例，可能只有20%。但这不是问题——因为AI生成代码的成本极低，失败了大不了重新生成。真正的成本在生成之后：每一段代码都要经过审查、测试、集成、重构，这些活动的复杂度是随着代码量非线性增长的。

举个具体例子。项目早期，我们用AI生成了一批REST API接口的CRUD代码，每个接口大约一百到一百五十行。AI生成这一段代码耗时不到一分钟，但当我们把这些接口接入统一鉴权、动态数据权限、操作审计、异常码映射、日志链路追踪这些横切逻辑时，每个接口都要手工修改。二十五万行代码里，这种“生成快、整合难”的场景比比皆是。所以我的结论是：AI编码项目的真正难点，从来不是生成，而是生成之后的整合、约束与治理。

1.2 治理缺失时到底会发生什么

如果不在早期建立治理机制，代码量到了一定规模后会出现一系列连锁问题。我在这条路上踩过，下面列几个最典型的：

第一，命名空间污染。AI在生成代码时会根据函数名自动推断语义，但如果上下文约束不明确，它会在不同模块里给同一个业务概念起不同的名字。比如订单状态，有的地方叫OrderStatus，有的地方叫OrderState，有的地方干脆用魔法数字。等到跨模块联调时才意识到，已经有三十多个地方定义了“订单状态”的判断逻辑。

第二，重复代码率失控。人工开发时，开发者有“复用意识”，会主动抽取公共方法。AI没有这种意识，它倾向于在每次接到独立任务时新写一份完整实现。我们用SonarQube跑出来的重复代码率峰值达到22%，这个数字在行业里属于偏高水平。

第三，依赖地狱。AI生成代码时会“顺手”引入自己认为合适的依赖库，同一个功能可能被引入多个功能重叠的库。比如JSON解析，项目里同时存在Jackson、Gson和Fastjson三个库；工具类层面，Apache Commons和Guava并存。这不仅增加了镜像包体积，还埋下了序列化行为不一致的隐患。

第四，隐含的业务逻辑分散。人工写的代码，业务逻辑通常会沉淀在Service或Domain层。AI生成的代码则不然，它会把校验逻辑、状态流转、金额计算这些散落在Controller、DTO、工具类甚至前端调用参数里，一改就炸。

这些问题单独看都不致命，但合在一起，团队迭代速度会被明显拖慢。新功能开发一小时，排查已有逻辑三天——这种状态一旦持续，项目基本就变成了一堆只能修修补补的“积木塔”。

2. 先建立治理基线：任何AI生成代码都必须遵循的规则

AI编码工具不是不能用，而是不能“裸用”。在项目启动的第一周，我就和团队一起定下了一套规则，这套规则后来成了项目能够维持在可控复杂度的基石。所有AI生成的代码，必须满足这些规则才能进入代码库，否则一律退回重新生成。

2.1 仓库结构与模块边界必须由人类定义

在让AI写任何业务代码之前，我们先用一周时间确定了整个仓库的结构。这是整个项目中最关键的一步，因为AI没有全局视角，它只会基于当前对话上下文或当前任务生成代码。如果仓库本身没有清晰的结构，AI会以“点状”方式生成大量逻辑纠缠在一起的代码，之后再去拆就是一场灾难。

我们最终用的是多模块Maven架构，顶层划分为common、domain、application、infrastructure、interfaces五个模块。依赖方向是单向的：interfaces依赖application，application依赖domain，infrastructure实现domain中定义的仓储接口，common被所有模块共享。这套结构在AI生成时代尤其重要——因为只要模块边界清晰，AI生成代码时即便不遵循依赖规则，编译阶段就能拦截大部分越界访问。

举个例子，我们让AI生成一个“创建订单”的完整流程时，提示词里明确要求“Controller只负责参数接收与响应封装，业务逻辑放在application层，订单状态判断放在domain层”。AI生成的代码在大多数时候是符合这个要求的，但偶尔会在Controller里直接调用仓储层，这时候编译不通过，我们就会让AI修正方向。这种纠错成本远低于事后重构。

2.2 制定AI专项编码规范：给生成代码套上紧箍咒

光有模块划分还不够，代码规范必须细化到AI能理解的程度。传统团队的编码规范大多面向人类，比如“命名要有意义”这种话，AI理解不了，因为它觉得data1、data2也是有意义的命名。必须把规范拆成AI能执行的“可检查条款”。

我整理了三类规则，项目中一直在用：

第一类是命名规则。所有公开类名必须包含业务领域名词，DTO类必须以DTO结尾，领域对象必须与数据库表名一致，枚举类禁止用魔法数字代替。这条规则生效之后，专属于“订单状态”的重复定义从三十多处降到个位数。

第二类是禁止事项。AI生成代码时很喜欢写“万能类”，比如CommonUtils、StringHelper这种随意堆积方法的工具类。规则里明确禁止新增这种类，必须按领域拆分。另一个高频违规点是异常处理，AI默认喜欢吞异常或者catch Exception后返回null，规则里统一要求必须抛出可解释的业务异常。

第三类是尺寸控制。单个类的代码行数超过300行、单个方法的行数超过80行，AI生成的代码必须自行拆分。这个规则和可读性关系不大，主要是为了方便人审——行数越少，人工审查时间越短。

这些规则我们直接写进了提示词模板里，每次让AI生成或修改代码时都会附带完整规范。效果很明显，AI生成的代码合规率从最初的不足30%提高到了80%以上。

2.3 架构约束如何在AI时代自动生效

规范靠提示词约束，架构则必须靠工具强制。这个项目引入了两套自动约束机制，一套是ArchUnit，一套是编译期的依赖检查。

ArchUnit的配置很简单，我们在测试模块里加了几条规则，比如“interfaces包下的类不能直接访问infrastructure包中的类”“所有Controller类必须放在interfaces.controller包下”“所有类名以Controller结尾的类不允许抛出Exception，只允许抛出业务异常”。这些规则会随着CI流水线在每次提交时自动执行，一旦违规，构建直接失败。

这套机制的价值在后期尤其明显。当团队扩充到六个人时，手动约束已经不可能，全部交给自动化。AI生成的代码即使“不合规”，也会在流水线阶段被打回，不会污染主干分支。

另一个容易被忽视的问题是依赖收敛。AI会根据自己的知识库引入新依赖，如果不加限制，项目最终会变成一个大杂烩。我们的策略是提前锁定核心依赖版本，三方库清单由人类维护，AI无权新增依赖。如果AI在生成代码时引用了未登记的库，审查时会直接被拦截。

3. 上下文管理：AI编码成败的第一决定因素

二十五万行代码的项目中，AI生成代码的上下文管理是运营效率的分水岭。同样的任务、同样的模型，上下文设计得好与不好，生成质量可以差距数倍。我有几个实际经验想分享。

3.1 让AI拥有“足够小且明确”的任务边界

AI工具普遍存在的问题是，上下文窗口有限，而且注意力会衰减。让它在一个对话里生成一个完整的微服务，末期的代码质量明显劣于初期。后来的做法是把大任务拆解成小任务，每一个小任务只生成一份职责明确的文件或函数。

比如“订单服务”这个需求，我们拆成了：实体类、映射器接口、数据传输对象、领域服务接口、领域服务实现、应用层组装、控制器。AI不需要知道整个订单服务的全貌，只需要在一个对话里完成当前文件的生成即可。上下文越少，生成结果越稳定。

这其实和人工作一样：让一个人同时写“数据库表结构+业务逻辑+单元测试”，和让他只写其中一块，后者的质量大概率更高。AI也是一样，任务边界不明确，产出质量就全靠运气。

3.2 提示词模板的标准化

这个项目维护了一套提示词模板库，按任务类型划分：实体生成、Mapper生成、Service生成、Controller生成、单元测试生成、脚本生成等。模板里有五个固定部分：

1. 角色定义：告诉AI它是资深后端工程师；
2. 项目背景：用两三句话说明这次生成属于哪个业务领域，领域内有哪些核心概念；
3. 约束条件：明确不许用什么技术、必须遵循什么规范、禁止引入哪些依赖；
4. 输入输出要求：给出接口签名或数据库字段列表，要求输出完整Java类文件；
5. 验收标准：编译通过、方法级注释完整、只生成指定文件等。

这套模板的主要价值不是提高单次生成质量，而是让生成产物的风格稳定。AI是概率模型，没有模板时每次生成风格都有差异，有模板后几乎是同一套风格，审查成本会低很多。

3.3 上下文漂移与解决方案

AI生成代码最大的坑之一是上下文漂移。同一段代码，第一次生成时表现得“懂业务”，第二次只是改了一个方法名，结果整个文件的风格都变了，甚至把之前实现的逻辑删掉重新写了一个版本。这是因为AI在生成时会整合当前会话的全部历史信息，会话越长，早期的上下文权重越低。

解决这个问题的方法有三层。第一层是单次会话任务量控制在三个文件以内，尽量让每次生成都是“新鲜的”；第二层是给AI提供“锚点文件”，比如生成的代码需要实现某个接口时，把接口源码直接粘在提示词里，AI生成时就会向这个锚点对齐；第三层是维护一个“常量事实库”，把项目里通用的枚举定义、状态机、硬编码值汇总在一个仓库文件中，提示词里直接引用，避免AI自行“发明”状态值。

说到AI编码如何指定上下文，我印象比较深的一件小事是：项目早期没有把上下文管理当回事，直接让AI“实现JWT登录”，结果它生成了一份基于旧版Spring Security的实现，接口全是过期的。后来我们把规范里的“依赖版本必须使用pom.xml中的定义”加进模板，这个情况才被彻底堵住。所以说，上下文管理不是给AI更多信息，而是给它更精确的约束。

4. 开发循环与质量控制：生成之后才是真正的战场

代码生成只是第一步，真正的核心循环是：生成、审查、测试、重构、合并。这个循环跑得好不好，决定了二十五万行代码是资产还是负债。

4.1 人工审查时的优先级取舍

二十五万行代码不可能每一行都人工审查，必须把人力用在刀刃上。我的经验是划分三类优先级：

高优先级：涉及资金、数据、权限、状态的代码。这部分必须逐行看。AI生成代码在这类逻辑里犯过错——有一次生成金额累加逻辑时少了对税率的判断，从接口角度看不容易发现，但会造成结算错误。

中优先级：业务主流程。不用逐行看，但必须跑通关键路径的单元测试和集成测试。

低优先级：模板化代码，比如CRUD操作、DTO字段映射、简单的查询条件拼接。这一类代码我们基本不看实现，只看接口测试是否通过。

这种分级审查策略把单个功能的审查时间从两小时压缩到二十分钟，同时安全底线没有破。

4.2 单元测试由AI生成，但覆盖率由人类把关

这个项目的单元测试绝大部分也是AI生成的。一开始AI生成的测试存在一个通病：专门挑好测的方法测，绕过复杂分支，测试写了三千个，核心逻辑覆盖率只有30%。

后来我们换了一种方式：先让AI生成测试，然后人工补充漏掉的分支条件。具体做法是，把实现代码和“请根据以下分支覆盖要求生成测试”一起发给AI，要求它针对if/else、switch、边界值、异常路径逐一设计用例。实测下来，单元测试行覆盖率从30%提升到了85%左右，分支覆盖率提升到了70%。

有一点需要注意：AI生成的测试常常不校验结果，只验证“调用没出错”。这种测试形同虚设。审查测试时要特意关注是否有断言，且断言是否覆盖了业务预期。

4.3 每次合并前的自动守门策略

二十五万行项目的CI流水线里挂了七个检查步骤，任何一个失败都不会合并进主干：

1. 编译检查；
2. 单元测试与覆盖率阈值检查；
3. 静态代码扫描（SonarQube），包含重复代码率、复杂度、潜在bug、安全漏洞；
4. ArchUnit结构约束检查；
5. 依赖检查，确保没有引入未登记的三方库；
6. API兼容性检查，重点看对外接口是否被修改或删除；
7. 代码格式检查，统一用Spotless自动格式化。

这轮守门能拦住的问题中，我印象最深的是重复代码率。项目早期重复率在10%左右徘徊，我们没太在意。后来一个功能需求涉及三个页面做了相似的过滤逻辑，AI认为每个页面都应该有一份完整实现，重复代码率直接飙到22%。加了SonarQube的硬性门槛后，AI生成的代码一旦被检测出重复就会被拒，开发者就需要手动抽取公共方法。治理机制发生作用的不是规则本身，而是让AI的“坏习惯”在进入代码库之前就被阻断。

4.4 AI生成“对抗生成网络”的工程化思路

这个标题可能有点跨界，但我确实从对抗生成网络（GAN）的思路里借了一个概念到代码治理中：判别器与生成器的对抗。AI编码时的生成器是编码模型，判别器是CI流水线里的检查工具。生成器不断生成代码，判别器不断拒绝不合格的产物，两者对抗的结果是——生成器产出的代码质量被动提升。

我们做了三个“判别器”来约束AI生成代码：单元测试判别、结构约束判别、风格一致性判别。一个新的代码提交如果无法通过测试，就会被拒绝；如果违反架构规范，会被拒绝；如果和项目现有的代码风格差异很大，也会被拒绝。持续迭代之后，AI生成的代码质量会明显向上走，因为模型会根据拒绝信息调整。

很多团队只把AI编码当成“写更快”的工具，忽略了“AI也是可以被训练/被对抗的”这个属性。从工程角度来说，AI编码项目和传统项目的差别不在于工具，而在于反馈环路的设计。反馈环路越短越清晰，AI产物的质量就越稳定。

5. 技术债与架构治理：如何防止二十五万行变成大泥球

代码量增长到一个数量级后，架构治理的优先级必须高于新功能开发。功能可以晚一周上线，架构烂了之后的返工成本是几倍甚至十几倍。

5.1 接口契约先行，代码生成在契约之后

项目里所有微服务之间的接口，都是先定义OpenAPI规范，再交给AI生成实现。这个顺序绝对不能被反过来。一旦AI先写了实现代码，再去补接口文档，生成的文档大概率会遗漏很多参数校验、响应码和异常场景的说明，后续联调时间会翻倍。

我们用OpenAPI作为“锚点文件”，在提示词中直接粘贴接口定义片段，AI生成的Controller会自动对齐路径、参数、响应结构。实测下来联调阶段的接口不匹配问题减少了大约七成。

5.2 依赖治理：AI时代的依赖爆炸危机

AI编码工具一个让人头疼的地方是，它会倾向于用“已知的库”解决问题，而这个“已知”并不一定和项目的现有技术栈匹配。项目里出现过三次依赖爆炸级事故：一次是同一个序列化功能引入了三个JSON库，一次是同一个日志场景集成了两套日志框架，还有一次是缓存客户端并行存在Jedis和Lettuce两套连接池。

依赖治理的措施是每月末做一次依赖清单审视，把项目内的全部依赖输出成表格，人工标记“必须保留”“可替换”“可移除”。同时pom.xml里配置了dependencyManagement，把依赖版本集中管理，避免AI生成代码时带入不同版本的同名库。

5.3 架构腐化预警信号与实际干预

我把架构腐化的预警信号分成早、中、晚三期。早期信号是编译依赖混乱——domain模块里的类引用了infrastructure里的类，虽然能编译，但架构不干净。中期信号是接口膨胀——一个Service接口堆了几十个方法，职责一多必然导致实现类无法维护。晚期信号是数据流混乱——同一个事务在多处被改写，调用链复杂到无法画清。

我的处理方式是：早期阶段靠ArchUnit自动拦截，发现一次就整理一次；中期阶段每两周做一次接口拆分，把大接口拆成小接口，这是一个纯粹机械性的工作，AI可以辅助；晚期阶段必须人工介入，把数据流走向重新梳理成文档，然后在文档基础上重写核心链路代码。

在项目进行到十八万行左右时，我们曾经因为架构腐化严重，停下了所有新功能开发，集中两周时间做技术债清理。那次清理删掉了七千多行重复或废弃代码，接口拆分了十一个，依赖移除了一百多个。效果立竿见影——单元测试跑一圈的时间从四十分钟降到了十八分钟。

5.4 缓存治理与性能治理的AI化

项目里用到了Redis缓存，AI在生成缓存相关代码时最爱犯的错是“缓存穿透”：查询不存在的数据时，它不会缓存空值，导致恶意请求无限穿透到数据库。另一个常见问题是缓存更新策略不统一，同一个数据源有的地方删除缓存、有的地方更新缓存、有的地方直接不处理。

我们的治理策略是在domain层定义统一的缓存访问接口，所有缓存读写都必须走这个接口。AI生成业务代码时，不允许绕过接口直接操作RedisTemplate。这个约束靠ArchUnit强制执行，非常有效。

性能治理方面，AI生成的循环代码经常忽略批量操作。比如循环一千次每次都查库，这种代码在数据量小的时候没问题，一旦数据量上去就会出现慢SQL和连接池占满。我们要求AI生成涉及集合操作的代码时，必须添加日志来记录影响的数据量，作为性能监控的基础数据。

6. 常见问题与排查技巧实录

这个部分的内容全部来自项目实际运行中的踩坑记录。以下是我认为最有参考价值的一些问题和对应的排查思路。

6.1 生成的代码可以编译，但运行时总是出某种“灵异问题”

AI生成代码最常见的坑是null值处理。编译期完全正常，运行时只要有一个字段没有从数据库映射出来，就会出现空指针，而且报错位置往往离真正的原因很远。

排查思路分三步走：先看数据源头，确认数据库查询结果中该字段是否有值；再看DTO/Entity的字段映射，检查是否有类型不一致（比如数据库是tinyint，Java里却是String）；最后看调用链，AI生成的代码经常会在某个工具方法里把值“吞掉”。

这类问题靠经验很容易定位，但如果是新手上手，效率会很低。建议在项目初期就在AI提示词里明确“所有对象字段访问前必须判空”，能减少至少一半的空指针问题。

6.2 并行开发时AI生成的代码互相冲突

多个开发者同时用AI工具生成代码，代码风格差异和命名冲突会格外明显。AI会根据不同的对话历史生成不同的实现风格，比如一个用Builder模式，一个用构造器，一个用静态工厂。即使功能等价，合并时也会产生大量冲突。

解决方式有两个层面。第一层是统一的代码格式化工具（Spotless），从机械格式上抹平差异；第二层是相同的业务功能只允许在同一个包下开发，代码合并后立即跑架构测试，发现重复时优先抽取公共模块。

6.3 生成代码的命名混乱怎么治理

AI命名混乱几乎是所有AI编码项目的通病。项目里出现过最典型的三类：同义词混用customer/client/buyer表示同一个“客户”，缩写混用info/data/msg表示同一类数据结构，复数单数混用orders/orderList/orderRecord。

治理第一步是做“项目词表”，把核心业务名词的唯一写法固定下来。词表放在仓库根目录，AI工具的提示词引用词表，生成的代码命名就有约束。第二步是代码扫描插件加规则，比如禁止data作为类名、禁止info作为变量名，这些规则能过滤一大部分模糊命名。

6.4 如何避免AI生成代码形成“死代码”黑洞

“死代码”是指看起来有调用、实际上永远不会被执行到的代码。AI生成代码时经常因为上下文不完整，会生成一些对当前需求毫无意义的类或方法。如果审查不仔细，这些代码就会堆积成黑洞，占用维护精力。

排查方式很简单：定期跑一次调用链分析工具（比如jdeps或IDEA里的Find Usages），找那些“只有定义没有调用”的类和方法，逐个确认后删除。这个操作可以安排给AI做，但删除动作必须经人工确认，防止AI误删运行时反射调用的方法。

6.5 常见问题速查表

7. 效率工具链的取舍与实践建议

关于AI编码工具，网络上能看到的推荐多到数不清，但真正落到项目里，工具选型必须围绕“生成-治理”闭环来考虑。我这里只围绕闭环保留了四个环节的工具。

生成环节：优先选支持自定义提示词模板的工具，像Cursor、GitHub Copilot都能模板化。有一个技巧是，把项目的编码规范文件放到仓库中，并配置工具使其总是被加载进上下文，这样AI每次生成时都会自动参考这些规范。

测试环节：用AI生成单测模板，再用Maven插件统一执行覆盖率检查。覆盖率不达标则构建失败。这里的核心是“AI生成+人工补边界条件”，而不是让AI全权负责全部测试生成。

架构检查环节：ArchUnit + SonarQube是基础搭配，前者管结构边界，后者管代码质量。这两个工具必须集成进CI，而不是等开发者本地跑，否则一定有人跳过检查。

效率度量环节：建议用JIRA或者ClickUp看板记录AI生成代码的缺陷率变化，每周统计一次。我自己统计的结果是，规范建立后AI代码缺陷率从9.8%降至3.5%左右，说明治理机制确实在起作用。

关于热词里提到的“字节跳动扣子空间”“AI生成没有违禁限制”这类话题，我统一不做具体推荐，因为这类工具和场景波动太快，今天能用明天可能就变了。我更建议把重点放在“如何为AI设置边界”和“如何建立反馈机制”上，工具会迭代，方法论是稳定的。

8. 回顾与实用心得

二十五万行代码的项目做完，我最大的体会是：AI编码并不会减少开发者的工作，它改变的是工作的重心。以前我们花时间写代码，现在花时间写更精确的任务描述、审代码、定规范、治理技术债。如果你把AI当成“加速器”，你会发现它确实快，但快到最后整个项目会变得不可控。把它当成“新员工”，给它培训、给它规则、给它反馈，它会成为一名合格甚至优秀的开发者。

对正在从零开始做AI编码项目的人，我有三条最实在的建议。

第一，项目启动的第一天就建好治理机制。不需要一开始就搞很重的体系，但至少要包括：模块边界划分、提示词模板库、命名词表、代码格式工具、基础的CI把关。这些工作建议排在最前面，不要等到代码堆了几万行再回头补。

第二，让AI生成的代码始终有“锚点”。锚点可以是接口定义、数据库表结构、状态机、已有的工具类。没有锚点的生成就像没有图纸的施工，每面墙都砌得不一样。

第三，留出至少20%的编码时间做清理。AI生成代码的速度越快，垃圾产生的速度也越快。两周一次的技术债清理、一个月一次的依赖审视，这些活动必须写进迭代计划里。不做清理，代码就是纯负债，做清理，它才是可长期演进的项目。

我个人现在如果再启动一个类似项目，流程会和这次不同：第一阶段先用AI生成完整的可运行骨架；第二阶段人工审结构，定规范和阈值；第三阶段让AI在规范内灵活填充；第四阶段持续做架构监测和反馈。AI编码的未来一定不是人和机器赛跑，而是人和机器一起把项目做大、做稳、做干净。