AGENTS.md 约定本身 — 规则与语义

本章讲什么: AGENTS.md 没有代码可读,它的「实现」就是一组被各家工具共同遵守的语义规则。这一章把这些规则一条条讲清——它们大多写在官网的 FAQ 和「怎么用」区里,是这份约定真正的规范文字。

约定刻意做得极简。核心可以压成五条,先给全景表,再逐条展开:

规则	一句话	依据
无必填字段	就是普通 Markdown,爱用什么标题用什么	`components/FAQSection.tsx:13-17`
就近生效	离被改文件最近的 AGENTS.md 赢	`components/FAQSection.tsx:18-22`
用户最高	对话里的临时指令盖过一切	`components/FAQSection.tsx:18-22`
自动执行	你列了测试/检查命令,agent 会去跑并修红	`components/FAQSection.tsx:23-26`
可嵌套	monorepo 每个子项目放各自的 AGENTS.md	`components/HowToUseSection.tsx:35-40`

3.1 无必填字段:它只是普通 Markdown

要解决的小问题: 格式一旦规定「必须有 X 段、Y 字段」,采用成本就上去了,还得有校验器。约定选择零 schema。

规则原文: 「没有必填字段。AGENTS.md 就是标准 Markdown,用任何你喜欢的标题;agent 只是解析你给的文本。」(依据:components/FAQSection.tsx:13-17)

这意味着:

没有 YAML frontmatter 要求、没有保留关键字、没有解析失败一说。
常见分节(项目概览 / 构建测试命令 / 代码风格 / 测试说明 / 安全注意)只是惯例,不是强制(依据:components/HowToUseSection.tsx:16-29)。
因为门槛几乎为零,它才能铺开到很大规模——官网称有 6 万+ 开源项目在用(依据:components/ExampleListSection.tsx:76-80 的 GitHub 代码搜索链接)。

一句话直觉: 它不是「配置文件」,是「便条」。机器按自然语言读,不按字段解析。

3.2 就近生效 + 用户最高:冲突怎么裁

要解决的小问题: 一个大仓可能有多个 AGENTS.md(根一个、每个包一个),还叠加用户当场说的话。到底听谁的?

规则原文: 「离被编辑文件最近的 AGENTS.md 赢;显式的用户对话指令盖过一切。」(依据:components/FAQSection.tsx:18-22)

裁决顺序(从高到低):

① 用户在对话里的临时指令        ← 永远最高
② 离「正在改的文件」最近的 AGENTS.md
③ 更外层(更靠近仓库根)的 AGENTS.md

为什么这么设计。 「就近」= 局部约定比全局约定更懂当前上下文(某个子包也许用完全不同的语言和风格);「用户最高」= 保证人始终能一句话推翻文件里的任何默认。这两条合起来,让约定既能分层细化、又不会把人锁死。

3.3 monorepo 嵌套:每个子项目一份

要解决的小问题: 一个巨型 monorepo 里不同子项目技术栈天差地别,塞进一个根文件既臃肿又互相打架。

规则原文: 「在每个包里再放一个 AGENTS.md。Agent 会自动读目录树里最近的那个,所以最近的优先,每个子项目都能带定制说明。写作时 OpenAI 主仓有 88 个 AGENTS.md 文件。」(依据:components/HowToUseSection.tsx:35-40)

结构示意:

monorepo/
├── AGENTS.md               # 全仓通用:整体架构、通用提交规范
├── packages/
│   ├── api/
│   │   └── AGENTS.md       # 只讲 api:用什么 DB、怎么跑集成测试
│   └── web/
│       └── AGENTS.md       # 只讲 web:组件规范、Storybook 命令
└── ...

这条规则和 §3.2 的「就近生效」是同一枚硬币的两面:嵌套是布局手段,就近生效是裁决规则。

3.4 自动执行:agent 会真的去跑你列的命令

要解决的小问题: 光写「本项目用这些测试命令」不够——理想情况下 agent 干完活应该自己验证。

规则原文: 「会——只要你列出来。Agent 会尝试执行相关的程序化检查,并在收尾前修掉失败。」(依据:components/FAQSection.tsx:23-26)

含义与注意:

你在 AGENTS.md 里写的 pnpm test、pnpm lint 这类命令,agent 会当成「完工前必须绿」的关卡去跑。
所以这些命令要真实可跑、别写危险副作用——它们会被自动执行。
这条把 AGENTS.md 从「说明书」升级成了「验收清单」:它不只告诉 agent 怎么做,还告诉 agent 怎么自证做对了。

3.5 落地与迁移:各家工具怎么接

要解决的小问题: 有的团队已经有别的约定文件名(如 AGENT.md 单数),有的工具默认不读 AGENTS.md。约定给了低成本迁移路径。

从旧文件名迁移(依据:components/FAQSection.tsx:32-48):

改名 + 建软链,兼容仍在找旧名字的工具:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

让 Aider 读它(依据:components/FAQSection.tsx:50-66)——在 .aider.conf.yml 里:

read: AGENTS.md

让 Gemini CLI 读它(依据:components/FAQSection.tsx:68-88)——在 .gemini/settings.json 里:

{
  "context": {
    "fileName": "AGENTS.md"
  }
}

可随时更新。 约定明确把 AGENTS.md 当「活文档」——改了就改了,没有版本仪式(依据:components/FAQSection.tsx:27-30)。

3.6 生态:谁在支持它

约定的价值来自网络效应——支持的工具越多,写一份 AGENTS.md 的回报越高。官网维护了一份兼容清单(components/CompatibilitySection.tsx:14-142),节选:

类别	代表工具
CLI / 编码 agent	OpenAI Codex、Amp、Aider、Gemini CLI、opencode、goose、Kilo Code
IDE / 编辑器	Cursor、VS Code、Zed、Windsurf、Junie(JetBrains)
云端 / 平台 agent	Jules(Google)、Devin(Cognition)、Factory、Phoenix、Ona、GitHub Copilot Coding agent
其他	RooCode、Warp、Semgrep、UiPath、Augment Code

卖点被官网概括成一句:「一份 AGENTS.md,跨众多 agent 通用」(依据:components/CompatibilitySection.tsx:330)。

治理。 约定不属于某一家:它由 Linux Foundation 旗下的 Agentic AI Foundation 托管(依据:components/AboutSection.tsx:20-32),页脚署名 LF Projects(依据:components/Footer.tsx:6-13)。这解释了为什么它敢叫一个通用名字 AGENTS.md 而不是某家的专有文件名(依据:components/WhySection.tsx:56-60)。

4. 边界与局限(诚实)

没有强制力。 约定不定义解析器、不定义 schema、不做校验;某个工具是否读、怎么读 AGENTS.md,取决于它自己。约定只提供「预期行为」,不提供保证。
就近生效等语义靠各家实现兑现。 「最近的赢」「用户最高」「自动跑测试」这些行为写在约定里,但执行发生在 agent 工具内部——本仓库不含这套逻辑的代码,只含描述它的文字(依据:components/FAQSection.tsx:18-26)。
无冲突以外的合并规则。 约定只说了「最近的赢」,没定义多个同级文件如何合并、是否继承外层内容的细则——留给实现方。
规范即营销文案。 这份约定目前的「权威文本」就是 README 和官网 FAQ 的散文,没有独立的形式化规范文档。想抠边界只能读这些散文 + 各家工具自己的文档。

5. 代码地图(导航索引)

主题	文件路径	符号 / 锚点
无必填字段	`components/FAQSection.tsx`	`faqItems`("Are there required fields?")
冲突裁决 / 就近生效	`components/FAQSection.tsx`	`faqItems`("What if instructions conflict?")
自动跑测试	`components/FAQSection.tsx`	`faqItems`("Will the agent run testing commands...")
迁移 / Aider / Gemini 配置	`components/FAQSection.tsx`	`faqItems`(migrate / Aider / Gemini)
README vs AGENTS.md 分工	`components/WhySection.tsx`	`WhySection`
怎么用 / 嵌套 / 88 文件	`components/HowToUseSection.tsx`	`steps`
兼容工具清单	`components/CompatibilitySection.tsx`	`agents`(数组)
治理 / 基金会	`components/AboutSection.tsx`、`components/Footer.tsx`	`AboutSection`、`Footer`
真实 AGENTS.md 样例	仓库根 `AGENTS.md`	整文件

6. 横向对比

同 shelf(ai-agent-reference / coding-agents)里,AGENTS.md 与各家 agent 的「指令文件」是共识层 vs 实现层的关系:

AGENTS.md = 只定义「放哪、装什么、谁优先」的跨厂商格式共识,不含执行逻辑。
具体 agent(如 Codex、Cursor) = 真正读取并执行这份文件的运行时——就近查找、注入上下文、跑命令的代码在它们那边。

换句话说:本仓库是「插头标准」,各家 agent 是「插座」。想理解运行时怎么把 AGENTS.md 注入模型上下文、怎么裁决优先级,要去看具体 agent 子库的实现,而不是这里。

3.1 无必填字段:它只是普通 Markdown​

3.2 就近生效 + 用户最高:冲突怎么裁​

3.3 monorepo 嵌套:每个子项目一份​

3.4 自动执行:agent 会真的去跑你列的命令​

3.5 落地与迁移:各家工具怎么接​

3.6 生态:谁在支持它​

4. 边界与局限(诚实)​

5. 代码地图(导航索引)​

6. 横向对比​