这活儿我干过不止一次，而且每次都能在 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 完全可以成为老项目改造里效率最高的帮手。
