AI编码Agent最大的坑不是模型不够聪明，而是训练数据过时。Next.js出了新API，Agent还在用半年前的写法生成代码——你review的时候才发现全是废的。
Vercel和Google这周分别公布了各自的解决方案和测试数据。结论出人意料：一个8KB的纯文本文件，效果完爆需要主动调用的Skill系统。
问题到底出在哪
不管是Claude、Gemini还是GPT，模型的训练数据都有截止日期。框架更新了API、废弃了旧方法、改了配置格式，模型全不知道。
典型症状：
- Next.js的App Router写法生成成Pages Router的代码
- 用已经废弃的API，运行直接报错
- 配置文件格式过时，build都过不了
之前业界的思路是做一套Skill系统——把最新文档打包成”技能包”，Agent需要的时候主动去调用。听起来很合理对吧？
Vercel的Skill系统：Agent在56%的情况下根本不调用
Vercel做了一组严格的评测，117个编码任务，对比三种方案：
| 方案 | 通过率 | 备注 |
|---|---|---|
| 无文档基线 | 53% | Agent靠训练数据硬猜 |
| Skill系统（默认） | 53% | 和没有文档一模一样 |
| Skill系统（强制调用） | 79% | 必须在prompt里写”You MUST invoke the skill” |
| AGENTS.md | 100% | 8KB压缩文档，每轮自动注入 |
你没看错，默认情况下Skill系统的通过率和没有文档完全一样。
为什么？因为Agent在56%的测试里压根没调用Skill。文档就在那里，Agent就是不去拿。这不是bug，这是LLM的”决策疲劳”——每次调用Skill都是一个额外的推理步骤，模型需要判断”我现在需不需要查文档”，而这个判断本身就经常出错。
更离谱的是强制调用的措辞问题。”You MUST invoke the skill”会导致Agent跳过项目上下文直接查文档，生成的代码和项目不匹配。换成”Explore project first, then invoke skill”效果好一些，但措辞差一个词结果就天差地别——这在生产环境是不可接受的。
AGENTS.md：什么都不用做，100%通过
AGENTS.md的思路完全相反。不让Agent自己决定要不要查文档，直接把文档塞进系统上下文里。
Vercel的做法：
- 把Next.js的完整文档索引（40KB）压缩到8KB
- 放在项目根目录的AGENTS.md文件里
- Agent每轮对话自动读取，不需要任何主动调用
8KB装不下完整文档，但装得下一个精确的索引——告诉Agent每个API在哪个文件里、当前版本的正确用法是什么、哪些方法已经废弃。Agent需要细节的时候，根据索引去读对应的源文件。
这个方案的三个关键优势：
零决策点：信息已经在上下文里了，Agent不需要判断”我要不要去查文档”。消除了56%不调用的问题。
每轮可用：AGENTS.md内容在每次对话轮次都存在，不会因为Agent忘了调用而丢失上下文。
无时序依赖：Skill系统有”先查项目还是先查文档”的顺序问题，AGENTS.md没有。
Google的数据：Agent Skill让Gemini成功率从28%飙到96%
Google这周也发布了自己的Agent Skill方案，数据同样炸裂。
在117个编码任务上，Gemini 3.1 Pro Preview的成功率：
- 不用Skill：28.2%
- 用了Agent Skill：96.6%
但有个重要细节：老模型基本没啥改善。Gemini 2.5系列用了Skill提升很小，Google自己说原因是”推理能力不够”。换句话说，Skill系统对模型的推理能力有硬性要求——模型得足够聪明才能正确地使用Skill。
这恰好验证了Vercel的发现：Skill系统的瓶颈不在文档质量，而在模型的”元认知”能力——它能不能判断出自己需要帮助，以及什么时候需要。
Google的Agent Skill开源在GitHub上（google-gemini/gemini-skills），内容是Gemini API的最新模型信息、SDK用法和示例代码。本质上和AGENTS.md是一个思路，只是Google用了Skill的形式来分发。
实际项目里怎么用
如果你在用Cursor、Claude Code、GitHub Copilot或者其他AI编码工具，现在就可以开始用AGENTS.md。
最简单的做法：在项目根目录创建AGENTS.md，写上项目的关键约定：
# Project: my-nextjs-app # Framework: Next.js 15.2 (App Router) # Language: TypeScript 5.7 ## Routing - All routes use App Router (app/ directory) - Do NOT use Pages Router patterns - Dynamic routes: app/[slug]/page.tsx ## Data Fetching - Use Server Components by default - Client components must have 'use client' directive - API routes in app/api/ using Route Handlers ## Styling - Tailwind CSS v4 - No CSS Modules - Design tokens in tailwind.config.ts ## State Management - Server state: React Server Components - Client state: Zustand (not Redux) ## Testing - Vitest for unit tests - Playwright for E2E - Test files: __tests__/ co-located with source
进阶做法：用框架官方提供的工具自动生成。Next.js已经有了：
npx @next/codemod@canary agents-md
该命令会检测你安装的Next.js版本，拉取对应的文档，压缩后写入AGENTS.md。
如果你的框架没有官方工具，手动写也不复杂。核心是三类信息：
- 版本和技术栈：框架版本、语言版本、核心依赖
- 约定和禁忌：项目用什么不用什么，哪些模式是禁止的
- 文件结构：关键目录的用途，Agent该去哪里找什么
控制在8-15KB以内，太长了反而影响Agent处理其他上下文的能力。
AGENTS.md已经成了行业标准
2025年12月，Linux基金会成立了Agentic AI Foundation（AAIF），OpenAI、Anthropic、Google、Microsoft这些死对头破天荒坐在一起，定了三个核心开源标准：
- AGENTS.md（OpenAI主导）：编码指令的标准格式
- MCP（Anthropic主导）：模型和外部数据源的连接协议
- Goose（Block主导）：Agent工作流框架
AGENTS.md目前已经被超过6万个开源项目采用，Cursor、Devin、GitHub Copilot、Gemini CLI都原生支持。
这意味着你写一次AGENTS.md，所有AI编码工具都能读懂。不用为Cursor写一套规则、为Copilot写另一套。
Skill不是没用，但场景不同
Vercel明确说了，Skill系统在特定场景下更合适：
- 垂直操作型任务：比如”升级我的Next.js版本”，需要执行一系列具体步骤
- 知识量太大的领域：整个AWS SDK的文档塞不进AGENTS.md，需要按需检索
- 多工具协作：Agent需要调用外部API完成任务时，Skill提供了标准化的封装
但对于日常编码——”帮我写个组件”、”这个bug怎么修”、”加个新的API路由”——AGENTS.md就够了，而且更可靠。
我的判断
AGENTS.md干翻Skill系统这件事，本质上反映了一个更深层的问题：当前LLM的元认知能力还不够。
模型写代码的能力已经很强了，但”判断自己需不需要额外信息”这个能力还很弱。Skill系统假设模型能做好这个判断，现实是56%的时候它判断错了。
AGENTS.md的解决思路很”笨”——不相信模型的判断力，直接把信息塞给它。但在当前阶段，这个笨办法就是最可靠的。
等模型的推理能力再上一个台阶（Google的数据已经暗示了这个趋势），Skill系统可能会反超。但现在，先把AGENTS.md配好，是性价比最高的选择。
