16 万行代码4 个月3 个人。这三个数字放在一起很多人第一时间会问是不是在吹牛。说句实在话如果一年前有人这么跟我讲我也不信。但这次项目确实做完了而且不是靠“散装 AI Coding”碰运气堆出来的——中途一度被乱七八糟的生成代码拖到差点延期后来硬是把流程掰成了体系化的 AI Engineering才把 16 万行代码从“能跑”变成了“敢上线”。这篇文章就还原一下我们到底是怎么跑出来的哪些坑值得你绕开以及那些真正让 AI 写代码变得可控的约束条件。我默认看这篇文章的读者分两种一种是用过 ChatGPT、Copilot 或 Cursor 写代码但还没经历过大规模项目的另一种是团队里已经在推广 AI Coding但对代码质量心有余悸的技术管理者。这篇复盘对两类人都有参考价值因为核心不是“怎么让 AI 写出更多代码”而是“怎么让 AI 写出来的代码能进主干”。1. 项目是怎么定到 16 万行的规模盘点与工期测算1.1 这个项目要解决什么我们这次接的是一个供应链公司的统一数据清洗与报表平台。客户之前靠 Excel 加一堆零散脚本活着每个月月底对账让三个人整整耗两周而且数据口径经常对不上。我们要做的不是简单写几个报表接口而是一个完整平台数据接入、清洗规则引擎、调度编排、权限审计、前端可视化一条链路全打通。一开始做需求拆解的时候每个人心里都没底。光数据源就有 20 套异构系统清洗规则加起来超过 120 个模板调度层要支持 DAG 编排前端报表页面有 30 多个还带着权限控制和操作审计。这种体量放在传统开发模式下明摆着是一个 20 人月的项目但客户给的工期只有 4 个月我们团队只有 3 个人两个后端一个前端。当时就两条路要么砍需求跟客户重新谈范围要么把生产方式整个换掉。我们选了后者正式把 AI Coding 引入开发流程。1.2 16 万行是怎么估算出来的很多人听到“16 万行”觉得是个虚数其实这是我们按模块拆出来加总的结果。拆解的时候顺手做了个代码量预估表现在回看这个表基本就是整个项目的骨架模块预估行数纯手写人日AI 辅助人日数据接入层20 套数据源适配器4.0 万行50 人日18 人日清洗规则引擎规则模板 编排3.5 万行45 人日16 人日前端报表与控制台30 页面5.0 万行60 人日22 人日测试套件单元 集成2.5 万行30 人日12 人日基础设施与部署脚本、迁移脚本1.0 万行15 人日6 人日合计16.0 万行200 人日74 人日传统估算里一个开发人员一天写 60 到 80 行有效代码是常态而且这还不算返工和联调时间。200 人日意味着 3 个人不吃不喝要干 66 天以上加上需求沟通、测试修改、上线问题4 个月根本不可能。AI 辅助人日那列一开始是我们拍脑袋写的计划是比手写快 2 到 3 倍。实际跑下来前期只快了 1.5 倍后期体系化之后最快到 5 倍。这个数据变化后面会详细说。2. 散装 AI Coding 撑不过 1 万行三个必须转型的信号2.1 第一个信号代码风格割裂到没法看项目启动第一周我们用的是最常规的 AI Coding 方式——“遇到什么问什么生成的代码直接粘进项目”。单看每一段AI 写得还算像样但合在一起就出问题了。同一个用户实体的字段命名三个文件里出现了三种风格user_name、userName、username。订单金额的计算逻辑在订单服务里写了一遍在报表模块里又写了一遍而且两遍的舍入规则还不一致。为什么会这样因为 AI 的每个会话都是独立的它没有记忆每次生成都等于“重新发明轮子”。你要是不把约束前提写清楚它每次都会随机决定一种实现方式。我后来管这叫“散装 AI 代码综合症”。代码量小的时候感觉不明显超过 3000 行就开始露馅你查一个字段名可能要全局搜三遍。这种割裂不只是看着不舒服它是隐形的技术债会在重构和排查问题时集中爆发。2.2 第二个信号接口漂移直接把开发卡死真正让我意识到必须转型的是第二个信号。项目到了第三周代码量到了一万多行开始出现跨模块接口调整。数据层把某个函数从updateOrderStatus(orderId, status)改成了updateOrderStatus(orderId, status, operator)以支持审计字段然后服务层调用方就全乱了。AI 生成代码的时候根本没有全局视野。它看不到仓库里其他文件怎么调用这个函数也不知道接口变更会影响哪些下游。我试过直接把整个目录丢给 AI 让它自己改结果它改了第一处调用漏了第二处第三处编译一跑满屏报错。那段时间的日常就是AI 生成 1000 行人修接口引用花 800 行的精力。使用 AI 省下来的时间又被跨文件协作的返工给吃回去了。折腾了两三次之后我明白了一件事AI Coding 的问题从来不在生成这一环而在生成之后如何跟既有仓库保持一致。2.3 第三个信号质量不可追溯第三个信号出在 review 环节。散装模式下AI 生成的代码经常没有理由——不是“没有原因”而是“它不解释原因”。你问它为什么这里用线程池而不用协程它给你一段含糊的“这样可以提高性能”但具体评估逻辑完全缺失。更要命的是代码出 bug 的时候没法定位意图。传统代码有 commit message、有需求单号、有 reviewer 的讨论记录能还原一段逻辑的前因后果。AI 生成的代码就是凭空出现的没有上下文没有讨论历史出问题你只能翻代码猜猜不出来就删掉让 AI 重新生成。这种“黑盒产出”在小项目里可以忍在需要长期维护的业务系统里就是定时炸弹。后来我们定了一条规矩AI 生成的代码必须附带“为什么这么写”的说明不然不允许合入。这就是从 AI Coding 往 AI Engineering 走的起点。2.4 引爆点一次跨模块重构所有问题集中爆发是在第一次跨模块重构。我们要把支付状态机的状态字段从字符串改成枚举本质是个很小的调整但涉及 10 个文件。当时 AI 改了 7 个漏了 3 个而且漏掉的那 3 个文件在编译期不报错运行期才炸——因为字符串可以随意比较枚举一旦对不上就直接悄悄走默认分支。这个 bug 在测试环境里卡了我们整整两天。最后人工逐个文件排查才发现问题前端页面报“支付状态异常”后端日志里看不到任何报错。那一刻我们都清楚靠“提示词 复制粘贴”的散装模式已经走到头了。代码量超过 1 万行、涉及跨文件协作的时候必须给 AI 建流程、建规范、建上下文、建质检机制也就是完整地把 AI Coding 升级成 AI Engineering。3. 体系化改造规范、上下文与多智能体协作3.1 先立规矩让 AI 在约束里发挥转型的第一件事不是找更好的模型而是立规矩。我们在仓库根部放了一个AGENTS.md文件把所有 AI 生成代码必须遵守的约束写进去。这件事听起来简单实际操作挺讲究内容不是“你要写好代码”这种废话而是精确到“什么能做什么不能做”的硬性约定。我们当时的AGENTS.md核心内容大概是这样的结构# 技术栈与目录 - 后端Python 3.11 FastAPI目录结构参考 src/ 下的 modules 划分 - 前端React 18 TypeScript页面组件放在 src/pages 对应路由目录 # 编码约束 - 禁止在路由层直接写 SQL必须通过 repository 层访问数据库 - 禁止在前端组件里嵌套业务逻辑业务状态统一走 hooks 或 store - 字段命名统一使用 snake_case数据库层 / camelCaseAPI 层 # 过程要求 - 新增模块必须配套单元测试覆盖率不低于 80% - 修改接口定义必须同步更新 docs/contracts 下的接口文档 - 生成代码必须通过 RuffPython和 ESLint前端检查后才能提交 # 不建议做的事 - 不建议对已有函数进行“重构式重写”优先复用现有实现 - 不建议在代码注释里使用含糊描述必须写明业务上下文和设计原因这个文件的魔力在于它不是给 AI 当参考的而是给 AI 当“宪法”的。此后每次让 AI 生成代码我们都会先喂一份AGENTS.md让它按约束生成。结果非常明显代码风格从“五花八门”收敛到了“基本统一”命名割裂问题大幅缓解。而且因为约束写清楚了AI 不再自由发挥它自己生成代码的时候也更敢放手做因为边界已经划好。3.2 上下文池别让 AI 靠瞎猜规范之后第二个问题是上下文。散装模式下 AI 经常“一本正经地胡说八道”让它写一个订单聚合接口它能给你画出根本不存在的字段让它对接某个数据源它给你写一套没有对应的适配器接口。问题根子在于AI 对项目的领域知识一无所知它只能靠训练语料里的通用规律瞎猜。要解决这个问题就必须把项目的“上下文”主动喂给它而且这个上下文要准确、精炼、易获取。我们做法是在仓库里加了一个docs/contracts目录专门放三类文档接口契约每个 API 的路径、入参、出参、错误码定义数据字典核心实体的字段定义、类型、业务含义业务规则订单状态流转、权限判定逻辑、金额计算规则生成代码前我们会把相关的契约文档直接塞进上下文。比如要让 AI 写一个“创建订单”的接口就喂给它docs/contracts/order_api.md和docs/contracts/order_domain.md让它照着这些定义写不准自由发挥字段名和规则。这个改动带来的效率提升非常直观。我们把 AI 生成的“一次通过率”定义为“PR 提交后不需要人工修改逻辑、只改微小格式就能合入”的比例这条指标从 30% 直接拉到了 80% 左右。核心原因就一个AI 不再靠猜了它有据可依。3.3 多智能体分工把 AI 当团队用不把 AI 当打字机规范和上下文就位之后我们开始玩更进阶的东西多智能体协作。很多人一听“多智能体”就觉得是噱头但实际用下来它解决的是“单 Agent 上下文爆掉”的问题。我们的做法不是让一个 AI 干完所有活而是把 AI 拆成四个角色接口设计器负责根据需求文档产出 API 定义和数据结构输出物是一份契约文档实现器负责根据契约文档写具体实现代码输出物是符合规范的可运行代码测试器负责为实现代码补测试用例输出物是一组可执行的测试重构器负责在代码合入前对质量不过关的部分做定向优化每个角色都有明确的输入和输出互相之间不直接对话而是通过文件传递。比如“接口设计器”产出的契约文档会放到docs/contracts/下“实现器”读取这个文档生成代码“测试器”读取实现代码生成测试“重构器”跑完静态检查再把结果写回一个报告文件。为了让这些 AI 角色不“打架”我们还约定了一个超简单的任务状态机todo - in_progress - review - done规则是同一时刻只有一个角色能操作同一文件。实现器正在写的文件测试器不会同时往里面塞测试代码重构器要动的文件必须等前一个角色把状态标记成done。这个机制低技术含量但极其有效直接把“AI 之间互相覆盖代码”的问题给消灭了。多智能体的另一个价值是上下文专注。单个 AI 一次处理整个 16 万行项目必然力不从心但让它只盯着“接口设计”或者“测试补齐”它的上下文窗口就非常充裕生成质量自然更高。这也是我们为什么强调“分工而不是堆人”。3.4 上岗笔试让 AI 先提交一份可合入的 PR体系化改造进行到一半的时候我们引入了一个很有意思的机制AI 上岗笔试。起因是发现不同模型的编码能力差距很大同一个需求有的模型能规规矩矩地写完并通过测试有的模型会给出一堆花活代码但根本不遵守项目约束。总不能每次都人肉试错于是我们设计了一套笔试流程。笔试题目的设计很简单拿一个已经存在的内部项目切一个分支给 AI 一份需求文档要求它在一个小时内提交一个完整的 PR。评分维度就四个维度评估方式权重规范性是否遵守 AGENTS.md 中的命名和架构约束30%测试覆盖新增代码是否配套测试覆盖率是否达 80%30%可读性变量命名、函数拆分、注释是否清晰20%正确性编译、测试通过且不破坏既有逻辑20%四个维度下来有的模型综合通过率只有 30%有的能到 85%。我们直接采用通过率最高的模型作为主力其他模型留给简单任务。笔试这件事最大的价值不是“选模型”而是反向暴露了我们的提示词和规范文件写得够不够清楚。如果模型笔试时普遍不遵守某个约束说明我们的规范表述有歧义修文档比换模型更有效。顺带一提这也回答了一个常见问题——“ai coding 笔试”到底考什么。我的经验是不考模型记忆力考它能不能在给定约束下交付合格工程产物。4. 质量防线AI 生成代码凭什么敢合入主干4.1 用数据说话技术债登记表很多人担心 AI Coding 会拉低代码质量这个担心不算多余。我们在项目里把质量从“拍脑袋感觉”变成“看数据说话”最核心的工具是一张技术债登记表。每周五下午我们会统计一次代码仓库里的技术债标记包含TODO、FIXME、HACK以及“绕过规范”的注释。统计方式是简单的 grep 加人工确认分类把 AI 生成的代码里遗留的债务单独列出来。这张表每周都会更新发布到团队群里周次AI 代码预计行数TODO/FIXME 数量技术债密度每千行第 3 周散装模式1.2 万行87 个7.3第 6 周体系化初期4.5 万行110 个2.4第 12 周多智能体 质检12 万行152 个1.3技术债密度从 7.3 降到 1.3靠的不是让 AI“别写 TODO”而是靠 review 阶段强制要求AI 生成代码里的 TODO 必须给出兜底方案。如果是临时的 mock 数据要注明替代实现是谁、大概什么时候替换如果是性能问题的妥协要注明触发条件和后续跟踪 issue。AI 可以把单子挂出来但必须把上下文写清楚这样别人接手不会一脸懵。4.2 测试覆盖率卡点没有测试保护的代码等于没有保障测试是 AI 代码最大的软肋。阶段化之后我们定了一个硬性卡点所有新增模块的测试覆盖率必须高于 80%低于这个阈值的 PR 不给予合入。这条规则本身不稀奇稀奇的是执行细节。我们让“测试器”角色为 AI 实现代码补齐测试但很快发现一个问题AI 自动生成的测试特别喜欢覆盖 happy path——输入正常数据、输出正常结果看起来覆盖率挺高但边界条件全没测。举个例子一个金额格式化函数AI 生成的测试只测了“正常金额转字符串”没测“负数”“零”“超大数”“科学计数法传入”这些边界。覆盖率统计数字可能很好看实际防护效果很有限。我们的对策是在每个模块的测试配套里人工承担“边界用例设计”的角色把 AI 生成的测试跑一遍专门挑那些“我要是写这段业务逻辑会出什么 bug”的场景补进去。这个步骤没法完全自动化但可以把 AI 从“能写测试”提升到“能写有效测试”。后来又加了一条规定AI 生成测试用例时必须显式列出“已覆盖的边界条件”和“未覆盖但应该覆盖的边界条件”没列说明直接打回。4.3 Diff Review 方法不看“写了什么”看“为什么需要”AI 生成代码量大逐行 review 不现实我们调整了 review 的视角。以前人肉 review 的习惯是看每一行写得对不对现在改成按 diff 块做“为什么审查”。每个 diff 必须回答三个问题这段代码要解决什么问题为什么要在这里写而不是在更下层或更上层写为什么不用已有函数或已有模块第一遍让“重构器”角色自动跑第二遍人肉抽查。抽查比例是 30% 的 diff 块集中在核心路径支付、权限、数据写操作。剩下 70% 依赖静态检查和测试兜底。这套方法效果很不错它不要求 review 者逐行读懂每一行 AI 代码而是强迫 AI 先自证“这段代码存在的合理性”。不合理的地方一抓一个准比如曾经发现一段 AI 在服务层直接用矩阵拼接的方式拼 SQL虽然能跑但完全绕开了 repository 层。按老办法逐行看很难发现这种结构性问题但按“为什么”审查一眼就能看出逻辑放错了层。4.4 人机结对复查关键路径必须人工过一遍最后一道防线最传统也最有效人机结对复查。AI 可以生成 16 万行代码但核心模块、支付流转、权限节点这些关键路径我们还是坚持由人逐行审核并亲自动手调整。我们的做法是划定“禁区文件”名单。名单内的文件AI 可以提方案但不能直接改码。比如支付核心、订单状态机、权限判定逻辑这些文件里 AI 生成的代码全部由人工重写或逐行确认后才能合入。这不是不信任 AI而是这些模块一旦出错影响的是真实业务的资金和数据安全人类需要完全掌握这部分代码的语义和意图。这种“AI 跑量人守核心”的方式让我们在保证速度的同时不至于把项目存亡押在 AI 的“平均表现”上。到了后期禁区文件的命名和范围逐渐缩小但心理安全感是前期就建立起来的。5. 踩坑复盘与提速数据几个值得直接抄走的结论5.1 提速的真实曲线整个项目下来AI 辅助开发的速度变化不是一条直线而是三个阶段阶段模式每人力日均有效代码行数备注第 1 阶段散装 AI Coding约 30 行含大量返工和接口修复第 2 阶段规范 上下文池约 120 行一次通过率提升返工减少第 3 阶段多智能体 质检体系约 250 行分工协作各角色各司其职这个“行数”不是简单统计新增行数而是统计“合入主干且通过测试的有效代码”。所以它才是真实产能。如果只看新增行数散装模式其实也不少但那些代码有一半在返工。体系化改造本质上是把返工率降下来同时把有效产出提上去。5.2 最坑的三个场景及处理办法第一坑是“重构老代码”。AI 不懂老代码背后的历史原因它只知道“按当前需求生成”所以一旦让它动历史代码经常会“好心办坏事”。我们的处理办法是凡是重构历史模块先把现有行为用测试固定下来再让 AI 动刀。测试就是安全网没有安全网的 AI 重构一律不批。第二坑是“跨模块重命名”。AI 会漏改引用而且漏得无声无息编译期还发现不了。处理办法是跨模块重命名一律不依赖 AI 手动改而是用语言自带的工具比如 TypeScript 的find-references、Python 的 IDE 重构先做机械替换再用 AI 处理逻辑调整。AI 负责“改逻辑”工具负责“改引用”职责分开。第三坑是“并发与时序逻辑”。AI 生成的并发代码问题最多尤其是状态同步、事务边界、超时重试这些场景。不是 AI 不懂是它缺少运行时的细粒度反馈。我们的处理办法简单粗暴并发相关代码一律交给核心开发者亲自动手AI 只负责出初稿最后必须有人逐行推演一遍并发场景。5.3 给想复制这条路的人三条建议如果你正在把 AI Coding 引入团队或者已经在路上但觉得失控我建议先做这三件事第一先做好单 Agent 的护栏再考虑多 Agent。很多人一上来就想跑多智能体但基础规范、上下文文档都没建多 Agent 只会放大混乱。单 Agent 跑顺、一次通过率稳定到 70% 以上再拆角色分工。第二把“可合入”的定义写得非常具体。不要只说“要保证质量”要写清楚lint 通过、类型检查通过、测试覆盖率达到多少、必须通过哪些静态检查、review 必须回答哪几个问题。AI 是一个执行者你定义不清楚它就会默认“代码能跑就行”。第三保留一个“不用 AI 的模块”。我们特意留了一个核心模块规定从设计到实现全人工。它的意义不是拖慢进度而是当一个“质量基准线”。 AI 生成代码的质量到底行不行拿它跟这个基准模块一比心中就有数。没有基准你就只能靠感觉而感觉在工程问题里是最不可靠的东西。5.4 最后的体会做这个项目前我以为 AI Coding 的最大挑战是“怎么让 AI 生成更多代码”。做完了才发现真正的挑战是“怎么让 AI 生成的代码敢合入主干”。AI Coding 解决的是“从无到有”AI Engineering 解决的是“从有到敢用”。16 万行这个数字没什么值得吹的真正值钱的是后面那套约束、规范、上下文体和质检机制。没有它们这 16 万行只会变成一个巨大的噩梦有了它们它才真正是一个可以被维护、被迭代、被交付的项目。我个人的习惯是每次让 AI 动手之前先花五分钟检查三件事规范文档是不是最新、相关契约文档喂进去没有、这次的验收标准写清楚了没有。这五分钟花得很值它决定了一小时后你是花五分钟合并代码还是花半天给 AI 擦屁股。希望这篇复盘能帮你在复制这条路的时候少走我们走过的弯路。
