在Next.js 16 API的测试中，直接嵌入8KB文档索引的AGENTS.md实现了100%通过率，而传统技能方法最高仅79%。研究表明，AI编码助手需要即时更新的文档支持，而非依赖可能过时的训练数据。

标题：AGENTS.md在智能体评估中表现优于技能方案

核心发现

在针对Next.js 16 API的评估测试中，直接嵌入项目的8KB压缩版本文档索引（AGENTS.md）实现了100%通过率，而传统技能方案即使在明确指令下最高仅达79%通过率。未触发技能时，其表现与无文档支持的情况无异。

研究背景

AI编程智能体依赖的训练数据存在时效性问题。Next.js 16引入的'use cache'、connection()等新API尚未被模型掌握，导致生成错误代码或回退旧模式。团队试图通过版本匹配的文档解决该问题。

对比方案

1. 技能方案

   • 开放标准化的领域知识包（含提示词、工具和文档）
   • 需智能体主动调用，存在触发率问题
   • 默认情况下触发率仅56%，通过率与基线持平（53%）
   • 添加明确指令后触发率达95%+，通过率提升至79%

2. AGENTS.md方案

   • 项目根目录的Markdown文件，提供持久化上下文
   • 无需决策触发，内容始终可用
   • 关键指令："优先基于检索推理而非预训练推理"
   • 通过压缩技术将文档索引从40KB降至8KB

性能表现

| 配置方案 | 综合通过率 | 构建通过率 | 代码检查 | 测试通过率 | |-------------------------|------------|------------|----------|------------| | 无文档支持（基线） | 53% | 84% | 95% | 63% | | 默认技能方案 | 53% | 84% | 89% | 58% | | 带指令的技能方案 | 79% | 95% | 100% | 84% | | AGENTS.md方案 | 100% | 100% | 100% | 100% |

优势分析

1. 决策简化：消除"是否查阅文档"的判断环节
2. 持续可用：内容直接写入系统提示词
3. 顺序优化：避免"先读文档还是先探索项目"的时序问题
4. 精准检索：压缩索引指向具体文档文件，非全文嵌入

实践建议

• 通过命令快速部署：npx @next/codemod@canary agents-md
• 框架作者应提供可集成的AGENTS.md片段
• 文档结构需支持精准检索（非全文加载）
• 评估需针对训练数据未覆盖的API

结论

对于框架通用知识，被动上下文方案当前优于按需检索。技能方案仍适用于特定垂直场景（如版本迁移），但基础认知层面AGENTS.md更可靠实现"检索优先"的推理模式。

（研究由Jude Gao主导，完整CLI工具已发布）

以下是评论内容的总结：

主要观点和论据

1. AGENTS.md与Skills的比较

   • 支持AGENTS.md：认为AGENTS.md通过压缩和直接引用文档，提高了模型的效率和准确性。
     • 引用："The key finding is that 'compression' of doc pointers works."（评论25）
     • 引用："Obviously directly including context in something like a system prompt will put it in context 100% of the time."（评论10）
   • 支持Skills：认为Skills更具扩展性和模块化，适合复杂任务。
     • 引用："The advantage of skills is exactly that you don't cram them all into the AGENTS file."（评论12）
     • 引用："Skills optimize for extensibility and explicit capability boundaries."（评论14）

2. 模型训练与技能使用

   • 部分评论认为当前模型未充分训练使用Skills，未来会改善。
     • 引用："Skills are new. Models haven’t been trained on them yet. Give it 2 months."（评论4）
     • 引用："This seems like an issue that will be fixed in newer model releases."（评论7）

3. 测试方法与一致性

   • 对测试方法的透明度提出质疑，认为LLM的输出不一致性需更多测试。
     • 引用："Did they run it once, or multiple times? LLMs are not consistent for the same task."（评论6）
     • 引用："It’s not safe to assume that Codex or Gemini will behave the same way as Claude."（评论13）

4. 技术实现建议

   • 提出改进技术实现的建议，如使用.context文件夹或优化文件路径。
     • 引用："Create a folder called .context and symlink anything in there that is relevant."（评论21）
     • 引用："You need to make sure your file paths are self-explanatory and fairly unique."（评论24）

5. 批评与质疑

   • 部分评论认为文章分析浅显或误解了Skills的设计初衷。
     • 引用："This feels like the most shallow 'I compare LLMs based on the specs' kind of analysis."（评论26）
     • 引用："The article presents AGENTS.md as something distinct from Skills, but it is actually a simplified instance of the same concept."（评论11）

总结

评论中既有对AGENTS.md效率的肯定，也有对Skills扩展性的支持，同时指出了模型训练和测试方法的不足。技术实现建议和批评声音也体现了对当前技术发展的多样看法。