AI 把代码越修越乱后，我给每个脚本留了一份“重写说明书”

大量使用 AI 编程后，我有个担心：

一个脚本让 AI 反复改下去，最后会变成什么样？

会不会变成夸张的 shi 山代码？

我目前还没有遇到必须推倒重来的情况，但这种情况应该无法完全避免。

如果真到了返修很多次都搞不定的时候，继续缝缝补补，可能还不如考虑重构，直接重头开始。

于是，我想了个办法：

让所有脚本的维护与交接文档，都完整保留最初需求。

这样以后真遇到反复修都修不好的 bug，至少还有一份完整的“重写说明书”。

AI 不用只对着现有代码猜需求。

它能知道这个脚本起初要解决什么问题，后来改了什么，哪些功能必须保留，哪些办法已经试过但没用。

而且随着时间的推移，AI Agent 大模型的能力是越来越强的，成本大概率也会更低，这就很适合重写代码。

成本很低，预期的收益很高。Vibe coding 的时候，顺手让 AI 更新维护文档和需求，未来可能就拿来重写代码。

另外，我还想到一个问题：

低耦合。

功能之间绑得越紧，改一个地方就越容易牵连其他地方，牵一发而动全身。

所以维护与交接文档里，还应该写清楚：

每个模块负责什么、依赖什么、共享什么状态，哪些可以独立修改或重构。

这样遇到 shi 山代码时，就不是只有“继续修补”和“全部推倒”两个选项。

如果代码已经高度耦合，那再考虑全部推倒重来。

我把这套思路整理成一份通用规则，可以直接放进维护文档里：

【需求演进、模块边界与重构原则】

维护文档必须持续保留：

最初需求；

影响功能、流程、边界或验收标准的重要需求变更；

目前确认生效的需求；

已确认的业务边界、失败经验和验收标准。

历史内容不得直接覆盖或删除；已失效内容应标明“已废弃”或“已被替代”。

后续开发、修改和验收，以“目前确认生效的需求”为准。

代码设计和维护应尽量保持功能边界清晰、低耦合、高内聚，使单个功能可以独立定位、测试、修改或替换。

如果连续修复仍无法稳定解决问题，应停止继续叠加补丁，并按下面的流程处理：

先判断问题是否集中在边界明确的功能或模块；

可以独立替换且不会破坏其他功能时，优先局部重构；

如果代码高度耦合、整体结构已不适合当前需求，或局部重构成本接近整体重写，再考虑重新设计并整体重构。

任何重构前，都必须保留：

当前可运行版本、目前确认生效的需求、业务边界、失败经验、验收标准和必要验证材料。

【模块边界与耦合关系】

说明主要功能模块、各模块职责、相互依赖和共享状态，并标明哪些模块可以独立修改、替换或重构，哪些修改可能影响其他功能。

复杂脚本还可以附一个极简表格，至少包含：

模块或功能：

主要职责：

依赖对象：

可否独立重构：

主要风险：

总结一下，就是说最短路径不是“修不好就重写”，而是：

修复

判断模块边界

局部重构

必要时整体重构

这样既能避免无休止地打补丁，也能避免一看到 shi 山代码，就把还能用的东西全部推倒。

两种极端都很有 AI 风格，工程维护最好别学。