整洁代码：为AI节省token成本

660次Claude Code实验表明：整洁代码虽未提升通过率，但可减少7-8%的token消耗，并降低34%的文件重访次数。

许多人借助AI编写代码后，会产生一个疑问：

既然代码主要供智能体阅读，整洁代码是否仍具重要性？

过去我们强调代码清晰，是因为人类需要维护。函数不宜过长，命名需准确，模块边界要清晰，重复逻辑应提取。这些规则均为适应人类工作记忆而设。

但若未来主要由Claude Code、Codex、Cursor等智能体在代码库中读取文件、修改代码、运行测试，是否可适当放宽要求？

只要测试通过，代码稍显凌乱，机器也不会抱怨。

SonarSource的一篇新论文给出了一个颇具启发性的答案：

整洁代码未必使智能体更易完成任务，但能减少其绕行路径。

该论文题为《Does Code Cleanliness Affect Coding Agents? A Controlled Minimal-Pair Study》。

作者完成了一项颇具难度的工作：并非简单对比两个真实项目，因为真实项目间差异众多，难以判断是代码质量还是业务复杂度、架构、依赖、测试覆盖影响了智能体。

他们构建了6组“最小对照代码库”。

每组中，两侧代码库的架构、依赖、外部行为及测试目标尽量一致，主要区别在于代码整洁度：静态分析问题数量、认知复杂度、命名、函数拆分、结构清晰度。

随后设计了33个编码任务，让Claude Code在这些代码库上执行。

总计运行了660次。

关键在于：他们并非探究“哪个模型更强”或“哪个提示更优”。

他们固定了智能体和任务，仅改变代码库本身。

这更贴近我们日常真正关心的问题：

同一AI编程工具，面对整洁代码与凌乱代码，表现是否不同？

最直接的结果是：通过率无明显变化。

换言之，在此实验中，代码更整洁并未使Claude Code更易成功完成任务。

论文中的总体通过率差异为-0.9个百分点。此数据不足以支撑“整洁代码显著提升智能体成功率”的观点。

若仅看此结果，易得出一个偷懒结论：

代码质量已不再重要。

但真正有价值的结果紧随其后。

整洁代码降低了智能体的“运营成本”。

最关键的指标是文件重访。

文件重访指智能体已读取或修改某文件后，又反复打开它。

这类似于人类开发者在复杂代码中迷失方向：刚看完某个函数，跳至另一模块，片刻后又返回确认；修改一处后，又怀疑前面是否有遗漏；越不确定，越反复查看。

论文显示，在整洁代码中，Claude Code的文件重访次数减少了约三分之一。

这并非“更聪明”，而是“更少迷路”。

这一点至关重要。

许多人评价AI编程工具时，仅关注最终代码能否运行、测试能否通过、基准分数高低。

但智能体工作流的成本不仅体现在结果上。

它还包括：

• 读取了多少文件

• 反复读取了多少文件

• 消耗了多少输入token

• 生成了多少输出token

• 花费了多少轮对话才着手操作

• 修改了多少行

• 需要人类审查多久

对个人用户而言，这些成本可能表现为Claude Code配额更快耗尽、上下文更快变长、等待时间更长。

对团队而言，这会转化为更直接的金钱支出：更多token、更多推理时间、更多CI和审查成本。

因此，“通过率未变”不等于“代码质量无用”。

它仅说明：在此任务中，Claude Code足够强大，即便是凌乱代码也能勉强完成。

但它完成得更为费力。

论文中将整洁代码定义得十分朴素：可读性强、认知复杂度低、命名清晰、辅助函数拆分合理。

这些听起来仍是老生常谈。

但在智能体工作流中，它们有了新的意义。

清晰的函数名，是grep和搜索的路标。

短小的函数，是上下文窗口中易于消化的单元。

模块边界，是智能体判断“该改何处、不该碰何处”的地图。

低认知复杂度，是减少反复确认的保障。

这与人类维护代码的逻辑相似。区别仅在于，以前你是在帮同事节省脑力；现在你也在帮智能体节省token。

一个500行的庞大函数，人类读起来痛苦，智能体也不一定舒适。它或许能修改，但会读取更多上下文，来回确认更多次。

一个命名准确、职责清晰的函数，不仅“看起来优雅”。它能让智能体更快定位到需修改之处。

这篇论文的数据不可滥用。

第一，实验仅运行了Claude Code，模型为Claude Sonnet 4.6。作者未测试GPT、Gemini或其他框架。

第二，任务主要基于Python和Java代码库。结果能否推广至前端、移动端、嵌入式或大型单体系统，仍需更多实验验证。

第三，论文以token作为成本代理，但不等于可直接换算为美元。实际费用还取决于模型价格、缓存、队列、供应商计费规则。

第四，他们仅观察最终隐藏测试是否通过，未检查智能体是否破坏了项目中其他原有测试。

第五，他们未进一步扫描智能体最终生成的代码是否也更整洁。

因此更准确的结论并非：

“整洁代码使AI编程成功率更高。”

而是：

在此实验中，整洁代码让Claude Code用更少token、更少反复阅读，完成了大致相同的任务。

此结论已足够实用。

若你已在认真使用AI智能体编写代码，代码质量不应降级为审美问题。

它应转化为成本问题。

过去团队进行重构时，常难以解释投资回报率。因为收益是“以后更好维护”，听起来很虚。

但智能体工作流提供了一个新口径：

凌乱代码会导致智能体多读、多猜、多绕路、多消耗token。

整洁代码虽不使模型更聪明，但能让模型少浪费。

更实际的做法并非大规模重写，而是从几个方面入手：

1. 将超长函数拆分为有名称的小步骤。

2. 为业务概念赋予稳定、准确的名称，避免同一事物有多个称呼。

3. 减少无意义的缩写，便于搜索定位。

4. 为跨模块流程提供简短说明，尤其是权限、状态机、计费、异步任务。

5. 保持测试和入口命令清晰，使智能体能自行验证。

这些内容以前是为人类准备的。

现在也是为智能体准备的。

AI编程时代存在一个诱惑：既然机器能读，代码便可随意一些。

这篇论文提醒我们，事实可能恰恰相反。

智能体并非魔法。

它读取代码、搜索文件、建立假设、尝试修改、再回头确认。其许多行为，与一名新加入项目的工程师相似。

项目越混乱，它越容易来回翻查。

项目越清晰，它越少走弯路。

未来代码的读者不仅包括不耐烦的人类同事，还包括一个很昂贵、很勤奋、但会迷路的智能体。

整洁代码的价值并未消失。

只是账单以另一种形式呈现。