AGENTS.md 完全指南：一个文件让所有 AI 编程助手秒懂你的项目

AGENTS.md 是一个写在代码仓库根目录、专门给 AI 编程助手看的项目说明书，由 OpenAI Codex、Cursor、GitHub Copilot 等主流工具共同支持，已被超过 6 万个开源项目采用。它就是一个普通 Markdown 文件，用来告诉 AI：这个项目怎么构建、怎么测试、代码有什么规矩、哪些文件绝对不能碰。本文从零讲清它的写法、模板、与 CLAUDE.md 的区别，以及新手最容易踩的坑。

一、AGENTS.md 是什么：写给 AI 的项目说明书

一句话定义：AGENTS.md 是放在仓库根目录、面向 AI 编程助手的项目规范文件。

你的 README.md 是给人看的：项目介绍、快速上手、贡献指南。而 AGENTS.md 是给 AI 看的：构建命令、测试方式、代码约定、禁止事项——这些"新同事入职第一天必须知道的事"，现在写给 AI。

用一个表格理解它在工程体系里的位置：

没有它，AI 就像一个能力很强但完全不懂团队规矩的新人：组件放错目录、用错包管理器、commit message 随手写 "fix bug"、甚至动到你不想让它碰的文件。有了它，AI 从第一次对话开始就知道"在这里事情应该怎么办"。

AGENTS.md 官网把它称为"README for agents"（给代理的 README）。它没有必填字段、没有强制格式，就是标准 Markdown——AI 会直接阅读其中的文字。

二、为什么 2026 年值得马上配置一份

两个理由：生态已经成熟，以及一份文件通吃所有工具。

生态成熟：AGENTS.md 起源于 OpenAI Codex 的实践，由 OpenAI、Amp、Google Jules、Cursor、Factory 等公司联合推动，现在由 Linux 基金会旗下的 Agentic AI 基金会（Agentic AI Foundation）维护，是一个中立开放标准。截至目前，GitHub 上已有超过 6 万个开源项目在使用，OpenAI 自己的主仓库里甚至有 88 个 AGENTS.md 文件。

通吃所有工具：这是它相对各家私有配置文件最大的优势。以下主流工具都已支持：

也就是说：写一份 AGENTS.md，团队里不管谁用 Codex、谁用 Cursor、谁用 Copilot，大家拿到同一份项目规矩。 这在 AI 编程工具"一人一个偏好"的今天，是保持代码风格统一最省力的办法。

想了解这些工具怎么选，可以看我们之前写的《Cursor vs Claude Code：2026 年 AI 编程工具怎么选》。

三、工作原理：AI 是怎么读这份文件的

理解三个规则，你就理解了 AGENTS.md 的全部机制。

规则一：会话开始时自动注入。 AI 编程助手启动任务时会自动读取仓库中的 AGENTS.md，把内容作为项目上下文。你不需要在每次对话里重复交代"我们用 pnpm、组件放 src/components"。

规则二：嵌套优先级——离谁近听谁的。 在 monorepo（多项目仓库）里，可以在根目录和各子项目目录各放一份 AGENTS.md。AI 编辑某个文件时，会自动读取离该文件最近的那份，子目录的规则覆盖根目录的通用规则。

规则三：用户指令永远最高。 当你在聊天中明确说了"这次先用 JavaScript 别用 TypeScript"，即使 AGENTS.md 里写了强制 TypeScript，也以你的当次指令为准。官方 FAQ 的原话是：closest AGENTS.md to the edited file wins；explicit user chat prompts override everything（离编辑文件最近的 AGENTS.md 优先；用户聊天中的明确指令高于一切）。

四、手把手编写：可直接复制的中文模板

GitHub 官方博客分析了 2500 多个仓库的 AGENTS.md，结论是：优秀的文件都会覆盖六大核心区域——构建命令、测试、项目结构、代码风格、Git 工作流、行为边界。

下面是一份可直接复制的中文模板（以前端项目为例）：

# AGENTS.md

## 项目概览
- React 18 + TypeScript 前端应用，包管理器：pnpm
- UI 库：Ant Design 5；样式方案：Tailwind CSS
- Node >= 20

## 构建与测试命令
- 安装依赖：pnpm install
- 启动开发服务器：pnpm dev
- 跑全部测试：pnpm test
- 只跑某个测试：pnpm vitest run -t "测试名"
- 代码检查：pnpm lint
- 提交前必须通过：pnpm lint && pnpm test

## 目录结构
src/
├── components/   # 通用组件，PascalCase 命名
├── pages/        # 页面组件
├── hooks/        # 自定义 Hooks
├── services/     # API 请求统一封装
├── utils/        # 纯工具函数
└── constants/    # 常量

## 代码风格
- Props 用 interface 定义，禁止 any
- 组件文件名 index.tsx，目录名与组件名一致
- 示例（照这个风格写）：
  interface CopyButtonProps { text: string; onSuccess?: () => void }

## Git 工作流
- commit message 用 Conventional Commits：feat(scope): 描述
- 提 PR 前先跑 pnpm lint 和 pnpm test

## 边界（永远遵守）
- 永远不要修改 dist/ 和 node_modules/
- 永远不要提交密钥、token 等敏感信息
- 不要删除测试来"修复"失败
- 涉及数据库 schema 的修改，先问我

逐节说明写法要点：

1. 项目概览：技术栈写到具体版本。写"React 18 + TypeScript + Vite"，不要只写"React 项目"——React 17 和 18 的写法差异不小，版本号直接决定 AI 生成代码的正确率。
2. 命令：这是 AI 最常翻牌的一节，所以放在靠前位置。写完整的可执行命令（带参数），不要只写工具名。
3. 目录结构：列到一级目录就够，每个目录后面加一句注释说明用途和命名规范。
4. 代码风格：给一个真实代码示例。一个示例胜过三段描述——GitHub 的分析中反复强调这一点。
5. Git 工作流：commit 规范、PR 流程，AI 提交代码时会遵守。
6. 边界：用三层结构写——永远不要做（never）、做了但先问我（ask first）、始终要做（always）。"Never commit secrets"是 GitHub 分析中发现最高频也最有价值的约束。

不同技术栈只需要换第一、二节：Vue 项目写 Pinia + Vite，Python 项目写 pytest + uv，Java 项目写 Maven 命令。

五、进阶技巧：让它真正生效的 8 个要点

1. 命令放最前面。 AI 执行任务时最常引用的就是命令区块，位置越靠前权重越稳。
2. 示例代码优于文字解释。 想让 AI 写出符合风格的代码，直接贴一段"标准答案"。
3. 技术栈必须带版本号。 "TypeScript 5.x + React 18" 比 "现代前端项目" 有效十倍。
4. 边界写成三层：never / ask first / always，防止 AI 帮倒忙。
5. 别把它写成产品手册。 与编码无关的背景故事、公司介绍都会稀释关键信息，AI 的上下文是有限的。CSDN 上有篇高赞文章的标题说得很好：AGENTS.md 应该是一张地图，而不是一本手册。
6. 让 AI 帮你生成第一版。 Codex、Cursor、Copilot 都支持：直接对 AI 说"请阅读这个仓库并生成一份 AGENTS.md"，再人工校对。Claude Code 用户可以运行 /init 或 /import 命令。
7. monorepo 用嵌套文件。 根目录放通用规范，各子项目目录放专属规范（参考上文优先级示意图）。
8. 当活文档维护。 项目升级、规范变化时同步更新它。过时的指令比没有指令更危险。

六、AGENTS.md vs CLAUDE.md vs .cursorrules：一张表讲清

这是最多人混淆的问题。三个文件解决同一类问题（告诉 AI 项目规矩），但归属和兼容性不同：

实际操作建议：以 AGENTS.md 为唯一事实来源。

• Claude Code 用户：Claude Code 默认读 CLAUDE.md 而不是 AGENTS.md，但官方文档给出了标准解法——在 CLAUDE.md 里写一行 @AGENTS.md 引入，或者直接建软链接：ln -s AGENTS.md CLAUDE.md。这样一份文件同时服务两类工具，Claude 特有的指令（比如"改 src/billing/ 前先用计划模式"）写在 import 下方即可。
• Cursor 用户：直接用 AGENTS.md 即可，Cursor 官方文档明确把它列为项目规则的推荐方式之一；需要按文件路径精细触发规则时再补 .cursor/rules。
• 只写 CLAUDE.md 的写法技巧，我们单独写过一篇《Claude Code 提示词技巧：CLAUDE.md 怎么写、计划模式怎么用》。

七、常见错误与避坑清单

• 错误一：写得太抽象。 "你是一个专业的编程助手"这类话等于没写。有效的写法是具体的、可执行的动作指令。
• 错误二：什么都往里塞。 有人把团队 wiki、产品需求全贴进去。上下文有限，无关信息会让关键规则被"稀释"，反而降低遵循率。
• 错误三：忘了写 Never 规则。 边界约定是防范 AI 事故（误删测试、提交密钥、改动构建产物）的最后一道闸门。
• 错误四：写完就不管。 框架升级、目录调整后 AGENTS.md 还是旧内容，AI 会按过时规范写代码。
• 错误五：把敏感信息写进去。 AGENTS.md 会提交到仓库（包括公开仓库），内网地址、密钥、客户数据一律不能出现。
• 错误六：和工具私有配置打架。 同时维护 CLAUDE.md 和 AGENTS.md 却内容不一致，不同工具表现就会漂移——用上文的一源多用法解决。

八、真实效果：值得吗

掘金上有一篇传播很广的实战复盘《一份 AGENTS.md，让 AI 代码规范率从 60% 飙升到 95%》：同一个团队、同一批人，仅凭一份约 60 行的 AGENTS.md，AI 产出代码的规范率从 60% 提升到 95%——组件命名、目录放置、类型定义、commit 规范全部一次到位。

GitHub 官方博客对 2500+ 仓库的分析也得出了同方向结论：成功的 AGENTS.md 不是写得更长，而是更具体——明确的角色、可执行的命令、清晰的边界、真实的示例。

我们的判断：配置 AGENTS.md 的成本是 30 分钟，回报是此后每一次 AI 编程任务的规范率提升。这是目前 AI 编程领域投入产出比最高的一件事。

总结

AGENTS.md 的本质，是把"团队规矩"翻译成 AI 能执行的说明书：

• 一个文件通吃所有主流 AI 编程工具，Claude Code 用软链接或 @AGENTS.md 复用；
• 六大核心区域：构建命令、测试、项目结构、代码风格、Git 工作流、行为边界；
• 三条铁律：命令放前面、示例优于解释、边界必须具体；
• 从 30 行的最小模板开始，别追求一步到位。

现在就动手给你的仓库加一份吧。写完第一版，让 AI 改一个小需求试试效果——你会立刻感受到差别。

如果你想继续深入 AI 编程，推荐接着读：《Claude Code 提示词技巧：CLAUDE.md 怎么写、计划模式怎么用》、《Codex Skill 怎么安装：目录结构与不生效排查》和《MCP 和 Skill 的区别：AI Agent 工作流该先用哪个》。