在 AI 编程普及的今天，GitHub Copilot、Cursor、OpenAI Codex等工具已经成为开发者的标配。当有新的贡献者带着 AI 编程工具来到你的开源项目时，AI 是会成为一个高效的高级工程师，还是一个到处制造混乱的“实习生”？ 答案往往取决于你是否为 AI 提供了明确的上下文。这就是 AGENTS.md 规范诞生的原因。
与此同时，越来越多的开发者在参与开源项目贡献时使用自己的AI Coding Agent，这包括向Linux内核提交代码。所以开源项目及其维护者不得不积极面对这一现实变化。
1. 什么是 AGENTS.md？
简单来说：README.md 是写给人类看的，而 AGENTS.md 是专门写给 AI 编程工具看的。
它是一个放置在项目根目录下的标准 Markdown 文件（遵循 https://agents.md 开放规范），用于为 AI Agent 定义在当前仓库中工作的操作规范、架构约束、技术栈细节以及常用的终端命令。
2. 为什么要使用 AGENTS.md？
在项目中引入 AGENTS.md 能带来立竿见影的收益：
消除“幻觉”与过度重构：AI 经常会根据其训练数据推荐过时的库，或者在修复小 Bug 时擅自重构不相关的文件。在 AGENTS.md 中设定严格的边界，可以大幅降低这类风险。
统一跨工具的行为：无论贡献者使用的是 Cursor、Copilot 还是独立的 CLI ，AGENTS.md 都能作为唯一的事实来源（Single Source of Truth），确保 AI 生成的代码符合你项目的风格指南。
大幅降低新贡献者的上手门槛：当开发者启动 AI 助手时，AI 会自动读取该文件，了解如何构建项目、运行测试和格式化代码，无需开发者反复手动向 AI 投喂冗长的上下文。
提升测试与交付的成功率：通过提供精确的测试和校验命令，你可以要求 AI 在修改代码后自行验证结果。
3. 如何编写高质量的 AGENTS.md？
编写给 AI 看的文档，与写给人类看的文档有本质区别。AI 不需要客套话，需要的是可执行的命令和明确的规则。
第一步：在根目录创建文件 直接在仓库根目录新建 AGENTS.md ，并在头部明确其用途和角色设定。如果是一个大型单仓项目，那么你也可以在不同模块下创建专属于该模块的 AGENTS.md ，这完全没有问题，符合最佳实践。
第二步：指令命令化 (Command-First) 不要使用模糊的散文。例如，不要写“请确保代码通过测试”，而是直接提供命令，让 AI 可以通过退出码 (Exit Code) 来验证结果：
“在完成任何修改后，必须运行 npm run test 和 npm run lint。”
第三步：明确技术栈与代码规范 指出项目使用的具体库版本和约定俗成的写法，明确禁止 AI 引入你不想要的技术栈。
第四步：划定红线（边界） 明确告诉 AI 哪些目录是只读的，哪些文件是自动生成的、绝对不能手动修改的。
真实案例模板 以下是一个适用于前端项目的 AGENTS.md 示例，展示了如何清晰地向 AI 下达指令：
## AI 编程操作指南
你是一个资深的前端工程师。在修改本仓库的代码前，请严格遵循以下规则：
### 1. 技术栈与架构
- 这是一个使用 React 18 + TypeScript + Vite 的项目。
- 状态管理使用 Zustand，**请勿引入 Redux** 。
- 样式使用 Tailwind CSS。**禁止编写内联样式** (`style={{...}}`)。
### 2. 编码规范
- 优先使用 `const` 而不是 `let` 。
- 在定义类型时，优先使用 `interface` 而不是 `type` 。
- 组件必须放置在 `src/components/` 目录下，并使用命名导出（Named Exports）。
### 3. 测试与验证
在完成任何代码修改后，你必须在终端执行以下命令验证更改：
- 运行测试： `npm run test`
- 类型检查： `npm run typecheck`
- 代码格式化： `npm run lint:fix`
### 4. 边界与限制
- **绝对不要** 修改 `src/legacy/` 目录下的任何文件，该目录已被标记为废弃。
- 不要尝试手动修改 `package-lock.json`。
当然，对于相对比较简单的项目，你完全可以尝试让Coding Agent在阅读了 AGENTS.md 官网的信息后自动帮你快速创建一个 AGENTS.md 文档，在经过你的评审后即可使用。
4. 结语
在 AI 原生开发的浪潮中，让 AI 更好地理解你的项目，是维护代码质量和提升社区协作效率的关键。在你的开源项目中花几分钟添加一个 AGENTS.md，你将收获更高质量的 Pull Request 和更少的人工评审负担。
立刻行动起来，为你的代码库雇佣一个合格的“AI 守门人”吧！
相关链接
- AGENTS.md https://agents.md/
- AAIF https://aaif.io/