ARTICLE · 1037879
一份文件管所有AI编程工具:AGENTS.md保姆级教程,10分钟让你的＂上岗就懂规矩＂
一份文件管所有AI编程工具:AGENTS.md保姆级教程,10分钟让你的＂上岗就懂规矩＂用AI写代码的朋友，大概率遇到过这种憋屈： 你花了半小时，把项目背景、代码习惯、注意事项给AI讲得明明白白。过两天换了个AI工具，同样的项目，一切从头再来——它对之前的约定一无所知，写出来的代码跟你现有的项目风格完全对不上。 9月18日，这个老问题迎来了一个标志性解决方案：Claude Code 2.1.277版本正式支持AGENTS.md文件。这可能是AI编程工具"大一统"的一步——从今天起，写一份项目说明书，主流AI编程工具全都认。 这篇带你从零搞懂它，10分钟能上手。 一、AGENTS.md是什么？给AI看的"岗位说明书" AGENTS.md是一个纯文本Markdown文件，放在你的项目文件夹里，专门写给AI看的。 官方有个精妙的说法： "README for agents" ——如果说README.md是写给人类开发者看的项目说明，那AGENTS.md就是项目写给AI的"岗位说明书"。 里面通常写这几类内容： 这个项目是干什么的、用了什么技术； 文件夹结构长什么样，什么代码放在哪； 安装依赖、跑测试、构建项目的命令； 代码规范：命名习惯、禁止事项、提交格式。 你可能会问：这些话我每次跟AI聊天时说一遍不就行了？区别在于： 聊天时说的话，AI这次记住、下次忘；写进AGENTS.md的内容，AI每次干活之前都自动先读一遍。 相当于新员工入职第一天拿到岗位手册，不用你天天口口相传。 二、这次为什么是大新闻？两个背景 背景1：AGENTS.md已经悄悄成为行业标准 AGENTS.md这个格式最早由OpenAI的Codex在2025年8月推出，后来捐给了Linux基金会。到今天，超过6万个开源项目在用它，支持的AI工具一长串：Codex、Cursor、Gemini CLI、GitHub Copilot、VS Code、Devin…… 也就是说，除了Claude Code，几乎所有主流AI编程工具早就认这个文件了。 背景2：Claude Code是最后一家"倔强"的 Claude Code此前只认自家格式的CLAUDE.md，导致一个团队里用Codex的读AGENTS.md、用Claude Code的读CLAUDE.md，同一份项目规矩要维护两份，改了一份忘了另一份，AI的行为就悄悄不一致了。 这事闹到什么程度？Shopify的CEO曾公开表示考虑在公司内部停用Claude Code，除非它支持读取AGENTS.md——他把这种双份维护的负担叫"复杂性税"。 9月18日，2.1.277版本落地：项目里如果没有CLAUDE.md，Claude Code会自动读取AGENTS.md。消息一出，社区刷屏"终于统一了"，连OpenAI Codex的负责人都跑来留言祝贺："欢迎来到光明的一边。" 竞争对手在项目规则文件上握手言和——这件事本身，比功能更新更有信号意义。 三、新手实操：10分钟写出你的第一份AGENTS.md 第1步：在项目根目录新建文件 打开你的项目文件夹（最外层，和代码放一起），新建一个文件，名字严格是 AGENTS.md——注意大小写和拼写，写成 AGENT.md 或 agents.md 都可能不被识别。 第2步：照着模板填 新手直接抄这个模板，把内容换成你自己的项目： 
第3步：写的时候记住三个原则 模板是骨架，内容质量决定效果。三个原则： 1. 具体而不是抽象。 写"变量命名用小驼峰"，不要写"注意命名规范"——AI没法执行"注意"。 2. 命令写全。 怎么运行、怎么测试、用什么包管理器，直接列出命令原文。AI不需要你解释，需要可执行的一行字。 3. 持续迭代。 发现AI反复犯同一个错——比如总把你不想动的文件改了——就把对应的规矩补进AGENTS.md。这个文件不是一次写完的，是跟AI"磨合"出来的。它就是你的AI团队管理制度的草稿，越用越准。 第4步：验证它生效了 最简单的验证方法，重启AI会话后直接问它： 请根据当前项目的AGENTS.md，说明本项目的代码规范要求是什么。 它能准确复述，就是生效了。 Claude Code用户还可以输入 /config，在"Project instructions"里查看当前读取的是哪个文件。 四、几个新手常问的问题 Q：Claude Code会优先读哪个文件？ 有CLAUDE.md就只读CLAUDE.md，没有才读AGENTS.md。如果你想让两者同时生效，可以在 /config 里改设置。对新手来说记住一条就够：新项目直接用AGENTS.md，一份通用。 Q：项目里可以放多个AGENTS.md吗？ 可以。根目录放全局规则，子文件夹里可以再放一份更具体的规则。新手先用根目录这一份就够了，等项目变大再分层。 Q：用了AGENTS.md还需要跟AI解释需求吗？ 需要。AGENTS.md管的是"长期规矩"（规范、命令、禁忌），聊天时说的是"这次任务"（做什么功能）。一个是公司制度，一个是工单，不冲突。 Q：手机上/无代码工具能用吗？ AGENTS.md本质是个Markdown文件，任何能编辑文本的地方都能创建。关键是你的AI工具是否支持读取——Codex、Cursor、Copilot等主流工具均已支持。 五、写在最后 回顾AI编程这一年，工具越来越强，但每个工具各带一套配置格式，项目规则成了一笔"糊涂账"——换个工具，规矩清零。 AGENTS.md的意义，是把项目规则从"各家的私有格式"变成"代码库的公共基础设施"。规则跟着项目走，而不是跟着工具走——你花心血调教好的AI工作习惯，换任何工具都带走。 对新手的建议就一条：从下一个项目开始，先写AGENTS.md再开工。 哪怕只有十行，你的AI也已经比"裸奔上岗"强了。