Agent 的默认答案是「再加一个文件」：41% 的复杂度上涨，和四条压回去的路

周三下午两点，你让 Codex 给后台加一个导出订单的功能。二十分钟后它交活：测试通过，顺手把 lint 也修了，PR 上是 6 个新文件、+840 行、-12 行。

你扫了一眼，觉得挺利索，approve。

问题在于 src/utils/ 往外数三个目录，两年前就有一个 export/csv.py，做的就是这件事，连字段映射都差不多。Agent 没见过它，也没找过它。它只是按最省事的方式把活干完了。

单看这一次，没什么关系。这样的事发生八百次之后，你的仓库会变成一个只有 agent 敢动的地方。

数字比感受更刺人#

2026 年 MSR 会议上，He 等人交了一份用双重差分设计做的研究。样本是 806 个开源仓库，把采用了 Cursor 的仓库和匹配的对照组放在一起比，结论扛住了他们做的每一轮稳健性检验。

环复杂度平均上涨 25.1%。同一份研究里，整体代码复杂度的涨幅是 41%，静态分析告警多了 30%。速度提升是真的，但只在短期，复杂度是留下来那个。

GitClear 从另一个角度看到了同一件事。他们分析了 6.23 亿次真实代码变更，对比 2022 年的基线，八项可维护性指标里没有一项是往好的方向走的。转折点很明确，AI 辅助提交占比越过 25% 之后，所有信号同时掉头。

中间那三行才是要害。不是代码总量变多了，是新写的代码几乎不跟老代码发生关系。重复率涨 81%，跨文件调用掉 35%，这两件事本来就是同一件事的两面。

Agent 做加法，不是因为懒#

三个原因，全都跟模型聪不聪明没关系。

它看不见。 272,000 token 的上下文窗口装不下一个中等规模的仓库。当它看不到三个目录之外那个已经在做同样事情的函数时，能选的只有自己写一个。这不是推理出错，是信息没到手。在一个不完整的世界观里，写新函数就是最优解。

训练只奖励生成。 模型学的是人写下来的代码，不是人删掉的代码。重构的本质是减少和组织 token，这跟训练时的梯度方向正好相反。Horikawa 等人的实证很说明问题：agent 在 26.1% 的提交里做了重构动作，但其中 78% 只是重命名变量、调整格式这类一致性修补，真到设计层面做简化的很少。

沙箱让加法更安全。 Codex 在 Linux 上用 Landlock，macOS 上用 Seatbelt 限制文件系统。在这个约束下，新建一个文件永远是安全的；改动一个已有文件则可能弄坏别的测试。一个被优化成「完成任务」的 agent，待在一个奖励安全动作的环境里，理性选择就是新开一个文件。

三条叠起来，结论不好听：加法倾向不是 bug，是它在当前约束下的最优策略。骂模型没用，得改约束。

看不见的账单：理解债#

比复杂度指标更难处理的，是 Casserini 等人提出的 agentic entropy。以 diff 为中心的 review 只能看到改了什么，看不到它为什么这么改、中间试过哪些路、跳过了哪些跨文件的影响。一个不理解「这段代码当初为什么这么分层」的 agent 去重构，产出的东西能过单测，但会在生产的边界条件下塌。

五个独立机构的研究者在 2026 年初几乎同时指向一个词：理解债。AI 生成代码的速度是开发者理解速度的 5 到 7 倍。这笔债不会出现在 velocity 看板，也不会在 sprint review 上被提出来。它出现在六到十八个月后，某个人要改一个没人敢改的模块的时候。

Substrate Collapse 那篇论文把度量这层也点破了。像 truck factor 这种指标，前提假设是「作者等于理解者」。当 agent 每天生成几千行、而署名还是你的时候，这个相关性断了。指标照样能算出数字，数字已经没有意义。

四条可以今天就上的防线#

Codex CLI 提供了几个能对冲加法倾向的机制。没有一个是自动生效的，全都得主动配。

一、把结构约束写进 AGENTS.md，写成决策表#

最划算的单点干预，是明确告诉它别重复。

# AGENTS.md 结构约束
## 架构规则
- 存在等价行为的函数时，绝不新建
- 写新模块之前，先用 Grep 搜一遍已有实现
- 单函数环复杂度上限 10
- 单文件上限 300 行，超了就拆
- 优先扩展已有抽象，而不是新建一层

## 明确的反模式
- 不要把本该属于共享模块的逻辑内联
- 不要给简单函数调用套一层包装类
- 不要重复实现错误处理，统一用 src/errors/

研究上看，决策表写法的约束遵守率明显高于散文式描述。原因很直白：可验证的规则能被检查，形容词不能。

这里有个反作用力得认。我自己测过，AGENTS.md 写到 600 词以后，成功率没涨，token 账单涨了两成。结构约束应该小而硬，别顺手塞一堆背景说明进去。

二、用 PostToolUse hook 做硬闸门#

#!/bin/bash
# .codex/hooks/post-tool-use.sh
if [[ "$TOOL_NAME" == "write_file" || "$TOOL_NAME" == "apply_patch" ]]; then
    npx complexity-report --threshold 10 "$FILE_PATH"
    if [ $? -ne 0 ]; then
        echo "REJECT: File exceeds complexity threshold"
        exit 1
    fi
fi

好处是确定性，agent 再怎么解释也绕不过去。

但按单个文件跑复杂度有个明显的漏子：新建文件的复杂度天然是 0。agent 只要把逻辑摊成五个小文件，每个都不超标，总量照涨。所以闸门最好按 diff 算，至少把「本次新增文件数」和「净行数」一起卡住。只卡单文件阈值，等于在鼓励它拆得更碎。

三、给重构单开一个 profile#

Codex CLI 从 v0.143.0 起支持命名 profile，可以专门做一个只做减法的。

# ~/.codex/profiles/refactor.toml
[model]
name = "gpt-5.6-sol"
reasoning_effort = "high"

[approval]
mode = "full"   # 每一次改动都要看

[instructions]
system = """
你是重构 agent，目标是降低复杂度，不是加功能。
1. 净行数必须减少或持平
2. 除非拆分超大模块，否则不新建文件
3. 重复逻辑抽到共享函数
4. 先删死代码，再加新代码
5. 每改一次跑一遍测试
"""

用 codex --profile refactor "Reduce duplication in src/handlers/" 调用。

「净行数不增」是个很漂亮的硬约束，但它得配 mode = "full" 才有意义。没有人工过目的情况下，agent 完全可以把删掉的行挪到另一个文件里，让总数看起来漂亮，实际只是搬了个家。

四、把审计做成定时任务#

Codex App 的 automations 支持定时执行，可以挂一个每周的复杂度巡检：

codex exec --profile refactor \
  "分析代码库里的重复逻辑、未使用的 import、以及复杂度超过 10 的函数。
   把报告写到 docs/complexity-audit.md，并修复影响最大的三个问题。"

Ambrosino 在播客里把这个叫「过夜的垃圾回收」。听着很美，但要注意它和白天干活的是同一个模型，带着同样的加法倾向。这类任务的产出必须人工过一遍，尤其是那些「顺手修一下」的部分。

度量也得换#

老指标在 agent 密集的仓库里基本失效。换成这四个更直接：

• 重复率：重复出现的代码块占比，应该往下走
• 跨文件调用密度：每千行代码里的跨模块调用数，应该往上走
• 理解半衰期：新人从入职到第一次有把握地改动要多久，应该保持稳定
• 返工比：写完两周内被改动的行数占比，应该压在 15% 以下

前两个是结构信号，后两个是人跟不跟得上的信号。四个一起看，比单看行数增长有意义得多。

最后#

这些防线都绕不开一个根因：现在的模型在架构上偏向生成，不擅长缩减。除非训练目标改掉，让「删五十行换成一个十行的抽象」和「新写五十行」拿到同样的奖励，复杂度上涨就还是默认轨迹。

配置层面能做的其实有限。真正的结论是一句更难执行的话：省下来的每一个小时，至少要拿出十五分钟看结构。

加法是 agent 的默认答案，减法只能由人来下命令。四十一个百分点不是命定的，那是把 agent 当无人监督的贡献者、而不是当需要人在结构上掌舵的工具，要付的价钱。

参考来源

• He 等，Speed at the Cost of Quality: How Cursor AI Increases Short-Term Velocity and Long-Term Complexity（MSR 2026）
• GitClear，The Maintainability Gap: 2026 AI Code Quality Research
• Horikawa 等，Agentic Refactoring: An Empirical Study of AI Coding Agents（arXiv:2511.04824）
• Casserini 等，Beyond the “Diff”: Addressing Agentic Entropy in Agentic Software Development（arXiv:2604.16323）
• The Substrate Collapse（arXiv:2606.20882）
• 原文：Complexity Creep: Why AI Coding Agents Add More Than They Simplify，codex.danielvaughan.com