停止使用 /init 生成 AGENTS.md
内容
在采用 AI 编程智能代理的开发者中，几乎普遍存在一种仪式。你设置一个新的存储库（repo），运行 /init，观察智能代理扫描你的代码库，然后获得一个漂亮的 AGENTS.md 文件。它描述了你的目录结构、技术栈和测试约定。你浏览它，觉得还不错，然后提交。你觉得自己做了负责任的事情。你的智能代理已配置。
两篇发表于 2026 年初的论文表明，你可能刚刚让你的智能代理变慢、变贵，但准确性并没有提高。影响远不止于此，还关乎到是否包含代码库概述。
除了应该包含什么内容之外，还有一个结构性问题值得早期提出：存储库根目录下的单个 AGENTS.md 文件对于任何具有真正复杂性的代码库都不够用。你实际上需要一个 AGENTS.md 文件的层次结构，放置在相关目录或模块级别，自动维护以便每个智能代理都能获得与其工作代码相关的上下文，而不是一个混杂了整个项目关注点的庞大文件。
研究结果
Lulla 等人（ICSE JAWs 2026） 进行了一个干净的配对实验：124 个真实的 GitHub 拉取请求，在有和没有 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运行测试，否则你会从装置设置中得到假阳性 - 身份验证模块使用自定义中间件模式；不要重构为标准 Express 中间件
legacy/目录已弃用，但被三个生产模块导入 — 不要删除其中的任何内容
几乎没有什么其他内容。
静态文件问题
即使你编写了一个紧密的、非冗余的 AGENTS.md 文件，它也有一个结构上的弱点：它是静态的，而任务是动态的。
你的文件显示“始终在提交前运行测试套件。” 智能代理正在进行文档更改。它忠实地运行整个测试套件。在一个不适合的指令上，令牌被烧毁，分钟被浪费。
这不是假设性失效模式。它已内置于架构中。扁平的指令集无法根据正在运行的任务类型进行条件判断。处理 CSS 重构的智能代理不需要你的数据库迁移警告。实施安全修复的智能代理可能应该跳过性能优化提示。单个庞大的文件每次都以相同的方式加载。
ACE 框架（Agentic Context Engineering，ICLR 2026）直接解决了这个问题， 将上下文视为一个不断演变的游戏手册，通过生成器/反射器/管理器的管道进行适配，而不是静态文件。在智能代理基准测试中，它比静态方法表现更好 12.3%。架构很重要。
还未构建的更好架构
几位参与 AGENTS.md 讨论的人独立地逐渐趋同于同一个想法：正确的结构不是一个庞大的文件，而是一个分层结构，聚焦于按需加载的上下文。
结构看起来会像这样：
层 1：协议文件（AGENTS.md 应该的样子） 不是代码库概述。不是风格指南。一个路由文档。 可用的角色和何时调用它们。 可用的技能和它们涵盖的任务类别。 可用的 MCP 连接及其用途。 智能代理真正无法发现的最低限度的必要存储库事实 —— 除此之外。
层 2：聚焦的角色/技能文件 每个文件根据任务类型有选择地加载。专注于组件架构的 UX 智能代理加载的上下文与调试数据管道的后端智能代理不同。两者都不加载对方的上下文。任何给定任务的总上下文保持不变。
层 3：维护子代理 它的唯一工作是在代码库演变过程中保持协议文件的准确性。 因为有件事大家都没谈到：文档会腐烂。苏黎世联邦理工大学的研究使用了新生成的上下文文件，但仍然发现性能下降。六个月后，现实世界中的 AGENTS.md 文件 —— 描述你之后替换的依赖项、更改的目录结构 —— 将会更糟。糟得多。
第 3 层：维护子代理
其唯一任务是在代码库不断演变的过程中，保持协议文件的准确性。因为有件事大家都不愿谈论：文档会腐烂。苏黎世联邦理工学院的研究使用了新生成的上下文文件，但仍然发现性能下降。现实世界中六个月未被触及的 AGENTS.md 文件 —— 描述的是您后来已替换的依赖项或已更改的目录结构 —— 情况会更加糟糕。
目前没有主要的编码代理公开生命周期钩子，使得构建此架构变得容易。您可以使用子代理和作用域上下文来近似实现，但目前尚无干净的解决方案。那是一个待填补的工具缺口。
自动优化角度
该领域最具挑衅性的发现来自 Arize AI 的提示学习工作。他们没有手动编写 CLAUDE.md 指令，而是使用自动优化循环：运行代理执行训练任务，评估输出，生成 LLM 反馈，说明解决方案为何失败，然后使用元提示优化指令。重复这一过程。
结果：在跨仓库测试集上，准确率提高了 5.19%；在仓库内测试集（在过去的 Django 问题上训练，在未来的问题上测试）上，准确率提高了 10.87%。
优化器发现的结论令人不适：人类理解代码库的内容和 LLM 在代码库中导航的内容通常是不同的。对您来说显然有用的指令 —— “该服务使用存储库模式” —— 可能是模型不需要的噪声。而模型实际需要的 —— 某些特定的导入路径消歧义、某些非显而易见的文件命名约定 —— 您可能根本不会想到要写下来，因为您已经内化了这些知识。
手动编写 AGENTS.md 的方法假设您知道代理需要什么。但实证证据表明，您可能不知道。优化器可以找出您认为重要的内容与实际真正重要的内容之间的差异。
这并不意味着您应该放弃编写上下文文件；自动优化研究仍处于早期阶段，5% 的提升有意义但并不具有变革性。这意味着您应该对要包含的内容保持开放的态度，并可能需要对其进行测试。
AGENTS.md 的正确心态
将 AGENTS.md 视为一个待完善的文档，记录您尚未解决的摩擦。
您添加的每一行都表明代码库中存在某些令人困惑的内容，足以让 AI 代理绊倒 —— 这意味着它可能足以让新的人类贡献者也绊倒。对此正确的反应不是扩大上下文文件，而是修复实际的问题。
代理不断将新实用程序放在错误的文件夹中？也许文件夹结构令人困惑，应该重新组织。代理不断依赖已废弃的依赖项？也许导入结构使得错误的一个过于容易获取。代理忘记运行类型检查？也许构建管道应该自动捕获这一点，而不是依赖于书面指令。
AGENTS.md 成为一种诊断工具，而不是永久配置。您添加一行，调查代理为何不断犯这个错误，修复根本问题，然后可能删除这一行。
一种值得尝试的技术：首先让您的 AGENTS.md 几乎为空，然后添加单个指令：“如果您在此项目中遇到令人惊讶或困惑的事情，请将其标记为注释。” 大多数代理建议的添加内容都不是您想要永久保留的内容 —— 它们是代码库不清晰的指标。修复那些问题。保持文件简洁。
研究尚未解决的问题
这两篇论文都有值得注意的局限性。
Lulla 的论文根本没有衡量正确性 —— 只衡量效率。您无法从中得出 AGENTS.md 提高输出质量的结论。作者们很清楚这一点：他们进行了一项合理性检查，以确认代理生成了 nontrivial 的输出，但完整的正确性评估是未来的工作。更快、更便宜是有意义的，但前提是代码是正确的。
苏黎世联邦理工学院的论文使用了新鲜的上下文文件，这是理想的实验控制，但可以说这测试的是开发者们并不实际遇到的场景。现实情况是，上下文文件已经在仓库中存在了几个月，并且部分已过时。应该比论文中测量的结果更差。
两篇论文都没有测试多位从业者认为正确的架构：分层、动态加载的方法。仅评估了“扁平的整体上下文文件”。适当的分层系统通过选择性上下文加载是否具有不同的性能仍是一个开放的经验问题。
还有模型轨迹问题：每隔几个月，开发者报告说由于底层模型在代码库导航方面变得更好，他们在上下文文件中需要的内容减少了。六个月前必不可少的指令随着模型的改进而变得多余。今天您编写的 AGENTS.md 可能在下一个季度就变成纯粹的开销。
实用建议
停止运行 /init。自动生成的输出与现有的文档冗余，没有带来任何好处，除非您的仓库确实没有任何文档 —— 在这种情况下，它比没有要好一点。
在向 AGENTS.md 添加任何行之前，问问自己：代理是否可以通过阅读代码找到这个？如果可以，就不要写下来。
当代理反复纠结于某事时，在将其视为上下文问题之前，请将其视为代码库问题。重构代码。添加 linter 规则。提高测试覆盖率。在穷尽这些选项后，再考虑使用 AGENTS.md。
如果您在 CI/CD 或自动化审查管道中大规模运行代理，上下文文件的 15-20% 的成本开销会在数千次运行中累积。在假设这种权衡值得之前，请计算一下。
考虑构建一个维护代理，其任务是保持上下文文件的准确性，而不是让它腐烂。
并且要对您认为代理需要的东西保持开放的态度。您认为显然有用的东西可能是模型的噪声。实证证据表明，我们认为代理需要的东西与实际有帮助的东西之间的差距很大 —— 而且可能与我们预期的方向相反。
让您的编码代理像新员工一样 onboarding 的直觉来自于合理的出发点。但编码代理并不是新员工。它们可以在您输入提示之前 grep 整个代码库。它们需要的不是地图，而是知道哪里有地雷。
也许，而且越来越多的情况是，它们甚至不需要这些。
如果您对视频感兴趣，Theo 对这个话题的看法也很棒。
您应该删除您的 CLAUDE․md/AGENTS․md 文件。我有一项研究证明这一点。 pic.twitter.com/jOUNE53y7m — Theo - t3.gg (@theo) 2026 年 2 月 23 日