渐进式加载：优化 AGENTS.md，提升 Agent 效率与准确性

学习如何为 AI 编码 Agent 优化你的 AGENTS.md 文件。掌握 progressive disclosure，保持指令聚焦，并最大化 Agent 性能。

什么是 AGENTS.md？

AGENTS.md 文件是一个你提交到 Git 的 Markdown 文件，用于定制 AI 编码 Agent 在你的代码仓库中的行为。它位于对话历史的顶部，紧接在系统提示词之下。

把它想象成 Agent 基础指令与实际代码库之间的一个配置层。该文件可以包含两类指导：

• 个人层面：你的提交风格偏好、你偏好的编码模式
• 项目层面：项目的用途、你使用的包管理器、你的架构决策

AGENTS.md 文件是一个开放标准，受到许多（虽然不是全部）工具的支持。

CLAUDE.md

值得一提的是，Claude Code 不使用 AGENTS.md，而是使用 CLAUDE.md。你可以在它们之间创建符号链接，让所有工具以相同方式工作：

## 创建从 AGENTS.md 到 CLAUDE.md 的符号链接
ln -s AGENTS.md CLAUDE.md

为什么庞大的 AGENTS.md 文件会是个问题

存在一个自然的反馈循环，会导致 AGENTS.md 文件膨胀到危险的地步：

1. Agent 做了一些你不喜欢的事情
2. 你添加了一条规则来阻止它
3. 在数月内重复数百次
4. 文件变成了一个"泥球"

不同的开发者往里面添加了相互冲突的意见。没有人做过一次完整的风格审查。结果是什么？一个难以维护的烂摊子，反而会损害 Agent 的性能。

另一个罪魁祸首：自动生成的 AGENTS.md 文件。绝不使用初始化脚本自动生成 AGENTS.md。这类脚本会用"对大多数场景都有用"的内容塞满文件，而这些内容更适合通过 progressive disclosure 来呈现。生成的文件优先考虑全面性，而不是克制。

指令预算

Humanlayer 的 Kyle 在文章中提到了"指令预算"的概念：

前沿思考型 LLM 能够相当稳定地遵循约 150-200 条指令。较小的模型能遵循的指令数量少于大模型，非思考型模型能遵循的指令数量也少于思考型模型。

你的 AGENTS.md 文件中的每一个 token 都会在每一次请求中被加载，无论它是否相关。这就带来了一个硬性预算问题：

场景	影响
小巧、聚焦的 AGENTS.md	有更多 token 可用于特定任务的指令
庞大、臃肿的 AGENTS.md	用于实际工作的 token 更少；Agent 感到困惑
无关的指令	Token 浪费 + Agent 分心 = 性能更差

综合来看，这意味着理想的 AGENTS.md 文件应该尽可能小。

过时的文档会污染上下文

大型 AGENTS.md 文件的另一个问题是内容过时。

文档很快就会过时。对于人类开发者来说，过时的文档很烦人，但人类通常有足够的既有认知来质疑那些糟糕的文档。对于每次请求都会阅读文档的 AI Agent 来说，过时的信息会主动污染上下文。

当你记录文件系统结构时，这尤其危险。文件路径不断变化。如果你的 AGENTS.md 写着"认证逻辑位于 src/auth/handlers.ts"，而该文件被重命名或移动，Agent 会自信地在错误的地方查找。

与其记录结构，不如描述能力。给出事物可能在哪里的提示，以及项目的整体形态。让 Agent 在规划过程中自行生成即时文档。

领域概念（如 "organization" vs "group" vs "workspace"）比文件路径更稳定，因此记录它们更安全。但即使在快速变化的 AI 辅助代码库中，这些概念也可能发生偏移。保持点到为止。

精简大型 AGENTS.md 文件

对于放进去的内容，要毫不留情。把以下内容视为绝对底线：

• 一句话项目描述（相当于一个基于角色的提示词）
• 包管理器（如果不是 npm；或使用 corepack 来处理警告）
• 构建/类型检查命令（如果非标准）

老实说，就这么多了。其他一切都应该放到别处。

一句话项目描述

这一句话让 Agent 明白自己为什么要在这个仓库中工作。它为 Agent 做出的每一个决策提供锚点。

示例：

这是一个用于无障碍数据可视化的 React 组件库。

这就是基础。Agent 现在明白了自己的职责范围。

包管理器规范

如果你的 JavaScript 项目使用的不是 npm，请明确告诉 Agent：

这个项目使用 pnpm workspaces。

如果没有这句话，Agent 可能会默认使用 npm 并生成错误的命令。

Corepack 也是个不错的选择。你还可以使用 corepack 让系统自动处理警告，从而为你节省宝贵的指令预算。

使用 Progressive Disclosure

与其把所有内容都塞进 AGENTS.md，不如使用 progressive disclosure：只给 Agent 当前需要的内容，并在需要时指向其他资源。

Agent 在浏览文档层级方面非常高效，对上下文的理解足以让它们找到所需内容。

将特定语言的规则移到独立文件中

如果你的 AGENTS.md 当前是这样的：

始终使用 const 而不是 let。

绝不使用 var。

尽可能使用 interface 而不是 type。

使用严格的空值检查。

...

把这些移到独立文件中。在你的根目录 AGENTS.md 中：

关于 TypeScript 约定，请参阅 docs/TYPESCRIPT.md

注意这种点到为止的写法：没有"始终"，没有全大写式的强制，只是一个对话式的引用。

好处：

• TypeScript 规则只在 Agent 编写 TypeScript 时才会加载
• 其他任务（CSS 调试、依赖管理）不会浪费 token
• 文件保持聚焦，并且在不同模型之间可移植

嵌套 Progressive Disclosure

你还可以更进一步。你的 docs/TYPESCRIPT.md 可以引用 docs/TESTING.md。创建一个可发现的资源树：

docs/
├── TYPESCRIPT.md
│   └── 引用 TESTING.md
├── TESTING.md
│   └── 引用具体的测试运行器
└── BUILD.md
    └── 引用 esbuild 配置

你甚至可以链接到外部资源，如 Prisma 文档、Next.js 文档等。Agent 会高效地浏览这些文档层级。

使用 Agent Skills

许多工具支持 "agent skills"——Agent 可以调用一些命令或工作流，来学习如何做某件特定的事情。这是 progressive disclosure 的另一种形式：Agent 只在需要时获取知识。

我们将在另一篇文章中深入介绍 agent skills。

Monorepo 中的 AGENTS.md

你并不局限于在根目录放一个 AGENTS.md。你可以在子目录中放置 AGENTS.md 文件，它们会与根目录的内容合并。

这对于 Monorepo 来说非常强大：

什么内容放在哪里

层级	内容
根目录	Monorepo 的用途、如何浏览各个包、共享工具（pnpm workspaces）
包	包的用途、具体技术栈、该包特有的约定

根目录 AGENTS.md：

这是一个包含 Web 服务和 CLI 工具的 Monorepo。

使用 pnpm workspaces 管理依赖。

有关具体指南，请参阅每个包的 AGENTS.md。

包级别的 AGENTS.md（位于 packages/api/AGENTS.md）：

这个包是使用 Prisma 的 Node.js GraphQL API。

API 设计模式请遵循 docs/API_CONVENTIONS.md。

不要让任何层级承载过多内容。 Agent 会在上下文中看到所有合并后的 AGENTS.md 文件。让每个层级只关注该层级内相关的内容。

用这个 Prompt 修复有问题的 AGENTS.md

如果你开始对自己仓库里的 AGENTS.md 文件感到担忧，想按 progressive disclosure 原则重构它，试试把这个 Prompt 复制粘贴到你的编码 Agent 中：

我希望你按照 progressive disclosure 原则重构我的 AGENTS.md 文件。

请遵循以下步骤：

1. **找出矛盾**：识别出所有相互冲突的指令。对于每个矛盾，询问我想保留哪个版本。

2. **识别核心内容**：只提取适合放进根目录 `AGENTS.md` 的内容：

   - 一句话项目描述
   - 包管理器（如果不是 npm）
   - 非标准的构建/类型检查命令
   - 任何真正与每一个任务都相关的内容

3. **对其余内容分组**：将剩余指令组织成逻辑类别（例如，TypeScript 约定、测试模式、API 设计、Git 工作流）。为每个类别创建单独的 markdown 文件。

4. **创建文件结构**：输出：

   - 一个极简的根目录 `AGENTS.md`，其中包含指向各个独立文件的 markdown 链接
   - 每个独立文件及其相关指令
   - 建议的 docs/ 文件夹结构

5. **标记待删除的内容**：找出以下类型的指令：

   - 冗余的（Agent 已经知道的）
   - 过于模糊、缺乏可操作性的
   - 过于显而易见的（比如"编写干净的代码"）

不要构建一个泥球

当你准备往 AGENTS.md 里添加内容时，问问自己它应该放在哪里：

位置	使用时机
根目录 AGENTS.md	与仓库中的每一个任务都相关
独立文件	与某个领域相关（TypeScript、测试等）
嵌套文档树	可以按层级组织的内容

理想的 AGENTS.md 小巧、聚焦，并指向其他地方。它给 Agent 提供恰到好处的上下文来开始工作，同时留下通往更详细指南的面包屑。

其他一切内容都应归入 progressive disclosure：独立文件、嵌套的 AGENTS.md 文件或 Skills。

这样既能保持指令预算高效，也能让你的 Agent 保持专注，还能让你的配置在工具和最佳实践不断演进时依然经得起考验。

• 原文链接： aihero.dev/a-complete-gu...
• 鸿途知科网 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～