Vercel 团队近期公布了一项令人惊讶的实验结论：在为 AI Coding Agent 提供框架知识时，简单被动的上下文文件「AGENTS.md」比复杂的、主动调用的「Skills」更有效。这一发现挑战了当前 AI 开发中过度迷信 Agent 自主决策能力的趋势，为构建高可靠性的编程助手提供了新的思路。
两种知识获取路径的较量为了测试 AI Coding Agent 获取新知识的最佳方式，Vercel 团队基于 Next.js 16 的新 API 建立了一套评估测试集，对比了两种截然不同的方法：
Skills（技能模式）：这是一种按需调用的工具包，包含提示词和文档。Agent 需要“意识到”自己不懂，然后主动调用该工具获取帮助。 AGENTS.md（上下文模式）：这是一个放置在项目根目录的 Markdown 文件，作为持久的上下文信息直接提供给 Agent。
对比结果令人大跌眼镜，被寄予厚望的 Skills 模式表现惨淡，而看似原始的 AGENTS.md 模式却大获全胜。
Skills 模式：表现不佳且极其脆弱在测试中，Skills 模式的主要问题在于 Agent 经常不调用该工具。在 56% 的测试案例中，Agent 即使拥有查阅文档的能力，也选择直接瞎写，导致通过率仅为 53%。这一结果与没有任何文档支持的基准测试结果完全一致，意味着 Skills 的存在几乎毫无价值。
团队尝试在 Prompt 中加入“必须调用技能”的显式指令，虽然将通过率提升到了 79%，但这种方法极度脆弱。指令措辞的微小变化（例如是要求“先读文档”还是“先探索项目”）会导致 Agent 行为产生巨大差异，甚至引发新的错误。这种不稳定性使得 Skills 难以在生产环境中被信赖。
AGENTS.md 模式：100% 完美通关相比之下，AGENTS.md 模式展现了惊人的稳定性。Vercel 团队并没有把所有文档塞进 Prompt，而是在 AGENTS.md 中嵌入了一个压缩后的文档索引，并加入了一句关键指令：“IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning”（重要：优先基于检索的推理，而非基于预训练知识的推理）。
结果显示，这种方法实现了100% 的通过率——构建、Lint 检查、测试全部通过。
Vercel 分析认为，被动的上下文（AGENTS.md）战胜主动工具（Skills）主要有三个深层原因：
消除了决策点：使用 Skills 时，Agent 必须自己判断“我是否需要帮助？”以及“我该何时调用工具？”。当前的 LLM 在这方面的元认知能力并不稳定。而 AGENTS.md 直接提供了信息，Agent 无需做决策，直接使用即可。 持续的可用性：Skills 是异步加载的，且只有被调用时才存在。而 AGENTS.md 的内容在每一轮对话的 System Prompt 中都始终存在，确保了知识的连贯性。 避免了顺序问题：Skills 引入了复杂的执行顺序问题（是先看代码还是先看文档？）。被动上下文完全规避了这个问题，它只是作为背景知识静默存在，随时待命。
直接把海量文档塞进 Prompt 显然不可行，会消耗大量 Token 甚至撑爆上下文窗口。Vercel 采用了一种巧妙的压缩策略：
他们不在 AGENTS.md 中放入文档全文，而是放入一个约 8KB 大小的索引。这个索引包含文件路径结构和精简的映射。Agent 看到索引后，知道去哪里寻找具体的文档文件（例如 .next-docs/ 目录），然后按需读取具体文件。这既保持了上下文的轻量，又保留了全量知识的精确索引能力。
对开发者的启示Vercel 的这项实验为所有致力于 AI 应用开发的工程师提供了重要启示：
对于框架作者而言，不要指望 Agent 能通过通用的“搜索”或“工具”自动学会你的新框架。提供一个标准化的 AGENTS.md 索引片段，让用户添加到项目中，是目前确保 AI 写出正确代码的最可靠方式。
对于广大开发者来说，不要过度迷信 Agent 的自主决策能力。目前的模型在“何时使用工具”的判断上仍然很弱。Context is King，与其花时间调优复杂的 Agent 工具链，不如通过精心设计的 Prompt 和上下文文件直接“喂”给模型关键信息。拥抱 RAG，优先检索推理，才是当前阶段最稳健的 AI 编程实践。
