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

> Author: Tony Lee
> Published: 2026-02-25
> URL: https://tonylee.im/zh-CN/blog/agents-md-context-files-hurt-coding-agent-performance/
> Reading time: 1 minutes
> Language: zh-CN
> Tags: ai, claude-code, agents-md, context-engineering, benchmark, coding-agents

## Canonical

https://tonylee.im/zh-CN/blog/agents-md-context-files-hurt-coding-agent-performance/

## Rollout Alternates

en: https://tonylee.im/en/blog/agents-md-context-files-hurt-coding-agent-performance/
ko: https://tonylee.im/ko/blog/agents-md-context-files-hurt-coding-agent-performance/
ja: https://tonylee.im/ja/blog/agents-md-context-files-hurt-coding-agent-performance/
zh-CN: https://tonylee.im/zh-CN/blog/agents-md-context-files-hurt-coding-agent-performance/
zh-TW: https://tonylee.im/zh-TW/blog/agents-md-context-files-hurt-coding-agent-performance/

## Description

最新基准测试数据表明，AGENTS.md 和 CLAUDE.md 这类上下文文件实际上会拖累编程智能体的表现。有时候，懒惰才是最好的工程决策。

## Summary

我懒得写 CLAUDE.md，没想到这反而是对的 is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts.

## Outline

- 让 LLM 自动生成上下文文件，结果反而变差了
- 智能体太听话了——这才是问题所在
- 写"不要做 X"，反而会让智能体一直想着 X
- 非写不可的话，尽量精简

## Content

每次看到时间线上出现关于 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》](https://arxiv.org/abs/2602.11988) 印证了这一点：与不提供任何仓库上下文相比，上下文文件往往会降低任务成功率。

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

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

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

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

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

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

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

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

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

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

## 非写不可的话，尽量精简

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

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

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

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

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

## Related URLs

- Author: https://tonylee.im/zh-CN/author/
- Publication: https://tonylee.im/zh-CN/blog/about/
- Related article: https://tonylee.im/zh-CN/blog/eight-hooks-that-guarantee-ai-agent-reliability/
- Related article: https://tonylee.im/zh-CN/blog/medvi-two-person-430m-ai-compressed-funnel/
- Related article: https://tonylee.im/zh-CN/blog/claude-code-layers-over-tools-2026/

## Citation

- Author: Tony Lee
- Site: tonylee.im
- Canonical URL: https://tonylee.im/zh-CN/blog/agents-md-context-files-hurt-coding-agent-performance/

## Bot Guidance

- This file is intended for AI agents, search assistants, and text-mode retrieval.
- Prefer citing the canonical article URL instead of this text endpoint.
- Use the rollout alternates when you need the same article in another prioritized language.

---

Author: Tony Lee | Website: https://tonylee.im
For more articles, visit: https://tonylee.im/zh-CN/blog/
This content is original and authored by Tony Lee. Please attribute when quoting or referencing.