连AI自己也不愿意维护自己的屎山代码

6小时前
椰子皮
4
0
0
文章

“ 连 AI 自己也不愿维护的屎山代码 用 AI 把项目从零跑到能跑,现在确实不难。难的是两三个月之后:改一个需求牵动全身,同一个工具函数在四个文件里各有一份,报错栈指向一段你毫无印象的代码。这篇不去争“AI 能不能写代码”,而是把腐化是怎么发 ”

连 AI 自己也不愿维护的屎山代码

用 AI 把项目从零跑到能跑,现在确实不难。难的是两三个月之后:改一个需求牵动全身,同一个工具函数在四个文件里各有一份,报错栈指向一段你毫无印象的代码。这篇不去争“AI 能不能写代码”,而是把腐化是怎么发生的、怎么判断自己已经中招、以及一套能落地的止血与重构顺序讲清楚——顺带回答一个问题:为什么只要换一句提示词,AI 写出来的代码质量就会明显不一样。

掘金上那个引发讨论的帖子里,作者的说法很朴素:很多时候不是 AI 写不出干净的代码,问题出在下指令的人身上——只催着它把功能赶出来,从没告诉过它,这摊代码以后也得归它管。这句话点破了整件事的关键。围绕 AI 生成代码的维护难题,市面上流传的多是“别用 AI 写生产代码”或者“多用几个 Agent 就好了”这类判断,前者没用,后者没根据。真正有价值的是把中间那段讲清楚:AI 到底是怎么把代码库一点点写烂的,以及工程上有什么可执行的解法。

屎山的诞生不需要 AI 变坏,只需要它“只看得见眼前”

要理解 AI 为什么容易制造屎山,得先理解它读代码的方式和人有本质差异。

主流 AI 编程工具基于大语言模型,本质在做下一个 token 的预测。它会读当前文件、最近的对话,甚至整个项目索引,但它不像人类工程师那样,会在脑子里先建一张架构地图。一个刚入行的实习生接到“写个新模块”的任务,通常会先把 README 翻一遍,看看有没有类似功能,再找几个相关服务了解调用关系,最后才动手。AI 不会主动这么做,除非你在提示词里明确要求它先去检索代码库。它更倾向于根据当前文件的局部上下文,直接生成一段看起来非常合理的代码。

这个差异带来的后果,可以概括成一句话:AI 很擅长判断“当前这个函数写得顺不顺”,不擅长判断“这个函数该不该存在、和全局设计是否一致”。 项目里明明已经有一个统一的金额计算工具类,AI 还是会在一段新代码里自己再写一遍金额逻辑,因为它的上下文窗口里没有那个工具类。当前需求满足了,重复逻辑却像癌细胞一样扩散。

复读机:重复的不是代码,是业务规则

一个典型的样本是折扣计算。项目里已有 DiscountService 封装了所有折扣逻辑,AI 在支付模块里又写了一份:

python 复制代码
def pay_for_user(user, amount, discount=None):
    if user.type == "vip":
        final_price = amount * 0.8
    elif user.type == "vip_plus":
        final_price = amount * 0.75
    elif user.type == "normal":
        final_price = amount
    else:
        final_price = amount
    if discount:
        final_price = final_price - discount
    return final_price

表面上逻辑通顺,仔细看三处问题叠在一起:没有复用已有的服务,折扣规则多了一个维护入口;VIP 和 VIP Plus 的折扣数值已经和原实现不一致;更糟的是它把“折扣”和“减免券”两个概念混在一起,直接在当前方法里做减法。重复代码本身不可怕,重复的业务规则才可怕——规则一旦散布在多处,改一处漏一处几乎是必然,后面接手的人还得专门为这个模块写一堆防御代码来区分两个概念。

这背后有个结构性原因:AI 在不同会话之间没有全局记忆。今天这个会话里它写过“格式化日期”,明天换个会话它不记得,于是同一个工具函数在仓库里被重写三遍、五遍。人类工程师靠记忆和代码搜索规避这件事,AI 靠的是你有没有把检索动作写进流程。

堆肥效应:一次性代码是下一层补丁的温床

比重复更隐蔽的是“一次性代码”——为应付某个具体调用点而写死的逻辑:硬编码的魔法数字、重复的 if 分支、不完整的异常处理、缺失的日志。这类代码在当下能用,但没有演化能力,需求一变就得推倒重写而不是扩展。

一个具体的例子是订单金额拆分:AI 生成的版本没处理负数、没处理小数精度、没记录拆分明细。核心逻辑看着没毛病,测试也能过,但上线后上游传过来一个负数,整个账目就乱了。边界条件恰恰是 AI 最容易忽略的地方,因为训练数据里的代码很少认真处理边界。

真正恶心的地方在后面:当后来的人——或者后续的 AI——需要在这个基础上加功能时,因为原有逻辑不可靠,他们只能再加一层 if 判断或 try-except 兜底。每一次临时补丁都成为下一层继续堆叠的温床,这就是“堆肥效应”。它不是一次写坏的,是一层层捂出来的。

勇敢的平庸:AI 默认会写出 110 行的安全代码

很多人以为 AI 会生成花哨的黑科技代码,恰恰相反,它倾向于生成平庸、啰嗦、防御过度的代码。训练数据里大量存在这种风格,模型学到的是“多说多错、少说少错”,于是拼命加默认值、加空判断、加嵌套诊断,业务逻辑被淹没在防御性泥潭里。

有人做过对照实验:让同一个工具分别用“简洁模式”和“防御模式”生成同一个函数,简洁版约 40 行,防御版 110 行,多出来的全是空值检查、异常捕获和兜底分支。如果不做约束,AI 默认会往防御模式靠。安全,但肿。每个文件都肿上一倍,整个代码库的维护成本就指数上升。而且这些防御逻辑经常和业务规则混在一起,后来者根本分不清哪些是真正的业务约束,哪些只是模型的“自保性兜底”。

再加上命名问题——tempValue、data2、result_copy 这类变量名,或者业务领域词的随意变形——代码的可检索性会迅速归零。这里值得把一件事说清楚:素材里对“风格不统一算不算技术债”其实有分歧。一种观点认为风格不统一本身不是技术债,不该一看到 AI 味的代码就喊重构;另一种观点把命名混乱列为质量崩坏的信号。两者并不矛盾,命名混乱之所以是债,不在于它不好看,而在于它让语义不可检索:AI 下次生成时找不到可复用的符号,人也没法用 grep 定位,重复实现就此获得了滋生的土壤。

一个常被忽略的细节是,这套机制最终会反噬 AI 自己。有带队试点的负责人记录过,团队引入两款主流工具(编辑器内的智能补全助手 + 能在终端跑任务的编程代理),头两个月所有人觉得真香,到第三个月代码库开始出现让人心里发毛的东西,连 AI 自己都开始看不懂它曾经生成的代码了。

先分清:是“看着乱”还是“真的在腐化”

看到风格不统一的代码就想动手,是最常见的误判。AI 的输出风格常常和你的习惯不一样,但风格差异本身并不构成技术债。真正需要动手的是下面这些信号,出现三条以上,说明代码库已经在腐化,而不只是不好看:

  • 同一个逻辑有多份实现。 日期格式化、手机号校验这类工具函数,散落在各个文件里各写一遍。
  • 改一处崩三处。 模块之间没有清晰边界,AI 为了让当前需求跑通,把上层逻辑塞进了底层函数,形成隐蔽的反向依赖。
  • 风格像百家衣。 同一个项目里既有回调又有 async/await,既有类又有纯函数——输出风格会随上下文窗口内容剧烈波动。
  • 没人能解释某段代码为什么存在。 当初是 AI 为了绕过一个报错加上的,注释写着“确保兼容性”,但没人知道兼容什么。
  • 不敢删任何东西。 缺少测试覆盖,任何删除都像拆盲盒,死代码只增不减。

判断完之后还有一步:决定要不要现在治。技术债和金融负债的逻辑是一样的,适度举债是合理的,真正致命的是从不记账、也从不还。如果只中了一两条,且项目还在快速迭代期,最划算的做法是记下来、继续推进业务。把“记账”和“还债”分开,是这套方法里最容易被跳过、也最省心的一步。

最坏的第一反应:让 AI 把烂代码重构一遍

看到一堆烂代码,本能反应是让 AI 重构。这几乎是最坏的选择。在没有测试保护的情况下让 AI 大范围改动,你会得到一份“看起来更整洁、但功能悄悄坏了”的代码,而且完全不知道是哪一步坏的——因为每一步的 diff 都长得合理。

正确的顺序是先止血。

冻结范围。 明确这次只处理哪几个文件或哪个模块,其余一律不动。给 AI 的指令里要写清边界,否则它会顺手“优化”你没让它碰的地方。

补一张测试网。 不用追求覆盖率,先针对核心链路补几个端到端测试,只要能回答“改完之后这个功能还对不对”就够了。这类测试的作用是锁住当前行为,哪怕当前行为本身并不优雅。

这里有个关键陷阱,值得单独拎出来:别让 AI 一边补测试一边改代码。 这是最常见的翻车方式——AI 发现代码有问题,顺手改了,再写一个能通过的测试。结果测试和代码一起变了,你既失去了基线,也失去了判断依据。正确做法是把措辞写死:“阅读这个文件,为它当前的实际行为补充端到端测试,不要修改任何业务代码。如果发现现有行为看起来像 bug,也照现状写进测试,并在测试旁边用注释标注疑似问题。”补测试和改业务代码,必须是两个独立提交。

锁住依赖版本。 确认 lockfile 已提交,避免重构过程中依赖悄悄升级,让你分不清故障来自自己的改动还是来自新版本。

开独立分支,保证一键回滚。 每个重构阶段单独提交,出问题直接退到上一个可用点。

给代码库建一张 AI 读得懂的地图

AI 之所以越改越乱,本质原因是它每次只看得见上下文窗口里的那一小块。你要做的是把整体结构显式写下来,让它每次动手前都能读到。这份地图不用长,但必须准确,至少包含四样东西:

  • 模块清单:每个目录、每个模块负责什么,一句话说清。
  • 依赖方向:谁可以调用谁,明确写出禁止的反向依赖,比如“数据层不得引用业务层”。
  • 关键决策记录:为什么选了这个方案、当初排除了什么,避免 AI 好心“优化”掉一个有意为之的设计。
  • 危险区域:哪些文件改动风险高、必须人工评审。

让 AI 生成初稿是可行的,但一定要人工过一遍——它会把你当前的“现状”误当成“设计意图”写进去。生成之后放进项目根目录的 AGENTS.md 或 CLAUDE.md,主流 AI 编程工具都会自动读取。

生成这份地图的过程本身就有独立价值,尤其是“扫重复实现”这一步——它是 AI 相对人类的强项。人靠记忆和印象找重复,AI 能在几分钟内跑遍整个仓库,把同一逻辑写了三遍的地方连文件带行号列出来,包括你早就忘了的那三份日期格式化函数。给它的指令可以收得很紧:通读整个仓库,输出每个顶层目录的职责、模块之间的实际依赖关系并标出不合理的反向依赖、列出发现的重复实现及其文件行号,只输出报告,不要修改任何文件。

渐进式重构:每次改动小到出错能一眼看出是哪一步

有了测试网和地图,才轮到动手。核心原则只有一条:每次改动都要小到出问题时能一眼定位。以拆解一个几百行的巨型函数为例,合理的节奏分四个阶段:

阶段 做什么 验证方式 为什么不能跳过
提取 把明显独立的片段抽成辅助函数,不改变任何逻辑 测试全绿,diff 里没有逻辑变化 先降低复杂度,后面的改动才看得清
扫引用 动任何函数之前,先搜出所有调用点 人工确认引用清单完整 AI 常常只改了定义,漏掉两三个调用方
重组 按新模块边界重新组织,一次只搬一个文件 每搬一个跑一次测试 一次搬十个文件,坏了也不知道是哪个
并行切换 新旧实现同时保留,用开关切流,观察一段时间再删旧的 线上无异常后再清理 给自己留一条不用回滚代码的退路

第二阶段的出问题频率格外高,也是 AI 重构最危险的地方。AI 修改一个函数签名时,往往只处理了当前上下文里可见的调用方,仓库另一头那两处调用就被静默漏掉了。如果那部分没有测试覆盖,问题会一直潜伏到上线。所以改签名之前,先单独让它跑一次全局引用扫描,并且人工核对结果——扫描和修改要分成两个动作,不要让 AI 在改代码的同时“顺便”找引用。

并行切换这一阶段经常被当成过度设计,其实它解决的是一个具体问题:回滚代码是有成本的,回滚开关没有。新旧实现并存、用开关控制流量、观察一段时间再清理旧的,实际上是用一点代码冗余换掉了一次潜在的线上回滚。

工具链上还有个低成本的杠杆:主流工具都提供了“先规划后执行”的模式,比如 Claude Code 里连按两次 Shift+Tab 进入计划模式,AI 只分析不改文件,先给出完整方案等你批准。重构类任务默认都该走这一步。多花五分钟审计划,能省掉后面半小时的回滚。

把共识变成机器能执行的约束,而不是文档里的道德

重构完只是回到起点。如果不改变生产方式,三个月后会再烂一次——这不是危言耸听,是那支试点团队已经验证过的曲线。美团技术团队公开过一次 31 万行代码的 AI 重构实践,其落点同样是把治理动作固化成规则,而不是靠一次大扫除。

固化这件事有个判断标准:写在文档里但没人读的规则等于没有规则;能被机器执行的约束才算数。 具体落到几层:

架构约束要能跑成检查。依赖方向写在 AGENTS.md 里是给 AI 看的,写成 import 检查脚本是给 CI 看的,后者才是硬约束。命名规范、复杂度上限、禁止的 API 调用,走 lint 和静态检查,别指望评审时靠人眼抓。

测试门槛要卡在合入路径上,而不是停在口号里。核心链路的端到端测试一旦建立,就把它设成合并的硬性条件,否则下一次“赶进度”就会绕过它。

PR 模板里加一栏:本次改动是否引入了新的重复实现、是否修改了函数签名、调用方是否已全部确认。这一栏的意义不是让人填,而是让“扫引用”这个动作在流程里有位置。

提示词层面同样要固化。把“你是这个代码库的所有者,这摊代码以后归你管”写进项目级指令,效果和只在对话里说一次完全不同——后者随会话消失,前者每次生成时都在场。这是全文开头那句话的工程化版本:不是 AI 写不出干净代码,而是没人告诉过它这摊代码归它管。你给它一个所有者的身份,它会开始考虑调用方和复用;你只给它一个“把功能做出来”的目标,它就只会把功能做出来。

代价与边界:这套流程不是免费的

必须承认,上面这套流程每一步都在拖慢交付。冻结范围意味着这一轮不顺手清理;补测试意味着先花时间锁住一个你明知不优雅的现状;一次只搬一个文件意味着重构周期被拉长数倍。对于还在找产品方向、随时可能推倒重来的项目,这些投入大概率是浪费的——那种阶段最理性的选择就是记账不还债,甚至不记账。

真正的判断点在于成本结构的变化。当“改一处崩三处”开始出现、当核心链路的改动需要预留两天做回归、当没人敢删任何一行代码时,不治的成本已经超过治的成本,这时候才该启动。反过来说,如果代码只是风格不统一、看着别扭,但改动可控、边界清楚,那它就不是屎山,只是不好看。

还有一个更深的边界:这套方法并没有消灭维护成本,它把成本从“读代码”转移到了“维护地图和约束”。模块清单会过期,依赖方向会漂移,测试网会因为业务变更而失效。地图需要定期刷新,规则需要定期校准,否则它会变成另一种形式的死代码——一份没人维护、却依然被 AI 当作事实读进去的架构文档,危害比没有更大。

最后留一个开放的问题。今天我们衡量代码质量的标准——命名是否达意、结构是否清晰、注释是否充分——基本是围绕“人读代码”建立的。但如果未来的代码库主要由 AI 来读写,“可维护”的定义可能会变:人靠命名和结构导航,AI 靠检索和上下文命中;对人的可读性,和对模型的可检索性,并不总是同一件事。也许下一代代码质量规范里,“这个复用点能否被稳定检索到”的权重要往上提,而“这个变量名是否符合人类的审美习惯”的权重会往下走。这未必是坏事,但它意味着我们此刻正在写的那些规范,可能需要重写一遍。


📚 参考来源

  1. 连AI自己也不愿意维护自己的屎山代码一句“你是代码库的所有 ... —— juejin.cn
  2. AI 写的代码怎么维护?2026 反屎山实战指南 · IMAI —— ai.cheemao.com
  3. AI编程工具如何避免代码库变成“屎山”?一线实战指南-CSDN博客 —— blog.csdn.net
  4. 屎山代码的本质:AI 时代如何避免把项目写烂 - 知乎 —— zhuanlan.zhihu.com
  5. 用 AI 写代码会破坏原有代码结构,变成难以维护的屎山代码吗? —— zhihu.com
赏
支付宝微信
0
关注公众号获取更多内容
DeepSeek 长对话限额:三条规则、三种成本与一句笼统的解释
8省份入选!6G试点来了
暂无评论,快抢沙发吧