停止为 AGENTS.md 使用 /init
核心要点：正确的思维模型是将 AGENTS.md 视为你尚未修复的代码库问题的动态清单，而不是永久配置。自动生成的 AGENTS.md 文件会损害代理性能并使成本膨胀 20% 以上，因为它们重复了代理已经可以发现的内容。人工编写的文件只有在包含不可发现的信息时才有帮助——工具陷阱、非显而易见的约定、地雷。其他每一行都是噪音。
在采用 AI 编码代理的开发者中，有一个几乎已成为普遍现象的仪式。你设置一个新仓库，运行 /init，看着代理扫描你的代码库，然后得到一个闪亮的 AGENTS.md。它描述了你的目录结构、技术栈、测试约定。你浏览一遍，看起来合理，然后提交它。你觉得自己做了负责任的事情。你的代理已经配置好了。
2026 年初发表的两篇论文表明，你可能刚刚让你的代理变得更慢、更昂贵，而且并不更准确。而且其影响远不止是否包含代码库概述。
除了放什么内容之外，还有一个值得早期提出的结构性问题：在仓库根目录放置单个 AGENTS.md 对于任何真正复杂的代码库都是不够的。你真正需要的是 AGENTS.md 文件的层次结构——放置在相关的目录或模块级别——自动维护，以便每个代理获得精确范围限定到它正在工作的代码的上下文，而不是一个混淆整个项目关注点的单体文件。
研究实际上说了什么
Lulla 等人（ICSE JAWs 2026）进行了一个干净的配对实验：124 个真实的 GitHub pull request，在有和没有 AGENTS.md 文件的情况下执行，其他一切保持不变。相同的任务、相同的仓库快照、相同的代理。他们发现，AGENTS.md 文件的存在使中位挂钟运行时间减少了 28.64%，输出令牌消耗减少了 16.58%。统计上显著。代理变得更便宜、更快。
这听起来像是明显的胜利。先记住这一点。
苏黎世联邦理工学院的一项独立研究在 SWE-bench 和一个已经有开发者编写的上下文文件的仓库的自定义基准上测试了四个代理。他们的发现恰恰相反：LLM 生成的上下文文件使任务成功率降低了 2-3%，同时使成本增加了 20% 以上。开发者编写的文件使成功率提高了约 4%——但也使成本增加了高达 19%。
那么到底是哪种情况？AGENTS.md 是有帮助还是有害？
两者都有，取决于你放什么内容。而这实际上是更有趣的结果。
苏黎世联邦理工学院的论文发现了一些重新定义整个辩论的东西：当他们从仓库中剥离所有文档——README、docs 文件夹、markdown 文件——然后用 LLM 生成的上下文文件进行测试时，这些文件突然使性能提高了 2.7%。自动生成的内容并非无用。它是冗余的。代理无论如何都可以通过阅读仓库找到所有这些内容。给它同样的信息两次，你只是增加了噪音。
相比之下，Lulla 论文使用的是来自开发者实际一直在维护的仓库的人工编写的 AGENTS.md 文件。真正的项目特定知识。非显而易见的工具要求。实际的陷阱。这就是节省代理时间的上下文，因为它不必推断它无法发现的东西。
问题不在于是否要有 AGENTS.md。问题在于什么值得在其中占一行。
粉红大象问题
AGENTS.md 文件有一个更微妙的成本，它不会出现在效率指标中：锚定效应。
如果你的 AGENTS.md 提到你在后端使用 tRPC——即使只是在架构概述中顺便提到——模型现在在每个提示中都有 tRPC 的上下文。如果 tRPC 只在少数遗留端点中使用，而所有新内容都在其他东西上运行，你刚刚将你的代理偏向了当前代码库的错误模式。你说了它，它在那里，而 LLM 不会区分"这是我们过去做的"和"这是你应该做的"。
这就是为什么提示工程智慧一直说要小心你在系统提示中放什么。你添加的每一样东西都与实际任务竞争。关于 LLM 上下文的更广泛研究显示了一个一致的模式——更多的上下文通常会降低性能，不仅通过成本，还通过稀释注意力。Liu 等人的"Lost in the Middle"结果（2024）显示 LLM 在处理放置在长上下文中间的信息时会遇到困难。Levy 等人显示，即使内容完全相关，更长的上下文也会降低任务性能。AGENTS.md 中的每一行都是与你实际要求代理做的事情竞争的一行。
反对 /init 的理由
这是自动生成的上下文文件的核心问题。/init 产生什么？代码库概述。目录结构。技术栈描述。模块解释。苏黎世联邦理工学院的论文发现，Sonnet 4.5 的自动生成上下文文件中 100% 包含代码库概述。GPT-5.2 的 99% 也是如此。
这些恰恰是代理可以通过列出目录和阅读你现有的 README 自己发现的东西——无论 AGENTS.md 是否存在，它都会这样做。所以你添加了一个代理阅读的文件，然后去通过阅读你的实际代码来确认，现在必须协调两个真相来源。更多的推理令牌。更多的步骤。相同的结果，只是更慢、更昂贵。
什么真正值得占一行
苏黎世联邦理工学院的论文显示了关于什么有效的具体内容。当开发者编写的上下文文件提到 uv 时，代理平均每个任务使用它 1.6 次。当没有提到时，代理使用它少于 0.01 次。其他仓库特定工具也保持相同的模式：提到时每个任务使用 2.5 次，而没有提到时少于 0.05 次。
uv 与 pip 是一个完美的例子，说明什么属于 AGENTS.md。它是：
- 无法从代码库中通过推断发现
- 操作上重要（它改变了代理运行的命令）
- 代理无法通过约定正确猜测
将其与"这个项目使用 monorepo 结构，包在 /packages 中"进行比较——这是代理在运行的第一个目录列表中找到的东西。其中一个值得占一行。另一个是噪音。
实用的过滤器很简单：代理可以通过阅读你的代码自己发现这个吗？如果是，删除它。每一行都应该代表仓库中尚不存在的信息。
这意味着你的 AGENTS.md 应该看起来更像：
- 使用
uv进行包管理 - 始终使用
--no-cache运行测试，否则你会从 fixture 设置中得到误报 - auth 模块使用自定义中间件模式；不要重构为标准 Express 中间件
legacy/目录已弃用，但被三个生产模块导入——不要删除其中的任何内容
几乎没有其他内容。
静态文件问题
即使你编写了一个紧凑、非冗余的 AGENTS.md，它也有一个结构性弱点：它是静态的，但任务是动态的。
你的文件说"提交前始终运行测试套件"。代理正在做文档更改。它忠实地运行完整的测试套件。令牌被消耗，分钟被浪费，在一个对代码更改有意义但对这个更改没有意义的指令上。
这不是一个假设的失败模式。它被烘焙到架构中。扁平的指令集无法根据正在运行的任务类型进行条件判断。一个处理 CSS 重构的代理不需要你的数据库迁移警告。一个实现安全修复的代理可能应该跳过性能优化提示。单个单体文件每次都以相同的方式加载。
ACE 框架（Agentic Context Engineering，ICLR 2026）通过将上下文视为通过生成器/反射器/策展器管道演化的剧本，而不是静态文件，直接解决了这个问题。在代理基准测试中，它比静态方法的性能高出 12.3%。架构很重要。
人们尚未构建的更好架构
AGENTS.md 讨论中的几个人独立地大致收敛到相同的想法：正确的结构不是单体文件，而是按需加载焦点上下文的路由层。
结构看起来像这样：
第 1 层：协议文件（AGENTS.md 实际上应该是什么）不是代码库概述。不是风格指南。是路由文档。可用的角色以及何时调用它们。可用的技能以及它们涵盖什么任务类别。可用的 MCP 连接以及它们的用途。代理真正无法发现的最小必要仓库事实——没有其他内容。
第 2 层：焦点角色/技能文件根据任务类型有选择地加载。一个专注于 UX 的代理处理组件架构时加载的上下文与调试数据管道的后端代理不同。两者都不加载对方的上下文。任何给定任务的总上下文保持有界。
第 3 层：维护子代理其唯一工作是随着代码库的演变保持协议文件的准确性。因为这是没有人谈论的事情：文档会腐烂。苏黎世联邦理工学院的研究使用了新生成的上下文文件，仍然发现性能下降。六个月没有触及的真实世界 AGENTS.md 文件——描述你已经替换的依赖项、已经改变的目录结构——将会更糟。糟糕得多。
主要的编码代理都没有公开生命周期钩子来使这种架构易于构建。你可以用子代理和范围上下文来近似它，但还没有干净的解决方案。这是一个等待填补的工具空白。
自动优化角度
这个领域最具挑衅性的发现来自 Arize AI 的提示学习工作。他们没有手动编写 CLAUDE.md 指令，而是使用了自动优化循环——在训练任务上运行代理，评估输出，生成关于解决方案为何失败的 LLM 反馈，使用元提示来完善指令。重复。
结果：在跨仓库测试拆分上准确性提高了 +5.19%。在仓库内拆分上提高了 +10.87%（在过去的 Django 问题上训练，在未来的问题上测试）。
优化器发现的是令人不安的含义：帮助人类理解代码库的东西和帮助 LLM 导航它的东西通常是不同的。对你来说似乎明显有用的指令——"这个服务使用仓库模式"——对模型来说可能是噪音。而模型实际需要的东西——某个特定的导入路径消歧、某个非显而易见的文件命名约定——可能永远不会出现在你的脑海中写下来，因为你已经内化了它。
AGENTS.md 的手动方法假设你知道代理需要什么。经验证据表明你可能不知道。优化器找出你认为重要的东西和实际推动针的东西之间的差异。
这并不意味着你应该放弃编写上下文文件——自动优化研究仍处于早期阶段，5% 是有意义的但不是变革性的。这意味着你应该松散地持有你关于包含什么的直觉，并且可能应该测试它们。
AGENTS.md 的正确心态
将 AGENTS.md 视为你尚未修复的摩擦的动态文档。
你添加的每一行都是关于代码库中某些东西足够令人困惑以至于会绊倒 AI 代理的信号——这意味着它可能也足够令人困惑以至于会绊倒新的人类贡献者。对该信号的正确响应不是增长上下文文件。而是修复实际问题。
代理一直把新的实用程序放在错误的目录中？也许目录结构令人困惑，应该重新组织。代理一直伸手去拿已弃用的依赖项？也许导入结构使错误的依赖项太容易抓取。代理忘记运行类型检查？也许构建管道应该自动捕获它，而不是依赖散文指令。
AGENTS.md 成为诊断工具而不是永久配置。你添加一行，你调查为什么代理一直犯这个错误，你修复底层的东西，然后你可能可以删除这一行。
一个值得尝试的技术：几乎空着开始你的 AGENTS.md，并添加一个指令："如果你在这个项目中遇到令人惊讶或令人困惑的东西，将其标记为评论。"代理提出的大多数添加不是你想永久保留的东西——它们是代码库不清楚的地方的指标。修复那些。保持文件最小。
研究没有解决的问题
两篇论文都有值得提出的真正局限性。
Lulla 论文根本不测量正确性——只测量效率。你不能从中得出 AGENTS.md 提高输出质量的结论。作者对此很清楚：他们进行了健全性检查以确认代理产生了非平凡的输出，但完整的正确性评估是未来的工作。更快、更便宜是有意义的，但如果代码是错误的就不是。
苏黎世联邦理工学院的论文使用了新的上下文文件，这对于实验控制来说是理想的，但可以说测试了大多数开发者实际上并不生活在其中的场景。真实世界的情况是上下文文件已经在仓库中存在了几个月并且部分过时。这应该比论文测量的表现更差。
两篇论文都没有测试多个从业者认为是正确架构的分层、动态加载方法。"扁平单体上下文文件"是唯一被评估的东西。具有选择性上下文加载的适当分层系统是否表现不同仍然是一个开放的经验问题。
还有模型轨迹问题：每隔几个月，开发者报告他们的上下文文件中需要的东西越来越少，因为底层模型在代码库导航方面变得更好。六个月前必不可少的指令随着模型的改进而变得冗余。你今天编写的 AGENTS.md 到下个季度可能是纯粹的开销。
实用要点
停止运行 /init。自动生成的输出与你现有的文档冗余，并且在没有好处的情况下增加了开销，除非你的仓库真的零文档——在这种情况下，它比什么都没有稍微好一点。
在向 AGENTS.md 添加任何行之前，问：代理可以通过阅读代码找到这个吗？如果是，不要写它。
当代理反复与某事斗争时，在将其视为上下文问题之前将其视为代码库问题。重构代码。添加 linter 规则。改进测试覆盖率。只有在你用尽这些选项后才伸手去拿 AGENTS.md。
如果你在 CI/CD 或自动审查管道中大规模运行代理，来自上下文文件的 15-20% 成本开销会在数千次运行中复合。在假设权衡值得之前计算它。
考虑构建一个维护代理，其工作是保持上下文文件准确，而不是让它腐烂。
并且松散地持有你关于代理需要什么的直觉。对你来说似乎明显有用的东西对模型来说可能是噪音。经验证据表明，我们认为代理需要什么和实际帮助它们的东西之间的差距是巨大的——而且可能不是我们期望的方向。
像新员工一样入职你的编码代理的本能——给它办公室参观，解释组织结构图，带它了解架构——来自一个合理的地方。但编码代理不是新员工。它们可以在你完成输入提示之前 grep 整个代码库。它们需要的不是地图。它们需要知道地雷在哪里。
也许，越来越多地，它们甚至不需要那个。
如果你对视频感兴趣，Theo 对这个主题的看法也很出色。
Matt Pocock 的也是：