最近读了 Matt Pocock 的《A Complete Guide To AGENTS.md》。它讲的是每个用 AI 编程的人都躲不开的一件小事：给 Agent 写规则文件。这篇文章是我的读后复盘——先说原文讲了什么，再说我从中学到了什么，最后讲清楚这些想法是怎么一步步变成 AgentsMD-GEN 这个 Skill 的。如果你手上也有一份越写越长的 AGENTS.md，希望这条从阅读到动手的路径对你有参考价值。

越补越长的文件

事情通常是这样开始的。AI 编程 Agent 犯了一个错——比如用错了包管理器，或者跑了一个项目里根本不存在的命令。我们的第一反应很自然：往 AGENTS.md 里加一条规则，让它别再犯这个错。过两天它又犯了个别的错，我们再加一条。每一次都是好意，每一次都只加一两行。

Matt Pocock 在《A Complete Guide To AGENTS.md》里给这个文件下过一个定义：它是提交进 Git、用来定制仓库内 AI 编程 Agent 行为的 Markdown 文件，相当于基础指令与具体代码库之间的一个配置层。这个定位本身没有任何问题，出问题的是我们的使用方式。

在作者看来，一条条补下去的规则，最终会让文件累积成相互冲突、难以维护的「泥球」；而更隐蔽的代价是，大量与当前任务无关的指令，会在每一次请求里消耗模型的上下文和注意力。磁盘空间不值钱，但每次请求都要带着走的规则是有成本的。

这是一个工程判断，不是被严格证明的定律，但它解释了一个常见的困惑：文件越写越厚，Agent 为什么反而可能越来越不听话。所以真正的问题不是「要不要写规则」，而是「这份文件该怎么被治理」。原文给了一整套诊断和药方，下面先讲它说了什么。

配置层与渐进披露

原文最有解释力的一个概念是指令预算。它引用了 HumanLayer 的说法：前沿推理模型大约能以合理的一致性遵循 150 到 200 条指令，指令继续增加，遵循质量就会下降。需要说明的是，HumanLayer 自己也讲得很清楚：这个主题尚未经过极其严格的研究，这个数字是对工程经验和相关研究的概括，不是任何模型厂商的保证，更不是精确上限。但它给出了一个有用的心智模型——AGENTS.md 不是免费的，每条规则都在花掉同一笔预算。换句话说，预算的瓶颈不在磁盘里，而在模型每次请求能稳定吸收的指令数量上。

在这个视角下，原文给出了几条很具体的减法建议。一份最小化的根 AGENTS.md，主要内容是：一句话的项目说明、非 npm 的包管理器说明、非标准的构建或类型检查命令。除此之外的细节，都应该按需放到其他文件里。这是作者的建议而非强制标准，但方向很明确：根文件只保留几乎每项任务都需要的东西。

细节往哪放？原文给的机制是渐进披露：始终加载的入口保持精简，只提供主题线索和指针；Agent 在当前任务需要时，再去加载更细的规范、运行手册或 Skill。不过原文同样提醒，这不是免费午餐——发现、选择和读取那些细节文件，仍然要消耗工具调用和上下文。按需加载省下的是常驻成本，花掉的是检索成本。

对于 monorepo，原文建议根级和包级并用：根层保存整个仓库的目的与共享工具，包层保存该包的用途、技术栈和局部约定。至于多级文件是否合并、如何合并，取决于各个宿主的实现，文章提供的是结构上的建议。这其实和渐进披露是同一个思路在不同尺度上的应用：每一层只回答属于这一层的问题。

还有一点值得记住：原文有一个鲜明的倾向——不主张用初始化脚本自动生成 AGENTS.md。这个倾向和我后面要做的事看起来正面相撞，这个伏笔先按下，第四章再谈。

我学到的四件事

操作建议可以照抄，但真正留下来的是几个可以迁移的认识。操作建议会随工具演进而过时，认识不会。读完全文，沉淀在我这里的是四条认识，它们后来逐一变成了 Skill 里的设计决定。

第一，AGENTS.md 是配置，不是百科。配置层的价值在于克制——它应该只放能改变 Agent 行为的指令，而不是把项目背景、目录结构、历史决策全塞进去。什么都往里写，等于什么都没配置。后来 Skill 里「不把根文件写成项目百科」这条设计目标，直接源于此。

第二，真正稀缺的是上下文和注意力，不是磁盘空间。每一条常驻指令都会附着在每一次请求上；指令预算这个概念提醒我，规则的条数本身就是成本。这条认识后来决定了 Skill 的准入标准：一条规则要想进根文件，必须证明自己有长期驻留的价值。这条认识也解释了一个反直觉的现象：为什么精心补充的规则越多，Agent 的表现反而越不稳定。

第三，好指令要有证据、有作用域、有长期价值。这是我从原文的减法建议里提炼出的三重判据：规则应该能对应仓库里当前可验证的事实（证据），只在它适用的范围内生效（作用域），并且值得长期占着预算（长期价值）。这三点后来成了 Skill 规则政策的核心。

第四，按需加载是方向，但不是免费午餐。渐进披露解决的是「常驻太多」的问题，但发现和读取本身有成本，所以理想形态不是把文件拆成一百份，而是让入口足够精简、同时让细节能被可靠地找到。拆文件本身从来不是目标，可靠的入口才是。这条认识直接影响了这个 Skill 后来一次关键机制升级的方向——它的结局留在第五章。

一个表面矛盾

现在要诚实地面对一个矛盾。原文对自动生成持反对倾向，警惕那些一键生成的大段模板——文件生成的那一刻，往往就是它开始腐化的时刻。而我做的 AgentsMD-GEN，从名字看就是一个「生成器」。这个矛盾避不开：如果我连原文的反对意见都不处理，后面的工程细节就只是自说自话。

我的回答是：两边的反对对象其实是同一个。原文反对的，是无证据、无边界、一次性倾倒的粗暴自动生成；AgentsMD-GEN 并不反对自动化本身，它反对的也是这种粗暴。这个 Skill 要求每条规则都有仓库证据、有正确作用域、有长期价值，写入要经过验收门禁约束。自动化在这里只是工具，纪律才是它与粗暴生成之间隔着的那条线。换句话说，问题从来不是「该不该让机器参与」，而是「机器参与时是否遵守与人工精心维护同等的纪律」。

所以这不是对原文的反驳，而是顺着原文理念做的一次工程化延伸：把「人应该遵守的写文件纪律」，变成「机器执行时也必须遵守的流程」。当然也要如实说，这是我基于原文理念做出的个人工程判断，这个 Skill 并不能证明已经在所有真实项目里优于其他方案。

从原则到机制

理念要落成机制才算数。AgentsMD-GEN 的设计目标一句话就能说清：把 AGENTS.md 当作稀缺的常驻上下文来治理——每条规则必须有仓库证据、正确作用域和长期价值，不把根文件写成项目百科或文件系统地图。这正好对应上一章的前三条认识。

第一条机制是指令的放置。Skill 用「覆盖范围 × 激活条件」两个轴决定一条指令的去向：全局性的、几乎每项任务都需要的规则，进入根 AGENTS.md；独立子项目的稳定规则，进入该子项目自己的局部 AGENTS.md；只在测试、安全、发布这类特定任务触发的规则，进入对应作用域的 .agent-guides。要说明的是，.agent-guides 是这个 Skill 自己的工程约定，不是所有 Agent 宿主的原生标准。

第二条机制是克制。这个 Skill 不是「见到 AGENTS.md 就重写」。它区分 create、maintain 和 audit 三种情形，并明确规定：纯讨论、调研、规划或只读检查，一律跳过维护门禁；普通的功能实现，通常得到的结果是「AGENTS.md：无需改动」。只有当仓库里出现了可验证的事实、而现有指令确实缺位或失真时，才会提议最小化的修改。这是上一章承诺的兑现——自动化被纪律约束着。

第三条机制是只读检查器。Skill 附带一个检查脚本，以 JSON 汇总指令层级、Git 状态、manifest、独立子项目候选、命令来源、路径引用、文档链接和 Agent Guide 问题，当前的 schema 版本是 1.2。它的定位要讲准确：检查器只提供事实清单和风险信号，最终是否创建、更新或阻塞，仍由 Agent 结合规则政策来判断——它是证据的收集者，不是独裁的裁判。

第四是验证。在当前仓库里，Skill 的快速校验通过，14 个单元测试全部通过。这能证明的是：当前结构满足校验器的要求，且检查器所列行为都有测试覆盖。它不能证明的更多——没有缺陷、适配所有宿主、在所有真实仓库有效，这些都不在证据范围内。

最后看演化。仓库的公开提交历史有四次提交：初始的生命周期 Skill、补充通用安装提示、落实渐进式分层指令、加入分层 Agent Guide 协议——其中三次功能提交构成了清晰的机制演化。最有意思的是最后一步：更早的设计仍依赖根文件显式维护指向细分文档的入口，而这种指针会随着文件增删产生漂移风险。最新的 Agent Guide 协议把它升级成了动态发现：根文件不再维护易漂移的 guide 文件清单，而是让 Agent 在需要时发现当前入口。这正是渐进披露从静态组织走向动态组织的一步——第三章第四条认识埋下的钩子，在这里收拢。

让纪律可执行

回到第一章的问题。AGENTS.md 的价值从来不在厚度，而在治理：规则要有证据、有作用域、有长期价值，细节要按需披露。这些听起来像个人修养的东西，其实可以被沉淀为可执行的规则——AgentsMD-GEN 就是这样一次尝试，它把「认真维护一份配置文件」从自觉变成了流程：不需要记住多少条原则，只需要在每次写入时回答那三个问题——有证据吗？作用域对吗？值得长期留下吗？

边界也要如实说：这只是一个仓库、一条提交历史里的工程实践，不是普适标准；校验和测试通过也不代表零缺陷。自动化不会替人思考，它做的只是把「认真」这件事变得不再完全依赖自觉。

所以最后把问题还给你：你的 AGENTS.md，有多久没有被治理过了？

参考来源

  1. Matt Pocock, A Complete Guide To AGENTS.md, AIHero：https://www.aihero.dev/a-complete-guide-to-agents-md

  2. Kyle, Writing a good CLAUDE.md, HumanLayer：https://www.humanlayer.dev/blog/writing-a-good-claude-md

  3. AgentsMD-GEN GitHub 仓库：https://github.com/Niall-Young/AgentsMD-GEN