在 AI 编码代理（Coding Agent）大范围进入开发流程之前，一个开源仓库最重要的"自我介绍"几乎只有一份文件：README.md。它承担着项目门面、快速上手教程、贡献指南等多重角色，是所有人第一次"走进"一个仓库时看到的第一页。
但最近两年，一个微妙的转变正在发生：AI 代理开始像人一样"阅读"仓库，却并不总是读 README——它们在找一份专门写给自己的文件，叫做 AGENTS.md。截至 2026 年初，已有超过 6 万个开源项目在仓库根目录放置了这份文件，Claude Code、OpenAI Codex CLI、Cursor、GitHub Copilot、Devin、Gemini CLI、Windsurf、Aider 等主流工具都原生支持它，使它成为事实上的通用 AI 代理指令格式。
于是问题来了：既然有了 README.md，为什么还需要 AGENTS.md？两者到底有什么区别，又该如何配合使用？
README.md：项目的门面，写给人类
README.md 是一个项目最直观的入口。GitHub 会把仓库根目录下的 README.md 自动渲染成 HTML，作为仓库首页展示——它既是项目的"落地页"，也是文档的入口，更是留给访问者的第一印象。
它的目标读者是人：用户、贡献者、潜在的协作者，甚至是面试时浏览你仓库的雇主。因此，一份好的 README 通常在极短的时间内回答四个核心问题：
一份高质量的 README 并不需要写成小说，而应该结构清晰、可快速扫读。业界普遍推荐的最小结构包括：项目名称、一句话简介、安装说明和基本用法——这四样东西足以让一个陌生人在两分钟内理解并跑起来你的项目。
常见的 README 失败方式也很一致：信息过多、没有安装说明、示例代码过时、满屏文字缺少排版，以及没有许可证。说到底，README 的作用是"吸引人留下来使用和参与"，它偏科普、引导和说明，不具备强制性约束。
AGENTS.md：AI 代理的"员工手册"
与 README 面向人不同，AGENTS.md 面向的是 AI 编码代理。它的定位可以用一句话概括：AI 代理的 README——一个专为代理准备的、可预测的、存放项目上下文和指令的位置。
为什么要单独拆出来？官方的解释很直接：README 里的快速开始、项目简介和贡献指南是给人看的，而 AGENTS.md 存放的是那些"对人无用、对代理必需"的细节——构建步骤、测试命令、代码规范，以及那些塞进 README 会显得杂乱、人类贡献者其实并不关心的约定。
换句话说，AGENTS.md 更像一份给 AI 的"强制规则手册"。它约束的是 AI 的编码行为、修改逻辑、文件操作、技术选型和代码风格；它的内容偏向规范、约束、禁忌和强制标准，AI 的所有编码操作都应严格遵守其中的约定。
一个典型的 AGENTS.md 大致长这样：
# AGENTS.md
## 环境与命令
– 安装依赖：`pnpm install`
– 启动开发服务器：`pnpm dev`
– 运行测试：`pnpm test`
## 代码风格
– 使用 TypeScript 严格模式
– 单引号，不加分号
– 尽可能使用函数式写法
## 测试规则
– CI 计划在 .github/workflows 目录中
– 提交前必须通过 `pnpm lint` 和 `pnpm test`
– 改动了代码就要补充或更新测试，即使没人要求
这类文件最常被放进仓库根目录，代理会自动读取目录树中"最近的"那份 AGENTS.md。
二者到底差在哪
两者的关系可以用一句话说清：README.md 服务于人，AGENTS.md 服务于 AI，二者互补而非替代。
| 目标读者 | 人类：用户、贡献者、协作者 | AI 编码代理 |
| 核心目的 | 介绍项目、引导上手、吸引参与 | 约束 AI 行为、保证代码风格一致 |
| 内容属性 | 科普、说明、引导，无强制约束 | 规范、禁忌、强制标准，具备约束力 |
| 典型内容 | 项目简介、安装、用法、贡献指南、许可证 | 构建/测试命令、代码规范、文件操作规则、技术选型 |
| 位置 | 仓库根目录 | 仓库根目录，可嵌套于子项目 |
值得注意的是，随着 AI 越来越深入地参与开发，README 和 AGENTS.md 之间的边界正在变得模糊。有人观察到，开发者开始往 README 里塞进"专门优化给 AI 代理浏览"的段落——因为代理在探索仓库时也会读 README。于是产生了一个自然的疑问：如果 README 里已经有构建说明、架构笔记和贡献指南，为什么还需要一份独立的 AGENTS.md？
答案在于意图与优先级的不同。README 是给人读的长文，措辞可以解释、可以冗余；AGENTS.md 则是给代理的精确指令，需要简短、明确、可执行。把两者混在一起，往往会导致 README 臃肿难读，同时代理也难以从中提取到精确、无歧义的规则。
写好 AGENTS.md 的实践建议
AGENTS.md 看起来很轻量，但"写了"和"真的起作用"之间还有距离。经过在 OpenAI Codex、Claude Code、Cursor、OpenCode 等工具上的大量实践，一些规律逐渐浮现：过于冗长或充满空话的规则最容易被代理忽略，而简短、具体、可执行的指令效果最好。
一份有效的 AGENTS.md 通常覆盖这几个模块：
- 项目定位：项目类型、核心业务场景、开发/运行环境，让 AI 快速理解方向，避免技术路线误判。
- 技术栈规范：明确框架、版本、构建工具，禁止 AI 随意替换技术方案。
- 命令清单：安装、构建、测试、lint 的确切命令，代理会据此自动执行并修复问题。
- 目录结构说明：告诉代理各包/模块的职责，减少乱放文件的概率。
- 代码风格与禁忌：明确的风格约束和"禁止操作"清单，例如"不要引入新的依赖"“不要修改某个公共 API”。
- 测试与提交规范：PR 标题格式、提交前必须通过的检查等。
对于大型 monorepo，官方推荐在每个子包内放置各自的 AGENTS.md：代理会自动读取目录树中最接近的那份，最近的文件优先级最高，每个子项目都能有自己的定制指令。以 OpenAI 主仓库为例，一度同时存在 88 份 AGENTS.md。
此外，不同工具对这份文件的默认命名略有差异——Cursor 曾用 .cursorrules，Claude 用 CLAUDE.md，GitHub Copilot 用 .copilot-instructions——但格式基本一致，写完一份即可通过复制或软链接分发到多个工具中，不必为每个工具重写。
结语：把"给人看的"和"给 AI 看的"分开
AGENTS.md 的出现，本质上是一次文档职责的再分工：它没有取代 README，而是替 README 卸下了那些本不该由它承担的、面向机器的细节。你可以把 README 想象成项目的"门面"和"欢迎手册"，把 AGENTS.md 想象成一份写给新同事的"内部操作手册"——前者负责让人愿意进来，后者负责让 AI 一进来就能正确干活。
在 AI 编码代理已成为日常工具的今天，一个同时拥有清晰 README 和精准 AGENTS.md 的仓库，既能让人类贡献者快速上手，也能让 AI 保持一致的开发标准。这不是多此一举，而是现代 AI 驱动项目越来越标准的"双重说明书"配置。
