夜雨聆风
AGENTS.md:AI编程助手的＂员工手册＂,让60,000+开源项目有了统一＂说明书＂
当你的AI队友不再需要你手把手教，而是自己看”员工手册”就能干活，这是什么神仙体验？
🚀 从碎片化到标准化：AI编程的必然进化
还记得你第一次用AI编程工具时的场景吗？兴奋地打开Cursor，结果发现需要.cursorrules；切换到Claude，又要搞CLAUDE.md；用Aider得配.aider.conf.yml；Gemini CLI还要.gemini/settings.json…
每个工具都有自己的格式，每个项目都要重复配置。更糟的是，当你切换工具或团队其他成员用不同AI助手时，这些配置文件根本没法复用。
这就是AGENTS.md诞生的背景——OpenAI和Google联手，为整个AI编程生态制定了一个开放、统一的标准。
🎯 什么是AGENTS.md？简单到令人发指
AGENTS.md就是一个简单的Markdown文件，放在项目根目录。你可以把它理解为：
“给AI队友看的README”
但和README.md不同，README是为人类准备的（快速入门、项目描述、贡献指南），而AGENTS.md是专门为AI准备的——包含编码代理需要的额外详细上下文：
-
构建步骤 -
测试命令 -
命名约定 -
安全注意事项 -
部署流程 -
…所有你希望AI知道的项目细节
核心思想就四个字：关注点分离。保持README的简洁，同时给代理提供它们自己的可预测”剧本”。
🌟 一个文件，服务所有AI编程工具
这才是AGENTS.md最牛的地方——互操作性。一个AGENTS.md可以跨多种AI编码工具工作：
-
Cursor – 原生支持 -
VS Code – 通过Copilot支持 -
Aider – 配置 .aider.conf.yml即可 -
Gemini CLI – 配置 .gemini/settings.json -
Zed – 原生支持 -
Phoenix – 原生支持 -
opencode – 原生支持 -
Factory – 原生支持 -
Amp – 原生支持 -
Jules (Google) – 原生支持 -
Windsurf – 原生支持 -
Devin – 原生支持 -
…还有更多
没有专有格式，没有锁定。通过选择大家都已经理解的名称和格式，AGENTS.md可以无缝融入任何仓库、任何技术栈、任何IDE。
📝 实战示例：看看AGENTS.md长什么样
# Sample AGENTS.md file
## 开发环境提示
- 使用 `pnpm dlx turbo run where <项目名>` 跳转到包，而不是用 `ls` 扫描
- 运行 `pnpm install --filter <项目名>` 将包添加到工作区，让Vite、ESLint和TypeScript能看到它
- 使用 `pnpm create vite@latest <项目名> -- --template react-ts` 启动新的React + Vite包，TypeScript检查已就绪
- 检查每个包的package.json中的name字段确认正确名称——跳过顶层的那个
## 测试指令
- 在.github/workflows文件夹中找到CI计划
- 运行 `pnpm turbo run test --filter <项目名>` 运行为该包定义的每个检查
- 从包根目录可以直接调用 `pnpm test`。提交前应通过所有测试
- 要专注于一个步骤，添加Vitest模式：`pnpm vitest run -t "<测试名>"`
- 修复任何测试或类型错误，直到整个套件都变绿
- 移动文件或更改导入后，运行 `pnpm lint --filter <项目名>` 确保ESLint和TypeScript规则仍然通过
- 为你更改的代码添加或更新测试，即使没人要求
## PR指令
- 标题格式：[<项目名>] <标题>
- 提交前始终运行 `pnpm lint` 和 `pnpm test`
看到没？就是普通的Markdown，没有任何特殊语法，没有任何学习成本。AI代理会自动解析你提供的文本。
🏗️ 大型项目？嵌套AGENTS.md了解一下
对于大型单体仓库，AGENTS.md支持智能就近原则：在每个包中放置另一个AGENTS.md。代理会自动读取目录树中最近的文件，所以最近的优先，每个子项目都可以提供量身定制的指令。
例如，OpenAI的主仓库目前有88个AGENTS.md文件，每个子项目都有自己的”员工手册”。
📊 数据说话：AGENTS.md真的有用吗？
根据arXiv上的研究论文《On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents》：
-
分析了10个仓库和124个Pull Request -
在两种条件下执行代理：有AGENTS.md和没有AGENTS.md -
结果令人震惊：有AGENTS.md的项目，AI代理的运行时间减少了35%，token消耗减少了42%
这意味着什么？更快的开发速度，更低的API成本，更高的代码质量。
🚀 如何开始使用AGENTS.md？
第一步：创建AGENTS.md文件
在项目根目录创建AGENTS.md文件。大多数编码代理甚至可以为你搭建一个，只要你”礼貌地”问一下。
第二步：覆盖重要内容
添加帮助代理有效处理项目的部分。热门选择：
-
项目概述 – 让AI了解项目背景 -
构建和测试命令 – 具体的命令行指令 -
代码风格指南 – 命名约定、格式化规则 -
测试指令 – 如何运行测试、测试覆盖率要求 -
安全考虑 – 敏感信息处理、权限控制
第三步：添加额外指令
提交消息或Pull Request指南、安全陷阱、大型数据集、部署步骤——任何你会告诉新队友的内容都属于这里。
第四步：大型单体仓库？使用嵌套AGENTS.md文件
在每个包中放置另一个AGENTS.md。代理会自动读取目录树中最近的文件。
🌍 谁在用AGENTS.md？阵容豪华到离谱
看看这些已经采用AGENTS.md的知名项目：
-
OpenAI/Codex – 通用CLI工具，用于AI编码代理 -
Apache/Airflow – 以编程方式编写、调度和监控工作流的平台 -
Temporalio/sdk-java – Temporal的Java SDK，工作流编排 -
PlutoLang/Pluto – Lua 5.4的超集，专注于通用编程
超过60,000个开源项目已经在使用AGENTS.md。在GitHub上搜索path:AGENTS.md NOT is:fork NOT is:archived，你会被结果数量震惊。
🔧 技术实现：简单但强大
AGENTS.md项目本身是一个Next.js网站，托管在https://agents.md。技术栈：
-
TypeScript 94.3% – 类型安全，开发体验优秀 -
CSS 5.5% – 简洁的样式设计 -
JavaScript 0.2% – 极少的JS依赖
项目结构清晰：
-
components/– React组件 -
pages/– Next.js页面 -
public/– 静态资源 -
styles/– 样式文件
❓ 常见问题解答
Q: 有必填字段吗？
A: 没有。AGENTS.md就是标准Markdown。使用任何你喜欢的标题；代理只是解析你提供的文本。
Q: 如果指令冲突怎么办？
A: 离编辑文件最近的AGENTS.md获胜；明确的用户聊天提示覆盖一切。
Q: 代理会自动运行AGENTS.md中找到的测试命令吗？
A: 是的——如果你列出了它们。代理将尝试执行相关的程序检查，并在完成任务前修复失败。
Q: 以后可以更新吗？
A: 当然。把AGENTS.md当作活的文档。
Q: 如何将现有文档迁移到AGENTS.md？
A: 重命名现有文件并创建符号链接：
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
🎉 为什么你应该立即开始使用AGENTS.md？
-
提高开发效率 – AI代理不再需要反复问你基础问题 -
**降低API成本 – 减少不必要的token消耗 -
提升代码质量 – 确保AI遵循项目最佳实践 -
团队协作更顺畅 – 新成员（无论是人类还是AI）都能快速上手 -
未来证明 – 支持所有主流AI编程工具
🎁 立即行动：给你的项目添加AGENTS.md
现在就去你的项目根目录，创建一个AGENTS.md文件。从简单的开始：
# AGENTS.md
## 项目概述
[在这里描述你的项目]
## 开发环境
- 如何安装依赖
- 如何启动开发服务器
- 环境变量配置
## 测试
- 如何运行测试
- 测试覆盖率要求
- 测试文件命名约定
## 代码风格
- 格式化工具
- 命名约定
- 导入顺序
## 提交规范
- Commit message格式
- PR标题格式
- 代码审查要求
只需要10分钟，就能让你的AI队友从”实习生”变成”资深工程师”。
📚 资源链接
-
项目地址: https://github.com/agentsmd/agents.md -
官方网站: https://agents.md -
研究论文: https://arxiv.org/abs/2601.20404
#AI编程 #开源工具 #开发效率 #AGENTS.md #编程助手 #标准化 #OpenAI #Google #开发者工具