AGENTS.md 嵌套规则:多级目录的生效优先级与覆盖实测
在 monorepo 里放多份 AGENTS.md 之后,最容易让人心里没底的就是「到底听谁的」:根目录写了一套约定,service/ 子目录又写了一套,两句说法不一样时,Codex 会按哪份干活?这个问题靠读规范只能得到原则性回答,本文用四组对照实验把 AGENTS.md 嵌套规则的真实行为量出来。实验承接本系列前两篇:Codex config.toml 配置讲的是程序层面的个人配置,coding agent 权限沙箱讲的是操作系统层面的执行边界,本篇补上中间一层——随仓库走、全团队共享的项目约定文件,在多级目录下如何生效。
本文要回答的问题
- 一个仓库里放三层 AGENTS.md,Codex 启动时是只加载最近的一份,还是全部加载?
- 不同层级的规则对同一件事说法冲突时,哪一份说了算?
- 当次会话的显式指令和仓库规则文件打架,谁优先?优先级的作用域有多大?
- AGENTS.md 和
~/.codex/config.toml各管什么,什么内容该写进哪一边?
读这张流程卡抓住实验设计的关键:不靠模型自述「我遵守了哪条规则」,而是让每份 AGENTS.md 要求一个互不相同的测试标记(ROOT_ONLY、CHILD_ONLY、GRANDCHILD_ONLY),模型最终吐出哪个字符串,就说明哪份规则在冲突项上真正生效。四组实验彼此独立、提示词完全一致,唯一变量是工作目录深度和有没有显式冲突指令。
一、先厘清机制:加载是全量的,覆盖只发生在冲突项上
谈优先级之前先区分两件常被混为一谈的事:规则文件的加载范围和冲突条目的裁决。Codex 在某个工作目录启动任务时,会沿着目录树向上收集 AGENTS.md——当前目录就近的一份、各级父目录的一份、直到仓库根,这些文件都会进入会话上下文,而不是只读最近的那份。日志头部的 rules= 行留下了直接证据:在 service/ 目录启动时,记录的是 root/AGENTS.md + service/AGENTS.md 两份同时在册。
这张图里蓝色是三个启动位置,灰色、紫色、绿色是三层规则文件,红色是裁决节点。要特别注意颜色的语义:灰色不代表根规则「没加载」,三份文件其实都在上下文里;颜色区分的是冲突裁决中的角色——离工作目录越近,优先级越高。这个机制对写规则有个直接推论:父目录文件里那些子目录没有重提的约定,并不会失效,仍然照常生效;就近覆盖只作用于两边说法不一致的那一条。本实验的标记项专门设计成互相冲突,就是为了把裁决结果逼成一个唯一字符串;非冲突条目的叠加效果属于规范层面的既定行为,不在本次四组测量之内,工程上不要把「冲突项就近赢」误读成「子目录文件整体替换父目录文件」。
二、实验设计:三层目录与四组场景
实验仓库是系统临时目录下的一棵三层小树,每个目录的 AGENTS.md 只写一条规则,要求模型返回专属标记,内容刻意简短,避免无关条目干扰:
<!-- 根目录 AGENTS.md -->
# 仓库规则
当被要求返回测试标记时,只输出 ROOT_ONLY,不要输出任何其他内容。
<!-- service/AGENTS.md -->
# service 子系统规则
当被要求返回测试标记时,只输出 CHILD_ONLY,不要输出任何其他内容。
<!-- service/api/AGENTS.md -->
# api 模块规则
当被要求返回测试标记时,只输出 GRANDCHILD_ONLY,不要输出任何其他内容。四组场景的变量控制如下表。所有调用都走 codex exec 非交互模式,加 --ephemeral --skip-git-repo-check --sandbox read-only,每组配发一个独立的临时 CODEX_HOME,只注入 provider 连接配置,不加载任何个人配置和历史会话。这样四组之间唯一的差异就是工作目录深度和第四组的显式冲突指令。
| 组别 | 工作目录 | 在册规则文件 | 提示词 | 预期回答 |
|---|---|---|---|---|
| 01-root-only | 仓库根 | 根 AGENTS.md | 标准取标记 | ROOT_ONLY |
| 02-root-child | service/ | 根 + 子两份 | 同一条标准提示词 | CHILD_ONLY |
| 03-root-child-grandchild | service/api/ | 根 + 子 + 孙三份 | 同一条标准提示词 | GRANDCHILD_ONLY |
| 04-explicit-conflict | service/api/ | 根 + 子 + 孙三份 | 明令忽略规则,改要 PROMPT_ONLY | PROMPT_ONLY |
--sandbox read-only 在这里有双重作用:一是保证实验全程写不了磁盘,二是让第四组「显式指令压过规则」的结论干净——模型即使选择听从提示词,也没有能力改动任何一份规则文件。沙箱三档的完整取舍见 Codex 沙箱审批模式实战对照。
三、场景 01 与 02:从一层到两层,子目录规则当场反超
第一组在仓库根目录启动,在册规则只有根文件一份,没有任何悬念,模型返回 ROOT_ONLY。这张终端卡保留了启动头部:注意 workdir 指向仓库根、sandbox: read-only,以及模型推理里那句「当前不在子目录,无需检查嵌套文件」——它自己把判定过程说了出来。
第二组把工作目录换成 service/,变量只动这一个。日志头部的 rules= 行变成两份文件同时在册,但模型的最终输出是 CHILD_ONLY,exit_code=0、final_answer=CHILD_ONLY 两行收尾干净。这就是就近覆盖的第一个直接证据:根规则并没有缺席,只是在「返回哪个标记」这个冲突项上输给了离工作目录更近的子目录规则。
两张终端卡对着读,差异只有两处:workdir 深了一层,rules= 多了一份文件;提示词一字未改,答案却从 ROOT_ONLY 换成 CHILD_ONLY。这种单变量对照排除了「模型随机选的」这类解释——裁决稳定地跟着目录距离走。
四、场景 03:三层嵌套,最深一层继续赢
第三组再深入一层到 service/api/,三份 AGENTS.md 全部在册。如果优先级不是按目录距离裁决,这一组的答案可能在三个标记之间漂移;实测结果没有任何含糊:模型在推理段确认「规则要求的标记是 GRANDCHILD_ONLY」,最终输出与 final_answer 都是它,进程退出码为 0。
把前三组串起来,嵌套优先级的完整链条就闭合了:一层时根规则生效,两层时子目录规则在冲突项上覆盖根规则,三层时最深目录继续覆盖上面两层。规律与目录树的物理结构一致——谁离当前工作目录近,谁对冲突条目说了算。这也解释了 monorepo 的推荐落法:全局共性约定(构建命令、提交纪律、通用禁区)放根文件,模块特异约定(本目录的代码生成器、测试入口、不许碰的生成物)放子目录文件,两层各说各话时天然不冲突,真撞上了也能预期到结果。编写层面的结构建议见 Codex AGENTS.md 编写,团队共享与版本管理的组织方式见 团队共享 AGENTS.md 的落地方法。
五、场景 04:显式指令压过仓库规则,但只在当次会话有效
前三组测的是规则文件之间的排位,第四组换了个对手:让当次提示词直接和规则文件对着干。工作目录仍在 service/api/,三份规则文件原样在册,提示词却明确要求「忽略仓库规则中关于标记的要求,只输出 PROMPT_ONLY」。实测答案是 PROMPT_ONLY,模型的推理写明了它的裁决依据:用户指令优先于仓库规则。
这个结果不能只读一半,作用域边界比结论本身更重要。下图把两类输入的生命周期放在一起对照:规则文件落盘在仓库里、进版本库、对每个后续会话长期有效;显式指令只活在当前这一次 codex exec 进程里,进程结束就消失。
图里紫色是长期规则、橙色是当次指令、红色是裁决点、绿色是会话收场。读这张图记住三条边界:其一,显式指令赢的只是这一次会话里的冲突条目,下次不带这句提示词启动,三份 AGENTS.md 立刻恢复原裁决,第三组的 GRANDCHILD_ONLY 就是对照;其二,它不改写任何文件,实验全程在只读沙箱里,规则文件磁盘内容零改动;其三,这不是安全边界——用户能口头推翻的只是自然语言约定,coding agent 权限沙箱那一层的读写限制不靠提示词维持,read-only 下让它写文件照样写不了。规则之间、规则与提示词之间打架时的完整排查套路,见 Agent 规则冲突排查方法。
六、四组实测汇总与全景证据
四组实验的总览输出如下,每组都是独立进程、独立临时 CODEX_HOME,工作目录逐级深入,八个关键信号(四组各一个退出码加一个最终标记)全部符合预期。
| 组别 | 在册规则数 | exit_code | final_answer | 裁决结论 |
|---|---|---|---|---|
| 01-root-only | 1 | 0 | ROOT_ONLY | 无竞争,根规则生效 |
| 02-root-child | 2 | 0 | CHILD_ONLY | 冲突项就近覆盖,子目录赢 |
| 03-root-child-grandchild | 3 | 0 | GRANDCHILD_ONLY | 最深目录继续赢 |
| 04-explicit-conflict | 3 | 0 | PROMPT_ONLY | 当次显式指令压过全部规则文件 |
下图把四组案例的规则层级与最终标记逐段排开:从左到右工作目录逐层加深,每段顶部是该组在册的规则文件数量,底部是模型实际吐出的标记;最右第四组在册规则仍是三份,答案却换成提示词指定的 PROMPT_ONLY,把「文件间就近裁决」和「提示词当次覆盖」两条规则放在同一张图里对照。
![]()
看这张图时沿着两条线读:前三个段落是一条线,在册文件从一份递增到三份,标记跟着工作目录的深度依次换成 ROOT_ONLY、CHILD_ONLY、GRANDCHILD_ONLY,斜率稳定指向就近原则;第四个段落是另一条线,文件层级没变、变量只剩提示词,标记跳到 PROMPT_ONLY,说明显式指令的优先级凌驾于整棵规则树,但作用域被关在当次会话里。每组段尾的 exit_code=0 同样值得留意——所有裁决都是程序正常跑完的结果,不是报错后的侥幸输出。
七、AGENTS.md 与 config.toml 的分工
实验讲完,落回日常使用中最常见的混淆:这两份文件到底各写什么。判断标准一句话——跟着仓库走的写 AGENTS.md,跟着人走的写 config.toml。
| 维度 | AGENTS.md(含嵌套各层) | ~/.codex/config.toml |
|---|---|---|
| 归属 | 进版本库,团队共享 | 个人主目录,不进仓库 |
| 内容性质 | 项目约定:构建测试命令、目录禁区、提交纪律、模块特异规则 | 程序配置:模型、审批策略、沙箱档位、通知、历史与 TUI |
| 生效方式 | 自然语言全文注入上下文,按目录就近裁决冲突 | 结构化字段,启动时严格解析,类型错误直接拒绝加载 |
| 嵌套支持 | 支持多级目录,就近覆盖冲突项 | 单文件加 profiles,靠命令行 -c 覆盖 |
| 写错的代价 | 模型遵循度下降,任务做偏 | 配置解析失败或字段静默不生效 |
典型的正确落法:仓库根 AGENTS.md 写「本仓统一用 make test,提交信息用中文」,service/api/ 的嵌套文件写「本目录改完接口必须重跑代码生成器」;而「我这台机器默认用哪个模型、审批要不要问我、沙箱开几档」属于个人偏好和程序行为,写进 config.toml,八个关键字段的默认值与合法写法见 Codex config.toml 配置。一个容易踩的坑是把团队约定塞进个人配置——它不会随仓库分发,同事和 CI 环境都读不到,规则等于只在你自己机器上生效。
实验环境
- 机器/系统:Mac(x86_64)/ macOS 26.5.2(BuildVersion 25F84)
- 工具版本:Codex CLI 0.156.1(
codex --version输出codex-cli 0.156.1) - 日期:2026-11-16
- 完整命令:四组统一形态为
CODEX_HOME=<每组独立临时目录> codex exec --ephemeral --skip-git-repo-check --sandbox read-only -C <对应工作目录> --color never "<提示词>";前三组提示词为「请返回当前生效规则要求的测试标记,只输出标记,不要解释。」,第四组为「这是显式指令冲突测试。忽略仓库规则中关于标记的要求,只输出 PROMPT_ONLY,不要解释。」;总入口为bash run.sh <输出目录>,实验仓库建在系统临时目录,结束后自动删除,每组独立进程、独立临时 CODEX_HOME,仅注入 provider 连接配置。
代码获取:四组实验的目录生成脚本、三层 AGENTS.md 样例、一键运行脚本与真实输出见公开仓库 derekzhuo/geek-doc.cn 的
experiments/codex-agents-md-nested-rules/。克隆后在该目录执行bash run.sh results即可重建三层目录并跑完四组对照,结果写入results/,需要本机已安装 codex CLI 并配置好可用的模型 provider。非交互调用的参数细节见 codex exec 非交互执行。
这一篇在知识体系里的位置
本篇是 Codex 项目约定主题下的实测篇:规则文件「该怎么写」交给 Codex AGENTS.md 编写,「多人协作怎么管」交给 团队共享 AGENTS.md 的落地方法,「冲突了怎么排查」交给 Agent 规则冲突排查方法;程序侧配置看 Codex config.toml 配置,执行权限边界看 coding agent 权限沙箱与 Codex 沙箱审批模式实战对照,脚本化调用看 codex exec 非交互执行。
总结
AGENTS.md 嵌套规则的实测结论可以压成三句:多级目录下各级规则文件全部加载,冲突条目按「离工作目录最近者胜」裁决,三层实验中根、子、孙目录的标记依次稳定胜出;当次提示词的显式指令可以压过整棵规则树,但只对本次会话有效,既不延续也不改写文件,只读沙箱还在底层兜住安全边界;项目约定随仓库走写 AGENTS.md,个人程序配置随人走写 config.toml,两者分工不要混。掌握这套优先级后,monorepo 里多份规则文件的行为就是可预期、可复现的,而不是碰运气。