一个文件让 AI Coding 效率翻倍：AGENTS.md 实践指南
前言
这是我”AI Coding 经验总结”系列的第五篇文章。前几篇聊的是工具选型、工作流范式、Harness Engineering 这些偏宏观的话题，这篇回到一个更具体的问题：怎么写好一份 AGENTS.md？
「在代码仓库中放一份上下文文件，告诉 AI 工具这个项目是什么、怎么构建、有什么规矩」——这个做法现在已经有了一个统一的名字：AGENTS.md。在展开实践之前，先花一点篇幅介绍它的前世今生，已经了解的同学可以跳过。
AGENTS.md 是什么？
AGENTS.md 是一个简单的开放格式，用于指导 AI Coding Agent 在你的项目中工作。你可以把它理解为给 AI 看的 README——README.md 是给人类看的项目说明，AGENTS.md 则是给 AI Agent 看的项目指令，包含构建命令、编码规范、测试要求、安全注意事项等 AI 需要知道的上下文。
官方建议的使用方式很简单：
- 在仓库根目录创建一个
AGENTS.md文件 - 写上对 Agent 有用的内容：项目概述、构建测试命令、代码风格、安全注意事项
- 补充额外指引：commit 规范、部署步骤、安全陷阱——任何你会告诉项目新成员的东西
- 大型 monorepo 可以在子目录放嵌套的 AGENTS.md，Agent 会读最近的那个（OpenAI 自己的仓库有 88 个 AGENTS.md）
格式上没有任何强制要求，就是标准的 Markdown，用什么标题、写什么内容完全自由。
前世今生
这个概念最早由 Anthropic 通过 Claude Code 的 CLAUDE.md 普及。Claude Code 运行时会自动加载当前目录下的 CLAUDE.md，把内容注入到发给模型的请求中。这个设计简单而有效——维护好一份上下文文件，Agent 的表现就会变好；表现变好了，你就更愿意用它，进而更愿意维护这份文件，形成正向循环。
随后各家 AI Coding 工具跟进了自己的版本，一度各自为政：
| 工具 | 上下文文件 |
|---|---|
| Claude Code | CLAUDE.md |
| Cursor | .cursorrules / .cursor/rules |
| Copilot | .github/copilot-instructions.md |
| Gemini CLI | GEMINI.md |
| Cline | .clinerules |
| AMP (Sourcegraph) | AGENT.md（单数） |
| OpenAI Codex | AGENTS.md（复数） |
这种碎片化意味着团队需要为不同工具维护多份内容相同的配置文件，改一次规则要同步好几个地方。
2025 年 5 月，Sourcegraph 旗下的 AMP 率先提议统一标准，建议用 AGENT.md（单数），并注册了 agent.md 域名。随后 OpenAI 宣布买下了 agents.md 域名，提议用 AGENTS.md（复数），理由是多个 Agent 会共用同一份配置。AMP 随即主动让步对齐，将 agent.md 重定向到 agents.md。
最终 AGENTS.md 成为事实标准，由 Linux Foundation 下属的 Agentic AI Foundation 托管。截至 2026 年初，GitHub 上已有超过 6 万个开源项目使用这个格式。Cursor、Kiro、灵码、Qoder、Copilot 等主流工具均已支持。Claude Code 虽然仍用 CLAUDE.md，但内容完全通用，一个软链接即可兼容：ln -s AGENTS.md CLAUDE.md。
过去半年里，我为手头的多个项目都维护了 AGENTS.md——有管控系统、有内核引擎代码、有产品基线、也有文档系统。不同项目的技术栈、仓库结构、团队规模各不相同，但在 AGENTS.md 的实践上逐渐收敛到了一套相似的方法论。这篇文章我挑了其中投入最多、也最通用的一个场景——管控系统（Spring Boot + React 的前后端分离项目）来展开介绍，希望对正在写或者想写 AGENTS.md 的同学有参考价值。
