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

2026-09-11 13:24 3 阅读

README.md：写给人看的项目门面

在 GitHub 上打开一个仓库，最先映入眼帘的通常是 README.md。它自动渲染成仓库首页，承担着多重角色：项目简介、安装指南、使用示例、贡献说明，甚至是你技术品味的第一印象。

它的读者是活生生的人——可能是想试用你工具的开发者，也可能是考虑是否要提 PR 的贡献者，甚至是面试时翻你 GitHub 的招聘经理。因此，一份好的 README 必须能在几秒内回答几个关键问题：这是什么？为什么需要它？怎么跑起来？怎么参与？

业界普遍认为，最小可行的 README 应包含四要素：项目名称、一句话描述、安装步骤和基本用法。再多一点，可以加上截图、许可证和贡献指南。但切忌堆砌细节。满屏文字、过时示例、缺失依赖命令，都是劝退用户的常见原因。

README 的本质是“吸引”和“引导”。它不需要强制约束，而是通过清晰的结构和友好的语气，让人愿意留下来尝试甚至参与。它的语言可以带点温度，比如解释某个设计背后的思考，或者提醒用户注意某个坑。这些对人有用的信息，对 AI 却可能是噪音。

AGENTS.md：专为 AI 代理准备的操作手册

当 AI 编码代理（如 Cursor、Claude Code、GitHub Copilot 等）开始“阅读”代码仓库时，它们发现 README 虽然信息丰富，但不够精准。于是，一种新的文件格式应运而生：AGENTS.md。

AI 走进仓库——人类开发者与 AI 编码代理开始同时阅读同一个仓库

截至 2026 年初，已有超过 6 万个开源项目在根目录添加了这份文件。它的定位非常明确：AI 代理的 README。不同于面向人的科普式文档，AGENTS.md 是一份指令集，告诉 AI 在这个项目里“能做什么、不能做什么、怎么做”。

它的内容通常包括：

环境与命令：pnpm install、pnpm test、npm run build 等确切命令
代码风格：单引号还是双引号？是否加分号？TypeScript 是否启用严格模式？
技术栈约束：禁止随意引入新依赖，必须使用指定版本的框架
测试要求：修改代码必须同步更新测试，提交前需通过 lint 和单元测试
文件操作规则：不要删除特定目录，不要修改公共 API 签名

这些内容如果塞进 README，会让人类读者觉得冗长枯燥。但对 AI 来说，却是确保行为一致性的关键。AGENTS.md 的语言必须简短、明确、可执行，避免解释性文字。例如，“使用函数式写法”比“鼓励函数式编程以提高可维护性”更有效。

两者的核心差异

虽然都放在仓库根目录，README.md 和 AGENTS.md 的目标和写法截然不同：

维度	README.md	AGENTS.md
目标读者	人类（用户、贡献者）	AI 编码代理
核心目的	介绍项目、引导使用、吸引参与	约束行为、保证一致性
内容属性	说明性、引导性、可选读	规范性、强制性、必遵从
典型内容	项目背景、安装、示例、许可证	构建命令、代码规范、禁忌清单
语言风格	可解释、可冗余、带语气	简洁、精确、无歧义

README.md 项目的门面——回答四个核心问题

有人可能会问：既然 AI 也会读 README，为什么不把所有信息都放进去？问题在于意图冲突。README 需要照顾人类的阅读体验，允许适度重复和解释；而 AGENTS.md 追求机器可解析的确定性。混在一起，结果往往是两边都不讨好——人觉得啰嗦，AI 提取不到关键规则。

AGENTS.md 给 AI 的员工手册——四个核心内容模块

如何写一份有效的 AGENTS.md

README.md 与 AGENTS.md 的核心区别对比

不是随便列几条命令就算 AGENTS.md。实践中发现，只有满足以下条件的文件才能真正影响 AI 行为：

写好 AGENTS.md 的最佳实践——六个核心模块

具体而非抽象：不要写“保持代码整洁”，而要写“使用 Prettier 默认配置，单引号，不加分号”。
可执行而非建议：命令必须完整可复制，如 pnpm test --coverage，而不是“运行测试并检查覆盖率”。
覆盖关键场景：至少包含环境、构建、测试、风格四大模块。
支持嵌套结构：在 monorepo 中，每个子包可有自己的 AGENTS.md。AI 会优先读取最近的文件。例如，OpenAI 的主仓库曾同时存在 88 份 AGENTS.md，分别对应不同子项目。

现代项目的双重说明书——README.md 写给人类，AGENTS.md 写给 AI

此外，不同工具对文件名的支持略有差异。Cursor 曾用 .cursorrules，Claude 支持 CLAUDE.md，GitHub Copilot 识别 .copilot-instructions。但格式基本一致，写好一份后可通过软链接或复制适配多个平台，无需重复劳动。

实际案例对比

假设你正在开发一个 React + TypeScript 的组件库。

README.md 片段可能这样写：

这是一个轻量级 UI 组件库，专为内部管理系统设计。基于 React 18 和 TypeScript，提供按钮、表单、表格等常用组件。安装只需一行命令，5 分钟即可集成到你的项目中。
npm install @myorg/ui-kit
查看在线文档获取完整 API 和示例。

而 AGENTS.md 则会这样写：

# AGENTS.md

## 技术栈
- React 18.2+
- TypeScript 5.0+（strict: true）
- Vite 4 构建
- Storybook 7 用于文档

## 命令
- 安装：`pnpm install`
- 开发：`pnpm dev`
- 构建：`pnpm build`
- 测试：`pnpm test:unit && pnpm test:e2e`
- Lint：`pnpm lint --fix`

## 代码规范
- 所有组件必须用函数式写法 + hooks
- 禁止使用 any 类型
- 样式使用 CSS Modules，文件名后缀 .module.css
- 每个组件必须有对应的 Storybook 示例

## 禁忌
- 不要升级 React 主版本
- 不要引入新 UI 依赖（如 lodash）
- 不要修改 public API 的 props 接口