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 文件读取详细信息。
393
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
