AGENTS.md使用建议
更新: 4/22/2026 字数: 0 字 时长: 0 分钟
AGENTS.md是OpenAI和Google联合退出的一个新标准，其核心作用是为Agent提供一种可预测的方式来理解和操作项目
AGENTS.md可以理解为是给AI看到README文件，其核心价值是让AI更好的理解当前的项目或是使用当前项目
为什么需要AGENTS.md
统一的数据管理
在VibeCoding盛行的时代，我们的每一个AI IDE都会添加上一个.xxx的目录来存放自己需要的东西在项目的根目录下，比如cursor是.cursor，kiro是.kiro，这会极大程度的污染我们的根目录，我们迫切的需要一个统一的标准来放置给agent的信息
AGENTS.md就是这个愿景下产生的工具，其核心是实现了对项目的README文件，将整个项目的结构，我希望如何开发，等一系列数据都告诉了Agent
可预测的流程
Agent的发展是不断的规范自己操作流程的过程
Harness工程告诉我们一个道理：好的Agent重要的不只是模型，而是一个更好的架构
AI对于一些想法有自己的实现方式，他会尝试这个指令，只有失败才会尝试另一种方案
一个典型的例子是我在Windows环境下使用Cursor为我写代码，他会频繁的尝试在powershell中使用&&来将两个命令连在一起，但很显然我们知道这是不可能的，而AI也知道这个事情，所以他会在出错后立刻选择另一种方案
这种情况下，我们如果提前告诉AI我们现在运行的环境是Windows，那么AI就不会出现这种错误
另一个案例是skills的使用，众所周知skills采取的是按需加载的方式，Agent会在对话的开始将skill的名字和描述交给AI，但是AI很可能会觉得你的要求并不需要使用这个skills（即时你觉得是需要的），那么AI就会放弃使用Skills而自己进行操作
这个时候，如果我们能提前告诉Agent：在执行xx操作下必须使用xx skills，那么Agent就会使用这个Skills了
AGENTS.md 与 Skills
vercel对skills进行了评估，他们将Next.js封装成了Skills，试图让Agent使用skills来生成正确的代码，但是代码通过率只有53%，这可以说是十分的不尽人意了
这一点在OPENAI的博客中也有提出
vercel在AGENTS.md中直接写出要使用技能
在编写代码之前，首先探索项目结构，然后调用nextjs-doc技能进行文档编写。这时我们发现skills的触发率直接打到95%，代码通过率直逼79%
同时，vercel还给了我们一个措辞对AGENT的影响：
| 教学 (Instruction) | 行为 (Behavior) | 结果 (Outcome) |
|---|---|---|
| “你必须调用这个技能” | 先看文档，锚点在文档模式上 | 缺失项目背景 |
| “先探索项目，然后调用技能” | 先建立心理模型，以文档为参考 | 更好的成绩 |
vercel指出：在一次评估（“ 使用缓存” 指令测试）中，“先调用”方法写出了正确的 page.tsx，但完全遗漏了所需的 next.config.ts 更改。“先探索”的做法同时实现了两者。
反直觉的是: vercel在测试中发现，使用AGENTS.md直接指出文档的目录，并告诉AGENT一切知识优先使用我们项目中检索到的，效果优秀于在AGENTS.md中指出使用skills
这种看似“愚蠢”的方法（静态标记文件）表现优于更复杂的基于技能的检索，即使我们微调了技能触发器。
vercel将其理解为一下原因：
- 没有决策点：即时你在AGENTS.md中明确指出了要使用XXX.skills，仍然会出现生成 Tool Call决定执行函数，等待执行skills并获取skills中的数据，最后将返回的结果和当前的任务结合的过程
- 稳定的可用性：skills是异步加载的，只有被调用才会加载，而AGENTS.md内容在系统提示中，每回合都有。
- 可观测的顺序：技能决定了是先探索项目在读文档，而被动语境下则避免了这一点
最佳实践
- 保持简洁：AGETNS.md应该保持住够的简洁，因为每次对话都会将他里面的内容引入
- 使用清晰的格式：项目符号、标题和代码块可以让Agent更容易理解和执行这些说明
- 尽量具体：具体示例和明确约定比含糊的指导原则效果更好
一个好的配置文件应该回答三个问题：
- WHAT: 技术栈、项目结构。
- WHY: 设计决策的背景。
- HOW: 如何运行、测试、验证。