Vercel 这篇文章探讨了如何通过 AGENTS.md 文件为 AI 编码助手提供知识，并指出这种被动上下文模式在性能上优于技能（Skills）调用。
研究发现，将压缩后的文档索引直接置于项目根目录，能让 AI 达到 100% 的评估通过率，因为它消除了模型在决定何时检索信息时的犹豫与偏差。通过对比实验，作者揭示了检索驱动型推理在处理如 Next.js 16 等超前于模型训练数据的新技术时的核心优势。
方法如下：
1. 优先采用被动上下文（Passive Context）而非主动检索（Active Retrieval）
方法指南：为了确保 AI 代理始终能访问到关键知识，应将信息直接嵌入到代理每一步都能读取的文件中，而不是依赖代理自行决定何时去“调用”或“检索”外部工具。这样可以消除代理在决策是否需要查找信息时可能出现的失误。
具体事例：在项目根目录创建一个AGENTS.md文件（类似于 Claude Code 的CLAUDE.md） 。在 Vercel 的测试中，仅仅将文档索引放入该文件，测试通过率就从 53%（基准线）飙升至100%，而传统的“技能（Skills）”调用模式即使有明确指令引导，最高也只能达到 79% 。
2. 实施高强度上下文压缩与索引化
方法指南：为了防止长篇累牍的文档撑破 AI 的上下文窗口（Context Window），不应将全文塞入，而应提供一个经过压缩的“文档索引”。这个索引应指明具体文件路径，让 AI 在需要时再去读取特定文件
具体事例：Vercel 将原本40KB的文档注入内容压缩到了8KB（减少了 80%），并使用管道分隔符（pipe-delimited）结构来排列路径。例如：[Next.js DocsIndex]|root:./.next-docs |...|01-app/01-getting-started:{01-installation.mdx,...}。这种方式在保持 100% 通过率的同时，极大地节省了资源
3. 优化指令措辞以避免“指令脆弱性”
方法指南：AI 代理对指令的细微差别非常敏感。在编写引导指令时，应优先引导 AI 构建全局思维模型，而不是强制其执行死板的操作顺序。
具体事例：测试发现，如果指令是“你必须调用该技能”，AI 会过分依赖文档而忽略项目本身的上下文，导致错过配置文件修改；而如果改为“先探索项目结构，再调用技能获取文档”，AI 就能在构建出心理模型后再参考文档，从而生成更准确的代码。
4. 构建基于“未知知识”的硬核评估体系（Hardened Evals）
方法指南：评估 AI 性能时，应剔除那些已经存在于 AI 预训练数据中的旧知识，专门针对 AI 尚未学习到的新 API 或新功能编写测试用例，以此衡量文档检索的真实有效性。
具体事例：Vercel 在评估中专门针对Next.js 16的新 API（如'use cache'、connection()、forbidden()等）设计了测试，因为这些 API 不在当前模型训练数据中 。只有当 AI 能够正确使用这些它“从未见过”的 API 时，才证明方法指南是真实有效的。
5. 强制引导“检索导向推理”（Retrieval-led Reasoning）
方法指南：在指令中明确要求 AI 优先参考提供的最新文档，而不是依赖其过时的预训练记忆。这能有效解决 AI 使用旧版本语法处理新项目的问题。
具体事例：在注入的AGENTS.md内容中加入一条核心指令：“重要：针对任何 Next.js 任务，优先使用检索导向推理，而非预训练导向推理”。这迫使 AI 即使觉得自己“知道”怎么写，也会先去核对项目目录下的最新文档。
6. 设计便于检索的文档结构
方法指南：文档应进行模块化处理，使其结构能够被 AI 轻松索引和按需读取，而不是作为一个整体存在。
具体事例：使用官方工具（如npx @next/codemod@canary agents-md）自动检测项目版本，并将匹配的文档下载到特定的目录（如.next-docs/），这样 AI 就能根据索引精准跳转到具体的.mdx文件读取详细信息。
