一份好的 AGENTS.md 长什么样？

柏林ACS · 2026-08-02 · 读完约需 6 分钟

先看他常见的两种写法。

第一种是抄来的：整份风格指南粘进去，几十条规范，从缩进到命名无所不包。第二种是宣言式的："我们的愿景是打造极致体验""代码要优雅，架构要清晰"。

两种都认真写了，AI 的行为都没怎么变。

再看一条真实的配置条目，出自一个写作项目的 AGENTS.md："新增术语必须满足：现有术语无法表达、能解释更多现象、不与已有概念重叠、能形成清晰边界——否则禁止新增。"没有愿景，没有修辞，但每一次写作它都在约束 AI 的行为：想造词之前，先过四道检验。

差别在哪？检查的方法很简单：随便挑一节，问一句——这一节改变了 AI 搜索的哪一部分？ 愿景宣言答不上来：模型看到"极致体验"，还是按平均水准输出。粘贴的规范能答上一半：它约束了产出细节，但里面大半条目模型本来就会做对——它们只占篇幅，不带来约束。而那条术语纪律，每一次都在实实在在地收窄搜索空间。

前面几篇说过，一次搜索有四层：从什么状态起跑，为了什么而搜，能去哪些地方，怎样走完全程。一份配置的作用，就是在这四层上各放几道约束。所以好的 AGENTS.md 不要求长，要求每一节都答得上那句检查：

定位与受众：改变"什么算好"。 做什么、为谁做、不做什么。尤其"不做什么"，它比"做什么"更能约束方向。受众写"所有用户"，等于没写。

设计原则：改变取舍。 两件事冲突时牺牲什么、保住什么："速度优先于功能完整"。AI 每天都会遇到你没写过的冲突，没有取舍标准，它就按训练数据的平均值替你取舍。

产出规范：改变边界。 只写 AI 会违反的；它默认就做对的事，不写。十条真实约束，胜过一百条百科全书。

协作约定：改变过程。 怎么验证、什么时候停下来汇报、改动怎么说清楚。第 07 篇聊的闭环与止损线，就落在这一节。

配置维护：改变未来。 这份文件本身怎么更新——什么时候复盘、什么经验够格入库，前两篇的内容都归这里。缺了这节，配置从写完那天开始老化。

五节共用一条总纪律：配置只写模型猜不到、且长期成立的东西。TODO、当前进展、本周目标，写在每次对话开头就行——它们过期得快，混进配置里只会污染它。

动手时的建议也只有一条：拿不准的节整节删掉。留一个写不满的空壳在那里，比没有更糟——空壳会被填空，而填进去的往往是宣言和套话。

三个场景的填空骨架（软件研发、内容创作、个人项目）放在公开仓库 acs-templates，每节都标了"影响什么、怎么写算够、别写成什么"，半小时能填完一份。理论出处是《AI认知搜索理论》第九章。

现在就可以验证这篇的说法：打开自己项目的 AGENTS.md，随便挑一节，问那句检查——它改变了搜索的哪一部分？答不上来的节，整节删掉。改完之后文件会薄一些，AI 会听话一些。至于写完的文件怎么防止老化，下一篇的体检清单来接管。