AGENTS.md 是什么？AI 编程工具通用配置指南（2026）

如果你用过 Claude Code、Codex、Cursor 这类 AI 编程工具，多半遇到过同一个烦恼：换一个工具，就得重新告诉它一遍「我的项目怎么跑测试、用什么代码风格、提交信息要怎么写」。AGENTS.md 就是为了解决这件事而生的——它是一份放在仓库里、专门写给 AI 编程 Agent 看的开放格式配置文件，可以被多家工具通用读取。这篇文章带你搞清楚 AGENTS.md 是什么、到底怎么写，以及它和 CLAUDE.md、README 的区别。

AGENTS.md 是什么

用一句话概括：AGENTS.md 是「写给 AI Agent 的 README」。README 是给人看的，告诉协作者项目怎么装、怎么用；而 AGENTS.md 是给 AI 编程助手看的，把构建命令、测试方式、代码规范、提交约定等「让 Agent 干活不踩坑」的上下文集中放在一个可预测的位置。它是一个开放格式，2025 年由 OpenAI 等推动成型，到 2025 年底被纳入 Linux 基金会旗下的 Agentic AI 基金会（与 Anthropic 的 MCP、Block 的 Goose 同处一个治理框架），背后有 OpenAI、Anthropic、Google、AWS 等公司支持。截至 2026 年 6 月，官网列出 28+ 款支持工具，GitHub 上已有 6 万多个仓库放了 AGENTS.md。

AGENTS.md、CLAUDE.md、README 有什么区别

三者经常被搞混，但分工其实很清楚：README 面向人类贡献者，CLAUDE.md 是 Claude Code 专属的记忆文件，AGENTS.md 则是跨工具的通用 Agent 配置。

简单说：如果你只用 Claude Code，CLAUDE.md 够用；一旦团队里同时存在多种 AI 工具，AGENTS.md 才能避免「同一套规则抄好几份」。两者并不冲突，下文会讲怎么让它们共存。

AGENTS.md 怎么写：就是普通 Markdown

好消息是 AGENTS.md 没有强制的字段或固定结构——它就是标准 Markdown，你想用什么标题层级、分几个小节都行，Agent 只是把里面的文字当作上下文来读。放在仓库根目录、命名为 AGENTS.md 即可。一个最小可用的例子：

# AGENTS.md

## 项目简介
这是一个基于 Next.js + Prisma 的学习平台，TypeScript 严格模式。

## 常用命令
- 安装依赖：`pnpm install`
- 启动开发：`pnpm dev`
- 运行测试：`pnpm test`
- 代码检查：`pnpm lint`

## 代码风格
- 使用单引号，不写分号
- 组件放在 src/components/，按功能分目录

## 提交规范
- 用 Conventional Commits（feat: / fix: / chore:）
- 提交前必须本地跑通 lint 和 test

里面通常写些什么

虽然字段自由，但社区里大家常写的板块高度趋同，建议至少覆盖这几类：

• 项目概览：技术栈、目录结构、关键约定，让 Agent 快速建立心智模型。
• 构建与测试命令：怎么装依赖、怎么起服务、怎么跑测试——Agent 改完代码会照着自测。
• 代码风格：缩进、引号、命名、lint 规则，避免它生成不合规范的代码。
• 测试要求：改动后必须跑哪些检查、覆盖率要求等。
• 安全注意事项：哪些目录别碰、密钥怎么处理、危险操作要不要先确认。
• 提交与 PR 规范：提交信息格式、分支策略、PR 描述要求。

Monorepo / 多项目：就近的那份生效

AGENTS.md 支持嵌套：你可以在仓库根目录放一份通用的，再在各个子项目目录里放更具体的。Agent 会自动读取「目录树里离当前文件最近」的那份 AGENTS.md，所以越靠近代码的配置优先级越高。这对 monorepo 特别友好——官方拿 OpenAI 自家仓库举例，里面用了多达 88 份嵌套的 AGENTS.md，每个子项目都能带自己的定制规则。

哪些工具支持 AGENTS.md

支持阵营已经相当大，常见的有：OpenAI Codex、Cursor、GitHub Copilot（2025 年 8 月起支持）、Google Jules、Gemini CLI、Aider、Zed、Warp、VS Code、Devin、JetBrains Junie、Amp、Windsurf、Augment Code、goose、opencode 等。需要留意两点：

• Gemini CLI 默认用自己的 GEMINI.md，但文件名在 settings.json 里通过 context.fileName 可配置，把它指向 AGENTS.md 即可统一。
• Claude Code 一直以来读的是 CLAUDE.md。是否原生读取 AGENTS.md 随版本变化较快，最稳妥的做法是用软链接让两者指向同一份内容（见下一节）。

从 CLAUDE.md 迁移 / 让两者共存

如果你已经写好了 CLAUDE.md，不必推倒重来。常见做法是把内容统一到 AGENTS.md，再用软链接保持向后兼容，这样一份内容、多个文件名都能命中：

# 把现有 CLAUDE.md 改名为 AGENTS.md
mv CLAUDE.md AGENTS.md

# 再建一个软链接，让仍然读 CLAUDE.md 的工具也能命中同一份
ln -s AGENTS.md CLAUDE.md

# Windows（管理员 PowerShell）：
# New-Item -ItemType SymbolicLink -Path CLAUDE.md -Target AGENTS.md

写好 AGENTS.md 的几条建议

• 命令要能直接复制运行：写真实可用的安装/测试/构建命令，别写伪代码。
• 短而准胜过长而全：Agent 的注意力有限，核心约定写清楚比堆一堆细节更有效。
• 把踩过的坑写进去：常见错误、易混淆的目录、特殊的环境变量，能省下大量来回。
• 随项目演进更新：技术栈或规范变了就同步改，过时的指令比没有还糟。
• 多项目用嵌套分层，根目录管全局、子目录管局部。

AGENTS.md 看着只是一个小文件，背后却是 AI 编程从「单工具玩具」走向「团队标准工作流」的信号——会写配置、会喂上下文，正在成为用好 AI 编程工具的基本功。如果你想系统掌握怎么把 Claude Code、Codex、Cursor 这些工具真正用进日常开发、做出能上线的项目，欢迎来 IMAI 看看我们的体系化实战课程。