Codex CLI 与 AGENTS.md：团队协作的规则与实用技巧

团队多人多仓库使用 Codex CLI 时，靠临时提示词很难保证一致性。本文讲清 AGENTS.md 的定位、Codex 的指令加载顺序，并给出一份可直接套用的示例文件和团队维护要点。

AGENTS.md 解决什么问题

• 单人单项目时一句好提示词就够；团队跨仓库使用后，常见问题是跳过测试、换用别的包管理器、改动不该动的地方、无视项目约定。
• AGENTS.md 是一份纯 Markdown 的持久指令文件，Codex 开工前会先读它。它和 README 分工：README 给人看，AGENTS.md 给 agent 看。
• 内容重点是构建与测试命令、代码约定、以及哪些东西绝对不能改。
• 格式不绑定 Codex，多个工具都支持，现由 Linux 基金会下的 Agentic AI Foundation 托管，一份写好的文件可服务多个 agent。
• 没有必填字段，标题随意，关键是短而具体。

Codex 的指令加载顺序

• 全局层：在 Codex 主目录（默认 ~/.codex）读取 AGENTS.override.md，没有则读 AGENTS.md。
• 项目层：从项目根目录（通常是 Git 根）逐级向下走到当前目录，每个目录最多取一个文件，优先 AGENTS.override.md，其次 AGENTS.md。
• 合并：从根往下拼接，越靠近当前目录的指令排在越后面，优先级越高。
• 空文件会被跳过；达到体积上限后停止加载，默认 32 KiB，可用 project_doc_max_bytes 调整。
• 聊天中明确给出的指令始终覆盖文件内容。

三层指令各放什么

• 个人/全局（~/.codex/AGENTS.md）：通用偏好，如回复语言、常用包管理器、加依赖前先询问。
• 项目根目录 AGENTS.md：构建、测试、lint、项目结构、约定、禁区。
• 子目录 AGENTS.md 或 AGENTS.override.md：monorepo 中某个模块、服务或包的专属规则。
• override 文件适合临时替换规则而不删原文件，删掉 override 后原规则自动恢复。

一份可套用的示例结构

• 项目段：说明技术栈和内容位置，例如 Next.js 应用、博客内容在 content/blog 下分语言存放、文案在 messages 下且新增 key 要补齐所有语言。
• 命令段：安装用 npm ci，检查用 npm run lint，构建用 npm run build 且任务完成前必须通过。
• 规则段：未经明确要求不改路由、重定向和 .env；不确认不加依赖；diff 保持最小，不做任务外重构。
• 输出段：结束时汇总改动文件和构建结果。
• 关键点是列出的命令必须真能跑通——文件里写了测试或构建，agent 就会去执行并修到通过为止。

团队维护与常见坑

• 把 AGENTS.md 放进 Git，像代码一样走 PR 修改，当作活文档维护。
• 写规则而不是写文章，短条目比长段落更有效，也省体积预算。
• 明确点名禁区：生产配置、数据库迁移、支付逻辑、密钥。
• monorepo 用嵌套文件，别在根目录堆一个巨型文件。
• 让 agent 复述当前加载的指令来核对是否生效；看起来是旧的，就在目标目录重启 Codex。
• 绝不放密码或 API key，文件在仓库里，有权限的人都能读。

今天就能做

• 在项目根目录建一个 AGENTS.md，先写清安装、检查、构建三条可执行命令和禁区清单。
• 把文件提交进 Git，用 PR 评审的方式迭代规则。
• 让 Codex 复述它加载到的指令，确认没有旧 override 或超长截断的问题。