摘要每次打开项目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 CodeCLAUDE.mdCursor.cursor/rulesGitHub Copilot.github/copilot-instructions.mdGemini CLIGEMINI.mdOpenAI CodexAGENTS.mdCline.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但内容完全通用一条软链接即可兼容ln-sAGENTS.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.mdAgent 优先采纳离正在操作的文件最近的规则。父目录的 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-contextKyle.Writing a good CLAUDE.md. HumanLayer Blog, 2025.https://www.humanlayer.dev/blog/writing-a-good-claude-mdThibaud 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.11988Dr. 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/
给 AI 一张地图，而不是一本手册——AGENTS.md 内容策略完全指南
发布时间：2026/6/10 6:50:01
摘要每次打开项目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 CodeCLAUDE.mdCursor.cursor/rulesGitHub Copilot.github/copilot-instructions.mdGemini CLIGEMINI.mdOpenAI CodexAGENTS.mdCline.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但内容完全通用一条软链接即可兼容ln-sAGENTS.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.mdAgent 优先采纳离正在操作的文件最近的规则。父目录的 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-contextKyle.Writing a good CLAUDE.md. HumanLayer Blog, 2025.https://www.humanlayer.dev/blog/writing-a-good-claude-mdThibaud 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.11988Dr. 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/
