别让 Agent 拆了你的老房子：祖传代码渐进式重构 5 条军规

残酷真相：Agent 对祖传代码一无所知

祖传代码最值钱的部分不在代码里。为什么这个 if 要套三层？为什么这个字段叫 status2？为什么周二晚上不能部署？答案在五年前的 git commit message 里，在离职同事的脑子里，在某次线上事故的复盘文档里——唯独不在代码里。

而 agent 恰恰只能看到代码。它看不到的东西，它会用「合理推测」填上。合理推测在绿地项目里是效率，在祖传代码里是事故。那个看起来冗余的判空，可能是三年前一次 P0 故障换来的；那段「明显可以删掉」的兼容代码，可能撑着某个大客户的旧版本。

我的核心判断：让 agent 重构祖传代码，最大的风险不是它写错代码，而是它删掉正确的代码——那些看起来多余、实则承载着血泪教训的代码。想清楚这一点，后面五条军规就都顺理成章了。

军规一：先建安全网，再让 Agent 动手

顺序不能反。安全网有三层，一层都不能少：

1. 行为基线：先让 agent 把现有系统跑起来，把关键路径的输入输出记录下来——快照、录制线上流量都行。这是你的「对照组」，重构完对不上的地方，就是出问题的地方。
2. 关键路径测试：没有测试就补。补多少？覆盖核心业务流程即可，不用追求 100%。可以让 agent 帮你写测试，但测试的断言你来定——agent 定的断言，很可能只是在给现状背书，测了等于没测。
3. 现状说明书：动手改代码之前，先让 agent 输出一份「这个模块是干什么的、依赖谁、有哪些已知坑」的文档。你审这份文档的过程，就是在把隐性知识显性化。这份文档本身，就是重构的第一笔收益。

一句话纪律：agent 的第一行代码改动，应该发生在安全网建好之后。在此之前，它只许读，不许写。只读的 agent 闯不了祸，动手的 agent 才需要被监管。

军规二：切片小到可以回滚

祖传代码重构的头号死因：一次改太多，出了问题不知道是哪一刀切错的。祖传系统的依赖关系是网状的，你以为只动了一个函数，实际抖动了三条调用链。

切片标准很具体：每个改动独立、可单独 revert、半天内能验证。一次只动一个模块、一层、一个关注点。如果一个 PR 里既有重构又有行为微调，切片就太大了，拆。

大杀器是绞杀者模式：新实现和老实现并存，用开关或路由灰度切换，观察一段时间再下掉老的。听起来笨，但这是唯一一种「出问题能一键回滚」的重构。对祖传代码来说，能回滚比什么都重要——因为你永远不知道哪块石头下面压着什么。

配套纪律：每个 PR 只做一件事，PR 描述里写清楚「回滚方案」。写不出回滚方案的 PR，说明切片太大了，打回重切。

军规三：让 Agent 当考古学家，不当拆迁队

改变你给 agent 的角色设定。不要说「重构这个模块」，要说「先分析这个模块：它在什么场景被调用、改动它会影响谁、有哪些你不确定的地方」。前者是拆迁队，后者是考古学家——祖传代码需要的是后者。

强制输出三件套再动手：影响面分析 + 风险清单 + 不确定的问题列表。你拍板了，它再动手。这个顺序下，agent 的幻觉会被暴露在动手之前，而不是线上事故之后。

还有一个狠招：要求每个改动附一句「为什么这样改是安全的」。这句话是写给你看的，也是写给它自己的——逼它把推理过程显性化，幻觉最怕的就是被要求自证。说不出为什么安全的改动，就是不安全的改动。

红线：当 agent 说「这段代码看起来没用，我删掉了」——立刻叫停。删代码的决定权永远在人手里，这是重构里不可让渡的一票。

军规四：锁定行为，不锁定实现

重构的定义就一句话：不改变外部行为的前提下改善内部结构。把这句话变成验收标准：重构完成后，军规一里建的行为基线必须全部通过，一条都不能少。

对比运行是最硬的证据：同一份输入，新老实现输出一致，才算过关。嘴上说「逻辑等价」不算数，跑出来的结果一致才算数。

警惕「顺手优化」：agent 重构时最爱干的事，是顺手把业务逻辑「优化」一下——把三个 if 合并成一个，把魔法数字改掉，把「冗余」分支删掉。每一个顺手，都是在往安全网外面走。纪律：重构 PR 里出现行为变更，直接打回。想优化？另开一个 PR，走正常的需求评审流程。重构和优化是两件事，混在一起做的代价是出了问题两边都说不清。

军规五：把隐性知识写下来

重构是挖掘隐性知识最好的时机——你正在被迫读懂每一行代码。别浪费这个机会。每次踩坑，产出两样东西：一条回归测试 + 一条文档（这个坑是什么、为什么会有、以后怎么避）。测试防复发，文档防失忆。

完工时留下「墓志铭」：这个模块的已知坑清单、历史包袱清单、「不要动这里」清单。下一个人（很可能是三个月后的你自己）会感谢这份文档。祖传代码之所以可怕，不是因为它旧，是因为它沉默——没人知道它为什么长这样。

判断一次重构是否成功的标准：如果结束时文档和测试没有任何增加，那它大概率只是把代码挪了个地方，没有真正降低维护成本。变漂亮的代码不值钱，变透明的知识才值钱。

什么时候该重写而不是重构：诚实的判断框架

先说结论：重写很少是正确答案。「推倒重来」听起来解气，但你要重写的不是代码，是代码里沉淀的业务规则——而那些规则，恰恰是你还没搞懂的部分。重写最大的风险不是工作量，是你把没读懂的规则又实现错一遍。

三个可以认真考虑重写的信号，要同时满足：

• 核心业务规则已经无人能讲清，且现有测试覆盖率接近于零——这时重构的风险和重写的风险一样大，继续啃老代码没有安全溢价；
• 技术栈本身已经让招人、部署、依赖都成了问题——不是代码丑，是生态死了，留着它等于慢性失血；
• 你有能力并行跑新老两套系统做对比验证——没有这条，重写就是裸奔，99% 会死在上线那一刻。

如果三个信号没凑齐，绞杀者模式是中间道路：不重写、不硬啃，一个模块一个模块地替换。慢，但是能活着到终点。重构的终极目标从来不是代码变漂亮——是让知识从代码里搬进文档和测试里，从此可维护。做到了这一点，老房子就翻新完了，还一次都没塌过。