AGENTS.md 越写越长，AI 越来越傻，记我踩过的 15 个坑

公告：“业余草”微信公众号提供免费CSDN下载服务(只下Java资源)，关注业余草微信公众号，添加作者微信：xttblog2，发送下载链接帮助你免费下载！
本博客日IP超过2000，PV 3000 左右，急需赞助商。
极客时间所有课程通过我的二维码购买后返现24元微信红包，请加博主新的微信号：xttblog2，之前的微信号好友位已满，备注：返现
受密码保护的文章请关注“业余草”公众号，回复关键字“0”获得密码
所有面试题(java、前端、数据库、springboot等)一网打尽，请关注文末小程序
视频教程免费领

【腾讯云】1核2G5M轻量应用服务器50元首年，高性价比，助您轻松上云

最近看到一位知名的技术老总转发了一篇文章，说学了一个 AGENTS.md，这个好啊。readme.md 是给人读的，AGENTS.md 是给 AI 读的。然后在评论区贴了一个他做的 AGENTS.md。

朋友圈里的其他大佬也看到了，当即指出说，AGENTS.md 是目录不是百科全书，只放索引就够了。要是乱七八糟的都放进 AGENTS.md 里，那该多费 token 呢。

从这里就可以看出，不少人对 AGENTS.md（以及类似的 CLAUDE.md）有非常多的误解。所以，本文就尝试着把一些的常见错误用法、误解和非最佳实践案例分享给大家，希望能够帮助到一些网友。

内容层面的误区

首先是内容层面的误区，总结下来有下面 3 点。

写成百科全书

写成“百科全书”而非“目录”，这是一个最典型的案例。有的人写出了几千行的超级文档，试图把所有知识都塞进去。实际上 AGENTS.md 应该是索引和地图，指向详细文档位置，而非包含所有内容本身。

文章配图参考我的公众号原文《https://mp.weixin.qq.com/s/YwxbtnSZPmrBGMxKcOsgpA》。

正如 OpenAI 官方所言：“简短准确的 AGENTS.md 比充满模糊规则的长文件更有用”。过多的描述，只会消耗你的 token，以及让你的 AI “变傻”。

过度解释基础知识

在文档里详细解释“什么是 React”、“什么是 Git”等基础概念。要知道 AI 早已经具备了这些常识，重复说明只会增加噪音。

包含 llms.txt 式的完整内容

有人把 llms.txt（包含所有页面内容的纯文本文件）直接当 AGENTS.md 用，结果 LLM 被过多上下文混淆，反而不知道哪些信息重要。

结构与管理层面的误区

接下来是结构与管理层面的误区，我也总结了 3 条。

单文件过度膨胀

当 AGENTS.md 超过 100-300 行时，token 消耗激增，且关键信息容易被淹没。

正确的做法是保持主文件简洁，将任务特定规则拆分到独立文件（如 SPEC_backend.md、SPEC_frontend.md）。

把临时提示词当成持久规则

在对话中重复输入的规则本可以写入 AGENTS.md，但用户却每次都手动输入。反过来，也有人把本该放在 AGENTS.md 的持久规则，每次都写在提示词里。

缺乏版本控制意识

不把 AGENTS.md 纳入版本控制，导致团队无法共享积累的经验。正确的做法是像.gitignore一样维护它，随时间增删条目。

也就是说好的 AGENTS.md 是可以团队共享的，整个团队都可以遵守的。

使用策略层面的误区

在使用策略层面的误区方面，我也总结了 3 条。

预防性编程思维

首先是预防性编程思维，试图在 AGENTS.md 里预先写下所有可能的规则和边界情况，防止 AI 犯错。来自老外的实践和研究表明，验证比指令更重要，投资测试套件、linter、CI 管道等基础设施，比写冗长的预防性规则更有效。

让 AI 自己生成 AGENTS.md

讽刺的是，当让 Agent 自己生成指令文件时，产生的文件往往让它们本身表现的更差。有时给 AI 的最佳上下文是更少的内容。

这可能是 2026 年最讽刺的笑话，这一招如果能通用的话，就不会有 AGENTS.md 这个文件了，直接变成指令不更简单嘛。

忽视错误驱动的迭代

AGENTS.md 应该是事后总结的产物，而非事前设计的完美文档。

当前的最佳实践是：当 AI 犯同样错误两次时，让它做回顾分析，然后更新 AGENTS.md。

上下文管理层面的误区

这一点，参考社区里的老外实践，总结了 2 条，供大家参考。

会话管理混乱

一个项目只开一个线程，导致上下文膨胀、结果质量下降
不使用 /compact 清理已解决的错误堆栈，让残留的 40+ 条失败迭代记录占用 token
任务切换时不使用 /clear 或 HANDOFF.md，让不相关的历史干扰当前任务

过度预加载文件

每次会话开始时让 AI 读取所有文件，而不是按需搜索。正确的做法是让 Agent 使用 glob 和 grep 工具按需查找，可节省超过 100,000 token。

架构设计层面的误区

单 Agent 扛所有任务

试图用一个 AGENTS.md 指导 Agent 完成所有类型的任务（前端、后端、基建等），而不是为不同任务创建专门的子 Agent 或 Skill。

这就有点像单一职责原则，不像国内一个员工兼好几个岗位，通吃所有职责。

工具过度原子化或过度聚合

极端 A：一个工具做太多事，成为“万能工具”
极端 B：把每个功能点拆成独立工具（如 ListDir、ListDirRecursive、FindByName、FindByPattern…），导致模型”选工具困难”，Schema 噪音淹没上下文

忽视 Compact Instructions

长会话压缩后，如果不明确告诉系统“哪些信息绝对不能丢”，AI 很容易“失忆”。不在 AGENTS.md 中明确标注需要保留的架构决策、已修改文件、验证状态等关键信息。

安全与权限层面的误区

这个最主要的就是不要给 AI 赋予过度权限。

给 Agent 不需要的功能（如只需读取文档却给了修改删除权限）
使用过高权限的身份访问下游系统（如用具有全部 CRUD 权限的账号只读数据）
高风险操作（如删除文件、推送到主分支）不设人工确认