给 AI 一张地图，而不是一本手册——AGENTS.md 内容策略完全指南

摘要

每次打开项目，AI 编码助手都是一张白纸------它不记得上次的对话，不知道这个项目用什么包管理器，也不清楚团队有哪些不成文的规矩。AGENTS.md 正是为了解决这个问题而生：它是一份放在仓库根目录的 Markdown 文件，作为被众多主流编码助手工具广泛采纳的开放约定，让 AI 每次"上班"前都能快速完成"入职培训"。

然而，很多团队在实践中发现：精心维护的 AGENTS.md 非但没有让 AI 变得更好用，反而让它越来越慢、越来越贵、越来越难以预测。问题往往不在于写得太少，而在于写得太多、写错了方向。

本文综合了来自 ETH Zurich 的实证研究与一线工程师的实践经验，系统梳理从核心概念到高级策略的完整方法论，帮助开发者避开常见陷阱，真正发挥 AGENTS.md 的潜力。

第一章：概念解析：AGENTS.md 与 LLM 的契约

它是什么

想象你刚入职一家公司，第一天坐到工位上，桌上放着一份简洁的"项目快速上手指南"：这个系统是做什么的、怎么把代码跑起来、有哪些必须遵守的规矩。有了这份指南，你不需要问遍所有同事，就能快速开始工作。

AGENTS.md 扮演的正是这个角色------只不过受众不是新来的人类工程师，而是 AI 编码助手。

它是一份放在项目仓库根目录的 Markdown 文件，充当给 AI 看的持久化项目上下文 (Persistent Project Context)。每次开启新的对话，AI 工具会自动读取它，把内容注入到发送给模型的请求中，作为对话的背景知识。

这里有一个关键点值得理解：大语言模型（LLM）不具备跨会话的持久记忆 。它不像一个真正的同事，能记住上周你们讨论过的架构决策。每次对话对它来说都是全新的开始，之前所有的上下文都已消失。因此，AGENTS.md 的本质是：把原本存在于工程师脑子里的项目知识，转化成 AI 每次都能读到的文字。

可以用一句话概括它与 README.md 的区别：README.md 是给人看的项目说明，AGENTS.md 是给 AI 看的项目指令。

从碎片化到统一标准：简短的前世今生

这一理念最早由 Anthropic 通过 Claude Code 的 CLAUDE.md 普及。想法很简单也很有效------维护好一份上下文文件，AI 的表现就会变好；AI 表现好了，开发者更愿意维护它，形成正向循环。

随后，各家 AI 编码工具纷纷跟进，却各自为政：

工具	上下文文件
Claude Code	`CLAUDE.md`
Cursor	`.cursor/rules`
GitHub Copilot	`.github/copilot-instructions.md`
Gemini CLI	`GEMINI.md`
OpenAI Codex	`AGENTS.md`
Cline	`.clinerules`

这带来了一个令人头疼的问题：团队同时使用多个 AI 工具时，需要为每种工具维护一份内容几乎相同的配置文件------改一条规则，要同步好几个地方。

2025 年 5 月，局面开始改变。Sourcegraph 旗下的 AMP 率先倡议统一标准，随后 OpenAI 注册了 agents.md 域名，提出以 AGENTS.md 作为通用格式，AMP 随即主动让步对齐。最终，AGENTS.md 成为事实标准，由 Linux Foundation 下属的 Agentic AI Foundation 负责托管。截至 2026 年初，GitHub 上已有超过 6 万个开源项目采用这一格式，Cursor、Zed、Qwen Code、Copilot 等主流工具均已支持。

Claude Code 至今仍沿用 CLAUDE.md，但内容完全通用，一条软链接即可兼容：

bash 复制代码

ln -s AGENTS.md CLAUDE.md

本文的所有最佳实践，对 AGENTS.md 和 CLAUDE.md 同样适用。

AGENTS.md 适合承载的两类内容

明确 AGENTS.md 的"职责边界"，是写好它的前提。它适合放置两类内容，多一类都不该放：

AI 理解项目全貌的必要信息：技术栈、仓库结构、核心模块、关键命令。没有这些，AI 面对一个陌生项目就像没有地图的探险者------它可以靠自己摸索，但会走很多弯路，甚至走错方向。
违反会直接导致问题的硬性规则 ：编码规约、架构约束、禁止项。这些是 AI 最容易踩坑、同时又靠自己推断不出来的地方。比如"所有异常必须通过 BusinessException 抛出"这条规则，AI 不可能从代码里自行归纳出来，但一旦不遵守，代码就会风格不一致甚至引发运行时问题。

其他内容------详细的架构文档、组件使用手册、代码风格规范------不该塞进 AGENTS.md，而应放在 docs/ 目录下，由 AGENTS.md 用链接的形式按需指向。第三章将详细介绍这套组织策略。

指令的优先级层次

AGENTS.md 是人与 Agent 之间的核心契约 ，Agent 会认真遵循其中的指示。当项目中存在多个层级的 AGENTS.md 时，Agent 按以下优先级依次采纳规则：

用户即时指令（Chat Prompt）：对话中临时输入的指令优先级最高，可以覆盖任何文件中的规则------这是给 Agent 打"临时补丁"的通道。
当前目录的 AGENTS.md：Agent 优先采纳离正在操作的文件最近的规则。
父目录的 AGENTS.md：若当前目录没有，逐级向上查找。
仓库根目录的 AGENTS.md：作为全局兜底，优先级最低，适合存放整个仓库通用的规则。

这种"就近优先"的机制，在 Monorepo（单一代码仓库管理多个项目或模块的方式）中尤为有用：根目录放全局规则，各子目录放模块专属规则，实现精准分层管理。第四章将进一步展开这一实践。

AGENTS.md 的质量，直接决定了在没有人工干预时 AI 的表现水准。写好它，是让 AI 真正融入项目工作流的第一步。

第二章：膨胀的危害：为何庞大的 AGENTS.md 会适得其反

越多越好的直觉，为何是错的

面对一个"什么都不知道"的 AI，人类的本能反应是：多写一些总比少写好，万一有用呢？于是 AGENTS.md 开始不断膨胀------每次 AI 犯错，就追加一条规则；每次新功能上线，就补充一段说明。几个月下来，文件变成了一个"规则垃圾桶"，混杂着各种时期、各种开发者添加的内容。

来自研究人员和工程实践者的证据打破了这种直觉：庞大臃肿的 AGENTS.md 不仅无益，反而有害 。这三类问题表面各异，根源却指向同一处------AGENTS.md 承载了超出其定位的内容。

问题一：成本上升，成功率反而下降

ETH Zurich 的系统性研究（arXiv:2602.11988）对多个编码 Agent 和主流 LLM 进行了实测，结论出人意料：

推理成本平均上升 20%--23%
任务成功率不升反降

很多人的第一反应是："成本增加，是因为文件太大、占用了太多上下文窗口（即模型单次能处理的最大文本量）吧？"

但实验揭示的真正机制恰恰相反。问题不在于文件占了多少空间，而在于 Agent 太认真地遵循了那些指令 。AGENTS.md 里写了"要充分测试"，Agent 就真的运行了更多测试；写了"要理解相关文件"，Agent 就真的去访问了更多文件。这些额外行为消耗了大量 Token 和时间，却没有带来相应的成果提升，任务反而因为过度复杂化而失败率上升。

用一个比喻：就像给新员工写了一份过于详尽的操作手册，他每做一步都要翻手册核对，结果花了双倍时间，却因为分心于流程而忽略了真正重要的事情。

问题二：指令衰减与行为漂移

根据工程实践者的经验性观察，即使是顶尖的 thinking 模型（即具备深度推理能力的大模型），能够可靠遵循的指令数量也大约在 150--200 条之间；能力相对较弱的模型，这一上限会显著收窄。

当指令数量超出这个范围，会出现"指令衰减"现象：模型的注意力被稀释，开始均匀地降低对所有指令的遵循质量------不是优先忽略不重要的，而是一视同仁地降低执行精度。这意味着你精心写下的关键规则，和一条无关紧要的通用建议，在 AI 眼中开始变得同等"模糊"。

更值得警惕的是行为漂移：Agent 可能确实在执行你的某些指令（比如运行了更多测试），但与此同时悄悄偏离了核心任务目标，最终产出的结果与你的预期南辕北辙。

关于问题一与问题二的关系：两者并不矛盾，描述的是同一根源在不同阶段的表现。问题一发生在指令数量仍处于"可靠遵循范围"之内------Agent 执行了过多指令，造成不必要的过度工作；问题二则发生在指令数量超出上限之后------Agent 开始均匀降低遵循质量，关键指令和冗余指令一起被稀释。这两种情况也可能在不同模型或不同任务类型上分别呈现。

问题三：过时文档污染上下文

这是三类问题中最隐蔽也最危险的一个。

项目在持续演进：文件被重命名、目录被重构、构建命令被更新。但 AGENTS.md 很可能几个月没人动过------当初写下的"认证逻辑在 src/auth/handlers.ts"早已过时，真实文件早就迁移到了别处。

对人类工程师而言，读到过时的文档顶多是皱眉一下、自己去找；但对 AI 来说，AGENTS.md 里写的就是事实，它会基于这条错误信息，满怀信心地在错误位置查找、修改，直到失败才停下来。

过时的 AGENTS.md 不只是"没用"，而是会主动误导 AI，其破坏力甚至超过没有这份文件。这就是所谓"上下文污染"------用失效的信息毒化了 AI 的判断基础。

第三章：内容策略：写什么、不写什么、怎么组织

核心判断标准：一个问题，解决所有困惑

面对"这条内容要不要写进 AGENTS.md"的疑问，不需要凭感觉------只需问自己一个问题：

如果 AI 不知道这条信息，它会写出"错误的"代码，还是只是"不够好的"代码？

前者放 AGENTS.md；后者放详细文档，AGENTS.md 中只放一个指向该文档的链接。

"错误的"意味着功能出错、构建失败、违反架构约束------这些是 AI 靠自己无法推断出来的项目特有知识；"不够好的"意味着代码风格欠佳、表述不够优雅------这类内容 AI 可以通过参考已有代码自行学习，不值得占据宝贵的指令预算。

这个标准把"精确赋能"落实成了一个可操作的日常决策，也解释了为什么一份高质量的 AGENTS.md 往往只有寥寥几项核心内容。

应该包含的核心内容

依据上述判断标准，以下三类信息几乎在任何项目中都属于"不写必出错"的范畴：

1. 项目一句话描述

清晰地定义这个项目是做什么的。这听起来简单，却至关重要------它是 AI 每一个决策的方向锚点。没有这句话，AI 面对一个模糊的需求时，可能朝着完全错误的方向大展拳脚。

2. 关键命令

如何安装依赖、如何构建、如何运行测试。其中测试命令最为关键，它是 Agent 完成"改完即验证"闭环的钥匙。没有这把钥匙，Agent 只能改完代码就停下，把验证工作留给人类------这也意味着你无法放心地让它无人值守地工作。

3. 非标准工具链

如果项目用 pnpm 而不是 npm，用 bun 而不是 node，或者用了团队内部的脚手架工具------必须明确告知。否则 AI 会按照最常见的默认选项生成命令，错误发生时它还不会意识到自己错了。

对于有更复杂背景的项目，可以谨慎地增加高级架构描述，例如"这是一个基于 Gin 框架的 Web 服务，通过中间件处理认证"------注意是架构概念，而非具体的文件目录树（文件路径会过时，架构概念则相对稳定）。

应该坚决排除的内容

以下内容看似有帮助，实则是"信噪比杀手"：

文件和目录结构

文件路径是项目中最容易变化的东西，一次重构就可能让十条路径说明全部失效。更何况，现代 AI 编码工具本就有能力自行探索仓库结构------你不需要替它们画地图，它们自己会找。一旦路径信息过时，写了比不写危害更大。

自动生成的内容

很多工具提供 /init 命令来自动生成初始的 AGENTS.md。这类文件的问题在于追求"全面覆盖"------它会把所有可能有用的通用指令一股脑堆进来，最终产出一个几百行的配置文件，信噪比极低。把自动生成的文件视为起点而非终点，删除其中对你项目并不特殊的部分，只保留真正有用的内容。

代码风格细节

"用 2 空格缩进"、"变量名用驼峰命名法"------这些应该交给 Linter 和 Formatter 来执行。原因很简单：确定性工具比 LLM 更快、更准、成本也低得多。把风格规则写进 AGENTS.md，既浪费了宝贵的指令预算，又把本该由工具保证的事情交给了不确定的 AI 来把关。

通用编程知识

LLM 已经知道如何写循环、处理 null、捕获异常。把这些写进 AGENTS.md，就像在给一位资深工程师的入职材料里写"记得给变量起名字"------不仅没有帮助，还会让他对整份材料的可信度产生怀疑。

超越极简：地图，而非手册

遵循极简原则会带来一个天然的疑问：复杂项目怎么办？ 一个拥有十几个模块、各自有详细规范的大型仓库，怎么可能只用三条内容说清楚？

答案是：AGENTS.md 本就不需要说清楚所有细节------它只需要是一张地图，而不是一本手册。

手册把所有内容写在一处，读者每次都要翻阅整本；地图告诉你各类知识"在哪里"，你需要什么就去对应的地方找。一份 200 行左右的地图式 AGENTS.md，配合 docs/ 目录下的专题文档，不仅能支撑任意复杂度的项目，还能让 AI 每次执行任务时的上下文窗口里只装载当前真正需要的内容。

具体做法：

根 AGENTS.md 只放最核心、全局适用的内容，并在适当位置用一行链接指向专题文档：
复制代码
```
For TypeScript conventions, see docs/TYPESCRIPT.md
For testing patterns, see docs/testing.md
```

专题文档按职责拆分，存放于 docs/ 目录：

复制代码

docs/
├── testing.md        # 测试规范与命令
├── architecture.md   # 分层架构与依赖规则
└── api_design.md     # 接口设计约定

根文件中的引用描述要足够具体，让 Agent 能判断该在什么场景下读哪个文档。

效果： 当 Agent 执行测试相关任务时，它会按指引加载 docs/testing.md，上下文窗口里装的是高度相关的专项知识；当它处理接口设计时，加载的是 docs/api_design.md。每次任务的"工作记忆"都保持精简和聚焦，而不是让所有信息在同一个上下文里互相干扰。

局限性： 这套方法不是万能的。它要求 Agent 具备主动读取文件的工具调用能力，并能正确判断当前任务需要查阅哪个文档。同时，专题文档与根文件面临同样的过时风险------"地图"体系的价值，建立在每一份文档都保持准确的前提上。

第四章：编写与维护：让 AGENTS.md 持续有效

内容策略解决了"写什么"的问题，但 AGENTS.md 的长期价值还取决于一个更根本的问题：它能持续保持准确和有效吗？

一份三个月前写好、此后再未碰过的 AGENTS.md，很可能已经成为第二章描述的"上下文污染源"。以下四条实践，是让这份文件保持生命力的关键。

1. 视其为代码，纳入版本控制

AGENTS.md 不是一份写完就锁进抽屉的文档，它是活的代码资产。把它提交到 Git，像对待任何一个核心模块一样对它进行 Code Review（代码审查）：

每次变更都写清楚提交信息，说明为什么增加、删除或修改某条规则------"AI 老是用 npm 而不是 pnpm，补充工具链说明"比"更新 AGENTS.md"有用得多。
当项目的技术栈、构建命令或目录结构发生变化时，把更新 AGENTS.md 列入变更清单，而不是事后才想起来。
有条件的团队可以在 CI/CD 流水线中加入简单的有效性检查------比如验证文件中引用的命令是否仍然可以执行。

2. 善用目录层级，精准分层管理

在 Monorepo（单一仓库管理多个模块或微服务的架构模式）中，层级机制能发挥最大价值：

根目录：只放对所有模块都适用的全局规则，例如统一的提交规范、通用的安全要求。
子目录：放该模块专属的规则，例如前端子目录里放 TypeScript 的特定约定，后端服务目录里放 API 设计规范。

子目录文件只补充自己独有的部分，不重复根目录已有的内容。这样根文件保持精简，各模块又得到精准指导------正是第一章描述的优先级层次机制的最佳实践场景。

3. 规则要有执行力

写进 AGENTS.md 的规则，如果缺少配套的自动化检查，AI 和人都会违反------不是因为不想遵守，而是因为没有及时的反馈。

规则的可靠程度可以按以下优先级排序：

能自动化检查的 > 写在 AGENTS.md 中的 > 口头约定的

对于架构约束类规则（如"禁止 Controller 层直接调用 Repository，必须经过 Service 层"），最好配合 lint 脚本实现机械验证。让 Agent 改完代码后可以自主运行 make lint-arch，按照错误提示修复问题，形成"改 → 检 → 修"的自动闭环，而不是依赖人工事后审查。一条有自动化检查兜底的规则，比一条只存在于文本里的规则可靠得多。

4. Bad Case 驱动迭代：从错误中成长

AGENTS.md 不是一次性写完就锁定的文档。最有效的维护方式，是让它从 AI 实际犯下的错误中持续成长：

每当 AI 犯了一个错误，先问自己：这条规则该放在哪里？

如果是全局性的架构约定或项目规约 （例如"所有 HTTP 异常统一用 BusinessException 抛出，禁止直接抛 RuntimeException"）→ 补充到根 AGENTS.md
如果是某个模块的具体开发规范 （例如某个私有组件的某个 prop 必须传特定类型）→ 补充到对应的 docs/ 专题文档，根文件只加一行链接

这种"Bad Case 驱动"的迭代方式比一开始就绞尽脑汁预测 AI 会犯什么错更精准，也更可持续------每一条新规则都来自真实的失败教训，而不是凭空猜测。随着迭代积累，AGENTS.md 会越来越准确地指向这个项目真正的"雷区"。

第五章：总结

回顾本文的完整逻辑：AGENTS.md 之所以容易失效，是因为它太容易从一张精准的"项目地图"退化成一本臃肿的"项目手册"。而每一个退化的症状------推理成本上升、指令衰减、上下文污染------都指向同一个根源：写进去的内容超出了它应当承载的边界。

本文提出的所有原则，本质上都在服务同一个目标：精确赋能------用最小的上下文成本，让 AI 获得最大的项目理解。

判断标准（第三章）是"精确赋能"的操作入口：每增加一条内容，都问"不写会错，还是只是不够好"，只有前者才值得写进来。
地图 vs. 手册框架（第三章）是"精确赋能"的组织方式：根文件精简，细节按需索引，每次对话的上下文高度聚焦于当前任务。
版本控制与 Bad Case 迭代（第四章）是"精确赋能"的持续保障：让已经写进来的内容始终准确，不断从真实的失败中补充遗漏的规则。
规则执行力（第四章）是"精确赋能"的可信度基础：一条有自动化检查兜底的规则，才是真正可以依赖的契约，而不只是一个"可能被遵守的建议"。

AGENTS.md 是一把双刃剑。草率编写会让它成为消耗资源、误导决策的"上下文毒药"；而经过精心设计和持续维护的 AGENTS.md，则是让 AI 真正融入项目工作流的核心基础设施。

精通 AGENTS.md 的艺术，本质上是学习如何与 AI 高效协作的艺术：从"把所有信息都倒给它"的直觉，转变为"只给它没有就会出错的内容，其余的给它一张地图，让它自己去找"的精确赋能思维。

参考资料

Matt Pocock. A Complete Guide to AGENTS.md . AI Hero, 2026.

https://www.aihero.dev/a-complete-guide-to-agents-md#stale-documentation-poisons-context
Kyle. Writing a good CLAUDE.md . HumanLayer Blog, 2025.

https://www.humanlayer.dev/blog/writing-a-good-claude-md
Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? ETH Zurich, arXiv:2602.11988, 2026.

https://arxiv.org/abs/2602.11988
Dr. Fabian Deitelhoff. AGENTS.md: Helpful agent briefing or token hog? heise online / iX Magazin, 2026.

https://www.heise.de/en/background/AGENTS-md-Helpful-agent-briefing-or-token-hog-11245317.html
徐靖峰. 一个文件让 AI Coding 效率翻倍：AGENTS.md 实践指南 . 个人博客, 2026.

https://www.cnkirito.moe/ai-agents-md-practise/