AGENTS.md 是放在代码仓库根目录的一个 Markdown 文件，内容是写给 AI 编程 Agent 看的项目说明：怎么装依赖、怎么跑测试、代码风格是什么、哪些目录不要碰、提交信息按什么格式写。
它常被形容成「给 Agent 的 README」。README 是写给人看的——项目是做什么的、怎么参与贡献；AGENTS.md 装的是 Agent 干活时需要、但放进 README 会显得啰嗦的那些细节。
先用一句话抓住它
AGENTS.md 就是新同事入职文档，只不过读它的是 AI。
想想一个熟练但对你项目一无所知的外包工程师。他技术没问题，但不知道你们用 pnpm 不用 npm、不知道提交前要跑 lint、不知道 legacy/ 目录已经废弃、不知道所有日期字段都用 UTC。这些事你不写下来，他每次都会踩一遍。AGENTS.md 就是把这份「本项目的规矩」写在一个固定位置，让每次开工的 Agent 都能先读一遍。
它的由来和现状
这个文件最早是各家工具各起各的名字：有的叫 CLAUDE.md，有的叫 .cursorrules，有的叫别的。结果是同一个仓库里躺着好几个内容高度重复的文件。
2025 年 8 月，由 OpenAI 牵头，Google、Cursor、Factory 等参与，把它规范成一个开放格式 AGENTS.md；2025 年 12 月，该规范被捐赠给 Linux 基金会下属的 Agentic AI Foundation 进行中立治理。到目前为止已有超过六万个开源项目在用，二十多种 AI 编程工具支持读取。
需要注意的是并非所有工具都统一了：Claude Code 仍默认读 CLAUDE.md，实践中常见的处理是做一个符号链接指向 AGENTS.md，让两边共用同一份内容。
写什么、怎么写
格式上没有强制约束——就是普通 Markdown，标题随便起，Agent 直接读文本。实践中比较有用的内容包括：
环境与命令：包管理器是哪个、怎么装依赖、开发服务器怎么起、测试怎么跑、构建命令是什么。这一块收益最高，因为 Agent 猜错命令的代价是一连串失败的尝试。
项目结构：各目录职责，哪些是生成产物不要手改，哪些是废弃代码。
代码约定：语言和框架版本、命名规范、什么情况下允许引入新依赖、注释和文档的要求。
不要做什么：这一条常被低估，但往往最有用——不要改哪些文件、不要提交什么、不要自动升级依赖、不要在没跑测试时说完成了。
验证方式：怎么算改完了。能自动验证的步骤写清楚，Agent 就能自己判断而不是交给你。
作用范围规则：在 monorepo 里可以每个包放一份，离被修改文件最近的那份生效。用户在对话里当场给的指令优先级高于文件内容。
和相邻概念的区别
和 Agent Skills 的区别：AGENTS.md 说的是「这个项目是怎么回事」，每次都读；Skills 说的是「某项能力该怎么做」，按需加载。前者是项目上下文，后者是可复用能力。
和规格驱动开发的关系：SDD 里的「宪法」——项目级长期规则——通常就落在 AGENTS.md 里。规格描述这一次要做什么，AGENTS.md 描述做任何事都要遵守什么。
和智能体记忆的关系：它是最简单也最普及的一种记忆实现——文件式记忆。不需要向量库、不需要额外服务，还能用 Git 做版本管理和代码评审。代价是不会自动筛选，写多了会挤占上下文窗口。
和提示词的区别：提示词是一次性的、口头的；AGENTS.md 是持久的、进仓库的、团队共享的。一个人纠正过的约定写进去，其他人的 Agent 也能受益。
容易误解的地方
「越详细越好」——这是最常见的错误。文件每次都会被完整读进上下文，写成几千行就等于每次任务都先花掉一大块窗口预算，还会稀释真正关键的几条规则。控制在一两屏内，把「必须遵守」和「参考信息」分开，后者只留链接。
「写了 Agent 就一定照做」——它是上下文，不是强制约束。真正需要保证的规则应该同时有机器保障：lint、类型检查、CI、pre-commit 钩子。文件负责表达意图，工具负责兜底。
「写完就不用管了」——项目在变，规则也要跟着变。过期的命令和废弃的约定比没有更糟，因为 Agent 会认真执行错误的指示。把它当成活文档，在评审里一起看。
「这是 AI 工具厂商的私有格式」——AGENTS.md 是开放规范，且已进入中立基金会治理，不绑定单一厂商。
值不值得写
只要你在用 AI 编程工具做超过一次性的改动，就值得。这是投入产出比最高的上下文工程动作之一：一次半小时的整理，能省掉后续几十次「不对，我们用的是 pnpm」的往返。
起手建议先写三件事——怎么跑起来、怎么验证、什么不能碰。这三条覆盖了 Agent 最容易翻车的地方。等实际用一段时间，把每次纠正它的那句话补进去，文件会自然长成你项目真正需要的样子。