引言：AGENTS.md 的“过犹不及”困境

在 AI 辅助编程的实践中，AGENTS.md 文件常常经历一个有趣的演变过程：许多开发者最初觉得它“没什么用”，但随着使用深入，又容易走向另一个极端——恨不得把整个项目说明书、模型名单、价格表、临时通知全部塞进去。结果往往很喜感：文件越来越长，自己看着特别“规范”，但 Codex 反而开始“漏规则”。

你以为它不听话，第一反应是继续加几条规则；再加几轮，整份文件就成了大杂烩。其实 AGENTS.md 真没那么玄。排查它不生效时，先别急着重装 Codex，也别怀疑模型有问题。应该先看三件事：它到底读了哪份文件、谁把谁覆盖了、合并内容有没有顶到上限。

第一原则：写能验收的动作，而不是“正确的废话”

“请写高质量代码”、“请保持专业”、“注意代码安全”……这些话放哪儿都没错，但真到了执行时，Codex 很难知道什么叫“做到了”。我更喜欢把规则写得有点“笨”，但能验收。

例如：

# Project instructions

## Tests
- 修改 Python 文件后运行：`python3 -m unittest discover -s tests -v`
- 如果测试跑不了，说明原因，不得写“测试通过”

## Editing
- 不修改 `generated/` 目录
- 保留用户已有未提交改动

## Response
- 列出修改文件、实际运行的测试命令和结果

这类规则有一个好处：你不用猜 Codex 到底“理解没理解”，看最终结果就知道。能观察、能失败、能验收，比写一百句漂亮话管用。

排查第一步：它读的是不是这份文件？

AGENTS.md 不生效，八成要先查“它读的是不是这份”。官方现在的读取逻辑是分层的，而且是每次运行/会话启动时建立指令链。

读取层级与优先级

Codex Home 默认在 ~/.codex，这一层如果有 AGENTS.override.md，它会优先用 override；没有才读普通的 AGENTS.md。

项目里则从项目根目录一路往你当前工作目录走。每一层的查找顺序是：

1. AGENTS.override.md
2. AGENTS.md
3. 你在 project_doc_fallback_filenames 里配置的 fallback 文件名

同一个目录最多取一份。越靠近当前工作目录的规则越晚加入，所以冲突时更具体的下层规则会覆盖上层。这不是 Codex “随机抽风”，而是设计如此。

目录结构示例

repo/
├── AGENTS.md
└── frontend/
    ├── AGENTS.override.md
    └── src/

从 frontend/src 里启动 Codex 时，会先吃到根目录的通用规则，再把前端 override 加进来。你要是只盯着根目录 AGENTS.md 看，当然会觉得“咋就不听呢”。

排查第二步：改了规则却没变化？先开个新会话

还有个特别容易被忽略的小细节：AGENTS.md 的发现是在运行开始时建立的。你在一个已经跑了很久的会话里改文件，然后立刻问“为什么还没生效”，这个测试本身就不太干净。

最省事的做法是：改完规则，新开一次 Codex 会话，用一个只读的小任务验证。别在旧上下文里跟它拉扯半天，费劲不讨好。

排查第三步：32 KiB 不是“每个文件 32 KiB”

这个坑也挺常见。官方的 project_doc_max_bytes 默认是 32 KiB，限制的是合并后的项目指令，不是说根目录能写 32 KiB、子目录还能再白送 32 KiB。

一旦合并内容到上限，Codex 就会停止继续加入后面的文件。你要是每个目录都复制一遍同样的规范，看着挺勤快，实际上是在拿宝贵空间堆重复内容。

接近上限时的优化策略

接近上限时，我会先做这三件事：

1. 删重复：跨目录重复的规则删掉，只保留一份
2. 下沉规则：只对某个子目录有效的规则下沉到那个目录
3. 挪流程：只有特定任务才用的一长串流程，挪到 Skill，别让它天天常驻

顺手提醒：上限不是死的，配置项可以调整。但多数项目真正的问题不是“32 KiB 太小”，而是规则写得太散、太重复。先减肥，通常比直接把上限拧大更靠谱。

最简单的验证方法：故意放一条“傻规则”

排查加载顺序时，不用拿真实业务规则硬测。临时加一个明显、无害、看一眼就知道有没有生效的标记，反而最省脑子。

根目录 AGENTS.md：

回答第一行必须写：PROJECT_RULE_ACTIVE

frontend/AGENTS.override.md：

回答第一行必须写：FRONTEND_RULE_ACTIVE

分别从根目录和前端子目录发起只读请求。如果输出符合预期，说明加载链路没毛病。验证完把这类测试标记删掉，别真留在生产项目里，怪尴尬的。

哪些东西别往 AGENTS.md 里硬塞

我最不建议长期写死的，就是这几样：

• API Key（敏感信息）
• 模型实时名单（会变）
• 价格、折扣（会变）
• 渠道状态（会变）
• 临时活动（会变）

原因也不复杂：Key 是敏感信息，其他几样都是会变的。今天正确的价格，过几天可能就不是这个数；今天最合适的模型，下个月也可能换。把它们塞进 AGENTS.md，时间一长就变成“看着像事实库，其实是旧截图”。

AGENTS.md 与 AI Code With 的分层设计

如果你的团队会通过第三方 Provider 调模型，我更建议把 AGENTS.md 和 AI Code With 分成两层：

• AGENTS.md：负责稳定规则
• AI Code With：负责会变化的模型、渠道、余额和使用记录

这样 AGENTS.md 里不用天天追着价格改，也不用把 API Key 藏在项目文件里。真正执行任务时，再去 AI Code With 看当前模型和渠道状态。

说白了，一个管“原则”，一个管“现状”，别搅成一锅粥。

示例规则

## Model usage
- 调用外部模型前，先核对 AI Code With 当前模型与渠道
- 优先选择满足质量要求的较低成本方案
- 超过任务预算时停止并报告
- API Key 不写入 AGENTS.md 或仓库
- 最终报告里记录实际使用的模型与结果，不写死长期价格

这几条规则本身很耐用。哪怕模型换了、渠道调整了，AGENTS.md 也不用跟着大动干戈。对经常在 Codex 里切模型、跑长任务的人，这比写死一堆型号靠谱得多。

排查流程总结：我会按这个顺序查“不生效”

1. 确认当前工作目录：是不是你以为的目录
2. 查全局 override：~/.codex 里有没有 AGENTS.override.md
3. 逐层查找：从项目根目录一路往当前目录找，有没有更近的 AGENTS.override.md
4. 检查覆盖关系：确认同一目录里不是 override 把普通 AGENTS.md 顶掉了
5. 检查上限：合并内容是不是快到 32 KiB 默认上限
6. 新开会话验证：用一条无害的可观察规则做验证
7. 审视规则本身：是不是写得太抽象、互相打架

结论

AGENTS.md 不是越长越厉害，也不是写得像公司制度就越“听话”。它真正好用的状态，是短、稳定、能验收，而且层级清楚。

如果规则开始涉及模型选择和成本，把固定模型名、价格、渠道状态删掉，改成“运行前核对”。需要执行时再去 AI Code With 看实时模型和渠道。这样项目规则不容易过期，排错也没那么鸡飞狗跳。

参考链接

• AI Code With：https://aicodewith.ai/zh?s=m4d9w7
• OpenAI AGENTS.md：https://developers.openai.com/codex/guides/agents-md