Codex 如何加载 AGENTS.md

Codex 如何加载 AGENTS.md

AGENTS.md 不是一个孤立的提示词文件，而是一套分层指令机制。理解它的关键只有两个词：由远及近。

标准加载顺序

Codex 开始任务时，会先构建一条指令链。公开文档定义的标准顺序是：

  1. 用户级：读取 ~/.codex/AGENTS.override.md；不存在时读取 ~/.codex/AGENTS.md。
  2. 项目级：从项目根目录开始，沿着目录树向当前工作目录逐级查找。
  3. 子目录级：如果项目根目录到当前工作目录之间还有更深的目录，则继续加载这些目录中的 AGENTS.md。

同一目录只取一个文件，优先级依次是 AGENTS.override.md、AGENTS.md，再到配置的备用文件名。最终内容按照“用户级 → 项目根目录 → 当前工作目录”的顺序合并。

这里有一个容易误解的地方：如果 AI 在任务执行过程中开始处理某个子目录里的文件，它应该先主动查找并读取该目录及其上级目录中适用的 AGENTS.md。越靠近目标文件的规则越具体，发生冲突时优先级也越高。用户不需要每次显式提醒 AI 读取。

但这不代表 Codex 会在每条 shell 命令执行 cd 时自动加载新规则。自动加载和 AI 主动读取是两回事：前者由 Codex 根据工作目录构建上下文，后者是 AI 在处理更深层目录中的文件前应履行的检查责任。

.well-known 更像企业管理层

部分企业托管环境还可能在用户级配置之前注入通过 .well-known 端点分发的管理指令，用于统一安全策略、设备规范和组织级约束。

它不属于普通个人环境中公开文档定义的标准 AGENTS.md 发现链。国内大部分个人开发和小团队场景基本用不到；只有公司统一运维、集中配置开发设备或管理 Codex 使用策略时，才有实际价值。

因此，完整理解可以分成两层：企业环境可能先注入远端管理规则；随后 Codex 再按用户级、项目级和当前工作目录逐层加载本地规则。

越近，冲突时越重要

这套顺序是固定的。Codex 会把项目文件从根目录到当前工作目录依次拼接，越靠近当前工作目录的规则出现得越晚。发生冲突时，后面的具体规则应覆盖前面的通用规则。

例如，用户级规则要求所有项目使用 npm，但某个项目的 AGENTS.md 指定使用 pnpm，那么在这个项目中应以 pnpm 为准；如果某个子目录又要求使用 bun，则该子目录范围内再以 bun 为准。

可以把它理解为：距离任务越近，规则越具体，优先级越高。

但“优先级更高”不等于程序语言中的绝对覆盖。Codex 最终仍由概率模型执行指令。工程上可以认为 99.9% 会遵循更近、更具体的规则，但不应该承诺 100%。真正不能出错的约束，仍然需要测试、CI、权限和 Hook 等确定性机制兜底。

上下文同样由远及近

一轮完整任务的上下文也呈现类似结构：最上游是系统和管理指令，然后是用户级与项目级 AGENTS.md，接着是用户对话、工具结果，以及任务过程中显式读取的子目录说明和业务文件。

Codex 会对初始指令做程序化封装。例如，运行环境可能用 <INSTRUCTIONS>、<environment_context> 等结构化标签区分规则、环境和用户输入。这些标签能帮助模型识别信息类型，尽量维持 AGENTS.md 的指令地位。

但标签不是永久锁定的权重。上下文越长，新增对话、代码、日志和工具输出越多，模型需要同时处理的信息就越多。早期规则仍然存在，却更容易被后续细节稀释。用户感受到的表象通常是：对话越长，AI 越容易漏掉前面的要求，看起来像“变笨了”。

自动压缩会进一步放大风险

当对话接近上下文窗口上限时，Codex 可能自动压缩较早内容，用摘要替代完整历史。压缩的目标是保留任务状态、关键事实和下一步，而不是逐字保存所有信息。

问题在于，“什么最重要”本身也是模型判断。你认为关键的一句话，可能被摘要器视为次要细节；一旦压缩遗漏，后续模型接收到的就不再是原文，而是缺少该约束的摘要。此时 AI 不是暂时忘记，而是当前上下文里已经没有那条完整信息。

所以，重要规则不要只在早期对话里说一次。长期规则写入合适层级的 AGENTS.md；任务级硬约束在关键阶段重新确认；必须保证的结果交给测试和自动化验证。AGENTS.md 能提高遵循概率，但不能替代确定性约束。

结论

Codex 的指令组织原则是由远及近：上游规则负责通用边界，用户级规则负责个人习惯，项目级规则负责项目约束，子目录规则负责局部细节。越接近当前任务，规则越具体，冲突时越应优先。

但上下文也会随任务推进不断变长，并在必要时被压缩。结构化标签可以增强规则辨识度，却无法消除信息稀释和摘要遗漏。真正可靠的做法，不是把所有要求塞进一个超长文件，而是分层放置规则、控制对话长度，并用确定性工具守住底线。

参考资料：OpenAI Codex：Custom instructions with AGENTS.md

Comments

Post a Comment

Popular posts from this blog

How to turn off Sass warning prompts in Nuxt.js projects

Background of the Issue When developing projects with Nuxt.js, it’s common to encounter a large number of Sass-related warning messages in the console. These warnings mainly include: Warnings about the order of mixin declarations. Warnings about the use of Legacy JS API. Although these warnings do not affect the operation of the program, they can degrade the development experience by cluttering the console. Today, we will explore how to elegantly address this issue. Solutions 1. Disable Warnings via Configuration In the nuxt.config.js file, we can modify the Sass configuration to suppress these warning messages: export default { build: { loaders: { scss: { sassOptions: { quietDeps: true , // Suppress warnings from dependencies logger: { warn: function ( message ) { return null ; // Silence warning messages }, debug: function ( message ) { return null ; // Silence ...
Read more

Configuring SSH Access to a Docker Container via an Alternative Port

Configuring SSH Access to a Docker Container via an Alternative Port If you want to configure SSH access to a Docker container using an alternative port, such as port 6666 , follow the steps below carefully. This guide assumes that you have administrative access to your Docker host and are familiar with basic Linux commands. Step 1: Run the Container with SSH Service Start by running a new container from your image with port 6666 on the host mapped to port 22 inside the container: sudo docker run -it -p 6666 : 22 --name ssh-container testimage Make sure to replace testimage with the actual name of your Docker image. The --name option gives the container a specific name for easier management. Step 2: Install OpenSSH Server in the Container Once inside the container, update the package list and install the OpenSSH server: apt-get update && apt-get install -y openssh-server Step 3: Set the Root Password Set a password for the root user, which will be required when l...
Read more

Quickly Set Up a Cloud Database Using MongoDB Atlas

Quickly Set Up a Cloud Database Using MongoDB Atlas MongoDB Atlas is the official fully managed cloud database service from MongoDB, simplifying the deployment, management, and scaling of MongoDB in the cloud. This article will guide you on how to quickly create a MongoDB Atlas cluster and set up basic connection configurations. Creating a MongoDB Atlas Cluster Sign Up & Log In If you do not have a MongoDB Atlas account yet, head over to MongoDB Atlas to sign up. After logging in, click on “Build a Cluster” to start creating a new cluster. Select Cluster Configuration To meet the needs of most development and testing scenarios, you can choose the free tier (M0) shared cluster, which is usually sufficient for small applications or personal projects. When choosing a cloud provider, select based on your preference. Here we chose Azure, but AWS and GCP are also great choices. Specify Geographic Location For geographic location selection, choose according to your u...
Read more