AGENTS.md 不是变更日志

AGENTS.md 会在每次会话开始时被加载。团队把 PR 叙述和测量结果不断追加进去,文件就只会变长,真正的规则反而被埋住。指令要短,历史记录不该放在这份文件里。

·1 分钟阅读

公开的开发者 issue 和讨论里,经常会谈到怎么维护 AGENTS.md。本月早些时候,我们写过规则为什么会过时,也写过规则文件为什么不是决策日志。还有一个常见问题:文件只会越来越长。

没人想要一份更长的指令。大家是在防止这份每次都会被加载的文件,变成一本日记。

一份只会变长的文件

AGENTS.md 有用,是因为 agent 一开会话就会加载它。也正因为如此,文件一旦没有上限,代价就很高:多出来的每一段,明天还要再付一次。

在一份公开 issue里,作者写到自己在一个私有生产仓库里看到的情况。六份 AGENTS.md,再加上根目录那一份,一共 9,243 行。根目录文件本身有 1,792 行,有一份按区域划分的文件有 2,659 行。Agent 开工前会先加载根目录文件和这份区域文件,一次会话就要读进 2,000 到 4,000 行指令。一天的 agent 工作里,又追加了 218 行,多半是已经写在 PR 描述和 commit message 里、带日期的测量记录。原因很眼熟:有一项检查会标记「文档没有跟着更新」,agent 就追加一段事发经过,却从来没有检查要求删掉任何一行。

另一份公开 issue里,有一份 698 行的 AGENTS.md,每次 agent 开工都会被完整加载。大约 500 行是这个项目自己的规则,约 130 行是「如何使用 AI 工具」这类通用建议,约 70 行和其他文档里已有的内容重复。缓存指令、鉴权检查这些真正要紧的规则,被埋在其余内容里。这个团队希望把文件压到 350 行以内,重复的部分改成链接。

还有一场讨论问得很直接:把变更历史放在每次会话都会加载的指令文件里,到底有什么价值?说的是 CLAUDE.md。这份文件已经涨到 47,000 个字符,每次会话、每个项目 agent 都会被注入进去。

情况都一样。规则文件成了追加「刚刚发生了什么」最方便的地方。历史记录本身有价值,只是不该放在每次都会被完整加载的那份指令里。

更长的指令,并不是更好的指令

这已经不只是喜好问题。工具自己已经在限制文件的体积。

官方 AGENTS.md 网站把这份文件称作给 agent 看的 README。构建步骤、测试和约定放在这里,才不会把给人看的 README 挤乱。Cursor 的 规则文档 写得很清楚:每条规则控制在 500 行以内,过长的规则要拆成更集中的文件,引用其他文件,不要把内容复制进来。这样,每次都会加载的文本才能保持简短,也不会随着代码改动而过时。OpenAI 在 Codex 的 AGENTS.md 自定义指令 里写得更具体。Codex 会从项目根目录一路拼接到当前工作目录下的 AGENTS.md,合计大小一到 project_doc_max_bytes(默认 32 KiB)就停止添加。指令被截断是文档里已经写明的故障。建议的做法是提高这个上限,或把大文件拆开,好让关键指引还能完整保留。Anthropic 的 Claude Code 文档也说明会读取仓库里的 AGENTS.md,并建议每个指令文件控制在 200 行以内。更长的文件会占用更多上下文,遵守程度也会下降。1

就算文件还装得进上下文窗口,更长的上下文也不是免费的。2025 年 7 月 14 日,Kelly Hong、Anton Troynikov 和 Jeff Huber 在 Chroma 发布了 Context Rot: How Increasing Input Tokens Impacts LLM Performance。他们评估了 18 个模型,包括 GPT-4.1、Claude 4、Gemini 2.5 和 Qwen3。任务被有意保持简单,只改变输入长度,用的是扩展后的 Needle in a Haystack、一组对话式问答(LongMemEval),以及重复单词的抄写任务。模型并没有均匀地使用上下文。条件已经尽量简单,输入一变长,表现还是越来越不稳定。作者也写了,这项评估并不能覆盖所有真实场景,而 agent 任务通常更复杂,长度的影响在实际使用中可能会更明显。

一份 2,000 行、每次都要加载的指令,并不是更完整的项目记忆。它只是一个更大的草垛。当前那条规则,每个会话都要重新从里面找出来。

把规则编译出来,不要把故事追加进去

想追加的冲动很好理解。出了问题,你做了测量,希望下一个 agent 知道。错在把故事留在了规则该待的位置。

2026 年 11 月的一篇预印本,把另一种做法讲得很清楚。Nima Vahdat 和 Pashootan Vaezipoor(Georgian AI Lab)发布了 Decision Context: Persistent Behavioral Learning for AI Agents。他们的系统 forge_dc 会把人工纠正,以及模型自我评估出的工具调用失败,编译成祈使句式的规则指令,再在这些规则适用的决策点注入,而不是去检索原始历史。测试用的是 DC-Bench:71 个场景、9 个行为维度,基于真实执行过的 agent 轨迹,运行在确定性的模拟工具环境中。forge_dc 的遵守率达到 95%,朴素检索是 55%,每个查询注入的 token 大约少了十倍。

这些结果来自模拟工具基准,不是仓库里的 AGENTS.md。衡量的也是对编译后规则的遵守程度,不是端到端的软件质量。但它仍能说明问题:把昨天的叙述倒进每次都会加载的文件,就是那种朴素检索。更省、也更可靠的做法,是更新当前的规则,把故事放在可以事后查阅、却不必每次都注入的地方。

可以这样分:

  • 让 AGENTS.md 只承担当前的指令。 构建、测试、lint 和运行的命令,不要碰的目录,PR 该怎么开,以及其他今天对照仓库就能核实的事实。
  • 如果一次改动产生的测量或事发记录已经写在 PR 或 commit 里,就不必再追加到 AGENTS.md。 下一个 agent 不需要那份带日期的流水账。它需要的是规则;如果已经有检查来执行这条规则,把检查留下就行。
  • 如果某一节在 docs/ 里已经有了,就链过去。 这和 Cursor 的建议一致:引用文件,不要把内容粘贴进来。指令才能保持简短,长文档更新时也不会一起腐烂。
  • 文件变长时,要压缩或拆分,而不只是追加。 如果「如何使用 AI 工具」这类通用建议已经占了一百行,它多半不该继续占用这个仓库的指令篇幅。
  • 留意工具实际在用的预算。 根目录文件如果已经有数千行,就会撞上 Codex 默认的 32 KiB 上限,还可能把当前目录里更具体、嵌套的指引挤出去。

当前的答案,加上一条时间线

历史仍然需要一个位置。这和决策日志其实是同一套做法:一份可以整段重写的当前答案,再加上一条只增不改的轨迹,记录你们是怎么走到这一步的。带日期的测量、后来的撤销、事发说明,都属于这条轨迹。下一次会话该加载的,是当前的答案。

MindMux 自己也做这类产品,这里说一下它今天实际做了什么。

MindMux 会从你们已经在和 agent 进行的对话里,整理出背景、决策和约束,写成一份 Markdown 项目大脑。Agent 开始任务前,会通过 MCP 读到它。要把 Claude Code 或 Codex 接到这份大脑,安装 @mindmux/cli,在项目里运行 mmx setup。不想登录 Cloud、只要本地 Brain,用 mmx setup --local。开源、可在本地使用的对应产品是 brain.md:仓库里的一个 brain/ 目录,加上一个小的 CLI(@mindmux/brain-md)。每个页面都保留一层 compiled_truth,也就是当前的答案,以及一条只增不改的 timeline,记录你们是怎么走到这一步的。它就放在 git 里,也不绑死在某个 agent 上。Claude Code、Codex、Cursor,以及任何能读文件的工具,都可以用。

AGENTS.md 可以保持简短。大脑负责装决策,时间线负责装历史。下一次会话、换一个工具,都会从当前的理解开始,而不是从一份 2,000 行、记着上周 PR 的日记开始。

这是跨会话、跨工具的决策记忆。

如果这正是你遇到的问题:

如果你注意到的第一件事是,这份指令仍然读得下去,而且昨天的测量结果没有再被粘进去,那它就生效了。

Footnotes

  1. Anthropic,How Claude remembers your project。 ↩

分享到