30 秒快速回答
AGENTS.md 是放在仓库根目录的一个 Markdown 文件，相当于「写给 AI 编程 Agent 看的 README」。 它用自然语言告诉 Claude Code、Cursor、Codex 等 AI 编程助手：项目怎么构建、测试怎么跑、代码风格是什么、有哪些必须遵守的约定。截至 2026 年 9 月，GitHub 上已有 6 万+ 仓库使用 AGENTS.md，其规范已移交 Linux Foundation 旗下的 Agentic AI Foundation（AAIF）托管，成为 AI 编程领域的准标准。
核心价值一句话： 写好 AGENTS.md，你的 AI 编程助手从「每次瞎猜项目怎么跑」变成「一次到位直接干活」，省下每次 10-20 分钟的试错成本。
为什么 AGENTS.md 突然火了？
没有 AGENTS.md 时，AI 编程 Agent 接手一个新仓库是这样的：先 ls 翻目录结构 → 猜构建命令 → 猜包管理器（npm 还是 pnpm？）→ 瞎试测试命令 → 甚至可能用错框架约定。每一步都在消耗 token，还经常搞错。
有了 AGENTS.md 之后，Agent 直接读取文件里的指令，一次走对。区别就像让新人入职时看一份操作手册，还是让他自己摸索。
| 维度 | 没有 AGENTS.md | 有 AGENTS.md |
|---|---|---|
| 项目熟悉时间 | 每次 10-20 分钟 | 秒级读取 |
| 构建/测试命令 | 猜测，可能搞错 | 明确写入，一次成功 |
| 代码风格一致性 | 时好时坏 | 按约定执行 |
| 仓库规范传达 | 靠口口相传 | 文件即标准 |
AGENTS.md 里写什么？五大核心板块
一份合格的 AGENTS.md 通常包含以下内容：
- 项目概览与技术栈：一句话说明项目是什么、用什么语言和框架、目录结构怎么组织。
- 常用命令：构建、测试、运行、代码检查、格式化的确切命令，这是 Agent 最需要的。
- 代码规范与约定：命名风格、组件写法、错误处理方式、注释要求等。
- 架构说明：关键模块的职责划分、数据流方向、不宜随意改动的核心代码。
- 工作流规则：哪些操作被禁止（比如不要动 lock 文件、不要改某个生成目录）、提交前必须做什么。
实战：一份可直接复用的 AGENTS.md 模板
下面是一份适用于 Node.js 项目的完整模板，可以直接复制改造：
# AGENTS.md
## 项目概览
一个基于 Next.js 14 的电商后台管理系统，使用 TypeScript 开发。
## 常用命令
- 安装依赖：`npm install`
- 启动开发：`npm run dev`
- 构建生产：`npm run build`
- 运行测试：`npm test`
- 代码检查：`npm run lint`
- 格式化：`npm run format`
## 代码规范
- 使用 TypeScript 严格模式，禁止使用 `any`
- 组件使用函数式写法 + hooks，禁止 class 组件
- API 请求统一走 `src/lib/api.ts` 封装
- 样式使用 Tailwind CSS，禁止内联 style
## 架构说明
- `src/app/`：页面路由，文件即路由
- `src/components/`：可复用组件
- `src/lib/`：工具函数与 API 封装
- `src/store/`：全局状态（Zustand）
- 禁止直接修改 `src/store/` 以外的全局状态
## 工作流规则
- 提交前必须运行 `npm run lint` 和 `npm test`
- 禁止提交 `node_modules/` 和 `.next/`
- 禁止修改 `package-lock.json`，除非显式安装依赖
- 不要删除 `src/app/api` 下已有接口，兼容性优先
常见误区与进阶技巧
误区一：把 AGENTS.md 写成 README。 README 是给人类看的，讲背景、特性、截图；AGENTS.md 是给 AI 看的操作指令，要写「做什么、怎么做、别做什么」。两件事，两个文件。
误区二：写得又长又散。 Agent 的上下文窗口是有限的，AGENTS.md 越长，留给真正代码的空间越少。建议控制在 100 行以内，只写 Agent 必须知道的内容。
进阶技巧：
- 保持祈使句：「运行
npm test」比「你可以尝试运行测试」有效得多，指令要明确。 - 与生态工具协同：Anthropic 生态还支持
CLAUDE.md，Cursor 支持.cursor/rules目录，原理一致；团队统一选一个主入口即可，避免指令冲突。 - 纳入 Code Review：改架构或命令时同步更新 AGENTS.md，让它永远反映最新事实。
- 先小后大：先写最小可用版本跑通，再按 Agent 实际犯过的错逐步补充，比一次写完美更高效。
总结
AGENTS.md 用最小的成本解决了 AI 编程时代最痛的「项目上手」问题：一个文件、零基础设施、立刻生效。它不要求你懂任何新工具，只需要把项目里那些「默认大家都懂」的约定写下来。 随着 AAIF 托管和 6 万+ 仓库的采用，它正在成为 AI 编程工作流的标配。
延伸阅读：想进一步理解 AI 编程背后的协议生态，可以看看本站的《什么是 MCP 协议？一文读懂 AI 的 USB 接口标准》《Claude Code 怎么用？Anthropic AI 编程 Agent 全解析》和《什么是 Agent Skills？AI Agent 的模块化能力系统全解析》。