AGENTS.md 实战指南：让编程 Agent 真正好用

编程 Agent 每次会话都从零开始，而一个 Markdown 文件就能解决这个问题。但如果写得不对，它可能反而拖累效率——据一项研究，这类文件平均让成本上升超过 20%，却没有带来更好的结果。本文基于 YouTube 技术频道的深度解析，梳理 AGENTS.md / CLAUDE.md 的正确用法。

这个文件到底是什么

AGENTS.md 是放在代码仓库里的纯 Markdown 文件，官方站点称它为“写给 Agent 的 README”。没有强制格式，也没有 schema。OpenAI 于 2025 年 8 月发布该规范，同年 12 月移交 Linux 基金会下的 Agentic AI Foundation，与 MCP 并列。Claude Code 对同一概念有自己的命名 CLAUDE.md，Gemini CLI 则使用 GEMINI.md。

关键的心智模型是：Agent 在每次会话开始时把这个文件加载进上下文。这意味着每一行都会在每次任务中消耗 token，并与你的实际请求争夺模型注意力。Anthropic 的上下文工程文章说得很清楚——上下文是有限资源，存在边际递减。它也属于上下文，而非配置：如果某件事绝对不能发生（比如推送到 main 分支），写在 Markdown 里只是一句“请求”，应该用 hook 或权限设置来强制。

上下文工程（Context Engineering） 是 Anthropic 等模型厂商近年强调的概念，指在有限的上下文窗口内，有策略地选择和排列信息，使模型注意力集中在当前任务最相关的内容上。它区别于传统的提示词工程：后者关注单次提问的措辞，前者关注整个会话中所有进入上下文的材料——系统提示、工具定义、检索文档、历史消息以及像 AGENTS.md 这样的项目文件。核心假设是上下文窗口并非越大越好：随着 token 增多，模型对每条信息的关注度会被稀释，出现“边际递减”。因此，上下文工程的目标不是塞入更多信息，而是用最少的 token 传递最高的信息密度，并在必要时通过摘要、分层加载或按需检索来控制体积。理解这一点，就能明白为什么 AGENTS.md 的每一行都有成本，以及为什么“删减”往往比“添加”更能提升 Agent 的表现。

Hook 与权限设置 是 Claude Code 等 Agent 工具提供的强制机制，用于在模型行为之外划定硬边界。Hook 是在特定生命周期事件（如工具调用前、文件保存后、会话开始时）自动执行的脚本，可以拦截、修改或拒绝某个操作；权限设置则声明哪些命令、路径或工具无需询问即可运行、哪些必须人工确认、哪些完全禁止。与 Markdown 指令不同，这些机制不依赖模型“自觉遵守”，而是由运行时强制执行。例如，要防止 Agent 推送到 main 分支，可以在 pre-tool-use hook 中检查 git push 的目标分支并直接阻断，或在权限配置中把该命令列为拒绝。文章强调“绝对不能发生的事”应交给这类机制，正是因为 Markdown 文件只是上下文中的一句请求，模型可能忽略或在长上下文中遗忘，而 hook 和权限是确定性的。

哪些工具读哪个文件

截至 2026 年 10 月，各工具的支持情况差异明显，且变化很快：

Codex：从项目根目录读到当前文件夹的 AGENTS.md
Cursor：读取根目录及子文件夹中的 AGENTS.md
GitHub Copilot Agent：使用最近的 AGENTS.md，或根目录下单一的 CLAUDE.md / GEMINI.md；VS Code 中根目录文件默认开启，嵌套文件仍属实验性
Jules 与 Devin：同样读取该文件
Gemini CLI：默认读 GEMINI.md，但通过 context file name 设置可将 AGENTS.md 加入列表
Claude Code：自 2.1.277 版本起原生读取 AGENTS.md，但默认仅当所在目录及其上层没有 CLAUDE.md 时才生效

Jules and Devin read it too.

推荐做法是让 AGENTS.md 成为唯一事实来源。如果还需要 Claude 专属说明，就建一个 CLAUDE.md，首行写 @AGENTS.md 导入共享文件，再在下方追加 Claude 专属内容。这正是 Claude Code 文档建议的配置，避免维护两份会逐渐漂移的副本。

该写什么：命令、约定、坑

文件内容应聚焦三类信息。

命令。写清楚安装、运行单个测试文件、lint 的确切命令，而不只是完整测试套件。Agent 在每个任务中会多次自查，给它快的那条。Claude Code 最佳实践把“Agent 猜不到的 bash 命令”列为第一优先项。

约定。只写项目偏离显而易见默认值的地方，比如用 httpx 而非 requests，或某个文件夹里一个文件一个 router。Agent 无法预知这些，它会照搬互联网上最常见的模式。

坑。那些让上一位新人栽跟头的事：测试前必须先启动数据库、迁移文件由工具生成不可手改、某个遗留目录谁都不该碰。

Tests need the database running first.

这与研究结论吻合：Agent 能很好地遵循文件中的指令，作者由此得出结论——这类文件适合用来描述非标准实践。换句话说，写下你的仓库“令人意外”之处，而不是每个仓库都成立的通识。

非标准实践（Non-standard Practices） 在这里指一个仓库中偏离主流默认做法的约定。模型在训练中见过大量开源代码，会倾向于复制互联网上最常见的模式：Python 项目默认用 requests、React 项目默认用某种目录结构、测试默认跑完整套件。当你的项目有意选择不同做法时——比如用 httpx 替代 requests、要求每个文件夹一个 router、迁移文件只能由工具生成——模型无法从通识中推断出来，只能靠显式说明。研究结论之所以强调这类文件“适合描述非标准实践”，是因为标准实践本就在模型的知识范围内，写下来只是重复消耗 token；而非标准实践是模型猜不到的，写下来才能改变行为。判断一条内容是否值得写，可以问：这是否是任何同类仓库都成立的通识？如果是，删掉；如果只对当前仓库成立且反直觉，保留。

更该删掉什么

省略比添加更重要。四类内容应果断砍掉：

仓库导览。逐目录解释看似贴心，但 Agent 自己就能列文件。研究发现，仓库概览虽流行且被模型厂商推荐，实际并无帮助。
读代码就能知道的东西。框架、语言、逐文件描述——Claude Code 文档明确要求排除。
泛泛建议。“写干净的代码”“遵循最佳实践”只耗 token，不改变行为。
工具已强制的规则。格式化器能修的就不用解释，给命令即可。切记绝不放密钥或 token，文件会提交进仓库并被所有工具读取。

关于生成文件：Claude Code 的 init 命令会扫描仓库写出初稿，这是不错的起点，但研究中“无改善”的结论对生成文件和开发者手写文件同样成立。把初稿当作待裁剪的素材，而非成品。

That is a fine starting point, but in the study, the lack of improvement held for both generated files and files written by developers.

保持简短：200 行与 32KB 的硬边界

Claude Code 文档建议每个文件控制在 200 行以内，因为更长的文件消耗更多上下文、降低遵循度。其最佳实践页给出的裁剪测试很实用：对每一行问自己——删掉它会不会让 Agent 犯错？不会就删。文档还指出，如果 Agent 反复无视某条规则，多半是文件太长，规则被淹没了。

部分工具有硬限制：Codex 在指令文件合计达 32KB 后停止添加，Devin 只读取每个文件开头的 16KB，之后的内容 Agent 永远看不到。

维护方式要像对待代码：在 PR 中审阅变更，代码改了就把对应行删掉。我的规则是——Agent 犯同一个错两次之后才加一行。一次可能是噪声，两次才值得一句话。添加时连原因一起写，比如“永不手改迁移文件，因为它们是生成的”，带原因的规则在未预料的情形下更站得住。

Monorepo 与嵌套文件

根目录一个文件覆盖不了所有情况：前端用 pnpm，计费服务有关于资金的规则。把全局成立的内容放根文件，包专属的命令与坑放进该包内的 AGENTS.md。官方约定很简单——离被编辑代码最近的文件优先。

Your billing service has rules about money.

各工具实现不一：Codex 合并从根到当前目录的所有文件，后者覆盖前者；Copilot Agent 用最近的那个；Claude Code 启动时加载工作目录上层的文件，读到子文件夹内容时按需加载该层文件，且发现的内容是合并而非替换。一个实用推论是：别在嵌套文件里与根文件自相矛盾，否则模型可能两者都看到，被迫二选一。在嵌套文件里要具体，而非唱反调。若想按文件类型而非目录划分规则，Claude Code 有 rules 文件夹可标注适用路径，Copilot 有带 apply to 模式的 instructions 文件。

嵌套指令文件的加载与优先级 是 monorepo 场景下的关键机制，不同工具实现差异较大，理解其模型有助于避免规则冲突。常见策略有三种：其一是“合并覆盖”，如 Codex 从仓库根目录逐层读到当前目录，后读到的文件覆盖先前的同名规则；其二是“最近优先”，如 GitHub Copilot Agent 只采用距离被编辑文件最近的那一个文件；其三是“分层合并”，如 Claude Code 在启动时加载工作目录上层的文件，当 Agent 读到子文件夹内容时再按需加载该层文件，且发现的内容是合并而非替换。这些差异意味着同一条规则放在根文件还是嵌套文件，效果可能完全不同。实用推论是：根文件只放全局成立的内容，嵌套文件写包专属的具体命令和坑；不要在嵌套文件里直接否定根文件的规则，而应写得更具体，否则模型可能同时看到两条矛盾指令，被迫二选一，行为变得不可预测。

完整配方与安全提醒

综合起来：用 AGENTS.md 作唯一事实来源，加一个导入它的 CLAUDE.md；填入命令、非默认约定与坑；删掉导览、显而易见和泛泛之谈；保持在 200 行内并像代码一样修剪。想验证效果，可以仿照研究者的做法做小规模测试——给 Agent 同样的几个真实任务，对比有无该文件时的结果与 token 消耗。

最后一条警告：克隆来的仓库里的 AGENTS.md，是一套你的 Agent 会遵循的指令。在把 Agent 指向不受信任的仓库之前，先读一读它。