第二十八课：多层级配置

学习目标

• 理解 AGENTS.md 的多层级配置机制
• 掌握优先级和继承关系
• 了解如何组织大型项目的配置

一、三层配置

AGENTS.md 支持三个层级的配置：

1.1 全局配置

位置：~/.codex/AGENTS.md

全局配置适用于所有项目，通常包含：

• 通用的编码偏好
• 默认的工具配置
• 个人的工作习惯

1.2 项目配置

位置：项目根目录/AGENTS.md

项目配置适用于特定项目，通常包含：

• 项目技术栈
• 环境设置命令
• 项目特定的规范

1.3 目录配置

位置：子目录/AGENTS.md

目录配置适用于特定目录，通常包含：

• 目录特定的规范
• 模块特定的测试命令
• 特殊的代码风格

二、优先级

配置的优先级从高到低：

1. 目录配置（最具体）
2. 项目配置
3. 全局配置（最通用）

当存在冲突时，更具体的配置会覆盖更通用的配置。

三、继承关系

各层级的配置会合并，而不是完全替换：

• 全局配置定义基础行为
• 项目配置添加项目特定信息
• 目录配置添加目录特定信息

四、大型项目组织

4.1 按模块组织

project/
├── AGENTS.md           # 项目通用配置
├── src/
│   ├── frontend/
│   │   └── AGENTS.md   # 前端模块配置
│   ├── backend/
│   │   └── AGENTS.md   # 后端模块配置
│   └── shared/
│       └── AGENTS.md   # 共享模块配置
└── tests/
    └── AGENTS.md       # 测试配置

4.2 配置示例

项目根目录 AGENTS.md：

# 项目概述
这是一个全栈项目，使用 React + Node.js。

## 通用规范
- 使用 TypeScript
- 使用 ESLint + Prettier
- 提交信息遵循 Conventional Commits

前端模块 AGENTS.md：

# 前端模块
使用 React 18 + Vite + Tailwind CSS。

## 命令
- 启动：pnpm dev:frontend
- 测试：pnpm test:frontend
- 构建：pnpm build:frontend

五、配置冲突处理

当存在冲突时：

1. 更具体的配置优先
2. 同一层级的配置按文件顺序合并
3. 可以使用注释说明配置来源

六、本课小结

要点	说明
三层配置	全局→项目→目录
优先级	目录 > 项目 > 全局
继承	合并而非替换
组织方式	按模块组织配置

下一步

下一课我们将学习 /init 自动生成。