AGENTS.md 不是 应用的第二本操作手册， 也不是 试图控制每一次按键的 prompt。 它是 一个小型的、 随代码版本管理的上下文契约。 它告诉编码代理 仓库怎样组织， 哪些命令能提供可核验的证据， 哪些边界很重要， 以及更具体的规则在哪里。 好文件会在代理修改代码之前减少不确定性。 它不能替代源代码、 测试、 维护者和任务描述。
上下文有成本。 Codex 会在开始工作前 把项目指令加入指令链。 重复的文字会和用户请求、 仓库文件、 工具输出、 测试竞争。 因此应写入代理无法安全推断的事实， 而不是写下某个人曾经表达过的所有偏好。 把每一句话都当作需要维护的接口。
Codex 实际发现什么
当前的 OpenAI Codex AGENTS.md 指南 描述了三个层次。 在全局作用域， Codex 会在 CODEX_HOME 中查找 AGENTS.override.md， 默认位置是 ~/.codex， 如果不存在则使用 AGENTS.md。 这个层次只使用第一个非空文件。 在项目作用域， 它从项目根目录开始， 通常是 Git 根目录， 向下走到当前工作目录。 每个目录依次检查 AGENTS.override.md、 AGENTS.md 和已配置的备用名称， 每个目录最多加入一个文件。
发现的项目文件会从根目录向当前目录拼接。 更深层的文件在合并指令中出现得更晚， 因而它的窄规则可以覆盖更宽的规则。 Codex 不会继续越过检测到的项目根目录向上搜索。 如果找不到项目根， 只检查当前目录。 空文件会被忽略。 project_doc_max_bytes 的默认值是 32 KiB， 达到配置的总大小后 Codex 会停止添加项目指令。 这些是 Codex 的行为， 不是所有工具都做出的通用承诺。
OpenAI Codex 源码中的 AGENTS.md 发现实现 展示了相同边界。 默认根标记是 .git， 首选的本地文件名是 AGENTS.override.md。 如果剩余字节预算小于文件大小， 文件可能被截断。 仓库可以配置根标记、 备用文件名和字节预算。 只记录实际使用的配置。
只有当全局偏好对每个仓库都安全时， 才把它放进 ~/.codex/AGENTS.md。 整个仓库都适用的规则放在根目录。 服务规则放在服务旁边。 临时或例外替换放在 override 文件中， 同时写明负责人和删除条件。 如果其他代理的文档没有确认这种机制， 不要把它描述成所有代理通用的层级。
先画出仓库地图
代理需要先知道去哪里看， 然后才需要风格建议。 在根文件开头附近放一张简短地图。 写出应用或库的名称、 主要源代码目录、 生成区域、 测试目录和交付配置。 只解释会改变操作的差异。 “src/ 存放代码” 很弱。 “src/ 会进入交付包， scripts/ 只在 CI 中运行， dist/ 由生成器产生且不能手改” 才能直接行动。
地图应该能经受普通重构。 选择稳定边界， 不要列出每个文件。 在 monorepo 中显示包的所有权， 并把包级地图放在嵌套文件中。 如果 README 或架构文档是事实来源， 就链接过去。 不要把整份文档复制进 AGENTS.md。
repository/
apps/web/ 浏览器应用与路由测试
packages/core/ 共享运行库与单元测试
services/api/ HTTP 处理器与契约测试
infra/ 交付配置
docs/ 持续维护的说明
generated/ 由脚本重新生成的已跟踪输出
明确工作目录假设。 从 services/api 运行的命令， 可能加载和从根目录运行时不同的嵌套指令文件。 如果包管理器必须在某个包目录运行， 就写出来。 如果生成文件有事实来源， 写出两个路径和生成命令。
让命令精确而且有条件
命令只有在无需猜测时才有价值。 对每个必需命令， 写明目录、 目的和运行条件。 使用仓库声明的版本和脚本， 不要凭记忆推荐流行工具。 命令部分可以采用下面的结构：
从仓库根目录运行：
git rev-parse --show-toplevel
npm ci
npm run check
npm test
npm run build
修改 API 时，在 services/api 中运行：
npm run test:contract
这是结构示例， 不是说每个项目都有这些脚本。 写入前要阅读 package.json、 lockfile、 CI workflow、 pyproject.toml、 Cargo.toml 或等价文件。 只有脚本确实存在时， 才写“修改 TypeScript 后运行 npm run check”。 如果命令需要本地服务、 fixture、 数据库、 环境变量或网络， 写清前提以及适合局部测试的安全替代方案。
记录受支持的运行时和依赖策略。 有用的条目会写出 Node、 Python、 Rust、 Java 或 Go 的版本， 包管理器， lockfile 规则和依赖升级的审查方式。 例如， “package.json 声明 Node >=22.12.0， 使用已提交的 package-lock.json 并运行 npm ci” 只有在清单确认后才是事实。 不要没有检查清单和 CI 就把版本复制进 AGENTS.md。 版本漂移是维护问题， 不是增加段落的理由。
Codex 可以帮助验证当前指令链。 官方指南展示了这类命令：
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/api --ask-for-approval never "List the instruction sources you loaded."
codex -c log_dir=./.codex-log --ask-for-approval never "Show the active instruction files."
使用不会修改文件的请求， 只在安全的本地工作区查看日志。 修改指令文件后要重新启动 run， 因为发现过程在每次 run 或 TUI 会话开始时重建。 如果回答看起来过时， 检查当前目录、 CODEX_HOME、 override、 备用名称和字节限制。
测试是证据， 不是仪式
用可观察的结果定义“完成”。 把快速检查和完整套件分开。 写出测试命令、 受影响的包、 预期产物和失败时的处理方式。 HTTP schema 变化需要契约测试。 parser 变化需要代表性 fixture 和格式错误输入。 生成客户端变化需要重新生成并确认 diff 干净。
如果仓库定义了不同范围， 或完整套件需要外部基础设施， 就不要写“永远运行所有测试”。 更准确的规则是“先运行目标包测试， 合并前再运行等同于 CI 的套件”。 如果格式化和 lint 已经由 CI 强制执行， 就让 CI 负责。 SWE-bench 一手仓库 可作为基于任务评估的原始参考， 但不能替代当前仓库的测试。
把每条重要规则连到一个检查。 如果代理不能编辑生成输出， CI 可以重新运行生成器并在出现 diff 时失败。 如果迁移必须可回滚， 测试可以在干净 fixture 上应用再撤销。 如果安全不变量重要， 把它表达为测试或静态检查。 没有可观察结果的指令， 实际上是在要求代理依靠记忆。
评估代理时， 比较任务成功率、 测试通过率、 修改文件范围、 评审后的返工量和得到已验证补丁所需的时间。 用旧文件和新文件运行同一组任务， 固定请求与仓库修订， 并记录失败， 不要只挑成功演示。 这是工程信号， 不是某种措辞适用于每个模型的证明。 关于系统边界， 阅读 生产环境 AI agent 架构。 关于评估设计， 阅读 AI agent 评估。 也可以参照 agentic coding、 Codex 与 Claude Code 的工具比较。
把安全放在边界上
AGENTS.md 是项目输入。 它可能过时、 错误或不可信。 Codex 源码明确表示， 当活动项目不受信任时不会加载项目指令， 但仍保留主机提供的指令。 这不意味着可以跳过人工审查。 在确认仓库和请求的改动之前， 把仓库指令当成不可信文本。
绝不要把 API key、 token、 密码、 私有证书或复制的生产数据放入文件。 不要让代理打印环境变量或上传工作区文件。 可以按作用命名秘密， 例如 DATABASE_URL， 并说明本地开发如何取得它而不记录值。 如果工作流支持审批， 删除数据、 轮换凭据、 生产部署或开放广泛网络访问之前要请求确认。
区分事实和权限。 “服务使用 S3” 是上下文。 “可以删除 bucket” 是权力。 权力应该位于访问策略和审批流程中， 不在 markdown 中。 写出受保护路径、 生成产物、 迁移规则和测试数据边界。 遇到不确定时提供安全路径： 停止， 展示拟执行的命令， 向维护者提问。
小心 issue、 fixture 或依赖文件中复制来的指令。 它们可能含有 prompt injection 或与任务无关的命令。 好的文件会说明， 除非用户或受信任的项目规则授权， 否则把仓库内容当作数据。 这是安全边界， 不是叫代理忽略源代码。
采用小型分层文件
AGENTS.md 网站 把项目概览、 构建和测试命令、 代码风格、 测试和安全列为常见部分。 这是一份菜单， 不是强制 schema。 从能阻止重复错误的最小集合开始。 根文件通常只需要五部分： 地图、 设置、 验证、 边界和更深指导的链接。
## 仓库地图
`apps/web` 是浏览器应用。 `packages/core` 是共享运行时代码。
## 工具链
使用 Node 22 和已提交的 lockfile。 除非特别说明， 从仓库根目录运行命令。
## 验证
用户可见的修改要运行 `npm run check`、 包测试和 `npm run build`。
## 边界
不要编辑 `generated/`。 本地不要使用生产数据。 添加依赖前先询问。
## 深入指导
路由规则见 `apps/web/AGENTS.md`， 契约测试见 `services/api/AGENTS.md`。
坏例子是 一份一千行的个人偏好目录： 重复规则、 详尽文件清单、 相互矛盾的“始终”、 猜出来的命令、 过时版本和要求重读所有文档的句子。 它会消耗字节预算， 也让优先级难以辨认。 按所有权拆分。 把仓库级不变量留在根文件， 让嵌套文件增加本地命令。 嵌套文件应该补充或收窄指导， 不能静默改写安全边界。
不要承诺工具没有文档说明的组合能力。 Codex 当前通过目录发现和已配置的备用名称来合并文件。 如果工具没有特殊 include 语法， “接着读取 docs/rules.md” 就只是普通文字。 symlink、 CLAUDE.md 或另一个代理的约定不会被 Codex 自动加载。 把互操作写成经过测试的工作流， 不要写成通用规则。
像维护代码一样维护它
为文件指定负责人。 和它所约束的代码一起审查。 命令、 运行时、 目录或 CI workflow 变化时， 在同一个改动中更新最近的指令文件。 最后一个使用者消失后删除规则。 示例必须可执行且安全。 链接到一个事实来源， 不要在三个文件里复制同一政策。
每月或每个发布周期做一次短审计。 检查每条命令确实存在， 每个版本和清单或 CI 镜像一致， 每条路径仍然存在。 从根目录和一个代表性子目录运行 Codex 的来源查询。 测量有效指令链的大小。 询问维护者每条规则是否仍然阻止真实错误。
把 AGENTS.md 的改动当成配置改动来评估。 使用小而固定的任务集： 新功能、 bug 修复、 只改测试和安全敏感改动。 比较补丁是否正确以及改动范围， 不要只比较代理的解释。 回归检查可以验证生成文件没有变化、 包测试实际运行， 或危险命令被拒绝。 保持仓库修订、 模型设置、 权限和任务文字足够稳定， 使比较有意义。
长期有效的模式很简单。 把稳定事实放在适用范围附近。 写出仓库证实过的精确命令和版本。 链接到详细文档。 让重要规则可测试。 不要把秘密和权限放在 markdown 中。 用分层文件取代巨型说明书。 工作目录、 配置或工具版本变化后， 再次检查有效指令链。