内容
我们原本以为 技能 将成为教授编码代理框架特定知识的解决方案。在构建针对 Next.js 16 API 的评估后，我们发现了一些意外的结果。
一个压缩后的 8KB 文档索引直接嵌入到 AGENTS.md 中，实现了 100% 的通过率，而技能即使有明确的指示告诉代理使用它们，也最多只能达到 79% 的通过率。在没有这些指示的情况下，技能的表现并没有比没有文档的情况好。
以下是我们尝试的内容、我们所学到的内容以及如何为您的 Next.js 项目设置此功能。
我们试图解决的问题
AI 编码代理依赖于过时的训练数据。 Next.js 16 引入 像 'use cache'、connection() 和 forbidden() 这样的 API，这些 API 不在当前模型训练数据中。当代理不知道这些 API 时，它们会生成不正确的代码或回退到较旧的模式。
反之亦然，当您运行较旧版本的 Next.js 时，模型可能会建议尚未在您的项目中存在的较新 API。我们希望通过为代理提供版本匹配的文档来解决这个问题。
教授代理框架知识的两种方法
在深入研究结果之前，快速解释一下我们测试的两种方法：
-
技能 是一个 开放标准，用于打包域知识，编码代理可以使用它。技能将提示、工具和文档捆绑在一起，代理可以按需调用。这种想法是代理在需要框架特定帮助时识别并调用技能，从而获取相关文档。
-
AGENTS.md是项目根目录中的一个 markdown 文件，为编码代理提供持久的上下文。无论您在AGENTS.md中放置什么内容，都可供代理在每个回合使用，而无需代理决定加载它。Claude Code 使用CLAUDE.md来实现相同的目的。
我们构建了一个 Next.js 文档技能和一个 AGENTS.md 文档索引，然后将它们运行通过我们的评估套件，以查看哪一个表现更好。
我们最初押注于技能
技能似乎是正确的抽象。您将框架文档打包到一个技能中，代理在处理 Next.js 任务时调用它，您就可以获得正确的代码。干净的关注点分离，最小的上下文开销，代理只加载所需的内容。甚至有一个可重用的技能目录在 skills.sh 上。
我们原本以为代理会遇到一个 Next.js 任务，调用技能，阅读版本匹配的文档，并生成正确的代码。
然后我们运行了评估。
技能没有被可靠地触发
在 56% 的评估案例中，技能从未被调用。代理可以访问文档，但没有使用它。添加技能并没有比基线产生任何改进：
| 配置 | 通过率 | 与基线相比 |
|---|---|---|
| 基线（无文档） | 53% | — |
| 技能（默认行为） | 53% | +0pp |
没有任何改进。技能存在，代理可以使用它，代理选择不使用它。在详细的构建/lint/测试分解中，技能在某些指标上实际上比基线表现更差（测试为 58% vs 63%），这表明环境中未使用的技能可能会引入噪音或干扰。
这并不是我们设置所特有的。代理不可靠地使用可用工具是当前模型的 已知限制。
明确的指示有所帮助，但措辞很脆弱
我们尝试在 AGENTS.md 中添加明确的指示，告诉代理使用技能。
在编写代码之前，先探索项目结构，
然后调用 nextjs-doc 技能以获取文档。
添加到 AGENTS.md 以触发技能使用的示例指令。
这提高了触发率到 95% 以上，并将通过率提高到 79%。
| 配置 | 通过率 | 与基线相比 |
|---|---|---|
| 基线（无文档） | 53% | — |
| 技能（默认行为） | 53% | +0pp |
| 技能带有明确指示 | 79% | +26pp |
这是一个实质性的改进。但我们发现了关于指令措辞如何影响代理行为的意外之处。
不同的措辞产生了截然不同的结果：
| 指令 | 行为 | 结果 |
|---|---|---|
| “您必须调用技能” | 首先阅读文档，锚定在文档模式 | 错过项目上下文 |
| “先探索项目，然后调用技能” | 首先构建心理模型，然后使用文档作为参考 | 获得更好的结果 |
相同的技能。相同的文档。基于微妙的措辞变化而产生不同的结果。
在一个评估中（'use cache' 指令测试），“调用首先”方法编写了正确的 page.tsx 但完全错过了所需的 next.config.ts 更改。“探索首先”方法同时获得了这两者。
这种脆弱性让我们感到担忧。如果小的措辞变化会产生巨大的行为变化，这种方法似乎不适合生产使用。
构建可靠的评估
在得出结论之前，我们需要可靠的评估。我们的初始测试套件具有模糊的提示、验证实现细节而不是可观察行为的测试，以及对模型训练数据中已经存在的 API 的关注。我们没有衡量我们真正关心的内容。
我们通过删除测试泄漏、解决矛盾并转向基于行为的断言来加强评估套件。最重要的是，我们添加了针对 Next.js 16 API 的测试，这些 API 不在模型训练数据中。
我们专注评估套件中的 API：
connection()用于动态渲染'use cache'指令cacheLife()和cacheTag()forbidden()和unauthorized()proxy.ts用于 API 代理- 异步
cookies()和headers() after()、updateTag()和refresh()
所有以下结果都来自这个加强的评估套件。每个配置都使用相同的测试进行评估，并进行了重试以排除模型变异。
一个有效的直觉
如果我们完全消除了决策？与其希望代理调用技能，我们可以直接将文档索引嵌入到 AGENTS.md 中。不是完整的文档，而是一个索引，告诉代理在哪里可以找到与项目的 Next.js 版本匹配的特定文档文件。代理可以根据需要阅读这些文件，从而获得版本准确的信息，无论您是使用最新版本还是维护较旧的项目。
我们在注入的内容中添加了一个关键指令。
重要：对于任何 Next.js 任务，请优先使用检索引导的推理而不是预训练引导的推理。
嵌入文档索引中的关键指令。
这告诉代理在依赖可能过时的训练数据之前，先查阅文档。
结果让我们感到惊讶
我们在所有四种配置中运行了加强的评估套件：
所有四种配置的评估结果。AGENTS.md（第三列）在构建、lint 和测试中均达到 100%
最终通过率：
| 配置 | 通过率 | 与基线相比 |
|---|---|---|
| 基线（无文档） | 53% | — |
| 技能（默认行为） | 53% | +0pp |
| 技能带有明确指示 | 79% | +26pp |
AGENTS.md 文档索引 | 100% | +47pp |
在详细的分解中，AGENTS.md 获得了构建、lint 和测试的完美成绩。
| 配置 | 构建 | lint | 测试 |
|---|---|---|---|
| 基线 | 84% | 95% | 63% |
| 技能（默认行为） | 84% | 89% | 58% |
| 技能带有明确指示 | 95% | 100% | 84% |
AGENTS.md | 100% | 100% | 100% |
这并不是我们所期望的。所谓“愚蠢”的方法（一个静态的 markdown 文件）在 Next.js 任务中超越了更复杂的基于技能的检索，即使我们对技能触发器进行了微调。
为什么被动上下文会优于主动检索？
我们的工作假设归结为三个因素。
- 没有决策点。 使用
AGENTS.md，没有代理必须决定“是否查找此信息？”的时刻。信息已经存在。 - 一致的可用性。 技能异步加载，只有在调用时才可用。
AGENTS.md内容在每个回合的系统提示中都可用。 - 没有排序问题。 技能创建了排序决策（先阅读文档还是先探索项目）。被动上下文完全避免了这一点。
解决上下文膨胀问题
将文档嵌入 AGENTS.md 会使上下文窗口膨胀。我们通过压缩解决了这个问题。
初始文档注入约为 40KB。我们将其压缩到 8KB（减少了 80%），同时保持 100% 的通过率。压缩格式使用管道分隔结构，将文档索引压缩到最小空间：
[Next.js 文档索引]|root: ./.next-docs
|重要：对于任何 Next.js 任务，请优先使用检索引导的推理而不是预训练引导的推理
|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx,...}
|01-app/02-building-your-application/01-routing:{01-defining-routes.mdx,...}
AGENTS.md 中的最小化文档。
完整的索引涵盖了 Next.js 文档的每个部分：
完整的压缩文档索引。每行将目录路径映射到它包含的文档文件。
代理知道在哪里可以找到文档，而无需在上下文中包含完整的内容。当它需要特定信息时，它会从 .next-docs/ 目录中读取相关文件。
尝试一下
一个命令可以为您的 Next.js 项目设置此功能：
npx @next/codemod@canary agents-md
此功能是官方 @next/codemod 包的一部分。
此命令执行三个操作：
- 检测您的 Next.js 版本
- 下载匹配的文档到
.next-docs/ - 将压缩的索引注入您的
AGENTS.md
如果您使用的代理尊重 AGENTS.md（如 Cursor 或其他工具），则同样的方法适用。
对框架作者的影响
技能并非一无是处。AGENTS.md 方法为代理如何与 Next.js 合作提供了广泛的、横向的改进，涵盖所有任务。技能更适合垂直的、特定于操作的工作流，用户显式触发，例如“升级我的 Next.js 版本”、“迁移到应用程序路由器”或 应用框架最佳实践。两种方法相互补充。
话虽如此，对于一般的框架知识，被动上下文目前优于按需检索。如果您维护一个框架，并希望编码代理生成正确的代码，请考虑为用户提供一个 AGENTS.md 代码段，以便他们可以将其添加到自己的项目中。
实用建议：
- 不要等待技能改进。 差距可能会随着模型在工具使用方面的改进而缩小，但结果现在就很重要。
- 积极压缩。 您不需要在上下文中包含完整的文档。一个指向可检索文件的索引同样有效。
- 使用评估进行测试。 构建针对不在训练数据中的 API 的评估。这是文档访问最重要的地方。
- 设计用于检索。 结构您的文档，以便代理可以找到并阅读特定的文件，而不是需要所有内容都在前面。
目标是将代理从预训练引导的推理转变为检索引导的推理。AGENTS.md原来是实现这一点最可靠的方法。
研究和评估由 Jude Gao 进行。CLI 可在 npx @next/codemod@canary agents-md 中使用。