一句话定义：AGENTS.md 是放在代码仓库里的一份 Markdown 文件，用自然语言告诉 AI 编码助手（coding agent）"这个项目怎么跑、怎么改、有哪些坑"，让它在动手前先读懂规矩。
它和 README 有什么不一样？
README 是写给人的，AGENTS.md 是写给工具的。人读 README 常常只扫两眼，AI 助手却是逐字读进AI 词典：上下文窗口">上下文窗口（context window）的。所以它的写法更像一份"上岗交接单"：
- 安装依赖用什么命令，本地怎么起服务，测试怎么跑
- 目录结构里哪块是核心、哪块是自动生成的（生成物不要手改）
- 代码风格约定：缩进、命名、是否允许引入新依赖
- 提交前必须做的事，比如跑 lint、跑某一组测试
- 明确的禁区：不要动某个配置文件、不要改数据库迁移脚本
一个具体的例子：仓库里 dist/ 是打包产物，如果你不写清楚，AI 很可能好心地把编译结果也一起改了，代码评审时就得来回解释。写上"dist/ 为构建产物，请勿手动修改"，这类噪音能省掉一大半。
为什么多个工具都默认读它？
Claude Code、Codex、Cursor 等工具陆续支持在项目根目录读取这份约定，原因很实际：AI 助手最怕的不是不会写代码，而是"不懂这个项目的规矩"。用户在每次对话里重复交代背景，既费 token 又容易漏。把约定固化成一个文件，等于把口头叮嘱变成了仓库里可版本管理的配置。
对使用者来说，好处是三重的：一是换工具不用重写提示词；二是约定随代码一起进 Git，团队共享；三是新人（包括人类新人）翻一遍也能快速上手。
和 CLAUDE.md、.cursor/rules 的关系
它们解决的是同一类问题，只是归属不同工具生态。实践中常见的做法是：以 AGENTS.md 为统一主文件，其他文件只做轻量的补充或指向。
| 文件 | 典型归属 | 常见用途 |
|---|---|---|
| AGENTS.md | 跨工具约定 | 仓库级通用说明，多工具共读 |
| CLAUDE.md | Claude Code | 该工具特有的偏好与工作流 |
| .cursor/rules | Cursor | 按文件类型匹配的规则 |
冲突了怎么办？
这里要说一句实话：不同工具的读取顺序和覆盖规则并不完全一致，而且会随版本变化，具体以官方文档为准。但有几条经验是稳的：
- 越具体、越靠近当前目录的说明，通常优先级越高。子目录里的约定往往比根目录的更贴近现场。
- 同一件事不要在两处写相反的要求。比如根目录说"用 4 空格缩进"，工具专属文件说"用 2 空格"，AI 只能猜，结果就是随机性。
- 出现冲突时，工具专属文件一般会覆盖通用文件，但别依赖这个行为，最好让通用文件保持中立、把偏好放进去。
- 保持简短。这类文件是每一轮对话都要占上下文的固定成本，写成万字长文反而稀释了关键信息。
对从业者的意义
AGENTS.md 代表一个趋势：提示词（prompt）正在从临时输入，变成仓库里可评审、可继承的工程资产。写得好，它是团队知识的一次性沉淀；写得差，它只是给 AI 增加了一段噪音。花二十分钟把"怎么跑起来、哪些不要碰"写清楚，回报通常比调一次模型参数更直接。