04 · 为什么 AGENTS.md 能改变 Codex 行为

📖 本篇术语速查表

英文 / 缩写	中文	一句话解释
AGENTS.md	—	项目与 Agent 的协作接口文件，定义约定、命令和边界。
接口	interface	AGENTS.md 的本质：告诉 Agent 这个项目怎么协作的约定层。
发现顺序	discovery order	Codex 查找 AGENTS.md 的路径优先级。

不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你为项目起草一份 AGENTS.md（项目与 Codex 的协作接口）。

你是 AGENTS.md 起草顾问，帮我为项目写一份让 Codex 更稳定的 AGENTS.md。

【角色】
你理解 AGENTS.md 本质是项目和 Agent 的协作接口，知道它的发现顺序和三层内容（项目约定 / 命令 / 边界），能帮新手从零写出可维护的版本。

【输入】
- 项目类型和技术栈：___
- 关键命令（构建 / 测试 / 启动 / 检查）：___
- 必须遵守的约定（代码风格 / 目录规则 / 禁改区）：___
- 哪些操作必须人工确认：___

【工作流程】
1. 按三层内容组织：项目背景与约定、常用命令、行为边界
2. 把关键命令写成 Codex 可直接执行的形式
3. 标出禁改区和须人工确认的高风险操作
4. 给一个精简、可维护的初版，不堆无用内容

【输出规范】
▌一、AGENTS.md 初稿（含项目约定 / 命令 / 边界三层）
▌二、放在哪个路径（按发现顺序）
▌三、哪些该写、哪些不该写进去
▌四、后续怎么维护（什么时候更新）

【硬约束】
- 初稿要精简可维护，不堆砌用不到的内容
- 命令必须真实可执行，不编造项目里没有的命令
- 禁改区和高风险操作必须明确写出
- 不替我假设技术栈，信息不全先问我

AGENTS.md 能改变 Codex 行为，是因为它把“每次都要重复交代的话”变成了任务开始前就会进入上下文的项目规则。

下个月仍然有效的规则写进 AGENTS.md；只对这次任务有效的细节写进 prompt。

AGENTS.md

官方说明如何发现、合并和使用 AGENTS.md。

Rules

项目规则页讲全局、项目、嵌套和排障。

Context engineering

AGENTS.md 是长期上下文，不是一次性任务说明。

它本质上是接口

flowchart LR
    Repo["项目事实"] --> Agents["AGENTS.md"]
    Team["团队约束"] --> Agents
    Agents --> Codex["Codex 行为"]
    Codex --> Work["读文件 / 改代码 / 跑验证"]

README 主要解释项目给人看。AGENTS.md 主要约束 Agent 怎么干活。两者互补，不互相替代。

没有项目规则时，Codex 只能猜包管理器、目录职责、测试命令和禁止事项。有了 AGENTS.md，它能先知道项目真实约定，再开始做事。

发现顺序

Codex 启动时会构建 instruction chain。官方规则可以理解成三层：

Global scope：Codex home 下的 AGENTS.override.md 或 AGENTS.md。
Project scope：从项目根一路到当前目录，逐层读取 AGENTS.override.md、AGENTS.md 或配置里的 fallback 文件名。
Merge order：越靠近当前工作目录的规则越晚进入上下文，因此更能覆盖上层规则。

这意味着：

全局文件适合个人稳定习惯。
根目录文件适合全仓共同规则。
子目录文件适合模块规则。
override 文件适合临时强覆盖，但不能滥用。

什么该写进去

适合写：

项目用途。
技术栈。
包管理器。
目录职责。
启动、测试、构建、lint 命令。
禁止事项。
受保护路径。
验收要求。

不适合写：

本次任务细节。
临时想法。
长篇背景。
密钥、账号、私有 token。
没稳定下来的个人偏好。
与现有规则冲突的模板。

如果你第二次对 Codex 纠正同一个问题，这就是写进规则的信号。

三层内容

第一层是事实：项目用什么技术栈、哪个包管理器、哪些目录做什么、哪些命令能验证。

第二层是约束：哪些文件不要碰，哪些操作不能默认做，哪些高风险逻辑必须先确认。

第三层是验收：改完要跑什么检查，无法验证时要怎么说明，最终交付应该包含哪些证据。

只有事实，没有约束，就是说明书。只有约束，没有事实，就是口号。没有验收，就无法判断完成。

新手第一次怎么写

不要追求完整。先写六块：

项目概况：一句话说明项目做什么。
目录职责：列关键目录，不要逐文件注释。
开发命令：只列启动、测试、构建、lint。
编码规则：写具体可执行的约定。
禁止事项：写不能碰的路径、命令和依赖。
验收要求：写不同改动类型怎么检查。

写法要具体。“代码要优雅”没有用，因为 Codex 无法验证。“修改 API handler 后运行某个测试命令”有用，因为它能执行。

怎么维护

AGENTS.md 不是一次写完的文档。它应该随着项目和团队实践迭代。

每次 Codex 犯错后，先判断是任务没写清，还是项目规则缺失。只有会反复出现的问题，才沉淀到 AGENTS.md。

团队项目里，AGENTS.md 应该像代码一样走 review。它改变的是所有 Agent 进入项目后的行为，不能随手改。

如果文件越来越长，先删除低价值说明，再把局部规则拆到更靠近对应目录的位置。

新手常见坑

把 README 复制进去：人类介绍太长，Agent 规则不够清楚。
写一堆抽象要求：无法验证，无法稳定执行。
把任务模板塞进去：每次任务不同，应该写 prompt。
把密钥、账号、私有 URL 写进去。
规则互相冲突：根目录说用 pnpm，子目录又让用 npm。
没有验收要求：Codex 只会说“完成了”。

怎么验收

让 Codex 只读总结当前加载到的规则。它应该能复述项目用途、命令、禁止事项和验收要求。

给一个小任务，看它是否先读相关文件、是否只改允许范围、是否按规则跑验证。

检查最终回复是否包含改动文件、验证结果、未验证项和剩余风险。

如果这些没有发生，优先改 AGENTS.md 的具体性，而不是继续堆更多提示词。