AGENTS.md 多层配置实战：让 Codex 真正读懂你的项目规范

Codex中文教程大全 2026/9/29 约 1100 字大约 6 分钟

一、为什么需要 AGENTS.md

Codex 每次启动时都会自动读取 AGENTS.md 文件。这个文件相当于给 AI 智能体的"入职培训手册"，告诉它项目的技术栈、编码规范、安全红线和常用命令。没有它，Codex 只能靠猜；有了它，你可以把"每次都要重复交代的背景"一次性固化下来。

核心价值：减少来回沟通，让 Codex 按项目习惯工作，而不是每次从零开始。

二、文件加载顺序（优先级从高到低）

理解多层配置是写对 AGENTS.md 的前提。Codex 支持 6 层加载机制：

~/.codex/AGENTS.override.md    （全局覆盖，最高优先级）
~/.codex/AGENTS.md             （全局默认）
<项目根>/AGENTS.override.md    （项目覆盖）
<项目根>/AGENTS.md             （项目默认，最常用）
<子目录>/AGENTS.override.md    （子目录覆盖）
<子目录>/AGENTS.md             （子目录默认，最低优先级）

关键规则： - 所有文件按顺序合并，后加载的文件覆盖前面的同名区块 - 空文件被忽略 - 合并后总大小不能超过 project_doc_max_bytes（默认 32KB），超出部分被静默截断（不报错！）

踩坑点：Windows 记事本保存的 AGENTS.md 容易变成 ANSI 编码，导致 Codex 无法解析。务必用 UTF-8 编码保存。

三、写什么、不写什么

必须写的内容

内容类型	示例	原因
技术栈与主要依赖	React 18 + TypeScript + Vite + pnpm	Codex 猜不到你的具体选型
目录结构说明	`src/components/` 放组件，`src/api/` 放接口封装	防止乱建文件、乱改生成代码
编码规范	函数式组件、camelCase 命名、2 空格缩进	团队协作底线
常用命令	启动 `pnpm dev`、测试 `pnpm test`、构建 `pnpm build`	Codex 知道如何验证改动
安全红线	禁止修改 `.github/workflows/`、禁止硬编码密钥	硬性约束，必须单独强调

不必写的内容

内容类型	原因
完整依赖版本号	读 `package.json` 就行
详细 ESLint 规则	交给 lint 工具，别塞给它
业务背景长篇大论	占上下文，除非真的影响代码决策

经验法则：AGENTS.md 控制在 100-200 行以内。它不是文档，是约束。写得越长，每条规则的权重越低。

四、可直接复制的生产级示例

# AGENTS.md - 内部数据看板项目

## 项目概述
React 18 + TypeScript + Vite，部署在内部环境。

## 代码标准
- 使用函数式组件，禁止 class 组件
- 所有函数必须有 JSDoc 注释
- 单元测试覆盖率 ≥ 80%，用 Vitest
- E2E 测试用 Playwright

## 架构约束
- API 路由必须 RESTful
- 数据库操作仅限 Repository 层，禁止在 Controller 中直连
- 组件状态管理用 Zustand，不用 Redux

## 安全红线
- **禁止**修改 `.github/workflows/` 下的文件
- **禁止**执行 `eval()`、`Function()` 等动态代码
- **禁止**在源码中硬编码密钥，必须用环境变量

## 工具链
- 启动命令：`pnpm dev`
- 测试命令：`pnpm test`
- 构建命令：`pnpm build`
- 代码检查：`pnpm lint`

## 验证方式
改完代码后必须跑通 `pnpm test`，测试全绿才算完成。

五、验证是否生效

写完 AGENTS.md 不代表它就一定遵守，需要主动验证：

# 用只读沙箱执行一条命令，看 Codex 是否读到了规则
codex --sandbox read-only "总结一下你加载的指令内容"

如果输出包含"禁止修改 .github/workflows/"，说明加载成功。如果输出为空或无关内容，逐项排查：

编码问题：file AGENTS.md 确认是 UTF-8
覆盖问题：检查是否有 AGENTS.override.md 覆盖了它
大小超限：wc -c AGENTS.md 确认不超过 32KB
位置错误：确认文件在项目根目录，而不是嵌套子目录

六、Monorepo 进阶：子目录分层

如果你有 monorepo（前端 + 后端），可以在子目录放各自的 AGENTS.md：

your-project/
├── AGENTS.md              # 全局通用规则（包管理器、Git 规范）
├── frontend/
│   └── AGENTS.md          # React/TS 特有规范
└── backend/
    └── AGENTS.md          # Go/Python 特有规范

就近优先：子目录的规则会覆盖根目录的冲突项。这在前后端规范完全不同的场景下非常实用——根目录只放全局通用部分，各模块自己的规范放在各自的子目录。

七、常见踩坑清单

坑	现象	解决方案
文件写太长	智能体反而不听话，规则被稀释	控制在 200 行以内，只保留高频关键规则
用了"建议"语气	遵守率低	改成命令式："使用函数式组件"而非"我们倾向于使用函数式组件"
敏感信息泄露	AGENTS.md 进了 Git 仓库	不要写任何密钥、token、内部地址
子目录规则冲突	"明明根目录写了禁止，还是这么干了"	确认子目录没有相反的规则，就近优先
Windows 编码	Codex 读不到文件内容	强制保存为 UTF-8（无 BOM）

总结

AGENTS.md 是 Codex 从"通用助手"变成"懂你项目的项目成员"的关键一步。写的时候记住三句话：写约定不写教程、写规则不写态度、写约束不写文档。控制篇幅，用命令式语气，定期验证是否生效——这就是把 AI 真正嵌进工作流的最小成本投入。

来源：编程知识网站《Codex CLI 生产级使用手册：安装配置、安全沙箱与高手技巧》，发布时间 2026-09-28。原文地址：http://www.hqwc.cn/a/259805.html

资料最后核对日期：2026-09-29 · 内容整理自 CodexGuide 社区公开教程