同一个项目，两本说明书：README.md 写给人类，AGENTS.md 写给 AI

在 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.mdAI 代理的员工手册与 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二者互补而非替代。维度README.mdAGENTS.md目标读者人类用户、贡献者、协作者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 曾用.cursorrulesClaude 用CLAUDE.mdGitHub Copilot 用.copilot-instructions——但格式基本一致写完一份即可通过复制或软链接分发到多个工具中不必为每个工具重写。结语把给人看的和给 AI 看的分开AGENTS.md 的出现本质上是一次文档职责的再分工它没有取代 README而是替 README 卸下了那些本不该由它承担的、面向机器的细节。你可以把 README 想象成项目的门面和欢迎手册把 AGENTS.md 想象成一份写给新同事的内部操作手册——前者负责让人愿意进来后者负责让 AI 一进来就能正确干活。在 AI 编码代理已成为日常工具的今天一个同时拥有清晰 README 和精准 AGENTS.md 的仓库既能让人类贡献者快速上手也能让 AI 保持一致的开发标准。这不是多此一举而是现代 AI 驱动项目越来越标准的双重说明书配置。