推荐语

Vercel实验颠覆认知：简单被动的AGENTS.md完胜复杂主动的Skills，AI编程助手开发迎来新思路。

核心内容：
1. Skills模式与AGENTS.md模式的实验设计与对比结果
2. AGENTS.md实现100%通过率的关键机制解析
3. 当前AI开发中过度迷信Agent自主决策能力的反思

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

Vercel 团队近期公布了一项令人惊讶的实验结论：在为 AI Coding Agent 提供框架知识时，简单被动的上下文文件「AGENTS.md」比复杂的、主动调用的「Skills」更有效。这一发现挑战了当前 AI 开发中过度迷信 Agent 自主决策能力的趋势，为构建高可靠性的编程助手提供了新的思路。

两种知识获取路径的较量

为了测试 AI Coding Agent 获取新知识的最佳方式，Vercel 团队基于 Next.js 16 的新 API 建立了一套评估测试集，对比了两种截然不同的方法：

• Skills（技能模式）：这是一种按需调用的工具包，包含提示词和文档。Agent 需要“意识到”自己不懂，然后主动调用该工具获取帮助。
• AGENTS.md（上下文模式）：这是一个放置在项目根目录的 Markdown 文件，作为持久的上下文信息直接提供给 Agent。

实验结果：智能的“脆弱” vs 笨办法的“完美”

对比结果令人大跌眼镜，被寄予厚望的 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）主要有三个深层原因：

1. 消除了决策点：使用 Skills 时，Agent 必须自己判断“我是否需要帮助？”以及“我该何时调用工具？”。当前的 LLM 在这方面的元认知能力并不稳定。而 AGENTS.md 直接提供了信息，Agent 无需做决策，直接使用即可。
2. 持续的可用性：Skills 是异步加载的，且只有被调用时才存在。而 AGENTS.md 的内容在每一轮对话的 System Prompt 中都始终存在，确保了知识的连贯性。
3. 避免了顺序问题：Skills 引入了复杂的执行顺序问题（是先看代码还是先看文档？）。被动上下文完全规避了这个问题，它只是作为背景知识静默存在，随时待命。

技术实现：如何避免 Context 爆炸？

直接把海量文档塞进 Prompt 显然不可行，会消耗大量 Token 甚至撑爆上下文窗口。Vercel 采用了一种巧妙的压缩策略：

他们不在 AGENTS.md 中放入文档全文，而是放入一个约 8KB 大小的索引。这个索引包含文件路径结构和精简的映射。Agent 看到索引后，知道去哪里寻找具体的文档文件（例如 .next-docs/ 目录），然后按需读取具体文件。这既保持了上下文的轻量，又保留了全量知识的精确索引能力。

对开发者的启示

Vercel 的这项实验为所有致力于 AI 应用开发的工程师提供了重要启示：

对于框架作者而言，不要指望 Agent 能通过通用的“搜索”或“工具”自动学会你的新框架。提供一个标准化的 AGENTS.md 索引片段，让用户添加到项目中，是目前确保 AI 写出正确代码的最可靠方式。

对于广大开发者来说，不要过度迷信 Agent 的自主决策能力。目前的模型在“何时使用工具”的判断上仍然很弱。Context is King，与其花时间调优复杂的 Agent 工具链，不如通过精心设计的 Prompt 和上下文文件直接“喂”给模型关键信息。拥抱 RAG，优先检索推理，才是当前阶段最稳健的 AI 编程实践。