如果AGENTS.md气味难闻，你的代码将无法达到预期

编码代理的配置文件（如AGENTS.md或CLAUDE.md）旨在为AI编码代理提供行为指导，但错误的配置可能导致性能下降和资源浪费。近日，巴西米纳斯吉拉斯联邦大学的研究人员对532,000个文件进行了大规模分析，从中提取了100个热门开源项目，这些项目均包含AGENTS.md或CLAUDE.md配置文件。研究发现了六种常见的配置“坏味道”，其影响范围非常广泛。

在所有检测的配置文件中，Lint泄漏是最普遍的问题，出现在62%的文件中。Lint泄漏指的是代理指令重复了已经由linter或静态分析工具自动执行的规则，例如代码格式检查或语法错误检测。这种重复不仅浪费了模型的上下文窗口，还增加了不必要的token消耗，因为模型已经通过工具可靠地处理了这些任务。

上下文膨胀是第二大常见问题，影响了42%的配置文件。开发者往往过度指定代理的行为，导致文件内容超出Anthropic建议的200行限制。冗长的配置文件不仅增加token消耗和成本，还会稀释核心指令的可见性，使模型更难以聚焦于关键任务。技能泄漏出现在35%的文件中，表现为将不常用的工具或实践直接加入主配置文件，而理想的做法是将这些内容放入单独的SKILLS.md文件中，仅在需要时加载。技能泄漏不必要地扩展了代理的上下文，并可能分散其对主要任务的注意力。

此外，研究还识别出其他三种坏味道：盲引用（配置文件通过URL引用外部文档但未说明何时相关）、初始化僵化（项目初始化时设置的配置细节已不再适用）以及冲突指令（代理指令之间存在矛盾）。研究论文指出，在100个测试项目中，至少有91个存在至少一种上述配置坏味道。这些发现表明，开发者迫切需要工具和目录来帮助识别和避免配置问题。

与此相呼应的是，苏黎世联邦理工学院（ETH Zurich）数月前的一项研究也揭示了类似结论。他们发现，开发者手动编写的上下文文件仅能将代码性能提升约4%，却显著增加了成本；而AI自动生成的上下文文件甚至对代码质量产生了约3%的负面影响。两项研究共同指向一个核心原则：对于编码代理的配置文件而言，少即是多。有时，甚至不提供任何配置文件，仅让代理依靠其默认行为，反而可能是更优的选择。