3分钟搞懂 AGENTS.md：AI编程代理配置实操手册

3分钟搞懂 AGENTS.md：AI编程代理配置实操手册

【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md

让AI写代码，改了三遍还是不对：构建命令用错、测试没跑、代码风格也乱。问题往往不在模型，而是它摸不到你项目的规矩。AGENTS.md 就是解决这件事的：一个给 AI 编程代理读的开放标准文件，把构建、测试和代码约定写在固定位置，代理接手项目会先读它。

📌 一句话看懂 AGENTS.md：给AI编程代理的操作手册

把AI当成刚入职的实习同事，AGENTS.md 就是贴在它工位上的操作手册。README.md 是给人看的说明书，这份写给代理看，两份文件各干各的，不互相挤占。它不是某个公司的私有格式，而是开放的命名约定：目前 GitHub 上已有 6 万多个仓库在用，Codex、Cursor、Gemini CLI、Devin 等主流 AI 编程代理都直接认这个文件名。

🛠 三步走通上手：AGENTS.md 最快配置方式

1. 在仓库根目录建 AGENTS.md

给所有代理一个固定位置读规则，免去每次口头交代。

2. 写清构建与测试命令

列在文件里的检查命令，代理会照单执行并修到通过。

3. 提交进仓库，随代码一起迭代

规则和代码在同一个版本库，改一次全团队生效。

写什么不用全猜，高频的是四样：项目概述、构建与测试命令、代码风格、测试说明。仓库大了可以嵌套：每个子包再放一份，代理自动读离被改文件最近的那份，近的说了算，OpenAI 的主仓库就放了 88 份。拿不准写什么，直接让代理帮你起草初稿，多数工具都支持。官方给的最小示例在 README.md，本仓库根目录的 AGENTS.md 本身也是现成范本。

👥 个人和团队用法区别

同样是这份文件，不同身份的用法侧重不一样：

读者身份	适用场景	能拿到什么
个人开发者	单人维护多个项目	换任何AI工具，代理都按同一套规矩干活，输出不再漂移
团队	多人混用多种编程代理	一份规则全员共享，新人和新工具接手不用重新培训
大型 Monorepo	一个仓库多个子包	每个子包各放一份 AGENTS.md，子项目有专属指令

❓ 避坑问答：冲突、格式与迁移

和 README.md 会冲突吗？

不会。README 给人看，AGENTS.md 给代理看，两者并存。真出现指令打架，离被改文件最近的 AGENTS.md 生效；你在聊天里下的明确指令优先于一切。

必须按固定格式写吗？

不用。它就是普通 Markdown，标题随你起，没有必填字段，代理只解析你给的文本。

老项目已有文档怎么迁移？

把现有文件改名为 AGENTS.md 即可，再给旧文件名留个符号链接兼容旧引用，一条命令搞定。

AGENTS.md 最值钱的一点：项目规矩第一次有了固定落点，人和AI共用同一份。现在就去你的仓库建一个，让AI先读手册再动手。

【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md