想象一下,你每天带一个聪明但失忆的新同事入职。他昨天刚学会用yarn,今天又用npm装包;你知道绝对不能碰的生成目录,他大摇大摆就改了。这不是他笨,是你没给他一本‘入职手册’。对于AI编程智能体来说,AGENTS.md就是这样一本手册。它和给人类看的README.md不一样,后者讲‘这是什么’和‘如何上手’,而AGENTS.md直截了当地告诉AI:‘项目用TypeScript,测试跑pytest,auth目录不能动。’这是从‘AI辅助’走向‘AI协同’的关键一步,而这一步,很多团队都还没迈出去。
为什么一份纯Markdown文件能带来质的飞跃?因为AI编程智能体天生无状态。每次新会话都像一次‘冷启动’,它会调用训练数据里的通用模式,却不知你项目有专有约定。这就解释了为什么你明明昨天纠正过它的错误,今天它又犯了一遍。AGENTS.md通过明确的命令、代码规范、项目结构和安全边界,给AI设定了一套行为准则。比如告诉它‘提交信息必须遵循约定式提交’,‘测试覆盖率不低于80%’,‘禁止在代码中写入硬编码密钥’。这不仅是提升效率,更是降低AI犯错风险的最直接手段——用规范把‘自由发挥’锁进笼子里。
写这份手册也有讲究,不是越长越好。研究指出,AI大模型能稳定遵循的指令大概在150到200条之间,但系统提示词已经占去一部分。一个600行的CLAUD.md或AGENTS.md并不会让它更聪明,反而会让它选择性地忽略你最关心的规则。核心原则是‘优先级排序’:写入那些AI无法从代码库或Linter中推导出的信息,比如特殊的工作流、不允许触碰的目录、特定的测试命令。而那些代码风格和空格规则,放心交给Prettier和ESLint就行。记住,让你的AI做Linter不该干的事,是浪费它也是浪费你的时间。
行业数据也印证了这件事的价值。目前已有超过6万个开源项目采用了AGENTS.md标准,甚至连OpenAI的核心代码库中也分布着80多个针对不同子项目的此类文件。像Cursor、Devin这些主流工具不仅支持它,还主动引导用户去创建。更关键的是,这份‘入职手册’具有互操作性。你为Aider写的AGENTS.md,在Copilot和Codex上也能跑。你不需要针对每个工具维护一套规则,写一次就能通吃。这正是Linux基金会旗下Agentic AI Foundation将其标准化的原因——让规范真正成为AI开发环境的基础设施。
最终,AGENTS.md的意义超越了单纯的配置文件。它代表了一种思维转变:我们的代码库不仅要‘对人友好’,还要‘对AI友好’。就像我们会在API设计中考虑开发者体验一样,现在我们也需要为AI规划它的‘体验路径’——干净的格式、明确的指令、可执行的命令。这不是在给AI找麻烦,而是在给未来的自己减负。当你的AI助手不再重复犯同一个低级错误,当你一句‘按惯例来’它就能输出符合规范的代码,你会发现,让机器理解规则,本质上是让我们自己摆脱重复低效的沟通成本。花5分钟创建一个AGENTS.md文件,可能是你今天为项目做的最有价值的一次配置。
夜雨聆风