ENZOMEGA.
Clipping 微信公众号

别再自动生成 CLAUDE.md 了，最新论文把真相讲透了

by j5land 原文 ↗
Created: 2026-06-18
#公众号文章

公众号名称：阿南的技术手记

作者名称：j5land

发布时间：2026-06-18 10:49

很多团队都给代码仓库加一个 AGENTS.md 或者 CLAUDE.md

那它通常是描述项目结构、怎么装依赖、怎么测试、代码风格以及哪些目录什么模块

不管是从直觉上还是从官方文档描述上，都觉得应该是很有用的

现在AI 编程助手经常缺上下文，那我们就把上下文写清楚，写个它，让它少猜一点

但在今年2月份的一篇论文给了一个反直觉的答案：

上下文的文件确实会改变 agent 的行为，但不一定会让它更容易的完成任务

《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》

论文的原文地址：https://arxiv.org/abs/2602.11988

研究对象就是 AGENTS.md、CLAUDE.md 这类仓库级上下文文件是否对Coding Agents有帮助

整篇看完后的观点：

CLAUDE.md 我们很容易把它写成另一份 README，它应该是一份很短的工程约束

unsetunset实验内容unsetunset

对于仓库级上下文文件，真的能提升 coding agent 解决真实工程任务的成功率吗？

作者搭了两套 benchmark来进行测试，分别是：

数据集规模作用
SWE-BENCH LITE300 个任务测 LLM 自动生成 context file 在热门仓库中的效果
AGENTBENCH138 个任务测开发者真实 context file 在较新/小众仓库中的效果

其中 AGENTBENCH 是作者新构造的数据集，它来自 12 个真实 GitHub 仓库

这些仓库本身就带有开发者写的 AGENTS.md 或 CLAUDE.md

作者从 PR 和 issue 中抽取任务，再生成和校验回归测试，最终得到 138 个实例

实验内容设置也相对清晰：

NONE：不提供任何上下文文件

LLM：使用 agent 推荐方式自动生成上下文文件方式

HUMAN：使用仓库开发者真实提交的上下文文件

被测对象包括：Claude Code + Sonnet 4.5、Codex + GPT-5.2、Qwen Code + Qwen3-30B-Coder

主要指标是：success rate，也就是 agent 生成 补丁内容 之后，测试是否全部通过

另外还统计了Agent的步骤数、推理成本、工具调用、搜索文件次数、测试次数 和 reasoning token情况

unsetunset自动生成的 CLAUDE.md 不太行unsetunset

LLM 自动生成的 context file 在 8 个主要设置中，有 5 个降低了任务的成功率

自动生成md平均值：

  • 在 SWE-BENCH LITE 上，平均成功率下降约 0.5%

  • 在 AGENTBENCH 上，平均成功率下降约 2%

同时，在平均步骤数分别增加了 2.45 步和 3.92 步，在推理成本分别增加了 20% 和 23%

也就是说，自动生成的上下文文件不但没有稳定提效，反而让 Agent 做了更多事，花了更多的token，成功率还略降低

Human 参与写的表现稍好一点，在 AGENTBENCH 上平均带来约 4% 成功率提升，并且整体优于 LLM 生成版本

当然，这个收益也不是免费的， 就是同样会增加步agent骤数和一定成本

论文中里给出的平均步骤增量是 3.34 步，成本最高增加 19%

每多给 agent 一条规则，它就多背一份判断负担

unsetunsetAgent 非常遵守命令unsetunset

在案例中 AGENTS.md 没有提升成功率，实验首先怀疑是：是不是 agent 根本没看，没按我设置的规则来执行

其中trace 分析给了相反答案：agent 会遵守，而且遵守得非常明显

在有 context md 之后，agent 更频繁地进行 搜索代码、读取更多文件、运行更多测试验证

行为被 context file 提及时未被提及时
uv使用次数平均 1.6 次/实例低于 0.01 次/实例
仓库特定工具平均 2.5 次/实例低于 0.05 次/实例

在trace统计数据来看，发现agent确实是会认真执行文件里的指令

如果你的md文件里写太多看起来正确的建议，自然agent会认真的遵循，思考与执行，比如你写的目录它会去看，或者多跑一组测试与验证等等

另外也统计了 reasoning token 情况

LLM 生成 context file 后

  • 在 SWE-BENCH LITE 上，GPT-5.2 reasoning token 增加 22%，GPT-5.1 Mini 增加 14%

  • 在 AGENTBENCH 上，GPT-5.2 增加 14%，GPT-5.1 Mini 增加 10%

就像给一位工程师交代任务时，额外的塞给他十条需要注意的事项

它自然会更谨慎一条条核对，当然也会更慢。 如果这些注意事项都是关键约束条件，那非常值得

如果只是重复常识的复述，在代码里面能获取到的，那就是上下文的噪音

unsetunset仓库上下文没想象中有用unsetunset

很多 AGENTS.md 或者 CLAUDE.md 会写项目结构，比如：

- src/: core implementation
- tests/: unit tests
- docs/: documentation
- scripts/: helper scripts

看起来能帮助 agent 更快找到相关文件与内容

在文中也专门测试了这个指标：agent 第一次触达原始 PR patch 中的相关文件，需要多少步

结论是：context file 并没有明显缩短这个过程

在GPT-5.1 Mini ，相对若的模型，在有 context file 时反而变慢

通过手工检查 trace 后发现，它会多次寻找并阅读上下文文件，即使这些内容已经被放进上下文

这说明一个现实问题：对于现代 coding agent 来说，仓库概览等信息可能并不是稀缺信息

它本来就会 ls、rg、读文件、看测试，你把目录树再讲一遍

真正重要的不是信息，而是这个目录为什么不能改等约束信息

unsetunset自动生成文件为什么容易没用unsetunset

论文还有一个非常关键的消融实验。

作者先生成 context file，然后删除仓库中的所有文档类材料，包括 .md 文件、示例代码和 docs/ 目录，再评估 agent。

结果反而变了：

在没有其他文档时，LLM 生成 context file 平均提升 2.7%，甚至优于开发者写的 context file。

这个结果解释了一个看似矛盾的现象：

  • 为什么论文主实验里，自动生成 AGENTS.md 没什么用？

  • 为什么很多开发者又觉得“加了 AGENTS.md 后效果变好了”？

答案可能是：

如果仓库本来文档很差，自动生成的 context file 确实能补一点文档缺口；

但如果仓库已经有 README、docs、examples，它往往只是把已有文档压缩复述一遍；

这时它的边际价值很低，甚至会制造额外负担

所以，自动生成 AGENTS.md 最大的问题不是不好，而是不能太像一份二手 README。

unsetunsetAGENTS.md 应该怎么写unsetunset

我的理解是，AGENTS.md 的定位应该要从项目介绍改成工程约束

不要写：README摘要、目录结构介绍、大段的项目背景、宽泛的编码原则；

这些话多数没错，但不够稀缺。agent 要么已经知道，要么可以自己发现。

案例：

类型示例
强制工具链必须用 uv sync，不要用 pip install -r requirements.txt
测试入口后端用 uv run pytest tests/api，前端用 pnpm test --filter web
生成文件规则不要手改 src/generated/，改 schema 后执行 codegen
迁移规则migration 必须用 alembic revision --autogenerate
完成前检查先跑 focused test，再跑相关 package test

一个相对合理的AGENTS.md

# AGENTS.md

## Required commands
- Install dependencies with `uv sync`.
- Run focused tests with `uv run pytest path/to/test.py -q`.
- Run package tests with `uv run pytest tests/ -q`.
- Format with `uv run ruff format`.

## Repository-specific rules
- Do not edit files under `src/generated/`; update schemas and run `uv run codegen`.
- Database migrations must be created with `uv run alembic revision --autogenerate`.
- Use `pnpm` for frontend packages. Do not use `npm install`.

## Known pitfalls
- Integration tests require `TEST_DATABASE_URL`.
- Snapshot files must be updated with `UPDATE_SNAPSHOTS=1`.

## Before finishing
- Run the smallest failing/relevant test first.
- Then run the package-level test suite touched by the change.

文件内容不长，但每一条都在试图降低真实场景的错误概率

unsetunset论文边界unsetunset

本篇论文证据链不错，但页不能过度解读

首先，它研究的Python语言的仓库，在前端、移动端，可能会有不同的结果，会存在局限性

其次，每个agent 或者 model 只进行了一次采样，会存在运行结果的随机性

最后，论文主要观测的指标是通过率，没有评估代码质量、架构一致性以及长期可维护等其他指标

但是还是有初步的结论与解读：不要写大而全的AGENTS.md / CLAUDE.md，而是要写能让模型减少犯错的内容

unsetunset最后：上下文是有成本的unsetunset

虽然AI 编程工具越来越强，模型上下文窗口越来越大

但工程里的上下文不是免费的，模型注意力会分散

会影响 agent 的搜索路径、工具选择、测试策略、推理长度

好的上下文会减少错误，差的上下文会制造犹豫

所以，AGENTS.md 的正确定位不是“让 agent 更懂整个项目”，而是：告诉 agent 那些它自己很难安全推断、但做错代价很高的少量规则

Context engineering 的核心不是堆上下文，而是筛上下文。

如果这篇文章对你有帮助，欢迎关注、点赞、转发

参考资料

[1] Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? Preprint, 2026-02-13.

内容效果不满意？点此反馈

输入关键词开始搜索