两种方案的对比

团队测试了两种让 Agent 获取 Next.js 16 新 API 知识的方法：

  • Skills（技能模式）：按需调用的工具包，包含提示词和文档，Agent 需要"意识到"自己不懂，然后主动发起调用。
  • AGENTS.md（上下文模式）：放置在项目根目录的 Markdown 文件，作为持久上下文直接提供给 Agent。

Skills 模式：表现不佳且极度脆弱

Skills 方案暴露了当前 LLM 的一个核心短板——不知道自己不知道。

  • 在 56% 的测试案例中，Agent 明明有查阅文档的能力，却选择不使用，直接凭预训练知识硬写代码
  • 最终通过率仅 53%，与完全没有文档的基准测试结果一致——等于白搭
  • 团队尝试在 Prompt 中加入"必须调用技能"的显式指令后，通过率提升到 79%，但这种方式极度脆弱：指令措辞的微小变化（比如"先读文档"还是"先探索项目"）会导致 Agent 行为出现巨大差异，甚至引发新错误

AGENTS.md 模式：100% 通过率

团队将一份压缩后的文档索引嵌入 AGENTS.md，实现了构建、Lint 检查、测试全部通过的 100% 通过率。

关键做法有两个：

  1. 不塞全文，只放索引：文件仅包含一个约 8KB 的索引，涵盖文件路径结构和精简映射。Agent 看到索引后，知道去 .next-docs/ 等目录按需读取具体文档。这既保持了上下文轻量，又保留了全量知识的索引能力。
  2. 加入一句关键指令：IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning（优先基于检索的推理，而非基于预训练知识的推理），引导 Agent 查资料而非凭记忆猜。

为什么"笨办法"赢了

Vercel 团队总结了三个原因：

  • 消除决策点：Skills 要求 Agent 自己判断"我是否需要帮助"以及"何时调用工具"，当前 LLM 在这方面的判断力并不稳定。AGENTS.md 直接把信息摆在面前，不需要 Agent 做任何决策。
  • 持续可用：Skills 只在被调用时才存在，而 AGENTS.md 的内容在每一轮对话中始终存在于 System Prompt 中。
  • 规避顺序问题：Skills 引入了"先看代码还是先看文档"的执行顺序问题，被动上下文完全没有这个困扰。

对独立开发者的实操建议

如果你在用 AI Agent 写代码：不要过度信任 Agent 的自主决策能力。与其花时间调优复杂的工具链，不如在项目根目录放一份精心组织的 AGENTS.md，把框架约定、API 用法、项目结构等关键信息直接"喂"给模型。

如果你在开发框架或工具库：为用户提供一个标准化的 AGENTS.md 索引片段，是目前确保 AI 能正确使用你的框架的最可靠方式。

核心思路：这本质上是一种轻量级 RAG 实践——用索引引导检索，用检索替代猜测。在当前模型的能力边界下，Context is King，主动喂上下文远比期待 Agent 自己找答案更靠谱。