Codex与AGENTS.md：2000行提示工程最佳实践

Codex 近期的热度确实惊人，与 Claude Code 一同，已成为继 OpenClaw 之后 AI 领域最受瞩目的两大关键词。用工具来类比，Claude Code 偏向管理调度，Codex 侧重执行落地——两者协同工作时，效率能够实现倍增。

上一期我们深入拆解了 Claude Code 的 CLAUDE.md，本期自然轮到 Codex 的 AGENTS.md。坦白说，初次编写 AGENTS.md 时，总以为它不过是个 README。但随着使用频次和深度的增加，理解层次就完全不同了。虽然同为 Markdown 文件，但写得好与写得差，Codex 最终展现出的工程能力存在天壤之别。这一篇投入了大量精力进行调研与分析，力求让大家读完后能直接上手操作，也能在面试中清晰地阐述其原理。

01、AGENTS.md 的本质是什么

先厘清最基础的概念。AGENTS.md 是面向 Codex 编程的指令文件，采用纯 Markdown 格式，没有强制字段，只需将其放置在项目根目录即可。

它与 CLAUDE.md 的核心区别在于：CLAUDE.md 是 Claude Code 的私有指令文件，仅 Claude Code 可识别。而 AGENTS.md 是一个开放标准，由 Linux 基金会旗下的 Agentic AI Foundation 管理，目前已被 60,000+ 开源项目采纳，并支持 25+ 种工具——包括 OpenAI Codex、Google Jules、GitHub Copilot、Cursor、Aider、Zed、JetBrains Junie 等。一份文件，即可实现多 Agent 通用。

当然，Claude Code 也同样可以兼容 AGENTS.md。常见的实施方式是：在 CLAUDE.md 中添加一行 @AGENTS.md，将 AGENTS.md 的内容导入，两边功能互不冲突。

那么，AGENTS.md 与 README.md 又有何不同？

• README.md 是面向人类的，告知开发者“这个项目是做什么的、如何启动、如何贡献代码”。
• AGENTS.md 是面向 Agent 的，告知 AI“构建命令是什么、代码风格有哪些约束、哪些目录不可修改、改动代码后需要同步哪些文件”。

02、Codex 的加载机制详解

理解了加载机制，才能确定 AGENTS.md 应放置在何处以及如何组织。Codex 每次启动时会构建一条指令链（instruction chain），该过程仅执行一次。

加载顺序分为两个层级：

第一层：全局配置。 Codex 会首先在 ~/.codex/ 目录下查找。如果存在 AGENTS.override.md，则读取它；不存在则读取 AGENTS.md。需注意，两者仅取其一，不会叠加。

~/.codex/
├── AGENTS.md              # 全局默认指令
├── AGENTS.override.md     # 全局覆盖指令（存在时替换 AGENTS.md）
└── config.toml            # Codex 配置文件

第二层：项目配置。 从项目根目录（通常是 Git 根目录）开始，逐层遍历至当前工作目录。每进入一个目录，按此顺序查找：AGENTS.override.md → AGENTS.md → fallback 文件名。查找到的文件会按路径顺序拼接在一起。

举例说明，假设项目结构如下：

my-project/
├── AGENTS.md                         # 项目根目录的规则
├── services/
│   └── payments/
│       └── AGENTS.override.md        # payments 子目录的覆盖规则
└── frontend/
    └── AGENTS.md                     # 前端子目录的规则

若你在 services/payments/ 目录下启动 Codex，其加载路径为：

1. ~/.codex/AGENTS.md（全局默认）
2. my-project/AGENTS.md（项目根目录）
3. my-project/services/payments/AGENTS.override.md（当前目录覆盖）

三份文件的内容依次拼接，后续文件的优先级高于前者。

override 的实用技巧

AGENTS.override.md 是一个精巧的设计。它的作用是“我不想修改原文件，但需要临时覆盖某些规则”。例如，公司有一份统一的 ~/.codex/AGENTS.md，但你需要临时换一套规则进行实验，只需创建一个 AGENTS.override.md，实验完成后删除即可，原文件完全不受影响。

与 Claude Code 的对比

Claude Code 的加载体系分为四层：系统级 → 用户级（~/.claude/CLAUDE.md）→ 项目级 → 本地覆盖（CLAUDE.local.md）。而 Codex 的设计有所不同。它在启动时便将当前路径上的所有 AGENTS.md 一次性拼接完成，后续运行时不再动态加载。这意味着 Codex 的指令是“启动时确定，运行中保持恒定”。

还有一个细节差异：Codex 包含一个 project_doc_max_bytes 配置项，默认值为 32 KiB。

所有 AGENTS.md 文件拼接后的总大小不能超过此值，超出部分会被截断。Claude Code 没有这种硬性限制，但存在指令预算的软限制（上一篇提到过，500 条指令密度下准确率降至 68%）。在 ~/.codex/config.toml 中可以调大该值：

project_doc_max_bytes = 65536
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

project_doc_fallback_filenames 是另一个实用配置。如果你的项目因历史原因使用 TEAM_GUIDE.md 这样的文件名，无需重命名，只需将其加入 fallback 列表，Codex 便会将其当作 AGENTS.md 处理。

03、OpenAI 官方的 AGENTS.md 最佳实践

OpenAI 自家的 Codex 仓库（github.com/openai/codex）就包含一份 AGENTS.md。

官方根目录的 AGENTS.md 核心内容值得拆解分析：

Rust/codex-rs 的编码规范

- Prefix crate names with `codex-` (e.g., `codex-core`)
- Inline variables in format strings when possible
- Never modify code related to sandbox environment variables
- Apply Clippy linting rules
- A void ambiguous boolean/Option parameters; prefer enums or named methods
- Use exhaustive match statements and a void wildcards
- Run `just fmt` automatically after making changes

这段规则中有几个值得借鉴的地方。第一，codex- 前缀。若不写明，Agent 在新建 crate 时很可能直接命名为 core 或 utils，导致与项目风格不统一。第二，“Never modify code related to sandbox environment variables”。将红线明确划定，Agent 在执行代码变更时便会绕开这些文件。第三，“Run just fmt automatically after making changes”。修改代码后自动格式化，若不写入这条指令，Agent 提交的代码可能格式混乱。

codex-core 的架构约束

Resist adding to the already-bloated codex-core crate.
Consider whether existing crates provide appropriate homes
or whether creating new workspace crates would better serve the architecture.

抵制向已显臃肿的 codex-core 添加新内容。没有长篇大论解释“单一职责”原则，没有绘制分层架构图，就是直截了当地告知 Agent：这个 crate 已经过于庞大，新功能不要往里塞，考虑放入其他 crate 或新建一个。

04、如何编写高质量的 AGENTS.md

OpenAI 官方在最佳实践文档中有一句精辟的原话：一份短小精准的 AGENTS.md，远胜于一份充斥着模糊规则的长文件。这与上一篇讲 CLAUDE.md 时提到的“指令预算”概念同理——写得越多，Agent 的遵循率反而越低。

应该写入哪些内容

①、构建与测试命令。 这是最基本且 Agent 最频繁使用的信息。Agent 每次修改代码后都需要知道如何构建、如何运行测试。写清楚了，Agent 就能自动完成“改代码 → 构建 → 测试 → 格式化”的完整闭环。如果你的项目存在多种测试方式（快速回归、全量测试、单测），全部列出，Agent 会根据具体场景选择最合适的方式。对于热部署项目，这一条尤为关键。

②、项目特有的编码规范。 只写与行业默认规则不同的部分。如果团队约定请求对象使用 *Params 后缀、响应使用 *Response，这类信息若不写明，Agent 可能时而用 *Request，时而用 *Req，导致命名风格混乱。

③、红线规则。 例如“禁止提交 .env 文件”“不要往 codex-core 添加新功能”这类一旦违反便会产生严重后果的硬约束。红线规则最好使用明确的否定句式，如“禁止”“不要”“Never”，让 Agent 在处理相关文件时能第一时间触发警觉。

④、代码定位策略。 比如“search_code 属于 RAG 辅助，优先使用 glob → grep → read 的顺序”。告知 Agent 查找代码的最高效方式。不同项目的代码搜索最优路径各不相同，Agent 的默认搜索策略未必适合你的项目。明确指定优先级，能显著减少无效操作。

05、AGENTS.md 与 CLAUDE.md 的协同配合

很多开发者同时使用 Claude Code 和 Codex。那么，AGENTS.md 和 CLAUDE.md 如何共存？一种可行的方案如下：

AGENTS.md 作为通用指令文件。 将构建命令、代码规范、架构约定、红线规则等“无论使用哪种 Agent 都需要遵守的内容”写入 AGENTS.md。

CLAUDE.md 作为 Claude Code 的增强文件。 在 CLAUDE.md 中使用 @AGENTS.md 导入通用规则，然后额外添加 Claude Code 特有的配置，如 Skills 引用、与 memory 相关的规则、hooks 配置说明等。

这样做的好处是：通用规则只需维护一份，修改 AGENTS.md 即可同时作用于两边。Codex 那边无需任何额外配置，因为它天然就会读取 AGENTS.md。

还有一个小技巧。Codex 的 config.toml 中有一个 project_doc_fallback_filenames 配置，可以将 CLAUDE.md 加入其中：

project_doc_fallback_filenames = ["CLAUDE.md", "TEAM_GUIDE.md"]

这样一来，即使项目中没有 AGENTS.md 但存在 CLAUDE.md，Codex 也会读取它。

06、Codex 的 Agent Loop 架构解析

AGENTS.md 仅仅是 Codex 的指令入口。真正决定 Codex 工程能力的，是其背后的 Agent Loop。OpenAI 今年发布了一篇技术博客《Unrolling the Codex Agent Loop》，公开了 Codex 的核心引擎——harness 的内部架构。这篇文章技术密度极高，核心要点值得深度拆解。

一个 Turn 的完整生命周期

Codex 的 Agent Loop 遵循经典 Agent 模式：用户输入 → 模型推理 → 工具执行 → 模型推理 → ... → 最终响应。从用户发送一条消息到 Codex 给出回复，这个过程被称为一个 Turn。一个 Turn 内部可能包含数十次“模型推理 → 工具调用”的循环。

模型每次推理的输出只有两种形式：要么是给用户的最终回复，要么是一个工具调用请求。只要输出的是工具调用，循环就持续进行；输出了最终回复，循环即告结束。

统一的 Harness 与 App Server

还有一个架构层面的关键信息。Codex 的 CLI、VS Code 扩展、Web 应用、macOS 桌面应用，底层运行的是同一套 harness。连接它们的是 Codex App Server——一个双向的 JSON-RPC API。

为什么要设计统一的 harness？因为 Agent Loop 的逻辑极为复杂：Prompt 构建、工具调度、沙箱管理、Context 压缩、缓存优化，这些如果每个客户端都自行实现一遍，维护成本极高，且容易出现行为不一致的问题。统一的 harness 保证了无论你在终端、IDE 还是浏览器中使用 Codex，Agent 的行为都是一致的。这个架构还有一个副产品：由于整个 Codex 都走 Open Responses API，理论上可以接入任何兼容该 API 的模型，包括本地部署的开源模型。

Prompt 的分层构建

AGENTS.md 在 Codex 的 Prompt 中处于什么位置？Codex 的 Prompt 构建是分层的，按优先级从高到低排列。

更准确地说，AGENTS.md 会被 Codex 发现、拼接后，作为项目级的 user instructions 放入初始上下文之中。它不属于系统指令，也不是工具定义的一部分。系统/开发者级别的安全约束、沙箱策略、权限策略仍然具有更高优先级；AGENTS.md 主要承担的是“项目约定”和“工作偏好”的持久上下文角色。

Prompt Cache 与线性复杂度

这是 Codex 性能优化的核心机制。Agent Loop 每一轮都需要将指令、工具定义、对话历史等上下文一起交付给模型。如果不做优化，随着对话的不断延长，每轮推理的 token 消耗将是 O(n²) 级别的——第 1 轮发送 1000 token，第 2 轮发送 2000，第 10 轮发送 10000...累积消耗呈二次方增长。

Codex 通过 Prompt Cache 将这个问题压缩到了 O(n)。其原理是：Prompt 中稳定的前缀内容可以被缓存，只要前缀精确匹配，就可以复用之前的计算结果，仅需对新增部分进行推理。

但这有一个前提：前缀必须精确匹配。工具列表变化、模型变化、沙箱配置变化、approval mode 变化、工作目录变化，都可能导致缓存失效。AGENTS.md 作为启动时加载的稳定项目上下文，也有助于提高缓存命中率。但不要将其理解为“为了缓存才这样设计”。更准确的说法是：AGENTS.md 提供了稳定的项目规则，而 Prompt Cache 则利用这种稳定性来进行性能优化。

Context Window 压缩

当 token 计数超过阈值时，Codex 会调用一个专门的 /responses/compact 端点。该端点会返回一个压缩后的消息列表，用以替代原来的完整对话历史。压缩后的内容包含一个加密的 compaction 项，保留了模型对原始对话的“潜在理解”。

这并非简单的截断或摘要，而是利用模型自身来进行信息提炼和压缩。被压缩的对话内容虽然消失了，但模型对项目上下文的理解依然存在，不会因压缩而“失忆”。对 AGENTS.md 来说有一个关键影响：AGENTS.md 的内容不会被压缩。它属于 Codex 会反复带入的初始项目上下文，无论对话多长、经历多少次压缩，AGENTS.md 中的核心规则通常都会继续存在。这就是“持久化指令”这个名称的真正内涵。

Codex 的工具体系

Agent Loop 中所调用的“工具”分为三类。第一类是 Codex 内置工具：文件读写、Shell 执行、代码搜索。这些工具运行在沙箱内部，受沙箱策略约束。第二类是 API 提供的工具，由 Responses API 暴露。第三类是用户通过 MCP 接入的外部工具。这类工具不受 Codex 沙箱保护，需要自行实现安全边界。

这三类工具在 Prompt 的 Tool Definitions 层被一并注册。模型在推理时并不区分工具来源，它仅依据工具的名称、描述和参数定义来决定调用哪一个。AGENTS.md 可以在此处发挥作用——告诉模型优先使用哪些工具、避免使用哪些工具，相当于为工具调度增加了一层人为偏好。

08、面试回答思路

讲完底层原理，回到面试场景。如果面试官问：“你用 Codex 时，AGENTS.md 是怎么写的？”

第一句阐述标准。 AGENTS.md 是 Linux 基金会管理的开放标准。与 CLAUDE.md 的区别在于：CLAUDE.md 是 Claude Code 的私有格式，而 AGENTS.md 是通用格式。

第二句说明加载。 Codex 启动时构建指令链，从全局到项目根目录再到当前目录，逐层拼接，后续的优先级更高。override 文件会替代同级的 AGENTS.md。存在 32 KiB 的硬截断限制。

第三句描述内容。 只写入 Agent 无法自行推断的信息：构建命令、编码规范、红线约束、联动规则。

如果面试官深入追问——“AGENTS.md 在 Codex 的 Prompt 中处于什么位置？”AGENTS.md 会被 Codex 聚合到初始上下文中的项目级 user instructions。这个位置意味着两件事：第一，它的优先级低于 system/developer 级别的安全和权限约束，但会作为项目约定持续影响 Agent 的行为；第二，它通常比较稳定，有利于 Prompt Cache 复用前缀计算，从而降低长对话场景下 Agent Loop 的资源消耗。

来源：互联网