我懒得写 CLAUDE.md，没想到这反而是对的

每次看到时间线上出现关于 CLAUDE.md 或 AGENTS.md 的帖子，我都告诉自己”回头再弄”，然后划过去了。看着别人精心搭建各种 AGENTS.md 配置，我心里多少有点虚——是不是落后了？

直到最近一批基准测试数据出来，这种焦虑一扫而空。原来我的懒，恰恰是一种相当理性的工程判断。

让 LLM 自动生成上下文文件，结果反而变差了

“给智能体更多背景信息，肯定有帮助吧？“我之前也是这么想的。

但研究者在 SWE-bench Lite 上测试 LLM 自动生成的上下文文件时，任务成功率下降了 0.5%；在 AgentBench 上又跌了 2%。就算是人工精心编写的文件，提升幅度也只有 4%。我把这个现象叫做”上下文过拟合”。

• LLM 生成上下文后，SWE-bench Lite 成功率下降 0.5%
• AgentBench 上再跌 2%
• 推理成本上涨 20–23%
• 只有在完全没有任何文档的仓库中，才观察到 2.7% 的正向效果

Gloaguen 等人发表的论文 《Evaluating AGENTS.md》 印证了这一点：与不提供任何仓库上下文相比，上下文文件往往会降低任务成功率。

智能体太听话了——这才是问题所在

问题不在于智能体忽视你的指令，恰恰相反。

你在上下文文件里写一行”请使用 uv”，它就会在每一次操作中都先安装、再运行 uv，哪怕完全用不上，也会多走这一圈流程。

使用 GPT-5.2 的测试中，有上下文文件时推理 token 用量增加了 14–22%。智能体忙着遵守指令，反而分散了解决问题本身的注意力。

• 多余的 pytest 执行次数明显增加
• grep 和文件读取工具的调用范围远超实际需要

写”不要做 X”，反而会让智能体一直想着 X

我在之前的文章里聊过 SKILL.md 的内容在特定时机才会被读取，AGENTS.md 也有类似的问题。

它所在的位置处于”开发者消息”层，夹在系统提示词和用户提示词之间。这个位置对智能体的推理方式有很强的约束力。

你写”不要改这个文件”，智能体反而会额外多想一次那个文件。研究者把这称为”粉象效应”——你让人”别想粉色大象”，他脑子里浮现的第一个画面就是粉色大象。

• 优先级顺序：提供商指令 → 系统提示词 → AGENTS.md → 用户提示词
• 人工维护的文件很难跟上代码变化的节奏，信息很快就会过时

非写不可的话，尽量精简

如果你的仓库真的完全没有任何文档，上下文文件是有帮助的——数据显示在这种情况下有 2.7% 的正向效果。但如果要写，篇幅一定要控制住。

一行说明仓库特有的构建工具用法。 一行纠正智能体反复踩坑的模式。

加一条类似”发现结构异常时立即上报”的指令，智能体就变成了专门汇报代码库问题的工具。除此之外，把代码结构本身整理得更直观，远比写一堆说明更有效。

• 强化单元测试和类型检查，比写上下文文件更管用
• 如果文件位置让人困惑，直接移文件，别写说明

写出一份优秀的上下文文件，未必是技术能力的体现。真正的本事在于理解上下文文件的工作机制，并围绕它设计出更高层次的元系统。而有时候，“懒得写”，本身就是最好的工程决策。