先说一下背景。上个月我负责内部一个老订单模块的改造任务是把订单编号规则从“日期随机数”改成“日期自增序列”。这类活儿以前纯靠人肉review这次我们试着用AIcoding走完整套流程。折腾下来最有价值的不是生成了多少代码而是两件不起眼的小事一张写着改造意图和边界的 intent.md以及一套每次AI产出diff就自动跑一遍的持续评测机制。这篇就从头到尾讲讲这套东西怎么落地的踩了哪些坑以及为什么我建议内部改造项目都这么干。先说结论intent.md解决的是“AI知不知道该改什么、不该改什么”的问题持续评测解决的是“AI改完到底有没有改坏”的问题。两者缺一个AIcoding在存量项目里基本就是颗定时炸弹。1. 项目定位与落地思路1.1 内部项目改造为什么要引入 AIcoding内部老项目改造和从零写新功能完全是两码事。新功能是一片空地AI随便发挥都行改造是一片已经住了人的老小区你不能为了换根水管把承重墙拆了。过去我们团队遇到订单模块这种“历史包袱重、逻辑绕、但又天天要改”的模块基本都是老人不敢动、新人看不懂、需求排不过来。这次引入AIcoding不是因为AI写代码有多快而是想解决一个更实际的问题把“理解存量代码”的苦力活儿分出去。AI可以快速把整个模块的调用链、边界条件、历史怪逻辑都读一遍并且生成初步改动的diff。真正让人惊喜的是只要任务边界定义得足够清楚AI产出的代码在结构上经常比一些着急赶工的人类同事还干净——它不会因为“赶进度”而顺手复制粘贴一段旧逻辑。难的不是让AI写代码而是让AI在一个已经有八年历史、经过十几手维护的模块里知道什么是“可以动的”什么是“碰了会出事的”。这个问题靠聊天窗口里的一句话提示是解决不了的。1.2 intent.md 与持续评测在闭环中的角色AIcoding的标准化流程现在业内基本都认同先定义任务意图再让AI生成代码然后自动验证最后人工确认。这个闭环里intent.md和持续评测是两个以前常被忽略、但恰恰决定成败的环节。intent.md可以理解成给AI发的“改造合同”。人工review之所以累是因为每个人对“这次改动到底要动哪些范围”心里都有自己的理解。intent.md就是把这个理解白纸黑字写下来包括改造目标、允许修改的目录、禁止触碰的文件、必须兼容的旧行为、验收标准。AI读完它生成的diff才不会是“看心情发挥”。持续评测则是这份合同的“质检员”。每次AI生成完diff不直接进代码库而是先自动跑一轮检查编译能不能过、单测有没有被打挂、关键业务行为有没有悄悄变掉。这就像一个工厂里每个工人做完一道工序先过一遍自动探针再流到下一道而不是等整台机器装完了才发现螺丝拧错了。说实话没有持续评测之前我根本不敢让AI独立改核心模块。有了之后心理压力小很多AI改错了会被评测打回来不会带着问题硬合并。1.3 为什么没一上来就追求全自动化这套方案设计的时候团队里有人问既然都上AIcoding了评测也自动了为什么不干脆全自动生成、全自动合并我的答复是内部改造项目的目标不是“无人化”而是“安全地提速”。全自动化的前提是验收标准极其完备、测试覆盖极其充分。但老项目的现实是单测覆盖不全、历史逻辑诡异、依赖关系复杂。这时候全自动就是拿系统的稳定性开玩笑。所以我们把AI的定位设成“高级实习生”事情交给你做方案你来出代码你来写但我这关必须人工过。持续评测是让“人工过”这关可以从检查每一行代码变成只盯着diff和评测报告里标记出来的风险点。这个定位挺重要的。团队里其他工程师看到AI不是来抢饭碗的而是把一些重复劳动接下来反而愿意配合。2. intent.md把改造意图变成可执行的边界2.1 一份能用的 intent.md 长什么样第一次写intent.md的时候我也没经验以为是写需求文档洋洋洒洒写了三大页结果AI生成的diff离谱到把整个模块的文件都改了。后来我们迭代出一个精简模板每个任务都用这个结构效果好很多。直接贴出来供参考# 任务意图订单编号规则调整日期随机 - 日期自增序列 ## 改造目标 - 现状订单编号在创建订单时生成规则为日期5位随机数。 - 目标改为日期全局自增序列保证顺序可追溯且唯一。 - 非目标不改变前端展示格式不改变数据库存储长度。 ## 范围与边界 - 允许修改的目录order-service/src/main/java/.../order (仅限以下文件) - OrderNumberGenerator.java - OrderServiceImpl.java - 禁止触碰文件 - 迁移脚本目录 db/migration/* - 对外接口定义 OrderApi.java - 历史兼容类 LegacyOrderNumberParser.java ## 存量约束 - 已存在的历史订单编号格式不允许重新生成。 - 新编号必须与旧编号在长度上保持一致避免改表结构。 - 生成器必须线程安全支持高并发下唯一性。 ## 验收标准 - 新增单测覆盖并发100线程生成编号无重复。 - 行为快照对比通过率100%。 - 编译通过无新增lint告警。这个模板看起来简单但每一条都是后来用教训填进去的。比如“禁止触碰文件”这一节一开始没写AI就自作主张去改了一个数据库迁移脚本差点出事。“非目标”这一节也很关键AI经常会往目标里加私货比如顺手把校验逻辑重构了写清楚非目标能有效刹车。2.2 存量项目改造时intent.md 的写法差异如果是全新项目intent.md可以写得粗放一些让AI自由发挥。但存量项目改造写法上有个核心差异不能只写“要改什么”必须花一半篇幅写“哪些不能动”。我总结出来的经验是存量改造的intent.md至少要包含三类特殊约束。第一类是技术债禁区老代码里有一些“看着很蠢但千万别动”的逻辑比如某个字段在特定状态下必须保持空字符串而不是null否则下游解析会炸。这类行为必须白纸黑字写进“存量约束”否则AI一定会出于“代码整洁”的洁癖给你改掉。第二类是依赖锁定改造过程中不允许升级任何第三方依赖版本不允许调整Spring Bean的装配方式。老项目很多问题都是依赖版本错位引起的AI不知道这些历史渊薮放开这个口子等于埋雷。第三类是隐式约定比如团队约定所有金额计算用Long而非Double、所有时间用时间戳而非字符串。这些约定可能不在任何文档里但老代码里贯彻得很彻底。intent.md里不写AI按通用最佳实践来生成的代码和整个项目风格格格不入。写这些约束的时候有个技巧是从代码里反推。我会先用搜索工具把模块里所有带Deprecated、TODO、特殊注释的地方扫一遍把这些“雷区”直接写进intent.md的禁止项里。与其等AI踩雷不如提前排雷。2.3 三个让 intent.md 失效的反模式写intent.md这件事我踩过不少坑。最常见的反模式有三个每次写的时候都要提醒自己别犯。第一个反模式是把intent.md写成需求文档。有同事模仿PRD写了一份里面有一大段“业务背景”描述公司战略还有用户故事、交互流程图。AI读完之后完全不知道要它干嘛生成的diff文不对题。intent.md是面向执行器的任务单不是给产品看的说明书。背景只写必要的上下文重点全在范围、约束、验收上。第二个反模式是只有目标没有验收标准。写过“确保系统稳定”“优化代码可读性”——这种话AI根本没法执行。“稳定”怎么测“可读性”怎么打分没有量化验收标准持续评测就是空转。正确写法是给可验证的标准并发线程数、快照通过率、lint告警数、不允许修改的文件列表。要强迫自己把每条验收都写成能被脚本检查的命题。第三个反模式是一个文件塞多个任务。有一段时间为了省事我把“调整编号规则”和“顺便优化一下订单查询性能”写进了同一个intent.md结果AI的diff又大又乱评测跑出来的失败点根本分不清是哪个任务引入的。后来定了个规矩一任务一意图一次intent.md只描述一件事。任务拆小了AI的成功率高评测结果也可解释。3. 持续评测把“质量”变成每次 diff 的自动化闸门3.1 评测时机的选择为什么是每一次 diff持续评测这个名字很容易被理解成“持续集成”也就是代码合并前跑一遍测试。但我们这次做的最重要调整是把评测时机提前到“AI每次生成diff之后、进入代码库之前”。这里有个很关键的细节。AIcoding的工作方式是交互式的AI先生成第一版改动你看了不满意它会根据反馈生成第二版。如果评测只在最终合并前跑一次那AI在中间好几轮迭代里其实是在“盲目飞行”——它不知道自己的方向对不对只是根据人粗糙的反馈瞎猜。把评测嵌入到每一轮生成之后AI就能收到精确的信号用了被禁止的文件、破坏了某个行为快照、编译不过。这些信号比人类说的“不太对你再看看”有用得多。有同事问每轮生成都跑评测时间成本会不会太高实测下来我们控制在两类评测快的一类一两分钟就出结果重的回归放到合并前跑。只要把评测拆成“快速反馈”和“最终确认”两个档次这个节奏是完全可以接受的。AI多迭代几轮的成本远远低于人肉review一个半小时然后打回重做的成本。3.2 三级评测体系的具体设计这套评测体系不是拍脑袋定的是参考了代码评审的一贯关注点代码能不能编译、测试有没有破坏、业务行为有没有变。只是把这三个关注点全部拆成了自动化环节。第一级叫静态与构建检查跑得最快。包括编译、lint、依赖变更检测和文件黑白名单校验。“文件黑白名单”这个功能就是我们这次改造特意加上的因为AI屡次把手伸到禁止文件中。顺手把这套名单做成了共享配置以后任何AIcoding任务都能复用。第二级叫行为回归是这套体系的核心。老模块的单测覆盖率不高所以行为回归不全依赖单测更多依赖行为快照对比。简单说就是先把当前线上代码的关键行为录制成“快照”AI改完之后重放一遍逐条对比结果。这两级的关系如下评测层级检查内容典型耗时触发时机失败后动作L1 静态与构建编译、lint、依赖变更、黑白名单1-3分钟每轮AI生成后自动打回禁止进入人工reviewL2 行为回归单元测试、行为快照对比5-10分钟每轮AI生成后自动打回附差异报告L3 人工评审逻辑合理性、边界case、代码风格20-40分钟前置评测全通过后人工反馈AI按反馈修改第三级是人工评审但这里的人工评审范围已经大大缩小了。以前review改造代码要通读整个模块深怕AI漏了什么。现在有前两级自动检查兜底我只需要盯三件事diff的代码逻辑是否合理、AI有没有把简单问题复杂化、以及评测报告里勾出来的“边界case”处理是否符合业务预期。3.3 行为快照基线——存量改造最实用的评测手段这一节单独拎出来说是因为行为快照基线这个方法对存量项目改造来说价值被严重低估了。单测再齐全也覆盖不到所有历史行为code review再仔细也总有盲区。行为快照恰好补上了这个空当。做法不复杂。拿订单编号这次改造举例改造前我在测试环境写了一段采样脚本模拟真实请求路径把“创建订单-生成编号-保存库存-扣减”整条链路跑一遍对关键接口录制输入输出。样本不是随便录的要刻意覆盖正常值、边界值、异常值。我这次录了21组样本其中包括并发批量创建、编号位数达到上限、重复提交等场景。AI改完之后评测脚本会把同样21组样本重放一遍然后把输出和基线逐字段对比。只要有一个字段对不上比如编号位数从20位变成了21位评测就报失败并把差异字段标出来。这个反馈给到AI它下一轮就知道收敛了。实际用下来快照基线最大的坑是“录得太粗”。一开始我只录了正常流程的十几条数据AI改了并发逻辑导致锁竞争环境下的偶发问题快照完全没暴露出来。后来加上并发批次样本才兜住。另外一个坑是基线更新要克制不要AI一动就顺手把基线改了那样快照就失去了“守护既有行为”的意义。只有当团队确认行为变更是有意为之才去更新基线。3.4 评测报告的判定逻辑如果评测报告只是“通过/不通过”两个大字AI和人对反馈的理解都容易偏。我们设计的报告分成了绿、黄、红三个信号。绿色信号代表全部通过可以直接进入人工review。黄色信号表示有非阻断问题比如lint告警新增了两个、编译有warning这类问题不阻止合并但必须记录在案人工review时需要看一眼。红色信号则是硬阻断编译失败、单测挂了、快照行为不匹配、触碰了禁止文件。只要有一个红色出现这轮diff就不会进入代码库AI直接收到失败原因开始下一轮。这个信号体系最大的作用是给人和AI一个共同的“语言”。AI不像人你说“感觉不太对”它听不懂但你说“编号位数从19位变成20位快照比对差异字段orderNo.length()不匹配”它立刻知道怎么改。持续评测越精准AI的迭代效率就越高人需要投入的审查精力就越少。4. 实操全流程复盘一个订单模块编号规则改造4.1 改造前梳理现状与生成行为基线这次改造的具体任务我再交代一下订单编号原来生成规则是“yyyyMMdd5位随机数”要改成“yyyyMMdd6位自增序列”。看似简单涉及的东西不少。改造前三天我花了小半天做现状梳理。先找出编号生成的核心代码路径确认影响范围其实非常收敛创建订单的服务实现、编号生成器、以及一条消费消息的重试逻辑。真正让这个任务变得危险的是数据约束线上已有几千万历史订单编号格式变了索引结构、对账逻辑、导入导出脚本都可能受影响。梳理完之后我开始建行为基线。这里没有现成工具是写了一个Python脚本调用测试环境接口走通“创建订单-获取编号-断言格式”这条链路。21组样本里除了正常创建订单还包括并发200个订单同时创建、订单创建失败回滚后是否消耗序号、老格式编号的解析兼容等。每组样本都记录了输入参数、输出订单编号和几个关键中间量。这个基线建完我当天晚上就把快照脚本挂到了评测流程里。后来复盘这一步是整个项目最值得的投资因为后续AI每次迭代都在这条基线上直接得到“过还是不过”的结论。4.2 写 intent.md一份完整的改造实例基线建好后写intent.md花了大概半小时。这个时间不算浪费因为后面所有环节——AI生成、评测、人工review——都靠这份文档兜底。任务切割时我特地只放了两个允许修改的文件禁止文件列了三个一个历史迁移脚本、一个对外API接口定义、一个旧格式编号解析类。写“存量约束”的时候我把老编号格式“日期5位随机数”的兼容要求写得很死新生成的编号长度必须与老编号一致因为下游很多地方用固定长度截取。验收标准没有写空话。并发唯一性那一条我直接写“200线程并发调用生成器编号无重复且不抛异常”快照对比那一条写“21组行为样本重放字段级对比通过率100%”。这些标准后来都原样变成了评测脚本里的断言intent.md写得好不好直接决定评测能不能自动化。4.3 AI 生成 diff 的第一轮评测失败之后第一次让AI动手生成的diff总共改了5个文件。比允许的2个文件多了3个我一看详情好家伙它动了被禁止的数据库迁移脚本说“顺手修复了历史脚本中一个潜在的类型转换问题”。这就是没有intent.md约束时的典型表现AI发现了一个问题主动扩大改动范围去“帮忙”。它这份好心在存量项目里就是事故的前奏。好在L1评测第一时间就亮红了原因就是黑白名单校验发现改动涉及禁止文件自动标记“越界修改”。我没有直接改AI生成的代码而是回去改intent.md的“范围与边界”把“禁止触碰”一节的描述加重了任何文件只要不在允许修改之列一律视为禁止修改。这相当于从规则层面切断了AI的发挥空间。然后重新让AI生成第二轮。第二轮diff干净多了正好两个文件编号生成器和订单服务实现。L2行为回归跑了5分钟结果是有一个快照不一致——并发场景下自增序列出现了两个相同的编号。原因出在AI实现的序列生成器没有加锁。评测报告把这条差异标得很清楚AI看到后自己加了并发控制逻辑第三轮生成后就全绿了。这三轮迭代大约花了二十分钟。对整个改造来说多跑两轮AI是零成本的但要是没有持续评测第一轮那个越界修改的diff很可能就混进review流程甚至代码库了。4.4 人工 review 环节如何快速收尾三级评测全绿之后进入人工review。我实际审下来耗时大概二十分钟attention只集中在两块一是diff里改动最大的OrderNumberGenerator类确认并发控制方案确实正确二是评测报告里黄色警告的两处非阻断问题AI在日志里漏了一个历史格式兼容分支的debug输出属于小事不阻断。真正让我觉得这套流程跑通了的时刻是旁边一个老同事看了一眼diff说“这次改动倒是挺干净的没碰不该碰的东西。”这句话以前只会出现在我们对资深工程师的评价里现在也能用在AI生成的代码上了。review通过之后还有一个动作不能省把这次AI生成过程中踩过的坑和解决方式沉淀回intent.md和评测配置。比如这次新增的“禁止修改任何范围之外的文件”这条规则后来就被写进了团队通用的AIcoding工作流配置里。5. 常见问题与排查技巧实录5.1 高频问题速查表实践这套流程的过程中从intent.md写法到评测配置前后踩了不少坑。整理一个速查表方便大家直接对照排查。问题现象可能原因排查思路解决方案AI改了禁止文件intent.md约束描述太模糊检查“禁止触碰”是否明确到文件级别用文件黑名单硬校验在L1直接阻断评测全绿但业务逻辑错行为快照样本覆盖不全检查快照是否覆盖边界与异常场景增加并发、边界、失败回滚类样本单测数量少快照挂不住老模块没有测试基数先补核心链路的接口级快照快照优先于单测补齐快速建立基线AI多轮迭代仍然不收敛intent.md验收标准不可量化检查验收是否写成“确保”“优化”改成可断言的数字与规则全量评测太慢评测没有分层统计各环节耗时占比拆分L1/L2生成后只跑快速档团队不信评测结果评测报告可解释性弱看报告是否只说“失败”不指原因按字段输出差异指到具体行与值5.2 三个值得写进团队规范的避坑细节有几个细节没有实战体会很难想到但踩过之后就特别想写进团队规范。第一个是依赖版本锁死。AIcoding过程中AI有时候会顺手“修”依赖里的小版本比如把某个工具库从1.2.3升到1.2.8。表面看没啥风险但老项目里一个依赖的升级可能牵连好几个模块。我们在intent.md里统一了措辞“禁止变更pom.xml / build.gradle中任何依赖版本”并且评测脚本里也加了依赖文件diff检查。这一条救过我们一次AI曾经悄悄把日志库版本升了而那个版本和团队自研的链路追踪组件不兼容。第二个是坚持一任务一意图。有人觉得一个intent.md多写几件事更高效实际上AI多任务同时执行的时候评测失败了很难定位问题出在哪个任务上。把任务拆细的额外好处是intent.md可以复用下次遇到类似的编号规则改造直接把上次的模板拿出来改改就能用。第三个是快照样本必须包含脏数据。用真实业务数据做快照的时候不要只挑“好看”的样本。我们这次用了一个真实环境导出的脱敏数据包里面有几条历史脏数据比如日期格式少了前导零、编号超长的老记录。AI改完之后看到这些样本还在、而且行为没变我才真正放心——只有处理得了脏数据的改造才算没破坏存量兼容。5.3 团队怎么用起来从试点到制度这套流程从一个模块试点到全量推广其实是有一个自然路径的。第一步千万别一上来就搞平台化、工具化先把一个模块跑通把intent.md模板和评测脚本沉淀下来。第二步是拉一个共享工作流大家用差不多通用的模板避免每人一套写法。第三步是每周花20分钟过一次评测数据看不通过的案例主要是intent.md写得不清楚还是模型能力问题——这两个原因对应的解法完全不同。团队推广过程中有个偏见的转变挺有意思。最开始有人质疑“这是不是让AI帮我们写题”后来我们把AIcoding的笔试/实操题也按这个思路设计了给候选人一段存量代码和一个intent.md模板要求完成改造并让评测通过。能写好intent.md、根据评测反馈迭代的人实际产出的代码质量比那些只会刷算法题的人靠谱得多。这也反过来验证了我们的思路intent.md和持续评测本来就是AIcoding能力里最值得精进的部分。6. 写在最后一点体会这套流程跑完之后我对AIcoding的理解有了一个很大的转变。以前总觉得AIcoding的核心是模型多强、提示词多妙现在发现对内部项目改造来说真正决定成败的是任务边界的定义能力和质量反馈的闭环能力。intent.md就是边界持续评测就是闭环。模型能力可以在通用基准上提升但每个项目独有的“哪些不能动”和“怎么算没改坏”只能靠团队自己沉淀。最后分享一个我自己的判断标准吧。团队里所有人都感觉这套东西好使不是某次生成特别顺利的时刻而是第一次有工程师在review AI的diff时说了一句“这次我看着没什么可改的”。这句话的能量远大于任何评测通过率数字。如果你也要在内部项目里落地AIcoding我的建议是别急着让它写新功能先拿一个改造类任务练手。把intent.md写熟把持续评测跑顺AIcoding就不是“偶尔惊艳、经常翻车”的玩具而是一个真正干活稳当的帮手。