AGENTS.md 完全指南

了解如何为 AI 编码智能体优化 AGENTS.md 文件。掌握渐进式披露，让指令保持聚焦，并最大化智能体性能。

Matt Pocock

你是否曾经担心过自己的 AGENTS.md 文件太大？

也许你确实应该担心。糟糕的 AGENTS.md 文件会让智能体困惑，变成维护噩梦，还会在每次请求中消耗你的 token。

所以，你最好知道该如何修复它。

什么是 AGENTS.md？

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

可以把它看作智能体基础指令与你的实际代码库之间的一层配置。该文件可以包含两类指导：

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

AGENTS.md 文件是一项开放标准，许多工具都支持它——尽管并非全部工具如此。

CLAUDE.md

值得注意的是，Claude Code 不使用 AGENTS.md，而是使用 CLAUDE.md。你可以在两者之间建立符号链接，让所有工具都以相同方式工作：

```shellscript

Create a symlink from AGENTS.md to CLAUDE.md

ln -s AGENTS.md CLAUDE.md ```

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

有一种自然形成的反馈循环，会让 AGENTS.md 文件膨胀到危险的程度：

1. 智能体做了你不喜欢的事
2. 你添加一条规则来阻止它
3. 数月间重复数百次
4. 文件变成一个“泥球”

不同的开发者会加入互相冲突的观点。没有人对全文做统一的风格整理。结果如何？一个无法维护的烂摊子，反而会损害智能体的表现。

另一个罪魁祸首是自动生成的 AGENTS.md 文件。永远不要用初始化脚本自动生成 AGENTS.md。它们会向文件中塞满“对大多数场景都有用”的内容，而这些内容其实更适合渐进式披露。生成的文件重视面面俱到，而不是克制。

指令预算

Humanlayer 的 Kyle 在其文章中提到了“指令预算”这一概念：

前沿思考型 LLM 能够以较为稳定的方式遵循约 150–200 条指令。小模型能关注的指令少于大模型，非思考型模型能关注的指令少于思考型模型。

无论是否相关，AGENTS.md 文件中的每一个 token 都会在每一次请求中加载。这会造成一个严格的预算问题：

| 场景 | 影响 | | --- | --- | | 小而聚焦的 AGENTS.md | 为任务特定指令留出更多 token | | 庞大臃肿的 AGENTS.md | 实际工作可用的 token 更少；智能体会感到困惑 | | 不相关的指令 | 浪费 token + 分散智能体注意力 = 表现更差 |

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

过时文档会污染上下文

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

文档很快就会过期。对人类开发者而言，过时文档令人烦恼，但人类通常有足够的内在记忆，会对错误文档保持怀疑。对每次请求都读取文档的 AI 智能体而言，过时信息会主动污染上下文。

当你记录文件系统结构时，这一点尤其危险。文件路径经常变化。如果你的 AGENTS.md 写着“身份验证逻辑位于 src/auth/handlers.ts”，而该文件后来被重命名或移动，智能体就会自信地去错误的位置查找。

与其记录结构，不如描述能力。对内容可能位于何处以及项目的整体形态给出提示，让智能体在规划期间即时生成自己的文档。

领域概念（例如“organization”“group”和“workspace”的区别）比文件路径更稳定，因此记录它们更安全。但在快速演进的 AI 辅助代码库中，即使这些概念也可能漂移。请保持克制。

精简庞大的 AGENTS.md 文件

对放入其中的内容要毫不留情地筛选。可以把以下内容视为绝对最低限度：

• 一句话项目描述（起到基于角色的提示词作用）
• 包管理器（如果不是 npm；或者使用 corepack 发出警告）
• 构建/类型检查命令（如果不是标准命令）

说实话，就这些。其他一切都应该放到别处。

一句话项目描述

这一个句子能让智能体理解自己为什么在这个仓库中工作。它为智能体做出的每个决定提供锚点。

示例：

markdown This is a React component library for accessible data visualization.

这就是基础。智能体现在理解了自己的工作范围。

指定包管理器

如果你在 JavaScript 项目中使用 npm 以外的工具，请明确告诉智能体：

markdown This project uses pnpm workspaces.

否则，智能体可能默认使用 npm，并生成错误的命令。

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

使用渐进式披露

不要把一切都塞进 AGENTS.md，而应使用渐进式披露：只向智能体提供它当下需要的内容，并在需要时将它指向其他资源。

智能体很擅长快速浏览文档层级。它们对上下文的理解足以找到自己需要的内容。

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

如果你的 AGENTS.md 当前写着：

markdown Always use const instead of let. Never use var. Use interface instead of type when possible. Use strict null checks. ...

请把这些内容移到单独的文件中。在根目录的 AGENTS.md 中写：

markdown For TypeScript conventions, see docs/TYPESCRIPT.md

注意这种轻描淡写的方式：没有“永远”，没有全大写的强制要求，只是以对话式语气给出引用。

这样做的好处是：

• 只有当智能体编写 TypeScript 时，才加载 TypeScript 规则
• 其他任务（CSS 调试、依赖管理）不会浪费 token
• 文件能保持聚焦，并在模型变化时仍具有可移植性

嵌套渐进式披露

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

txt docs/ ├── TYPESCRIPT.md │ └── references TESTING.md ├── TESTING.md │ └── references specific test runners └── BUILD.md └── references esbuild configuration

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

使用 Agent Skills

许多工具都支持“Agent Skills”——智能体可以调用的命令或工作流，用于在需要时了解如何完成某项具体工作。这是渐进式披露的另一种形式：智能体只在需要时提取知识。

我们会在另一篇文章中深入介绍 Agent Skills。

[

AI Hero · 技能系统

一份出色的 AGENTS.md 是第一步

看看我在自己的 AGENTS.md 之上运行了哪些技能，把这个文件转化为实际交付的成果。

查看技能集](https://www.aihero.dev/skills)

Monorepo 中的 AGENTS.md

你并不限于在根目录只放一个 AGENTS.md。还可以把 AGENTS.md 文件放在子目录中，它们会与根目录层级合并。

这对于 Monorepo 非常有用：

各层级放什么内容

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

根目录的 AGENTS.md：

markdown This is a monorepo containing web services and CLI tools. Use pnpm workspaces to manage dependencies. See each package's AGENTS.md for specific guidelines.

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

markdown This package is a Node.js GraphQL API using Prisma. Follow docs/API_CONVENTIONS.md for API design patterns.

不要让任何层级过载。 智能体会在上下文中看到所有合并后的 AGENTS.md 文件。让每一层都聚焦于与该范围相关的内容。

用这段提示词修复损坏的 AGENTS.md

如果你开始对仓库里的 AGENTS.md 文件感到不安，并想重构它以采用渐进式披露原则，可以尝试把这段提示词复制粘贴到编码智能体中：

```txt I want you to refactor my AGENTS.md file to follow progressive disclosure principles.

Follow these steps:

1. Find contradictions: Identify any instructions that conflict with each other. For each contradiction, ask me which version I want to keep.

2. Identify the essentials: Extract only what belongs in the root AGENTS.md:

3. One-sentence project description
4. Package manager (if not npm)
5. Non-standard build/typecheck commands

6. Anything truly relevant to every single task

7. Group the rest: Organize remaining instructions into logical categories (e.g., TypeScript conventions, testing patterns, API design, Git workflow). For each group, create a separate markdown file.

8. Create the file structure: Output:

9. A minimal root AGENTS.md with markdown links to the separate files
10. Each separate file with its relevant instructions

11. A suggested docs/ folder structure

12. Flag for deletion: Identify any instructions that are:

13. Redundant (the agent already knows this)
14. Too vague to be actionable
15. Overly obvious (like "write clean code") ```

不要构建一团乱麻

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

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

理想的 AGENTS.md 小而聚焦，并指向其他地方。它只给智能体足够的上下文来开始工作，并留下通往更详细指导的线索。

其他一切都放在渐进式披露中：独立文件、嵌套的 AGENTS.md 文件或 skills。

这样可以高效利用指令预算，让智能体保持专注，并使你的配置在工具和最佳实践演进时仍然适用。