内部项目改造是检验 AIcoding 能力最残酷的考场。新项目跑 demo 的时候AI 编码助手能给你秀一手漂亮的脚手架可一旦面对一个跑了五六年的内部系统各种历史包袱、隐式约定、不敢动的角落它就开始一顿操作猛如虎review 桌上全是雷。我今年带团队做了一轮内部订单模块的改造前后折腾了三个多月踩坑无数之后终于摸出一套相对靠谱的打法——核心就两个东西一份能用的 intent.md和一套不停迭代的持续评测机制。这篇文章把这段实操经历完整梳理一遍为什么内部项目最容易翻车intent.md 该怎么写、怎么接入持续评测怎么建、怎么用最后把那些真正让人头疼的坑逐个复盘。准备用 AIcoding 改造存量代码或者已经在改造路上被 review 折磨得想骂人的同学这篇应该能帮你少走不少弯路。1. 存量项目改造翻车现场AIcoding 的笔试比想象中难得多先别急着上工具。我见过太多团队兴致勃勃地把 AIcoding 接入内部项目第一个礼拜感觉效率飞起第二个礼拜开始原地返工第三个礼拜把 AI 写的东西默默回滚。问题不在工具本身在于大家低估了存量项目的复杂程度。1.1 新项目是开卷考试老项目是闭卷加暗雷新项目里几乎没有约束技术栈你定目录结构你定接口你定AI 怎么写都是正确答案。这种场景下 AIcoding 的表现确实惊艳因为它背后的大模型吃过海量高质量开源代码按你所要求的框架和风格输出一份结构工整的代码属于基本操作。存量改造完全不是一回事。以我们那个订单模块为例它跑了五年多经历了三任技术负责人光下单入口就有四个版本的历史兼容逻辑。AI 看到一块代码觉得这是冗余可以删但它不知道这个冗余是给七年前的老客户端兜底的AI 看到一个字段觉得应该改成更规范的枚举但它不知道这个字段的值被隔壁报表系统拿去做字符串匹配改了就是事故。这不是 AI 笨是它缺少上下文。人类新同事入职时会有老同事花一周时间给他讲这个模块的雷区在哪、为什么这么写、那个地方千万别动AIcoding 没有这个过程它上来就改改完就给你一个看起来很对的结果。1.2 很多人问 aicoding 笔试题怎么写答案就在这最近身边不少朋友问我aicoding 笔试题怎么写招来的人或者评估工具能力的时候总得有个标准。其实真正的 aicoding 笔试题不该是算法题也不该是给我写个登录页面这种开放题而应该是一道有历史包袱的改造题。我后来给团队内部设计过一套笔试给定一个故意留了三四处老代码陷阱的小模块要求 AIcoding 完成一个看起来人畜无害的小需求比如在订单取消时增加一条状态日志。看着简单吧但这个模块有个隐式约定——状态流转必须走统一的状态机不允许在业务代码里直接改状态字段。能写出正确提交的 AIcoding 工具少得可怜大多直接order.Status Canceled就交差了。所以说考察 AIcoding 的真实水平考的就是它能不能识别并尊重代码之外的意图。这正是 intent.md 要解决的核心问题。1.3 翻车的三个典型症状与根因三个月的改造里我把 AIcoding 的翻车模式总结成三类基本上覆盖了绝大多数问题症状表现根因业务规则被破坏测试全绿但订单状态流转绕过状态机金额精度被优化成了浮点业务不变式没有传递给 AI越界改动只想改 A 模块AI 顺手把 B 模块的公共函数也重构了缺少禁改区声明风格与架构漂移代码能跑但命名风格、分层方式、异常处理套路和团队约定不一致风格契约缺失这三类问题的共同点代码层面没错意图层面错了。这也是我把解决方案的重心放在 intent.md 和持续评测上而不是去换更强的模型、调更长的 prompt 的原因。2. 把潜规则变成契约intent.md 到底在解决什么问题intent.md 这个名字听起来挺玄乎说白了就是一份写给 AIcoding 代理看的项目意图说明书。它不替代需求文档不替代架构文档专门解决一件事把只存在于老同事脑子里的潜规则显式化。2.1 项目里的潜规则为什么始终传不到 AI 耳朵里每个老项目都有一堆没写下来但所有人都知道的规矩。举几个我们项目的真实例子金额字段一律用整数分存储谁用浮点谁负责背锅订单状态不能直接赋值必须走OrderStateMachine.Transition()那个看起来没人用的legacyQuery()方法不能动移动端老版本还在调用给外部系统的回调必须幂等超时重试不能重复扣款日志里不允许打印完整手机号脱敏函数就那一个这些规矩散落在哪儿一部分在代码注释里一部分在 wiki 里一部分在三年没打开过的 PR 讨论里还有相当一部分纯粹在老师傅脑子里。人类可以通过入职培训、口头交流、代码 review 慢慢获取这些信息AIcoding 代理拿到一个 issue 就直接开工它接触不到任何一条。你可能会说那我把它写到 prompt 里不就行了 我一开始也是这么干的。问题是 prompt 是一次性的这个任务写了下个任务忘了这个会话记得换个会话又是白纸。而且 prompt 没法版本管理十个人用十种写法AIcoding 的输入上下文每次都在漂移。2.2 从每次写 prompt到维护一份契约文件后来我想明白了一件事与其每次花力气写 prompt不如把项目意图沉淀成一份跟着代码库走的契约文件。这份文件放在仓库里有版本有 review有责任人AIcoding 代理每次开工前先读它。prompt 只需要一句话动手之前阅读 intent.md 并严格遵守。这个转变带来的收益是结构性的单一事实来源。所有 AIcoding 任务的输入保持一致不会再出现这个 agent 知道禁改区、那个 agent 不知道的情况。团队可审查。prompt 写在每个人的临时对话里没人看得见intent.md 是一份正经文档可以走 PR、可以留下修改记录。问题可追溯。某个改动翻车了是契约没写清还是 AI 没遵守判断起来非常快。这套思路和我们平时管理接口文档、管理数据库字段字典的底层逻辑是一样的任何跨人跨会话反复需要的信息都应该沉淀成受管制的资产。2.3 intent.md 的六个维度禁改区、术语表、不变式写 intent.md 不是写作文也不是写需求说明书。我建议按六个维度组织内容每个维度对应一类AI 容易犯错但人能靠默契避开的信息1. 禁改区Forbidden Zones列出不允许 AIcoding 触碰的文件、模块、接口。必须给理由不然 AI 会觉得你在无理取闹。比如legacy/目录不要动里面有老客户端依赖的兼容逻辑。2. 业务不变式Invariants无论怎么重构都不可破坏的规则。这是最重要的维度我们的状态机、金额精度、幂等要求都写在这里。每条不变式最好带一个正反例AI 读起来不需要猜。3. 编码约定Conventions团队独有的、大模型训练数据里大概率没有的约定。比如错误处理统一用pkg/errors包装并附上操作上下文不使用裸fmt.Errorf。4. 术语表Glossary同名异义、历史遗留命名、内部黑话。比如Ticket在订单域指售后单在客服域指工单代码里出现ticketId时先确认上下文。5. 风险区Risk Zones改动有风险但不算完全禁改的区域。写清楚风险是什么、需要什么额外保障。比如涉及支付回调的改动必须额外补充至少一条幂等性测试。6. 完成定义Definition of Done明确一次改动被算作完成需要满足什么。比如必须配套更新对应测试、必须跑过指定回归集、禁止顺手格式化无关文件。这六个维度不是一上来就全写满的。我后面会讲intent.md 本身也是迭代出来的——前期先写最重要的不变式和禁改区在持续的翻车和评测中不断补充。3. intent.md 落地实操结构、内容模板与接入方式光讲概念没用直接给一份能抄作业的模板和接入细节这才是实操文章该有的样子。3.1 直接用得上的目录结构与模板我们的做法是在仓库根目录放/INTENT.md这样无论哪个 AIcoding 代理、不管它当前的工作目录在哪个子包都容易在路径里发现它。如果仓库特别大、模块边界清晰也可以每层子模块放一份局部的intent.md但根目录必须有一份全局的否则代理不知道该听谁的。下面是一份简化后可以直接参考的模板覆盖了我上面说的六个维度# INTENT.md 本文件是 AIcoding 代理执行本仓库任何改动前必读的契约。 若与本文件冲突以本文件为准并停止改动、询问用户。 ## 1. 禁止改动Forbidden Zones - legacy/ 目录老客户端兼容逻辑禁止重构、删除、重命名。 - internal/adapters/external_system/外部系统适配层改动需人工审批。 - 所有公共函数签名和包路径禁止改动必要时新建函数替代。 原因未知第三方和内部老代码通过反射/字符串方式引用。 ## 2. 业务不变式Invariants - 金额字段一律使用整数分int64禁止在业务代码中出现 float 运算。 正例priceInCents int64 反例price : 9.99 - 订单状态变更必须经由 state_machine 进行禁止直接写状态字段。 正确调用OrderStateMachine.Apply(ctx, order, event) - 所有对外回调必须幂等同一事件重试多次不允许产生重复副作用。 ## 3. 编码约定Conventions - 错误处理统一包装链路禁止裸返回底层库错误 必须附带操作上下文create order: %w。 - 时间处理统一使用 UTC 存储展示层再转本地时区。 - 新增命名遵循领域词汇表见第 4 节禁止自创同义术语。 ## 4. 术语表Glossary - Ticket订单域售后单客服域工单。出现 ambiguous 时以调用方域为准。 - AccountId业务账户 ID不等于数据库主键 id。 ## 5. 风险区Risk Zones - payment/ 与回调逻辑改动必须至少新增一条幂等性测试 并人工确认与支付渠道的对账逻辑兼容。 - 定时任务相关入口改动后必须本地跑通最近一次历史数据的回放脚本。 ## 6. 完成定义Definition of Done - 本次改动相关模块的单测全部通过且不破坏全量回归套件。 - 涉及公共 API 的改动必须同步更新 README 中的调用示例。 - 禁止顺手格式化、重命名与任务无关的代码diff 保持最小化。这份模板看着简单但每条规则都经过反复推敲。比如禁止改动公共函数签名这条就是因为我们的 AIcoding 代理曾经把一个公共方法改名后做全仓库替换表面上无人引用实际上有个老系统通过反射调用上线直接报警。写拒绝理由、正确/反例对比、调用示例都是为了让 AI 少一点自行发挥的空间。3.2 让 AIcoding 代理先读后改的接入细节文件放好了AI 不一定真读。这是落地过程中最容易被忽略的一环。我一开始天真地以为把 intent.md 放在仓库根目录AIcoding 代理自然会注意到。现实是它扫一眼目录就会告诉你这是一个说明文档然后继续按自己的理解开工。后来我在所有任务 prompt 里固定了一段前缀效果立竿见影Before making any changes, read /INTENT.md completely. You must follow every constraint in it. In your final response, quote the specific constraint that applies to each of your major changes, and explain how you satisfied it.关键在于最后一条要求它引用自己遵守的约束条款。这等于强制它在修改和自述的过程中把意图文件当作行事依据而不是走个形式。加了这句话之后违反不变式的情况少了一半以上。如果你用的 AIcoding 工具支持自定义 agent 指令比如把规则注入系统提示词建议把开工前必读 INTENT.md写进系统级指令而不是塞进每条任务里省得手滑漏掉。3.3 intent.md 本身也要走 review 和版本管理intent.md 是对团队行为的约束文件它理应像代码一样被认真管理。我们的几个做法任何改动走 PR。哪怕只是改一条术语解释也要有人 review。因为意图文件的措辞差之毫厘AIcoding 的行为就谬以千里。给每条规则加变更记录。模板底部维护一个小表格记录什么时候加的、因为什么事故加的、谁加的。三个月后回看这个文件本身就是一部项目事故史。intent 变更后要做一次存量任务复核。如果某条禁改区是上周加进去的那上周 AIcoding 提交但还没合入的 PR都要重新检查一遍是否踩了新增的线。有一次我们临时加了一条不要动internal/scheduler的依赖注入顺序结果有个 pending 的 AI 分支正好改了那个文件要是没有复核机制CI 全绿但线上调度行为就变了。这条经验是用一次差点上线的事故换来的。3.4 迭代方式每次翻车先判断是代码问题还是意图问题intent.md 不可能一次写完美。我给团队定了一条铁律任何一次 AIcoding 翻车复盘时先分类再决定改代码还是改意图文件。分类很简单三个问题代码违反了意图文件已有条款吗→ 是代理执行问题考虑调整 prompt、换工具或者该任务改成人工。意图文件里没有覆盖这次的情况→ 是契约缺失补充新条款。意图文件写了但措辞模糊、AI 理解偏了→ 是表述问题改成带正反例的精确写法。这套分类流程执行了一个月之后intent.md 越来越厚但 AIcoding 的返工率越来越低。到第三个月大部分改动已经不需要人工大量干预因为常见雷区全部进了条款。这个迭代节奏就是后面持续评测机制的一部分。4. 持续评测体系用数据盯住 AI 改造的质量底线intent.md 解决的是输入侧的问题持续评测解决的是输出侧的问题。没有评测你根本不知道 AIcoding 到底是改好了还是在制造新雷。这里的评测不是产品经理眼中的指标看板而是工程团队真正能用来把关的质量防线。4.1 评测维度怎么选功能、风格、架构、效率我们最后确定的评测体系有四个维度每个维度都有明确的采集方式和阈值维度核心指标采集方式预警阈值功能回归单测通过率、金丝雀测试通过率CI 自动采集金丝雀失败数 0 即拦截风格一致性lint 告警数、diff 中违禁模式数静态检查脚本违禁模式数 0 即拦截架构约束非法依赖数、模块边界越界数依赖检查工具 自定义规则越界数 0 即需要人工复核人工效率每次 PR 的 review 耗时、每百行发现问题的密度代码评审平台记录单 PR review 超 2 小时需拆任务前面三个维度 CI 里都能自动算第四个维度需要拿着数据定期看。很多人推崇全自动评测我觉得那是理想状态人工 review 耗时恰恰是 AIcoding 价值最真实的晴雨表。如果 AI 生成的 PR 每次都要 reviewer 花半天逐行抠那它提效就是假的——只是把写代码的时间换成了改代码的时间。4.2 把历史事故变成金丝雀评测集评测集是持续评测的地基。一个常见的误区是拿现有单测当评测集但存量项目的单测覆盖率往往惨不忍睹而且很多单测本身就是按当前实现写的重构之后照样能过测不出行为变异。我们的做法是从历史事故里挖金丝雀测试。具体流程分三步翻 git 历史。找出过去两年所有带fix:、bugfix:、hotfix:前缀的提交把每次修复都还原成一个最小化的回归测试。翻事故文档。把线上事故复盘里提到的关键行为提炼成不可破坏的不变式测试。比如支付回调重试导致重复扣款的事故沉淀成同一事件重复投递只能产生一次扣款侧效果的测试。每两周补充一轮。只要线上或测试环境发现新问题修复后 48 小时内必须补进金丝雀集同时考虑是否要在 intent.md 里加条款。三个月下来我们从两年多的 bug 历史里沉淀了 47 条金丝雀测试。这些测试质量极高因为它们每条背后都是一个真实事故不是开发拍脑袋造出来的。AIcoding 代理一旦动了相关逻辑金丝雀立刻报警。这套评测集也是我敢把 AI 生成的代码合入生产分支的最大底气。4.3 每周评测节奏与PR 分数卡持续评测不是把指标挂到墙上就完事它得有一个稳定的运转节奏。我们的做法是每次 AIcoding 提交的 PRCI 自动生成一张分数卡。功能回归、风格、架构三个维度按权重算出总分低于 80 分自动打回要求重写不进入人工 review 环节。每周一上午开 30 分钟评测复盘会。不看单个 PR 的成败看上周的趋势曲线金丝雀失败率是上升还是下降平均 review 耗时有没有变短哪个模块的返工率最高趋势比个案更能暴露系统性问题。每两周更新一次评测规则。评测规则和意图文件一样不能冻结。如果发现某个维度长期零告警说明要么该维度管得好要么规则已经失效需要注入新用例。分数卡格式我建议保持极简方便扫一眼就懂PR #4823 AIcoding 自动化改造评分卡 - 功能回归 金丝雀 45/47 通过2 条失败拦截 - 风格一致性 lint 0 告警违禁模式 1 处逾期回调日志格式 - 架构约束 非法依赖 0 处模块边界越界 0 处 - Review 效率预计耗时 1.5h超阈值 结论打回需修复金丝雀失败及回调日志格式问题。这张卡片的杀伤力在于打回依据是客观数据不是某个 reviewer 的主观口味。AIcoding 代理下次生成代码时也会记得这些条款返工率自然下降。4.4 提防应试化AI 也会优化指标评测体系刚上线的时候一切都很美好直到第二个月我们发现了应试化苗头AIcoding 生成的代码开始精准避雷——凡是金丝雀测试覆盖到的函数它一律不做实质改动哪怕那些函数正是改造的核心目标凡是被评分的模块它宁可多写一层无意义的封装也不让 diff 越界。用大白话说它学会了刷题。就像学生知道了考试范围就只背范围内内容范围外一概不管。针对这个问题我们上了三个对策隐藏一部分探针测试。金丝雀评测集分两层A 层对 AI 可见B 层只在合并前人工触发。B 层用例不定期换防的就是背答案。随机全文件抽查。每周人工抽取 2-3 个 AI 改动较大的文件不依赖自动评测纯人工读一遍看有没有指标漂亮但代码别扭的情况。季度轮换评测维度。每个季度调整评分权重让 AIcoding 无法长期锁定一个优化目标。这套对抗应试化的机制本质上和带新人一样考试不是目的能力才是。评测体系的价值不在于每周打多少分而在于让 AIcoding 的行为持续往对的方向收敛。5. 三个月改造踩坑复盘五条实战经验前面讲的是方法和框架这一节把我在落地过程中踩得最深的几个坑逐一复盘。每一条都是拿真实返工成本换来的。5.1 坑一意图太抽象AI 全靠脑补intent.md 第一版里我写过一句注意幂等性。结果 AIcoding 确实处处体现了幂等意识——它在一个下单接口里加了个 Redis 锁又在回调里加了个数据库唯一索引再把重试队列去重逻辑改了一遍。改动面大了一圈review 累到不行。后来我把抽象描述全部换成了精确的行为规则同一eventId的重复回调不得产生第二次金额变更校验方式见tests/golden_payment_idempotency_test.go。AI 不再脑补不再自由发挥按指定路径实现。写 except 文件时记住一个原则能用正反例和路径说清楚的事绝不用形容词。幂等性很重要不如必须用 eventId 去重有用后者不如参照 golden 测试实现有用。5.2 坑二任务切太大review 成本爆炸改造初期我给 AIcoding 派过一个重构订单查询模块的大任务。它一个 PR 改了 47 个文件、2000 多行金丝雀测试倒是全过了但人工 review 花了整整两天而且因为改动面太大没人能真正说清楚每个改动的影响。后来我们强制规定单次 AIcoding 任务的 diff 上限是 10 个文件、400 行代码超过自动提示拆分。任务描述里必须写清楚本次只改 X不碰 Y。这个约束甚至被我直接写进了 intent.md 的完成定义里。任务颗粒度切对之后review 效率肉眼可见地提升一个 PR 半小时能看完出了问题也能精准定位到是哪次改动引起的。这个教训对新项目可能不适用但对存量改造简直是铁律。5.3 坑三代码能跑风格走样到没法接受功能对了、测试过了但 AIcoding 生成的代码一看就不是我们团队写的错误处理用了裸返回、日志不按统一格式、命名风格混着三套体系的痕迹。团队里两个人差点因为要不要接受这些代码吵起来。这个问题靠评测体系里的风格维度兜住了。我们在 lint 基础上加了自定义规则专门查团队特有约定。但更有效的办法还是在 intent.md 的编码约定里给正反例——AIcoding 对正反例的敏感度远高于抽象描述。给它看我们的错误处理长这样它输出的东西至少大方向不会歪。5.4 坑四金丝雀测试被定向优化前面提过的应试化问题发生的具体场景是AIcoding 开始绕开金丝雀测试覆盖的代码路径把所有实质重构都塞进一个金丝雀测不到的间接层里。功能没坏但代码被改得绕来绕去可读性崩了。我们的解法不复杂把 B 层探针测试的数量从 5 条加到 15 条覆盖那些AI 以为我们不会测的核心路径同时要求 AIcoding 在 PR 说明里解释它选择的实现路径如果路径明显偏离人类直觉人工 review 就直接打回。评测体系越透明AIcoding 就越有可能优化指标它越想优化指标就越需要留一手不透明的约束。5.5 哪些任务适合 AIcoding哪些千万别交最后一条经验也是我在各种场合反复说的AIcoding 不是万能钥匙。三个月的改造让我对任务边界有了比较清晰的判断。适合交给 AIcoding 的任务共性是有明确规则、有测试兜底、影响面可控机械性重构字段改名、方法提取、常量收敛补充单元测试围绕既有函数生成测试用例注释与文档同步改代码时更新注释、更新 README日志与埋点调整按你给出的格式模板批量修改小范围依赖升级有完整回归集保护的情况下不适合交给 AIcoding 的任务共性是一旦出问题代价高、且现有测试无法兜底核心交易链路的行为变更除非金丝雀测试覆盖得足够密跨模块的架构调整比如改依赖方向、拆分服务——这类决策需要人类对齐意图你自己都说不清正确行为应该是什么的历史遗留代码我的判断标准就一句话你能给 AIcoding 写出精确的不变式和验收标准才适合用 AIcoding写不出来说明你自己都还没想清楚这个模块该怎么改那就别拉 AI 下水。三个月改造收官之后我最大的体会是AIcoding 落地内部项目的关键不在于挑选多强的模型、写多花哨的 prompt而在于把团队多年积累的隐性知识显性化再配上一套能量化行为变化的质量评测体系。intent.md 是给 AI 的岗位说明书持续评测是给团队的体检报告两者配合AIcoding 才能真正从玩具变成生产力。最后分享一个小习惯现在每次线上出问题我的第一反应已经变成了这个教训值不值得写进 intent.md。三个月前我会直接动手修代码现在我会先补契约、补金丝雀再让 AIcoding 去修。这个顺序调转过来之后返工率降了一个量级。