提升 AI Agent 性能 2 倍的 agents.md 策略：为何上下文比技术更重要

这是一个 AI Agent 编写代码、构建基础设施的时代。然而，一线的开发人员仍然感到不安。因为刚才还表现完美的 Agent 可能会突然给出离谱的回答，或者频繁忽略明确指示的工具。

Vercel AI SDK 团队最近的实验结果令人震惊。当把工具选择权（即技能 Skills）交给 AI Agent 时，发生的失败率竟然高达 56%。这并不是模型智商的问题，而是证明了我们向 AI 提供信息的方式存在根本性的错误。将 Agent 成功率提升至 100% 的秘诀不在于增加工具，而在于基于 agents.md 的持续上下文策略。

---

为什么 AI 技能模式在实际应用中会失败

许多开发人员赋予 Agent 各种工具调用功能，并期待 AI 在需要时能自主调用。但这种方式存在一个致命弱点，即“决策噪声”。

对话越长越容易产生的上下文腐败

AI 模型的上下文窗口就像人类的短期记忆。当对话往返超过 5 次以上，系统提示词（System Prompt）中最初写入的指令优先级就会降低。这被称为“上下文腐败”。Agent 在每一刻都在纠结：我现在该用工具呢，还是直接根据已知信息回答？这个决策点本身就成了诱发失败的单点故障。

---

agents.md：实现 100% 成功率的被动上下文

将 56% 的失败率降至 0% 的方法很简单。与其给 Agent 选择权，不如将项目的核心规则和信息固定在系统提示词中。而 agents.md 文件正是这一策略的核心。

为什么 agents.md 更强大

根据 Vercel 的基准测试，当以工具形式提供相同信息时，成功率为 79%；但当以索引形式直接包含在 agents.md 中时，记录到了 100% 的通过率。

• 消除决策点： Agent 无需纠结是否要查找文档，而是立即参考眼前的核心信息。
• 以搜索为中心的推理： 强制模型遵循提供的最新文档路径，而不是依赖其内部记忆。
• 保持时效性： 即使是训练数据中没有的最新 API 规则，也能确保毫无误差地被遵守。

分析指标	工具调用方式 (Skills)	持续上下文 (agents.md)
决策制定	Agent 每次决定是否加载	信息始终常驻系统中
可靠性	约 53% ~ 79% (不稳定)	最高可达 100%
推理负荷	决策噪声导致的高负荷	省略决策过程，低负荷
特点	按需 (On-demand) 方式	被动 (Passive) 方式

---

高效 agents.md 设计的 3 阶段路线图

要最大化性能，必须将 agents.md 设计为一份“给机器看的 README”，而不仅仅是一个简单的文本文件。

1. 明确标出约束条件

相比抽象的原则，具体的禁止事项能更直接地提高 Agent 的产出质量。例如，需要明确命令“使用 MUI v3 并必须使用 Jotai 进行状态管理”。通过指示“绝不要使用 alert()，务必利用特定库的组件”来防止 Agent 偏离轨道。

2. 结构可视化与执行命令提供

不应让 Agent 漫无目的地浏览整个仓库并浪费 Token。必须以“微型索引”的形式提供核心文件位置。通过清晰的地图告诉它：构建时是否应使用 pnpm，路由文件和 Schema 文件位于何处。

3. 8KB 原则：压缩文档索引

文件过于肥大反而会导致性能下降。Vercel 建议将 40KB 的文档压缩至 8KB 后进行索引。核心在于优化并传递访问知识的路径，而不是强行喂给 Agent 知识本身。

---

防止提示词债务的协作接口

正如代码会积累技术债务，AI 的使用也会积累“提示词债务”。如果每个团队成员给 Agent 的指令都不同，产出的一致性就会崩溃。将 agents.md 放在项目根目录并通过 Git 进行管理，可以实现版本控制的统一，无论使用哪种模型，都能应用相同的团队标准指南。

在 AI Agent 时代，胜负的关键在于“上下文工程”而非模型智力。与其等待 Agent 变得更聪明，不如构建一个让 Agent 无法犯错的环境，这才是提高生产力最可靠的途径。现在就开始在项目根目录创建 agents.md，并将团队规则条文化吧。