AGENTS.md 完整指南

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

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

因此，你最好了解如何修复它。

什么是 AGENTS.md？

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

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

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

这个 AGENTS.md 文件是一项开放标准，受到许多工具支持，但并非所有工具都支持。

# Create a symlink from AGENTS.md to CLAUDE.md
ln -s AGENTS.md CLAUDE.md

为什么超大型 AGENTS.md 文件会成为问题

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

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

不同开发者加入彼此冲突的意见，却没有人进行完整的风格梳理。结果是什么？一个无法维护的烂摊子，而且它会真正损害 Agent 的表现。

另一个罪魁祸首是自动生成的 AGENTS.md 文件。绝不要使用初始化脚本自动生成你的 AGENTS.md。它们会向文件中塞入大量“对多数场景都有用”的内容，而这些内容本应通过渐进式披露按需提供。生成式文件追求面面俱到，却缺乏克制。

指令预算

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

前沿推理 LLM 大约能以合理的一致性遵循 150–200 条指令。小模型能够关注的指令少于大模型，非推理模型能够关注的指令也少于推理模型。

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

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

陈旧文档会污染上下文

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

文档很快就会过时。对人类开发者而言，陈旧文档虽然令人厌烦，但人通常拥有足够的既有记忆，会对糟糕文档保持怀疑。可对每次请求都会阅读文档的 AI Agent 而言，过时信息会主动 污染 上下文。

记录文件系统结构时，这个问题尤其危险。文件路径不断变化。如果你的 AGENTS.md 写着“身份验证逻辑位于 src/auth/handlers.ts”，而该文件后来被重命名或移动，Agent 就会信心满满地去错误位置查找。

不要记录结构，而要描述能力。可以提示相关内容 可能 位于何处，并说明项目的整体形态。让 Agent 在规划期间自行生成即时文档。

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

精简过大的 AGENTS.md 文件

必须严格筛选放入其中的内容。可以把下面几项视为绝对最低要求：

• 一句话项目描述 （作用类似基于角色的 Prompt）
• 包管理器 （如果不是 npm；也可以使用 corepack 提供警告）
• 构建/typecheck 命令 （如果不是标准命令）

说真的，只需要这些。其他所有内容都应该放到别处。

一句话项目描述

这一句话会告诉 Agent 为什么 要在这个仓库中工作的原因，并为它作出的每项决策提供锚点。

示例：

This is a React component library for accessible data visualization.

这就是基础。现在 Agent 已经理解了自己的工作范围。

指定包管理器

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

This project uses pnpm workspaces.

如果不说明，Agent 可能会默认使用 npm ，并生成错误命令。

使用渐进式披露

不要把所有内容都塞进 AGENTS.md，而要使用 渐进式披露：只向 Agent 提供当前所需内容，并在必要时将它指向其他资源。

Agent 很擅长快速浏览文档层级，也能充分理解上下文，找到自己需要的内容。

把语言专用规则移到独立文件

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

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

请把这些内容移到独立文件中。然后在根目录的 AGENTS.md:

For TypeScript conventions, see docs/TYPESCRIPT.md

注意这里语气很轻：没有“始终”，没有全大写的强制命令，只有一句对话式引用。

这样做的好处包括：

• 只有当 Agent 编写 TypeScript 时，才加载 TypeScript 规则
• 其他任务（CSS 调试、依赖管理）不会浪费 tokens
• 文件保持聚焦，并能适应模型更替

嵌套渐进式披露

还可以继续深入。你的 docs/TYPESCRIPT.md 可以引用 docs/TESTING.md。由此创建一棵易于发现的资源树：

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

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

使用 Agent Skills

许多工具支持“Agent Skills”——Agent 可以调用的命令或工作流，用来学习如何完成某项具体工作。这也是另一种 渐进式披露：Agent 只在需要时才拉取相关知识。

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

AGENTS.md 在 Monorepo 中的用法

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

这对 Monorepo 非常有用：

各层应该放什么

根目录 AGENTS.md:

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）：

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

不要让任何一层承载过多内容。 Agent 会在上下文中看到所有已经合并的 AGENTS.md 文件。每一层都只应聚焦与该层范围相关的内容。

修复失控的 AGENTS.md ：使用这个 Prompt

如果你开始担心 repo 中的 AGENTS.md 文件，并希望使用渐进式披露原则重构它，可以尝试把下面这段 Prompt 复制到编码 Agent 中：

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:
   - One-sentence project description
   - Package manager (if not npm)
   - Non-standard build/typecheck commands
   - Anything truly relevant to every single task

3. **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.

4. **Create the file structure**: Output:
   - A minimal root AGENTS.md with markdown links to the separate files
   - Each separate file with its relevant instructions
   - A suggested docs/ folder structure

5. **Flag for deletion**: Identify any instructions that are:
   - Redundant (the agent already knows this)
   - Too vague to be actionable
   - Overly obvious (like "write clean code")

不要堆出一团泥球

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

理想的 AGENTS.md 应该小而聚焦，并指向其他资源。它只向 Agent 提供足以开始工作的上下文，同时留下通往更详细指南的线索。

其他所有内容都放在渐进式披露体系中：独立文件、嵌套的 AGENTS.md 文件或 Skills。

这样可以高效利用指令预算，让 Agent 保持专注，并使整套配置能够适应工具与最佳实践的持续演进。