我以为代码整洁对 AI Agent 影响很大，结果 660 次测试告诉我错了

2026-07-07几个月前我在重构一个项目的代码结构——把一个大函数拆成几个小函数改掉那些反模式的命名加上类型注解。同事问我在干嘛我说「给 AI 收拾房间代码整洁了 AI Agent 修 bug 才找得对地方」。这话听起来有道理对吧整洁的代码更容易理解更容易修改——这个假设在人类开发者身上已经被验证过无数次了。但 AI Agent 不是人类它不看代码「顺不顺眼」它只看 token 序列里有没有它需要的信号。一个很自然的假设一个很反直觉的实验普林斯顿大学的几位研究者Priyansh Trivedi 等在 5 月份发了一篇 arXiv 论文标题就是《代码整洁会影响编码 Agent 吗一个受控的最小对比研究》。他们做了一个非常干净的实验设计创建代码仓库的最小对比对——两个仓库架构相同、依赖相同、外部行为相同但静态分析规则违规数量和认知复杂度不同。简单说同一套功能逻辑一套写成了「整洁版」另一套「混乱版」。然后让 Claude Code 在这些仓库上执行同样的任务看通过率有没有差异。实验包含了 6 组最小对比仓库对覆盖 33 个任务总共跑了 660 次测试。这个规模不小了。我最初看到这个设计时心里已经有答案了——整洁版肯定通过率更高。这还用测吗结果数据打了我一巴掌。通过率没变但别的地方变了核心发现只有一句话**代码整洁度不会影响 Agent 的任务通过率。** 整洁版和混乱版上Claude Code 完成任务的正确率没有统计学显著差异。看到这个结果时我其实是有点沉默的。这不是调参能解决的问题是整个假设错了。但论文没有止步于此。研究者进一步分析了 Agent 的行为指标发现了另一个维度的差异Token 消耗减少 7-8%Agent 在整洁代码上完成任务消耗的 token 更少文件回访减少 34%Agent 在整洁代码上需要的文件回溯重新打开和浏览频率大幅降低编辑序列更短Agent 在整洁代码上需要的编辑步数更少也就是说整洁代码没有让 Agent 「更聪明」但让它「更高效」。这其实符合直觉——整洁代码的命名更一致、结构更清晰Agent 的注意力机制能够更准确地定位需要修改的位置不需要反复回溯上下文。但最终它能不能正确改代码取决于它是否理解了这个 bug 的语义跟代码长什么样关系不大。我从工位走到茶水间接水脑子还在算这几个数字。34% 的文件回访减少是什么概念如果一次 Agent 会话平均需要回访 15 次文件减少 34% 就是少了 5 次。每次文件回访大约消耗 2000-4000 token5 次就是 1-2 万 token。按 Claude 的价格算每次调用能省 $0.15-$0.3。那么问题来了花时间重构代码以降低 AI Agent 的使用成本——这笔账划算吗方案的逐步放弃我是怎么从「必须重构」到「不一定」的这个发现让我重新审视了我最近的几个工程决策。第一个想到的方案——全面代码重构。把所有混乱代码重构成整洁的、符合静态分析规范的代码。这个方案我很快就放弃了。原因很简单成本太高。对一个十万行级别的项目做全量 lint 清理和重构可能需要两周的人力投入。如果收益只是 Agent 调用省 8% 的 tokenROI 完全是负数。第二个方向——只在 Agent 会频繁访问的模块做清理。既然 Agent 在整洁代码上更高效那我只把 Agent 经常修改的几个模块清干净就行。这个方案听起来更合理但问题是「Agent 会频繁访问哪些模块」这件事本身在变化。你今天认为 Agent 应该改 A 模块明天它因为上下文关联频繁跑到了 B 模块你的清理就白做了。第三个方向——不对代码做任何重构直接在 Agent prompt 里加上下文约束。如果整洁代码只是让 Agent 少回访文件那我可以直接在 prompt 里告诉 Agent「修改前先列出所有相关文件名和位置」强制它一次性读完所有需要的内容减少回访。但实验后发现这个方案的问题在于——Agent 的上下文窗口虽然大但注意力是有限的prompt 越长关键信息的信噪比越低。我在三个方案之间犹豫了好几天最后选的是第四个方案——混合策略对 Agent 经常修改的核心模块做适度的代码清理主要是命名统一和死代码删除不追求全量 lint 合规同时在 CI 里加入 Agent 行为监控跟踪每次 Agent 调用的 token 消耗和文件访问模式当某个模块的回访率异常高时才针对性地清理。不完美远不完美。最理想方案当然是先做全量代码重构再引入 Agent 辅助开发但项目排期卡在那。这个混合策略的好处是成本可控问题是你永远不知道「当前的回访率」到底是代码质量问题还是 Agent 模型的固有行为。一个不可预测的细节混乱到整洁 vs 整洁到混乱实验里有一个不可预测的细节最小对比对是双向构建的——既通过 pipeline 把混乱仓库清理成整洁仓库也把整洁仓库破坏成混乱仓库。我一开始没意识到这个设计的意义后来才想到如果只做「混乱→整洁」的方向你无法区分「效果提升是因为代码变整洁了」还是「因为有人在改代码过程中无意中修了其他问题」。双向构建消除了这个混淆变量确保唯一变化的就是代码整洁度。这个实验设计的严谨程度让我有点意外。很多类似研究只做一个方向然后得出结论「XXX 提升了 YY%」。双向对比的设计不多见。代码整洁不是给 AI 看的我现在对这件事的看法跟两个月前完全不同了。最开始我以为代码整洁是为了让 AI Agent 更聪明——它能更容易找到 bug、更容易理解逻辑、更容易做对修改。但数据告诉我Agent 的理解能力和代码整洁度没什么关系。它能理解混乱代码也能理解整洁代码。真正受影响的是效率不是正确率。换句话说我们一直以来的「代码整洁 → 更好修改」这个链条在 AI Agent 身上断在了前一半。Agent 不需要整洁代码也能正确修改但整洁代码确实让它改得更快、更省 token。这个结论反过来也有意思如果我在一个混乱的代码库上运行 Agent它的表现正确率并不比整洁库差。这意味着对于历史债务很重的项目引入 Agent 辅助开发是有价值的——你不必先花三个月重构再让 Agent 上场。后来我一直在想如果论文进一步测试了 GPT-5、DeepSeek 等其他模型结果会不会有差异Claude Code 的特定行为模式是否会影响这个结论但那是下一个实验的事了。目前至少有一个数据点对 AI 辅助开发这个场景是有参考价值的——代码整洁有用但不是你以为的那个用法。关于维基框架维基框架Wiki Framework是一套面向复杂业务场景的轻量级开发框架支持多语言、多协议、多部署形态。适用于企业级应用开发、微服务架构、云原生部署等场景。官网framewiki.comGiteegitee.com/wiki-frameworkGitHubgithub.com/wiki-framework示例项目gitee.com/cdkjframework/framewiki-example 许可证MulanPSL-2.0木兰宽松许可证第2版