AI辅助改造老项目：防止AI顺手改坏原有功能的完整流程

这活儿我干过不止一次而且每次都能在 PR 里看到 AI 特别“贴心”地把一段看着冗余、实则关键的代码给“优化”了然后功能就崩了。在 AI 辅助编程几乎成为标配的今天真正的问题已经不是“AI 能不能改代码”而是“它改完那一刻开始到测试跑完之前你拿什么保证它没把旧功能顺带改坏”。这篇内容就是想把我自己总结的一套流程完整摊开讲一讲涵盖前期怎么立规矩、提示词怎么写、改完怎么验证、真出了问题怎么回滚。适合那些手里攥着老项目、又想让 AI 提效的开发者也适合团队里正准备引入 AI 编程但不知道该怎么控制风险的负责人。1. 为什么AI一碰旧项目就“手痒”改坏原有功能的根本原因1.1 旧项目的隐性契约AI看不见老项目之所以难改从来不是因为代码复杂而是因为它身上积累了大量的隐性契约。所谓隐性契约就是代码注释里没有写、接口文档里没有提、但运行时真正在依赖的东西。比如某个模块表面上只是提供一个查询方法背地里却依赖另一个模块在启动时写入的全局缓存又比如某个函数看起来“多余”的日志输出实际上是下游系统在做日志采集时用来切割数据流的锚点。这些契约是几轮需求迭代、人员更替之后沉淀下来的“伏笔”。人是靠业务上下文把它们记住的但 AI 看不到。它拿到你粘贴过来的三五个文件能理解的只有这几百行代码内部的逻辑。你让它改一个接口的返回结构它大概率不会意识到这个接口的返回结果还被另一个离线任务消费而那个任务调用它的时候可没做任何字段兼容处理。我遇到过一次特别典型的一个库存查询接口因为线上越来越慢需求是要给查询逻辑加本地缓存。需求本身不复杂我把核心 Service 文件丢给 AI让它“优化一下查询效率”。AI 很快给出了改动方案表面上漂亮极了——加了一个 ConcurrentHashMap 做缓存还把原来那段查询 SQL 顺手换成了新的写法。结果测试环境一跑商品列表出现了脏数据最后定位到根因老 SQL 依赖数据库端的实时库存状态而新写法把状态过滤逻辑挪到了应用层缓存命中之后根本不走数据库数据时效性全变了。这就是隐性契约在起作用。AI 并没有恶意它只是基于“教科书式”的理想工程范式给出了局部最优解但它不知道这个局部放在全局里意味着什么。1.2 模型的乐观偏差与上下文盲区AI 改老项目还有一个天然倾向过度自信。你可以把大模型理解成一个“急于讨好你”的实习生你让它改 A它往往会把 B 和 C 也顺手改了因为它觉得这样更像“一个完整合理的解决方案”。这不是 bug而是模型训练目标的副作用——它会在给定上下文中不断寻找最连贯、最完整的补全路径。更麻烦的是上下文窗口的限制。老项目动辄几十万行代码你不可能把整个工程都塞给 AI。你只能挑相关文件给它看于是 A 文件里的改动逻辑A 文件自己看是自洽的但 B 文件里对 A 的调用方式它完全不知道。这种“局部自洽、整体失衡”的改动模式正是 AI 改老项目时最大的风险来源。我后来做了个比喻让 AI 改老项目就像让一个只拿着导航 App 的人凭直觉在一个老城区里找路。导航显示的是全局地图而他手里的只是当前街区的局部视图。你让他决定哪个路口该转弯他能做但你要是让他判断这条路往前走会不会断头他根本无从得知。1.3 “顺手重构”才是最大的敌人我观察过很多次 AI 生成的 diff其中大部分“改坏功能”的根源不在于核心改动本身而是那些顺手捎带的重构。AI 看到一个函数命名不规范会顺手改掉看到一段代码风格不一致会顺手格式化看到一个可以抽取的公共方法会顺手抽取。这些改动单拎出来每一个都是“合理”的但在老项目里它们全是定时炸弹。为什么因为老项目里的每个“看起来不太合理”的实现背后往往都有一个说不出口的原因。那个看似不规范的命名可能被反射机制字符串匹配所引用那段风格不一致的代码可能是某个历史补丁特意绕开编译器的写法那个可以抽取的公共方法可能存在循环依赖而故意内联。AI 重构的冲动越强破坏隐性契约的概率就越大。所以在我的流程里提示词中有一条死命令禁止任何与目标无关的格式化、重命名、重构、注释调整。这一条的执行严格程度直接决定了改动是否可控。2. 动手之前先立“军令状”基线、快照与范围清单2.1 独立分支是底线回滚点是生命线任何 AI 参与的代码修改第一步永远是建独立分支并且记录当前的 HEAD 提交哈希。这一步听起来基础得不能再基础但在 AI 编程的热潮里恰恰是最容易被忽略的。很多人直接在 main 分支上让 AI 改改完出了问题才发现连回退点都不干净——本地工作区里既有手动调试的改动又有 AI 生成的改动混在一起根本没法分拣。我的标准做法是从最新的主干分支切出一个新分支名字直接标注“ai-refactor-xxx”切换前确保工作区完全干净用git stash或提交临时改动记录当前主干分支的 commit hash写入分支描述里在分支上先做一个空的初始 commit作为 AI 改动前的干净基线这样做的核心目的不是为了分代码而是为了后面能快速区分“哪些改动是 AI 造成的”。如果连基线都不干净那后面所有排查、回滚、责任界定都无从谈起。2.2 用可执行快照锁定“原有功能”老项目最尴尬的现状是根本没有自动化测试。没有测试就意味着没有“原有功能”的客观定义——你只能靠人肉去点而且谁点的记性都不靠谱。所以在动 AI 之前我会先花半小时到一小时做一份“可执行的行为快照”。所谓可执行快照就是说“记录下来的行为基线必须能随时重新跑起来拿到结果”而不是“当时我肉眼看着是好的”。具体做法分三类有接口的项目用 Postman 或 Apifox 把核心接口的请求和响应全量导出。即使没有自动化测试也要把这些请求保存下来跑一遍拿到完整的响应 JSON 存为基线文件。有前端页面的老系统录制关键路径的操作录屏或者至少截图文字记录每一步的期望值。我更推荐直接写一个简单的 Playwright 脚本把主流程跑一遍截图都归到一个基线目录。有命令行/批处理的记录标准输出。改写前跑一遍命令把输出重定向到文件作为行为基线。这份快照最大的价值不是看测试通过不通过而是让“原有功能”这个概念从主观经验变成客观数据。没有这层数据AI 改完之后就算出了问题你都说不清楚问题到底从哪一步开始变坏的。顺便说一句如果项目里连编译都跑不过那这个项目根本不应该让 AI 动。之前有个朋友跟我说想让 AI 帮忙修一个老项目的编译错误我劝他先把编译环境理清楚再做他不听结果 AI 生成了一堆“看起来能编译但实际依赖缺失”的代码报错反而更多了。老项目先解决工具链问题再谈 AI 改造。2.3 范围清单先划边界再放狗范围清单是写给 AI 的更是写给你自己的。它需要精确到文件、函数、接口并且明确标注“禁止触碰区域”。我每次让 AI 动手之前会先自己过一遍业务逻辑把改动范围缩小到 3 到 5 个关键文件以内并在提示词里附上下面这种范围声明本次唯一目标是在InventoryService.queryAvailableCount中增加本地缓存逻辑允许修改文件InventoryService.java、InventoryCacheManager.java新建禁止修改文件InventoryMapper.xml、ItemStockCalculator.java、StockSyncTask.java禁止理由数据源与缓存任务存在依赖关系改前必须先确认行为接口契约保持不变方法签名、返回字段、异常类型、日志级别都不许变范围清单还有一个重要作用它给了你一个事后审查 diff 的对照表。AI 一旦越界比如偷偷改了 Mapper 文件或者加了个无关的配置参数diff 阶段一眼就能看出来。没有范围清单你会靠直觉判断“这个改动是不是合理”有了范围清单你只需要靠“在不在清单内”来判断理性和客观得多。3. 提示词层面的工程打法怎么让AI老老实实“只做分内事”3.1 别让 AI 一次干三件事拆到不可能出错为止很多人给 AI 的指令是“帮我优化一下这个模块的性能”这种模糊指令放到人身上都容易跑偏放到 AI 身上更是灾难。AI 会自己解读“优化”的含义自行决定优化哪些点最后的 diff 可能涉及十几个文件的改动核心逻辑反而被淹没。我的经验是把改动拆到函数级别。一次只给它一个函数说清楚这个函数的输入输出、性能瓶颈点、期望达到的效果。比如同样是优化库存查询我现在的指令会写成现有方法queryAvailableCount(Long skuId)每次直接从数据库查询压力较大。请在不改变方法签名、返回结构、异常行为的前提下为该方法的查询逻辑增加本地缓存。缓存 key 为 skuId过期时间 5 秒。你只需要修改这一个方法内的实现不要改动任何其他方法或文件。粒度越细AI 的上下文盲区越容易被压缩。它只需要理解这一个函数及其直接依赖就能给出相对可靠的方案。就算出了问题排查范围也局限在几十行代码内而不是几百行的 diff。3.2 把“最小修改原则”写进提示词而不是心里默念直接告诉 AI“你要清楚这是老项目”或者“要保证兼容性”其实没用大模型对这类宽泛约束的处理能力很弱。真正有效的是给出可操作的最小修改规则清单。我常用的一套规则是这样的禁止重命名任何已有变量、方法、类添加新代码时也不得与现有命名空间冲突禁止删除或改写现有注释尤其是那些带 TODO、HACK、FIXME 标记的注释禁止调整代码格式包括缩进、换行、空行如需新增代码块保持与周围代码相同的风格禁止新增第三方依赖除非我明确要求禁止把已有函数抽取为工具方法除非该函数超过 100 行且我明确要求重构禁止修改 imports 中已有的引用如需新增 import放在默认位置这些规则单个看起来都很“笨”但组合起来能有效压制 AI 的“优化冲动”。我实测下来加了这套规则之后AI 生成的 diff 体积通常会缩减 40% 以上而且“顺手改动”的概率显著降低。3.3 用“行为兼容描述”代替“实现方案指定”这个技巧是后来踩了多次坑之后才总结出来的。之前我总喜欢在提示词里告诉 AI“用 ConcurrentHashMap 加缓存”“用唯一索引去重”“用异步队列削峰”结果 AI 会很积极地按照我的方案实现但实现过程中它会自由发挥——比如它觉得ConcurrentHashMap不够好会自己换成Caffeine觉得异步队列的线程池参数“太小”会自己放大十倍。问题是它这种“自由发挥”是在不充分了解项目上下文的前提下展开的。所以后来我改为用“行为兼容描述”来约束 AI请保证新实现对调用方完全透明。调用方仍然以相同方式调用你的方法期望在相同输入下得到语义一致的结果除已说明的性能数据时效性差异外。请在实现中用注释标记出所有与旧实现有行为差异的点并在最后统一报告给我。这样一来AI 的重心从“怎么实现”转移到“如何保持兼容”它会更谨慎地处理边界情况并且在主观判断受限时把决策权交还给我。我不会要求它放弃方案设计能力——我只要求它把方案差异显式暴露出来让我来做最终判断。3.4 先让 AI 写“行为描述测试”再让 AI 改代码对于有一点测试基础的老项目这招极好用。在要求 AI 修改代码之前先让它阅读目标方法的现有实现然后生成一组“行为描述测试”——不修改任何现有代码只写一个全新的测试类尽可能覆盖现有方法的各种入参、返回值、异常路径和边界情况。这样做的价值相当大AI 写测试的过程实质上是在通读并提炼这个方法的既有行为特征。当它理解“现有实现返回 null 而不是抛异常”“负数入参会先被绝对值化”这类细节之后再让它去修改实现它的潜意识里就有了行为约束。而且这份测试本身就是行为基线的一个可执行版本改完代码直接跑这份测试就能快速发现行为偏移。等测试跑通了再让它改代码。改完之后先跑这些行为描述测试再跑原有测试套件。两层过滤之后出问题的概率会大幅下降。我自己的经验是加了“先写测试再改代码”这个环节后AI 改动的回归率至少下降了一半。4. 验证才是真门槛diff审查回归测试契约快照的三层过滤4.1 第一层逐行 diff 审查重点不是看懂而是找“多余”AI 改完代码后我从不直接跑测试第一步永远是先看 diff。但要注意看 diff 的目的不是看懂每一行改动——那是代码评审的标准流程。AI 改动的 context 审查重点只有一个找那些和任务目标没有关系的改动。我会先执行git diff --stat看改动文件列表只要出现了范围清单以外的文件立刻停下来。哪怕那个文件改得再合理也要先 revert 掉因为它意味着 AI 的上下文越界了。然后再用git diff逐块审查。重点关注三类东西删掉的行删除是比修改更危险的操作。每一行被删掉的代码都要能说清楚“为什么删了不会影响功能”新增的辅助代码比如缓存类、配置项、工具函数——这些是不是 AI 为了完善自己方案而额外设计的有没有考虑到并发、生命周期、异常清理格式调整即使我明确禁止AI 有时候还是会忍不住调整格式。这类改动虽然没有功能风险但会污染后续的 git 历史导致 blame 追踪错乱建议一并 revert这里要插一句实用技巧。用 IDE 的 diff 工具看可能更直观但对于大量文本改动我习惯先跑git diff --word-diff它会以单词粒度显示改动很多肉眼不易察的“同一段代码被 AI 重写”就能立刻暴露出来。然后再切换回git diff做逐块审查。4.2 第二层回归测试怎么选怎么跑全量跑不一定是最优解老项目的回归测试策略向来是个平衡题。全量跑最稳妥但周期太长而且很多老测试本来就是“腐烂状态”动不动就挂AI 改完之后全量一跑几十个失败你根本分不清哪些是真正被 AI 改坏的哪些是本来就红的。我的做法是分层跑精确层改动点相关的测试类如果有场景直击、反馈最快核心层业务链路上下游的关联测试比如被改 Service 被哪些 Controller 调用、这些 Controller 有没有测试冒烟层全量测试里挑出核心路径的用例快速验证“没有大面积崩坏”如果项目完全没有自动化测试那就把之前做的行为快照拿出来按范围清单逐项人工验证。注意验证的标准不是“页面能打开、接口不报错”这种模糊标准而是和快照记录字段级对齐——返回结构一致、字段类型一致、关键值域一致。我强烈建议有条件的话把行为快照里的接口请求导出成自动化测试脚本哪怕是用 Python 脚本循环调用一遍再对比 JSON 差异。这十几分钟的工作能把你从后续可能长达数小时的手工点测里彻底解放出来。4.3 第三层文档和接口契约的快照对比这一层看起来玄乎其实非常实用。老项目里最容易被 AI 改动误伤的就是那些“跨系统约定”。比如一个接口的响应字段命名、一个消息队列的 topic 格式、一个配置项的 key 命名。AI 不会主动去动它们但如果它“顺手重构”时顺带改掉了某个常量跨系统的调用方就会在毫不知情的情况下收到不兼容的数据。所以在 diff 审查之后我会额外做一次契约对比。方法是在动工之前记录下所有关键接口的响应结构或 Swagger 导出改完之后重新导出一次两版 JSON 做一次结构 diff。这里推荐用 JsonDiff 这类库它能精确到字段级告诉你“哪个字段新增了、哪个字段类型变了、哪个字段被删了”。这个第三层过滤挡住过我很多次看起来“测试通过但上线就炸”的事故。一次是 AI 在改某个老接口时把错误码从 401 换成了 403 对应的枚举映射单独看代码没有任何问题测试也全过但前端根据 401 做的全局登录跳转逻辑瞬间失效。没有契约快照对比这个问题大概率要到生产环境才被发现。5. 真改坏了怎么办一套完整的排查和回滚链路5.1 先定位别急着回滚二分法与 git blame 结合即便做了三层过滤偶尔还是会有漏网之鱼。真到了功能不对、页面报错的时刻第一反应不是回滚而是先定位是什么改动破坏了行为。因为如果是 AI 生成了几十处改动整体回滚固然保险但也意味着这几小时的 AI 辅助工作白费了而且你没弄明白“AI 是在哪个环节开始出错的”下次还会重蹈覆辙。先看故障现象然后做两个动作第一步把故障点从现象映射到具体函数。比如“库存查询返回了脏数据”立刻去查queryAvailableCount这个函数在分支上的 diff看看 AI 到底改了什么。第二步用git log -p或git blame确认这些改动是不是来自同一个 commit以及意图是什么。如果故障点和 AI 改动不是一一对应的比如故障发生在客服系统但 AI 只改了库存模块那就需要做二分定位。切换到主干分支再跑一次同样的操作确认基线是否正常然后在两个基线之间用git stash或临时注释掉 AI 改动来逐步缩小排查范围。这个“搭配”思想其实就是“保留三分猜七分看 commit”commit 的职责边界划分得越清晰定位就越快。5.2 局部回滚的两种姿势git revert 与手动还原定位到破坏性改动之后就要做局部回滚。这里有两个常用姿势视场景选择。第一种姿势git revert -n回滚但不提交。先把破坏性的 commit 或改动还原跑测试确认问题消失然后再重新提交。优点是保留了完整的回滚历史问题是如果这个破坏性提交里混着一大半有效改动回滚整条 commit 会连带把有效改动也回滚掉。第二种姿势更精细手动还原代码。用git checkout把具体某几个被改坏的文件恢复到改动前的版本然后重新应用 AI 改动中的有效部分。这个操作 essentially 是“手工挑拣”费一点功夫但能保住大部分有效成果。不管哪种姿势回滚完之后都别急着继续让 AI 跑下一步。我的习惯是先把这次回滚的原因整理成一条备注写进分支的 commit message 里并同步更新范围清单和提示词规则确保下一次让 AI 动手时它不会再次踩进同一个坑。5.3 从事故里提取教训把 AI 的“坏习惯”沉淀成规则这其实是整个流程里最容易被跳过、但价值最高的一步。一次 AI 改动导致的回归事故表面上看是代码层面的问题实质上往往是提示词层面或流程控制层面的问题。比如它改坏了 SQL那大概率是因为范围清单里没有标注“不得修改 Mapper 文件”它贸然改了公共依赖说明你忘记显式说明该类被其他模块调用的情况。每次事故之后我会做三件事把“当时如果我做了什么本可以阻止这次事故”的答案写下来对应地更新我的提示词模板和范围清单模板把这次经验同步给团队让大家共用同一套 AI 辅助编程规范这一套动作坚持下来你会发现 AI 干的坏活越来越少。不是说模型变聪明了而是你在提示词里给它画的边界越来越清晰了。AI 的能力是恒定的但你对它的控制力是持续提升的。6. 我踩过坑之后的一些体会6.1 不要无条件相信 AI 的“我改好了”这句话我说过很多次了但每次还是会有人踩坑。AI 生成代码后说“已完成优化逻辑保持不变”这句话只是一段预测文本不是测试报告。它没有真正编译过没有真正跑过测试甚至没有看到过完整的项目结构。它的“完成”是它的训练经验推测出的“大概率完成”而不是工程意义上的“验证过完成”。所以我把 AI 当结对编程的实习生用它的输出是“提案”我的验证是“决策”。提案再漂亮没有经过 diff 审查、测试验证、契约对比都不值得进入主干分支。每当我多看了几眼 AI 的改动几乎都能发现至少一处不合理的假设。6.2 给老项目动 AI先看有没有三类“禁止触碰区”经过大量尝试之后我给自己定了一条硬性 checklist只要某次 AI 改动碰触了以下三类区域我宁可自己手写也不让 AI 动核心交易链路支付、库存扣减、账户余额这类逻辑一旦出问题就是钱的事AI 的容错率完全达不到要求没有测试覆盖的全局状态老项目里由静态变量、配置文件、数据库表共同维护的全局状态AI 根本看不全改动风险极高跨系统契约边界所有被外部系统消费的接口、消息、配置项AI 没有能力评估它的“外部影响面”对这三类区域我会人为引入“重写不动”原则需要 AI 出方案的话也必须先要求 AI 输出行为清单和影响分析我确认后才允许它动一行代码。6.3 最后的实用小技巧让 AI 先写探针代码最后分享一个我最近特别喜欢用的技巧。如果某个老项目你连编译都跑不起来但又想让 AI 帮忙改造某个模块可以先让 AI 为这个模块写一套“探针”代码——不是改业务逻辑而是加一个入口或者测试类把待改造函数的输入输出都打印出来。先跑起来拿到真实行为数据再交给 AI 改造。这等于先让 AI 帮你把“隐性契约”挖出来而不是让它在黑灯瞎火里猜。这招看起来绕了个远路但实际效率比“直接把代码丢给 AI”高很多。因为探针代码本身就是行为基线AI 改完之后你也可以复用同一套探针做回归对比等于一步完成了“定义行为”和“验证行为”两个环节。我上次改造一个存量五年、无任何测试的推送模块就是靠这套探针方案把原本预期的两天工作量压缩到一下午而且全程没有回归事故。AI 改旧项目这件事真正的难点从来不在技术而在于你的流程能不能管住它的“自由发挥”。把基线定清楚、范围画明白、验证做扎实AI 完全可以成为老项目改造里效率最高的帮手。