新手指南：3步写好 AGENTS.md，让 AI 编程代理一次就改对
【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md
AGENTS.md 是一个简单、开放的格式，专门给 AI 编程代理（也就是替你写代码的 AI 助手）写项目说明。它相当于给 AI 看的 README，告诉代理这个项目怎么构建、怎么测试、代码要遵循什么风格，帮它少踩坑、少犯错。
为什么 AI 写的代码总差点意思
想象你招了位新同事，他技术不错，却不了解你们团队的规矩。写出来的东西语法没错，但风格不对、测试没补、部署步骤也没走对。AI 编程代理一开始也是这样：它懂通用的编程知识，却不懂你这个项目独有的约定。
结果就是反复返工——改代码风格、补测试用例、调部署配置。其实，你把这些规矩写下来给它看，很多返工就能省掉。
一句话看懂它是什么
README 是给人看的说明书，AGENTS.md 是给 AI 看的操作手册。
它放在项目里一个固定、可预测的位置，专门存放代理干活时需要的上下文和指令。这样 README 能保持干净、只服务人类贡献者，而那些对 AI 才有用的细节（比如构建命令、风格约束）也有了明确的去处。它没有强制字段，本质就是一篇普通 Markdown。
三步在仓库里建好 AGENTS.md
第一步，在仓库根目录新建一个 AGENTS.md。别从零硬写，直接让代理帮你生成一份初稿，你只需修改补充。
第二步，写清楚关键信息。常见的几块：项目概览、构建与测试命令、代码风格约定、测试方法、安全注意事项。写具体，比如直接给出能跑通的命令，比空泛描述更有用。
第三步，补上额外约定。提交信息的格式、PR 规范、部署步骤，凡是你会交代给新同事的，都可以放进来。
大仓库用嵌套文件
如果你的仓库很大，可以在每个子包里再放一份 AGENTS.md。代理会自动读取离被改文件最近的那一份，就近优先，每个子项目都能拿到量身定制的说明。
新手最容易踩的几个坑
别把它当技术文档的替代品。它太长太啰嗦就失去意义了，定位是补充而非替代，保持简洁。
指令冲突时听谁的。离被编辑文件最近的 AGENTS.md 优先级最高；而你在聊天里明确说的指令，覆盖一切。所以文件里写的内容尽量无歧义。
列了命令，代理真的会跑。如果你写了测试命令，它会试着执行并修到通过，再收尾。所以命令务必能跑通，别写个坏的。
别忘了更新它。这是活的文档，项目结构变了、工具链升级了，都要跟着改，过期的说明反而误导代理。
一份文件，适配一大批工具
你不需要为每个 AI 工具单独维护一套规则。Codex、Jules、Gemini CLI、Copilot、Cursor、VS Code、Devin 等都认 AGENTS.md 这一个文件名，目前已有超过 6 万个开源项目在用它。
这带来的好处很直接：写一份说明，换工具时也能用，跨团队协作时大家读的是同一份约定。
从三行开始，今天就动手
现在 AGENTS.md 由 Linux 基金会下的 Agentic AI Foundation 维护，朝着开放标准的方向演进。你不用一次到位——先写三行：项目是干嘛的、怎么跑起来、测试怎么验。跑顺了再加细节。
官方说明文档：README.md。打开你手头的项目，建一个 AGENTS.md，让它先读，再动手。
【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
