# AGENTS.md 持久上下文为何优于按需技能调用：Vercel 代理评估深度解析 > 解析 Vercel 对比测试：AGENTS.md 实现 100% 通过率而技能仅 53%，揭示被动持久上下文在代理评估中的核心优势与工程实践。 ## 元数据 - 路径: /posts/2026/01/30/vercel-agents-md-outperforms-skills-agent-evals/ - 发布时间: 2026-01-30T12:17:05+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 站点: https://blog.hotdry.top ## 正文 AI 编程代理在现代开发工作流中扮演着越来越重要的角色，但它们面临一个根本性的矛盾：模型的知识来自预训练数据，而框架和库的 API 却在持续快速迭代。当 Next.js 16 引入 `'use cache'`、`connection()`、`forbidden()` 等新特性时，基于预训练的代理很可能一无所知，要么生成错误代码，要么回退到过时的模式。Vercel 团队近期进行的一项系统性对比实验，为这一困境提供了意想不到的解决方案，其结论可能重塑我们向代理传授框架知识的方式。 ## 两种范式的本质差异 在深入数据之前，有必要理解 Vercel 对比的两种方案在架构上的根本区别。**Skills（技能）** 是一个开放标准，旨在将领域知识打包成可按需调用的单元。当代理识别到需要特定框架帮助时，它会主动调用相关技能，获取其中的文档、工具和提示。这意味着代理需要做出一个关键决策：当前任务是否需要调用某个技能？这个决策点引入了不确定性——如果代理未能识别调用时机，技能中的内容就形同虚设。 相比之下，**AGENTS.md** 采用了一种截然不同的思路。它是一个位于项目根目录的 Markdown 文件，其中包含的内容会成为系统提示词的一部分，在每一次交互中持久存在。代理无需决定是否加载它，因为相关信息已经在上下文之中。这种设计将"是否查找文档"这个决策从代理的职责中移除，转而依赖开发者在配置阶段的显式声明。Vercel 团队最初对技能方案寄予厚望，认为这种按需调用的模式更符合"关注点分离"的设计原则，但实验结果打破了这一预期。 ## 令人意外的基线数据 实验的第一阶段揭示了一个严峻的问题：在没有额外干预的情况下，技能方案几乎没有任何效果。基线配置（不提供任何文档）获得了 53% 的通过率，而添加技能后的默认行为同样停留在 53%，零提升。更令人担忧的是详细指标分析：在 Build、Lint、Test 三个维度的拆解中，技能在部分指标上甚至略低于基线（Test 从 63% 降至 58%），这暗示了环境中存在但未被使用的技能可能引入干扰或认知负担。 深入分析调用日志后，团队发现了一个惊人的事实：**在 56% 的评估场景中，技能从未被代理主动调用**。代理拥有技能的访问权限，却从未选择使用它。这并非 Vercel 特有的问题——OpenAI 自己的评估研究也承认，代理可靠地使用可用工具是当前模型的一个已知局限。模型在预训练阶段积累的模式匹配能力，有时会让它自信地"凭记忆行事"，而忽略显式提供的资源。 ## 指令微调的脆弱性 面对零提升的困境，团队尝试在 AGENTS.md 中添加显式指令，引导代理在编码前先探索项目结构并调用技能。这一干预取得了显著效果：通过率从 53% 跃升至 79%，提升了 26 个百分点。然而，进一步实验揭示了指令措辞的脆弱性。两种看似等效的指令产生了截然不同的行为和结果。 第一条指令采用强制性措辞："You MUST invoke the skill"。代理在执行任务前会首先阅读文档，但这也导致它过度锚定于文档模式，反而忽视了具体的项目上下文。在 `'use cache'` 指令测试中，它正确编写了 `page.tsx`，却完全遗漏了必需的 `next.config.ts` 修改。第二条指令调整了顺序："Explore project first, then invoke skill"。代理先建立对项目的整体认知，再将文档作为参考资源，结果在两个文件上都取得了正确实现。同一套技能、同一份文档，仅因指令措辞的细微差异，就产生了完全不同的工程结果。这种脆弱性让团队对基于技能的方案产生了根本性的质疑：如果生产环境中的行为对措辞如此敏感，任何小改动都可能引发难以预测的回归。 ## 硬化评估套件 在得出结论之前，Vercel 团队首先硬化了自己的评估方法论。初始测试套件存在几个严重问题：测试提示模糊、验证的是实现细节而非可观察行为、且过度依赖模型已经熟悉的 API。他们重新设计了评估套件，重点关注 Next.js 16 中那些**不在模型训练数据内**的新 API，包括 `connection()` 动态渲染、`'use cache'` 指令、`cacheLife()` 和 `cacheTag()` 缓存控制、`forbidden()` 和 `unauthorized()` 访问控制、`proxy.ts` API 代理，以及异步 `cookies()` 和 `headers()` 等。每个配置都在相同条件下运行，并采用多次重试以排除模型方差的影响。这一硬化过程确保了后续数据反映的是真实能力差异，而非测试设计缺陷。 ## 被动上下文的压倒性胜利 实验的第三阶段测试了团队的"直觉方案"：将文档索引直接嵌入 AGENTS.md，移除技能调用这个决策点。实现方式非常直接——不是在上下文中包含完整文档（那样会快速耗尽 token 预算），而是嵌入一个压缩的索引，指引代理在需要时读取 `.next-docs/` 目录下的具体文件。关键在于添加了一句指令："IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks." 结果令整个团队惊讶。**AGENTS.md 配置在 Build、Lint、Test 三个维度上全部实现了 100% 的通过率**，而基线仅为 53%，带显式指令的技能方案最高也只有 79%。从 53% 到 100% 的 47 个百分点差距，用"显著"已经不足以形容——这代表着两种方案在代理能力上的本质差异。更值得注意的是，在详细指标拆解中，AGENTS.md 在 Build（84% → 100%）、Lint（95% → 100%）、Test（63% → 100%）上全面领先。 团队总结出被动上下文优于主动检索的三个核心因素。首先是**无决策点**：代理无需判断"是否应该查找文档"，信息已经在上下文中。其次是**一致性可用性**：技能是异步加载的，且仅在调用时生效，而 AGENTS.md 的内容在每次交互中都存在。最后是**无排序问题**：技能方案需要决定"先读文档还是先探索项目"，而被动上下文避免了这种序列化的决策依赖。 ## 80% 压缩率与上下文管理 将完整文档嵌入上下文的明显风险是 token 消耗。初始注入的文档内容约为 40KB，这对于大多数上下文窗口来说已经捉襟见肘。团队开发了一套压缩方案，将文档索引压缩至仅 8KB，实现了 80% 的体积缩减，同时保持了 100% 的通过率。压缩格式采用管道分隔的结构，将文档目录映射紧凑地编码为单行索引。 压缩后的索引格式如下：`[Next.js Docs Index]|root: ./.next-docs|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx,...}|01-app/02-building-your-application/01-routing:{01-defining-routes.mdx,...}`。代理通过这个索引了解文档的组织结构，在需要时读取具体文件，而非一次性加载全部内容。这种设计既保证了关键信息的持久可用性，又将 token 消耗控制在可接受范围内。 ## 工程实践建议 基于这次实验，Vercel 团队为框架维护者和开发者提炼出几条可操作的建议。第一，**不要等待技能方案改进**：虽然未来模型可能会更好地处理工具调用，但当前评估结果已经表明 AGENTS.md 是更可靠的选择，延迟采用意味着持续承受的性能损失。第二，**积极压缩**：完整文档并非必要，指向可检索文件的索引同样有效，且能大幅节省上下文空间。第三，**用评估验证**：构建针对训练数据外 API 的测试用例，这是文档访问价值的最真实度量。第四，**面向检索设计文档结构**：确保文档组织清晰，使代理能够快速定位和读取所需文件，而非在庞大的内容中漫无目的地搜索。 值得注意的是，团队并未完全否定技能方案的价值。AGENTS.md 提供的是"广度、水平"的改进，适用于代理与框架交互的通用场景；而技能在"垂直、动作特定"的工作流中仍然更具优势，例如"升级我的 Next.js 版本"、"迁移到 App Router"等需要明确用户触发的任务。两种方案在实践中可以互补，而非互斥。 ## 结论 Vercel 的这项对比实验揭示了一个反直觉但极具价值的结论：在向 AI 代理传授框架知识这件事上，简单的持久上下文方案（AGENTS.md）优于设计更精巧的按需检索方案（Skills）。核心洞察在于移除了代理的决策负担——当文档信息始终可用时，代理无需判断何时应该查阅，专注于任务本身。这一发现对于任何构建或维护框架的人来说都具有直接的实际意义：通过提供可嵌入的 AGENTS.md 片段，可以显著提升依赖该框架的代理生成代码的正确性。 资料来源：Vercel Blog, "AGENTS.md outperforms skills in our agent evals" (2026-01-28)。 ## 同分类近期文章 ### [NVIDIA PersonaPlex 双重条件提示工程与全双工架构解析](/posts/2026/04/09/nvidia-personaplex-dual-conditioning-architecture/) - 日期: 2026-04-09T03:04:25+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 NVIDIA PersonaPlex 的双流架构设计、文本提示与语音提示的双重条件机制，以及如何在单模型中实现实时全双工对话与角色切换。 ### [ai-hedge-fund：多代理AI对冲基金的架构设计与信号聚合机制](/posts/2026/04/09/multi-agent-ai-hedge-fund-architecture/) - 日期: 2026-04-09T01:49:57+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析GitHub Trending项目ai-hedge-fund的多代理架构，探讨19个专业角色分工、信号生成管线与风控自动化的工程实现。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation-framework/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [LiteRT-LM C++ 推理运行时：边缘设备的量化、算子融合与内存管理实践](/posts/2026/04/08/litert-lm-cpp-inference-runtime-quantization-fusion-memory/) - 日期: 2026-04-08T21:52:31+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 LiteRT-LM 在边缘设备上的 C++ 推理运行时，聚焦量化策略配置、算子融合模式与内存管理的工程化实践参数。