AGENTS.md 怎么写？给agent的README原则

开源社区里已有六万多个项目放了一份 AGENTS.md，给进场的 AI coding agent 当说明书。它的定位类似 README，但读者换了：README 写给人看，讲项目是什么、怎么上车；AGENTS.md 写给 agent 看，讲你在这个仓库里干活要守什么规矩。写得好的 AGENTS.md，能让 agent 第一次进仓库就像老熟人，命令不用猜、边界不越线、交付有验收；写得差的，洋洋洒洒几千字，agent 读完照样犯错。这篇给出写法原则：与 README 怎么分工、三要素是什么、嵌套怎么组织，以及最该避开的反例。

与 README 分工：各讲各的

分工先划清。README 面向人：项目背景、功能介绍、贡献流程，这些 agent 不需要每次都读。AGENTS.md 面向 agent：它干活时缺什么，这里就写什么——构建命令、测试命令、代码风格约定、哪些目录不要动。判断一条内容该不该放进 AGENTS.md，有个简单的筛子：agent 每次干活都会用到吗？会，就写；只是背景介绍，归 README。AGENTS.md 本质上是一份持久化的指令，指令为什么要短而具体、为什么泛泛的要求不好使，提示工程的原理是相通的，见提示工程一篇；它管的是「任务怎么干」，沙箱与审批那些运行层的事归配置文件管，分层分工见config.toml 分层一篇。

三要素：命令、边界、验收

实用主义的 AGENTS.md 通常三块就够。第一块命令：构建、测试、lint 的确切命令原样贴上，连包管理器的选择也写明——npm 还是 pnpm，agent 猜错一次就装错一遍依赖。第二块边界：哪些文件与目录不许碰（生成的代码、锁文件、部署配置），改动要避开哪些区域，格式化工具用哪个。第三块验收：改动完成后跑什么算通过——跑哪条测试命令、哪些点要人工确认。三块共用同一条写作纪律：短而具体。写「遵循项目代码风格」没用，写「Python 用 black 格式化，行宽 88」才有用；agent 执行不了形容词，只能执行命令与规则。

嵌套组织：目录各管各的

大仓库不必把所有规矩塞进根目录一份文件。AGENTS.md 支持嵌套：根目录放全局约定，子目录按需放各自专属的说明——前端目录写组件规范，后端目录写迁移流程。agent 在哪个目录里干活，就近读到哪一份，嵌套的说明补充或收窄根目录的约定。这个组织方式对应真实协作：前端组与后端组的规矩本来就不同，分开写各管各，也避免根文件越长越没人看。发现顺序、覆盖关系这些机制细节，排查篇有完整展开，见AGENTS.md 排查一篇。

反面教材：愿景文档为什么没用

最常见的失败形态是把 AGENTS.md 写成项目愿景书：项目使命、架构哲学、设计理念洋洋洒洒，唯独没有一条可执行的命令。这类文档 agent 读得再认真也用不上——它要的是「跑测试用哪条命令」，接收到的却是「我们相信简洁的力量」。另一个反例是当聊天记录堆放：临时问题的解法、过期的待办、某次任务的对话摘录，堆到后来真命令淹没在噪声里。维护纪律与内容同样重要：命令变了当天就更新文件，失效条目删掉，让每一行都值得 agent 花注意力。写完之后实际检验很直接：让 agent 在干净会话里跑一遍典型任务，看它卡在哪，卡点就是要补写的内容。拿不准措辞，可以让 DeepSeek 把草稿里的形容词全部替换成具体命令，再让豆包模拟新 agent 的视角挑出读不懂的条目，两轮下来文件就立得住。

AGENTS.md 写法速查

• 定位：写给 agent 的说明书，与写给人的 README 分工
• 筛子：每次干活都用到的才写，背景介绍归 README
• 三要素：确切命令、不许碰的边界、跑什么算通过
• 大仓库用嵌套：根目录全局约定，子目录各管各
• 反例：愿景书与聊天记录堆，短而具体是唯一纪律

AGENTS.md 写法快问快答

• AGENTS.md 越长越全越好吗？：相反。agent 的注意力有限，长文件会稀释关键条目；只留每次干活都用得到的命令与规则，其余移去 README 或文档站。
• 用中文写 AGENTS.md 可以吗？：可以，agent 对语言不敏感。但要保持条目化、命令原样可复制，命令与路径不要翻译。
• 个人偏好想生效又不想提交，怎么办？：用本地覆盖文件，不入库；团队共享的约定才写进随仓库提交的那份。