《你对 AGENTS.md 的理解几乎为零》

大熊进口优化师

《你对 AGENTS.md 的理解几乎为零》

作者：
@rwayne

@onlookersh


“公司变大之后，人和公司都会犯糊涂。他们想复制最初的成功，于是很多人以为：当初成功的过程里一定藏着某种魔力。于是他们开始把流程在全公司制度化。很快，大家就把流程当成了内容本身。” ———史蒂夫·乔布斯 《失落的访谈》

过去的时候呢，各种的 AI 编程工具有各自的说明书。比如Anthropic 家的 Claude Code，开机默认只读一个叫 CLAUDE.md 的说明书。而 OpenAI 家的 Codex 和其他很多工具，默认读的是 AGENTS.md。我相信很多人都是跟我一样，不止用一个编程工具。那么这就会出现一个问题，我同一个项目里面，我必须放两份说明书。Claude Code 后来增加了一种处理方式，如果项目里没有 CLAUDE.md，它会检查有没有 AGENTS.md。

那为什么说你对 AGENTS.md 的理解几乎为零？

大熊进口优化师

因为很多人听到这个消息后，首先想到的就是怎么把两个文件合并。合并当然可以解决重复维护的问题，但你把文件合并完了，原来怎么使用 Agent，现在还是怎么使用。

一个文件里该写什么，不该写什么，什么时候该让它去读别的东西，这些问题一个都没有解决。

这类文件最初要解决的问题其实很简单。早期用 Cursor 的时候，有些项目习惯每次开新会话都要再说一遍，于是可以把它们写进项目规则里。后来有了 CLAUDE.md，再后来有了让不同 Agent 都能读的 AGENTS.md。名字一直在变，但我们要解决的事情从头到尾都没有变过。

那就是，别他妈让我开始工作的时候都要从头到尾交代一遍背景跟习惯。

大熊进口优化师

可一旦你觉得“凡是希望 AI 做到的事，都应该提前写进 AGENTS.md”，这个文件就会一直长。遇到一次问题，加一条规则，然后换一种任务，再加一条。最后维护它本身成了工作。你开始关心自己到底写了多少规则、控制得有多细，却很少回过头想想这些规则是不是每次做事都需要？

写 AGENTS.md 本来是为了少解释几遍，让 Agent 更快进入工作；现在反过来，人花很多时间管理说明书，仿佛说明书越厚，就越懂得如何使用 Agent。

大熊进口优化师

我不是说规则写得长就一定有问题。有些项目确实有很多长期有效的约束，该写清楚就得写清楚。问题是，把不同任务才需要的东西，都当作每次开工的前提。写代码的时候该去检查哪个仓库就去检查哪个仓库。写文章的时候该去看哪个文档就去看哪个文档。它们是可以分开来做的。

让 AGENTS.md 先说清楚少数始终需要知道的事，再告诉 Agent 遇到哪类任务，去哪里找对应的规则。具体项目里的文件还可以把它指向工作区的通用规则。我的根文件不到 50 行，但它后面还有系统治理、文件交付等等不同的规则。

大熊进口优化师

西蒙在 1971 年谈信息系统时，区分过“把信息存起来”和“需要时能够取得、使用它”。我觉得这个区别放在 AGENTS.md 上就挺有意思。规则没有全部写在 AGENTS.md 里，不等于 Agent 用不上这些规则。它知道这次做什么、该到哪里去找就行了。

所以很多人一听到“按需调用”，就急着去做 Skill，我觉得也没到那一步。你只是想让 Agent 在某种情况下看一份已有的规则，AGENTS.md 写明去哪里读，很多时候就够了。只有一件事确实要反复走一套流程，才需要再想是不是做成 Skill。

大熊进口优化师

所以我说，AGENTS.md 不是一份越写越全的说明书。项目里的文件指向总入口，总入口再告诉 Agent：这次做什么，该去读哪份规则。复杂任务可能要读好几份，那就读；没碰上这类任务，就别每次开工都让它先看一遍

“这是每次都要交代的事，还是只有做这件事的时候才需要？”