1. 背景
在多代理协作（如 Codex、Claude Code）场景中，项目级指令文件用于约束代码风格、目录规范、测试要求和协作流程。常见文件名是 AGENTS.md 与 CLAUDE.md。
2. 两个文件的定位
AGENTS.md：Codex 生态常见的项目指令文件名。CLAUDE.md：Claude Code 常见的项目指令文件名。
两者本质上都属于“项目运行/协作说明”，只是不同工具默认识别的文件名不同。
3. 关键原则
- 单一真源：建议只维护一份完整内容，避免双文件长期手工同步。
- 防止空壳抢优先级：若工具优先读取
AGENTS.md，空壳AGENTS.md可能导致完整规则失效。 - 明确加载顺序：在工具配置中声明 fallback 文件名，避免依赖隐式行为。
4. 本仓库当前实践
- 完整规则保存在仓库根目录
CLAUDE.md。 - 根目录不再保留空壳
AGENTS.md。 - Codex 使用
project_doc_fallback_filenames回退读取CLAUDE.md。
当前实测（codex-cli 0.114.0）中，project_doc_fallback_filenames 放在 ~/.codex/config.toml 顶层可生效。
5. 推荐配置示例（Codex）
model = "gpt-5.3-codex"
project_doc_fallback_filenames = ["CLAUDE.md"]
说明：
- 将该键放在
config.toml顶层。 - 项目级
[projects."..."]段仍用于trust_level等项目属性。
6. 验证是否生效
- 确认仓库根目录不存在空壳
AGENTS.md。 - 新开 Codex 会话执行一次最小命令。
- 检查会话日志中是否出现
CLAUDE.md里的关键句。
示例命令：
env -u CODEX_THREAD_ID -u CODEX_CI -u CODEX_SANDBOX_NETWORK_DISABLED \
codex exec -C /mnt/datas/mmzyc/v10repos/hsmm-v10 "请只回复: TEST_OK"
SESSION_FILE=$(ls -t ~/.codex/sessions/*/*/*/rollout-*.jsonl | head -n1)
rg -n "项目结构与模块组织|make generate-init|clusterCodeGenerate|Repository Guidelines" "$SESSION_FILE"
若命中 CLAUDE.md 中的特征内容，即可判定 Codex 已通过 fallback 正确加载。
7. 常见误区
- 误区 1：保留空壳
AGENTS.md并期望自动跳转到CLAUDE.md。 - 误区 2：修改配置后不重开会话直接验证。
- 误区 3：在继承了旧线程环境变量的会话中做加载验证，导致结果被污染。