23 · AGENTS.md 高级用法

概述

上一篇文章介绍了 AGENTS.md 的三层加载机制，这是 AGENTS.md 体系的基础。但在实际的大型项目中，三层结构往往不够灵活。团队经常面临这样的场景：同一个 Git 仓库中包含多个服务或模块，每个模块都有自己的独特规范，同时还要继承项目级的通用规则。

AGENTS.md 的高级用法——多级覆写体系——正是为解决这类复杂场景而设计的。本文将深入探讨多级覆写、AGENTS.override.md 的机理、从根到叶的拼接规则，以及覆盖场景的真实案例。

多级覆写体系

基本概念

多级覆写体系允许你从项目根目录到任意深度的子目录逐层定义 AGENTS.md。每一层都会在前一层的基础上追加指令，同时允许同名指令的覆盖。

这个体系由三个核心概念支撑：

1. 继承：子目录默认继承父目录的所有 AGENTS.md 指令
2. 追加：子目录的 AGENTS.md 内容追加到已继承指令的后面
3. 覆盖：如果子目录重新声明了父目录已有的指令，子目录版本胜出

拼接规则详解

Codex 在加载 AGENTS.md 时，会使用"从根到叶"的拼接策略。

具体流程如下：

1. 加载 ~/.codex/AGENTS.md（全局层） 2. 定位 Git 根目录，加载根目录下的 AGENTS.md（项目层） 3. 递归查找从根目录到当前工作目录路径上的所有子目录 AGENTS.md 4. 按路径顺序拼接：全局 → 项目根 → dir1 → dir2 → ... → current_dir 5. 同一指令名在后出现的版本覆盖先出现的版本 6. 总内容超过 32KB 时截断，按文件加载顺序从末尾截断

拼接示例

假设项目结构如下：

my-project/ ├── AGENTS.md # 项目层 ├── services/ │ ├── AGENTS.md # 目录层 A │ ├── api-gateway/ │ │ └── AGENTS.md # 目录层 B │ └── user-service/ │ └── AGENTS.md # 目录层 C └── frontend/ └── AGENTS.md # 目录层 D

当你在services/api-gateway/目录下工作时，最终拼接的指令来自：

1. ~/.codex/AGENTS.md（全局）
2. my-project/AGENTS.md（项目）
3. my-project/services/AGENTS.md（目录层 A）
4. my-project/ser