Codex AGENTS.md 项目指令：让 Codex 懂你的项目

用过几次 Codex 后你会发现一个尴尬：它每次都是"失忆"的——不知道你的项目用什么命令、有什么约定，总要你反复交代。AGENTS.md 就是治这个的：一份放在项目里的说明书，让 Codex 每次开工前先读一遍，从此"懂规矩"。

AGENTS.md 是什么

一个 Markdown 文件，内容是"Codex 在本项目里应该遵守的规则"。Codex 在开始任何工作前都会读取它（官方原文确认）。

和你在对话里交代的区别：

Codex 每次运行都会重新整理一份"指令链"（官方原文），按两层叠加：

第一层：全局（你自己的规则）

在 Codex 主目录，默认 ~/.codex（可用环境变量 CODEX_HOME 改）。查找顺序：

~/.codex/AGENTS.override.md  →  优先
~/.codex/AGENTS.md           →  其次

这一层放"你对所有项目通用的要求"（比如"回复用中文""别改没有明说的文件"）。

第二层：项目（跟着仓库走）

从项目根目录（通常是 Git 根）一路查到当前目录，每一级按：

AGENTS.override.md → AGENTS.md → 其他备用文件名

每个目录最多取一个文件。

合并规则（官方原文）：从根到当前目录拼接，越靠近当前目录的文件越靠后——越具体的规则越靠后、覆盖力越强。总大小有上限（默认 32 KiB，可调），超出部分不加载。

官方文档给了一套非常实用的思路，核心是"反馈回路"：

从真正重要的指令开始——构建命令、测试命令、评审期望、仓库特有约定
纠正了 Codex 就顺手更新它——当它对你的代码库做了错误假设，把修正写进 AGENTS.md，并要求它"顺手更新 AGENTS.md"，让修正延续到后续会话
保持精简——它每次都要读，越长越稀释重点
什么时候该加：
- Codex 反复犯同一个错 → 补规则
- 它读太多无关文件 → 给路径引导（"优先看 src/ 和 docs/"）
- 反复出现的 PR 反馈 → 固化下来

# 项目规则

## 命令
- 包管理用 pnpm，不要用 npm
- 测试命令：pnpm test

## 硬性约束
- 不要修改 src/core/ 下的任何文件
- 提交信息用中文，格式：类型: 说明

## 路径
- 优先看 src/ 下的代码，docs/ 是设计文档

问题	解答
全局和项目规则冲突听谁的？	项目层在后，覆盖全局（越具体越优先）
改了 AGENTS.md 马上生效吗？	新会话生效；交互中可重新加载
它读太多文件怎么办？	加路径引导 + 必要时调大 32 KiB 上限
能自动生成吗？	可以！交互模式敲`/init`，Codex 自动生成一份（详见exec 模式篇）

AGENTS.md 是把"你和 Codex 的默契"写下来的地方。 写好了，它从"每次都要教的实习生"变成"懂项目规矩的老员工"。