Codex AGENTS.md 怎么写：全局规则、项目规则与覆盖关系

AGENTS.md 解决什么问题

如果每次都要提醒 Codex“用哪个包管理器”“修改后跑什么验证”“不要顺手发布”，这些稳定约定就适合写进 AGENTS.md。配置文件负责运行参数，AGENTS.md 负责工作说明；后者不能代替真正的文件权限或审批策略。

规则放在哪一层

启动时，Codex 从全局说明开始，再沿项目根目录到当前工作目录逐层读取。同一目录优先采用非空 AGENTS.override.md，再找 AGENTS.md；每层最多使用一个。更靠近工作目录的规则后加入，对冲突约定更具体。不要假定从仓库根目录启动就会预加载所有子目录规则。

一份能直接改写的项目模板

# 项目协作说明

## 先读什么
- 开始前阅读 README.md，确认目录和运行方式。
- 修改前检查现有实现，保留用户尚未提交的改动。

## 常用命令
- 安装依赖：npm ci
- 构建验证：npm run build
- 只在 package.json 存在对应脚本时运行测试。

## 修改约定
- UI 文案同时维护中文和英文。
- 不在源码、日志或示例里写入真实密钥。
- 不主动启动或停止用户正在运行的开发服务。

## 交付
- 说明改了什么、验证结果和仍未确认的问题。
- 提交和发布分别等待用户明确要求。

上面的命令只是 npm 项目的示例。仓库使用 pnpm、Python 或其他工具时，应按真实环境替换。比起写“保证代码质量”，明确构建入口、兼容要求和哪些动作要等授权更容易检查。

全局写偏好，项目写事实

• 全局文件适合语言、说明风格和稳定协作方式；不适合写某个仓库专用命令。
• 项目文件适合目录说明、测试入口与变更约束。路径和脚本变化后同步更新。
• 子目录文件只保留差异，避免复制整篇根目录规则。
• 不要把密钥、客户数据或大段日志当作长期指令。

确认规则真的加载了

codex "先不要修改文件。列出你加载的项目说明文件，以及本项目的验证命令。"

改完后新开会话再验证。若结果不符合预期，检查工作目录、CODEX_HOME、同层 override 文件、文件是否为空以及说明长度。默认合并上限为 32 KiB；长到被截断时，先压缩重复内容，不要不断追加规则。