AGENTS.md 完全指南：写得越大，智能体越笨（转载翻译）

本文为转载翻译，原文《A Complete Guide To AGENTS.md》
作者：Matt Pocock（AI Hero 创始人，TypeScript 领域知名作者）
原文链接：https://www.aihero.dev/a-complete-guide-to-agents-md
内容忠实于原文，表述按中文阅读习惯做了重写。

你的 AGENTS.md 是不是太大了？

你有没有担心过自己仓库里那个 AGENTS.md 文件？

也许你真的该担心。一个写砸了的 AGENTS.md，会迷惑你的智能体、变成一场维护噩梦，还会在每一次请求里悄悄烧掉你的 token。

所以，你最好知道该怎么写。

AGENTS.md 到底是干嘛的

说白了，AGENTS.md 就是一个提交进 Git 仓库的 markdown 文件，用来定制 AI 编程智能体在你代码库里的行为。

它的位置很特殊：对话历史的最顶部，紧挨着系统提示词。智能体每次干活，第一眼看到的就是它。

你可以把它理解成一层配置——垫在智能体的基础指令和你真实的代码库之间。里面放两类东西：

• 个人习惯：你喜欢的提交风格、你偏好的编码方式
• 项目事实：项目是做什么的、用什么包管理器、有哪些架构决策

AGENTS.md 是个开放标准，大多数工具都认。但有个例外：Claude Code 不读它，只读 CLAUDE.md。

解决办法也简单，建个符号链接，一套内容两头通用：

ln -s AGENTS.md CLAUDE.md

为什么文件越写越大、越写越烂

先说一个很常见的恶性循环：

1. 智能体干了一件你不喜欢的事
2. 你加一条规则，防止它再犯
3. 几个月下来重复了几百次
4. 恭喜，文件变成了一坨「烂泥」

更麻烦的是，团队里每个人都在往里面加自己的意见，互相矛盾也没人管，从头到尾没人做过一次整体梳理。结果就是一份谁都维护不动、还让智能体越干越差的文件。

还有一个坑要避开：永远别用初始化脚本自动生成 AGENTS.md。这种生成文件最爱塞「大多数场景都用得上」的内容，看着全面，其实全是噪音，远不如按需渐进披露。

为什么文件大就坏事？这里有个「指令预算」的概念，来自 Humanlayer 的 Kyle：

前沿的思考型大模型，大概能稳定遵循 150~200 条指令。模型越小，能照顾到的指令越少；非思考型模型能照顾到的指令，也比思考型模型少。

关键在这：你 AGENTS.md 里的每一个 token，每一次请求都会完整加载一遍，不管跟当前任务有没有关系。这就是一道硬预算：

情况	后果
小而聚焦的 AGENTS.md	更多 token 留给真正干活的指令
大而臃肿的 AGENTS.md	干活的 token 变少，智能体还容易懵
塞满无关指令	浪费 token + 分散注意力 = 表现更差

所以结论很直接：理想的 AGENTS.md，应该尽可能小。

文件大还有个隐藏杀手：过时。

文档这东西过期极快。人看到过时文档，好歹会本能地怀疑一下；但智能体每次请求都要读一遍，过时信息就等于直接毒化它的上下文。

最危险的是在 AGENTS.md 里写文件路径。路径说变就变，你今天写「认证逻辑在 src/auth/handlers.ts」，明天文件一改名，智能体就会自信满满地在错误的地方翻半天。

正确做法是：别记结构，描述能力。给点「东西大概在哪儿」的线索、项目的大致形状，剩下的让智能体在规划时自己现查现用。

相比之下，领域概念（比如「组织」「群组」「工作空间」的区别）比文件路径稳定得多，写进去更安全。但就算是这些，在 AI 辅助下快速演进的代码库里也可能漂移。总之：轻拿轻放。

到底该往 AGENTS.md 里放什么

对内容要狠一点。按作者的说法，绝对最小值就三样：

• 一句话项目描述（相当于给智能体的角色设定）
• 包管理器（只要不是 npm 就要写；或者用 corepack 省事）
• 构建 / 类型检查命令（如果不标准）

就这些。其他的一律请出去。

一句话项目描述

别小看这一句话。它告诉智能体「你为什么在这个仓库里干活」，是它做每一个决策的锚。

比如：

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

有了这一句，智能体就知道自己在什么范畴里干活了。

包管理器说明

JavaScript 项目里只要没用 npm，就得明说：

本项目使用 pnpm workspaces。

不写的话，智能体大概率默认你是 npm 项目，然后给你生成一堆跑不起来的命令。

想更省事的话，可以用 corepack 让系统自动处理这些警告，指令预算又省下一截。

用渐进式披露，别一把梭

核心思路一句话：只给智能体当下需要的东西，需要更多时让它自己去找。

智能体在文档层级里导航快得很，上下文理解能力也够用，你完全不用把所有东西塞到它嘴边。

比如你的 AGENTS.md 里现在有一堆 TypeScript 规矩：

始终用 const 而不是 let。
永远不要用 var。
能用 interface 就不用 type。
启用严格空值检查。
...

把这些全部挪到单独的文件里去，根目录只留一句指路的话：

TypeScript 约定见 docs/TYPESCRIPT.md

注意这个写法：轻描淡写，没有「始终」，没有全大写强调，就是随口一句指引。

好处显而易见：

• 智能体写 TypeScript 时才加载这些规则
• 其他任务（调 CSS、管依赖）不浪费 token
• 文件保持精简，换什么模型都通用

还可以套娃。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 Skills）——智能体可以主动调用的命令或工作流，本质也是渐进式披露的一种：用到才加载。作者说这个主题会单独写一篇，这里就不展开了。

Monorepo 里怎么安排

根目录一个 AGENTS.md 不是终点。子目录里也可以放 AGENTS.md，而且会和根目录的自动合并。

这对 monorepo 特别有用：

层级	内容
根目录	Monorepo 的定位、怎么在包之间导航、共享工具（pnpm workspaces）
包目录	这个包的定位、具体技术栈、包内特有的约定

根目录写：

这是一个包含 Web 服务和 CLI 工具的 monorepo。
用 pnpm workspaces 管理依赖。
各包的细则看对应包内的 AGENTS.md。

packages/api/AGENTS.md 写：

这个包是一个用 Prisma 的 Node.js GraphQL API。
API 设计模式见 docs/API_CONVENTIONS.md。

记住：每一层都不要贪多。 智能体会把合并后的所有 AGENTS.md 全塞进上下文，每一层只管自己范围内的事就好。

想重构？这段 Prompt 直接抄

如果你看自己的 AGENTS.md 越看越心虚，想按渐进式披露重构，把下面这段直接扔给你的编码智能体就行：

请帮我重构 AGENTS.md，使其遵循渐进式披露原则。

按以下步骤执行：

1. 找矛盾：识别彼此冲突的指令。每发现一处矛盾，问我保留哪个版本。

2. 找核心：只提取应该留在根 AGENTS.md 的内容：
   - 一句话项目描述
   - 包管理器（如果不是 npm）
   - 非标准的构建 / 类型检查命令
   - 任何与每个任务都相关的内容

3. 归类其余：把剩余指令按逻辑类别整理（如 TypeScript 约定、测试模式、
   API 设计、Git 工作流），每个类别建一个单独的 markdown 文件。

4. 搭结构：输出
   - 最小化的根 AGENTS.md，用 markdown 链接指向各单独文件
   - 每个单独文件及其指令
   - 建议的 docs/ 目录结构

5. 标记可删项：识别以下指令——
   - 冗余的（智能体本来就知道）
   - 太模糊、没法执行的
   - 过于显而易见的（比如「写干净的代码」）

别把 AGENTS.md 搞成一坨烂泥

以后每次想往 AGENTS.md 里加东西，先问自己一句：这东西该放哪？

位置	什么时候用
根目录 AGENTS.md	和仓库里每个任务都相关
单独的文件	只属于某一个领域（TypeScript、测试……）
嵌套文档树	可以按层级组织

理想的 AGENTS.md 就三个词：小、聚焦、指向别处。给智能体刚好够开工的上下文，再留下面包屑，让它需要时自己去翻更详细的指南。

其余一切交给渐进式披露：单独文件、嵌套的 AGENTS.md、或者技能。

这么做，指令预算不浪费，智能体不跑偏，以后工具和最佳实践再怎么变，这套配置也不用推倒重来。

---

看完这篇指南，我最大的感受是：我们总忍不住想把所有经验都塞进 AGENTS.md，但智能体时代恰恰相反——写得多，不如写得准。说白了，这份文件应该是一张地图，而不是一车说明书。值得你花一个晚上，好好收拾一下。

本文转载翻译自 AI Hero 的《A Complete Guide To AGENTS.md》，作者 Matt Pocock。