Agents.md 测评：比 Codex 更听话的代码助手

AGENTS.md：Codex 项目运行的规范手册

实际项目里，开发团队经常遇到一个典型问题：Codex 能生成代码，但对当前项目的具体约定一无所知。比如项目用什么命令启动、测试哪些模块、哪些目录禁止修改、哪些操作需要提前确认——如果每次都要手动写入提示词，费时且容易出错。

因此有了 AGENTS.md。它的作用就是把工程规范固化到文件中，让 Codex 在每次进入项目时自动加载这些规则。核心解决的是：让 Agent 真正理解你的项目上下文。

坦白说，不少开发者虽然长期使用 Codex，却从未深究 AGENTS.md 的内部结构。今天就将它的完整机制拆解一遍。

简单来说，AGENTS.md 是面向 Agent 的 README。

二者的差异在于：README.md 面向人类读者——解释仓库的用途和背景；而 AGENTS.md 面向 Codex——在编写代码之前，让它通晓仓库的工程约定。例如：

• 本项目的启动命令是什么
• 修改代码后需要执行哪些测试
• 哪些目录属于不可触碰的禁区
• 使用的包管理器是哪个
• 新增依赖前是否需要人工确认
• 数据库、API、前端各有哪些编码规范

文件名请规范为 AGENTS.md，大小写必须完全一致。若误写为 Agent.md、Agents.md 或 agents.md，某些环境可能无法加载该文件。

全局 AGENTS.md

全局配置文件默认存放在 ~/.codex/AGENTS.md。如果该目录不存在，请手动创建：mkdir -p ~/.codex。

全局规则适用于那些长期稳定、与具体项目无关的个人偏好。示例如下：

# ~/.codex/AGENTS.md

## 工作协议
- 默认以中文回复。
- 修改代码前必须通读相关文件。
- 优先沿用项目现有代码风格。
- 不得擅自覆盖用户已有的改动。
- 新增生产依赖前需先获得确认。
- 若无法运行验证命令，需说明原因。

这些规则不依赖任何特定仓库，适用于所有项目。配置完成后，可用一条命令验证是否生效：

codex --ask-for-approval never "梳理当前所有生效的指令"

如果输出中包含了刚才写入的规则，说明全局 AGENTS.md 已被成功加载。输出中可能还混有一些英文规则——这属于正常现象，因为该命令汇总的是“当前所有生效的指令”，除你编写的 AGENTS.md 外，还包括 Codex 自带的系统规则、当前工作目录、审批策略、沙盒权限等信息。

全局与项目级的区分策略

AGENTS.md 支持多层级部署，常见结构如下：

~/.codex/AGENTS.md        # 全局规则
repo/AGENTS.md            # 项目规则
repo/apps/web/AGENTS.md   # 子模块规则

这些层级并非互斥关系——拥有全局文件并不代表项目文件失效。实际上，它们会共同加载。理解方式如下：

• 全局规则：要求 Codex 始终遵循的通用工作方式
• 项目规则：该仓库特有的运行机制与约定
• 子目录规则：该模块独有的特殊约束

判断依据很简单：换一个项目仍然适用的约定放入全局；仅在本仓库成立的规则放入项目；只对某个子目录有意义的约束放入对应子目录。

举个例子。“新增生产依赖前先确认”这条规则适合放在全局，因为它不依赖项目类型。而“修改 Prisma schema 后运行 pnpm db:generate”这条规则，则适合放入项目级文件。不是每个项目都使用 Prisma，更不是每个项目都定义了 db:generate 脚本。

补充说明：Prisma 是 Node.js/TypeScript 生态中流行的数据库工具。它负责将数据库表结构、类型定义与查询代码无缝连接，让开发者以类型安全的方式操作数据库。当修改了 prisma/schema.prisma（即数据库表结构的定义文件）后，项目通常需要重新生成数据库客户端代码。因此该规则的本质是：不能只修改文件就结束，必须执行对应的生成命令。

项目级 AGENTS.md

项目级文件通常放在仓库根目录，内容应聚焦于该项目的具体工程约定，例如：安装命令、启动命令、测试命令、类型检查命令、lint 命令、目录结构、生成文件的边界、数据库变更要求、API 文档同步要求等。对于生产项目，可直接使用文末提供的模板，再根据实际情况增删调整。

验证项目级 AGENTS.md

我按常规创建了一个测试项目，目录结构大致如下：

agents-md-test/
  AGENTS.md
  apps/    web/
  packages/    ui/    db/
  services/    payments/
  docs/    api/
  src/    generated/

在项目根目录执行以下命令，可验证文件是否被正确加载：

codex --ask-for-approval never "列出你加载的所有指令来源，并总结 Project commands、Project structure 以及 Rules 部分的内容"

也可以测试某个子目录：

codex --cd services/payments --ask-for-approval never "列出你加载的所有指令来源"

这里有一个小技巧：验证 AGENTS.md 是否生效，不要只看它是否声明“已加载 AGENTS.md”。更有效的方法是让它提炼文件中的独有规则。例如输出中如果出现了 pnpm dev、src/generated、pnpm db:generate、docs/api 等项目特有的内容，才证明项目级规则已被成功应用。

子目录 AGENTS.md

除了项目根目录，子模块也可以利用 AGENTS.md 实现更细粒度的约束。例如在 monorepo 中，根目录存放通用规则，services/payments/ 放置支付服务的专属规则，services/search/ 放置搜索服务的专属规则。

举例来说，支付服务的 AGENTS.md 可能这样配置：

# services/payments/AGENTS.md

## 支付规则
- 修改计费行为时必须同步更新支付测试用例。
- 禁止记录卡号、令牌或客户机密信息。
- 修改支付逻辑后须运行 `pnpm test payments`。

这种分层方式在 monorepo 中尤其实用——一个仓库可能同时包含前端、后端、支付、搜索等多种模块，各模块的风险点和约束条件差异巨大，统一的规则无法覆盖所有场景。

AGENTS.override.md 是什么

除了 AGENTS.md，还有一个特殊文件叫 AGENTS.override.md。它的优先级高于同一目录下的 AGENTS.md，适用于需要强制覆盖的场景。

例如，当 services/payments/ 目录下同时存在 AGENTS.md 和 AGENTS.override.md 时，Codex 会优先加载 AGENTS.override.md，并完全忽略同目录下的 AGENTS.md。

哪些场景会用到它？比如某个子服务有特殊的安全规范、某个目录禁止修改生成文件、某个模块必须使用特定的测试命令、或者需要临时替代原有的规则。通常情况下，使用 AGENTS.md 已足够。只有在确实需要覆盖同目录文件时，才应引入 AGENTS.override.md。

自定义 fallback 文件名

有些团队可能已有自己的项目说明文件，例如 TEAM_GUIDE.md 或 .agents.md。如果不想将文件名改为 AGENTS.md，可以通过 Codex 配置来设置 fallback 文件名。

编辑 ~/.codex/config.toml，添加以下内容：

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

配置生效后，Codex 在每个目录中会按如下顺序搜索：AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md。不在列表中的文件名将被忽略。例如 README.md 不会仅仅因为存在就自动成为 Codex 的指令文件。

project_doc_max_bytes 用于控制所有项目说明文件合并后的最大字节数。如果规则较多，可以适当调大该值。

使用 CODEX_HOME 切换配置目录

默认情况下，Codex 使用 ~/.codex 作为主目录，全局 AGENTS.md 自然位于 ~/.codex/AGENTS.md。但如果你希望临时使用另一套配置，可以通过设置环境变量 CODEX_HOME 实现：

CODEX_HOME=$(pwd)/.codex codex exec "列出当前生效的指令来源"

该命令的含义是：本次执行不使用默认的 ~/.codex，而是使用当前项目下的 $(pwd)/.codex。适用于为项目自动化任务准备独立配置、区分个人配置和 CI 配置、或临时测试不同的 AGENTS.md。如果发现规则加载异常，可以先执行 echo $CODEX_HOME 检查——如果输出非空，说明 Codex 当前使用的不是默认目录。

可直接使用的生产级 AGENTS.md

最后提供一个更适合生产项目的 AGENTS.md 模板。这份模板偏重工程纪律，适用于多人协作项目、monorepo、以及涉及数据库、API、CI 的项目。可以直接复制到项目根目录，再根据实际情况增删调整。

# AGENTS.md

本仓库中 AI 编码代理的工作协议。

冲突时遵循：用户显式指令 > 本文件 > 现有代码约定 > 默认行为。

当决策存在风险，或可能对架构、数据、安全、对外行为产生实质性影响时，应停止并询问，而非自行猜测。

## 初步了解
每次会话先执行以下步骤。

在编写任何代码之前，基于仓库实际内容建立工作模型：
- 阅读 `README`、`CONTRIBUTING` 以及根目录下的所有 `*.md` 文件，获取配置和规范。
- 根据锁文件检测包管理器：
  - `pnpm-lock.yaml` → 使用 `pnpm`
  - `yarn.lock` → 使用 `yarn`
  - `package-lock.json` → 使用 `npm`
  - `uv.lock` 或 `poetry.lock` → 使用对应的 Python 工具
- 使用检测到的包管理器。禁止引入第二个包管理器。
- 在 `package.json` 脚本、`Makefile`、`Taskfile`、`justfile` 或 CI 配置中查找真实命令。
- 将 CI 配置（`.github/workflows`、`.gitlab-ci.yml` 等）视为通过标准的唯一依据。
- 在修改文件前，先阅读将要更改的文件及其测试。
- 不要假设技术栈。通过仓库实际内容验证。

## 核心原则
- 用最小的改动完成任务。
- 不得进行无关联的代码重构、重命名或格式化。
- 保持 diff 中不包含无关变更。
- 与周围代码风格一致：命名、结构、错误处理、测试风格。
- 一致性优于个人偏好。
- 优先重用现有辅助函数、组件和模式，再考虑新增。
- 不要添加尚不存在的投机性抽象、配置或错误处理。
- 注释应解释非显而易见的决策。不要注释代码已经表达清楚的内容。

## 验证
在任务完成前必须执行：
- 使用项目定义的具体命令。优先执行针对性的检查，再执行较全面的检查。
- 运行你修改的文件、包或功能对应的窄范围测试。
- 然后运行项目定义的更广泛门禁：lint、类型检查或编译、以及全量测试。
- 尽可能在本地模拟 CI 环境。
- 不要凭空捏造无关的验证命令。
- 修复由你的修改引起的失败。
- 对行为变更必须添加或更新测试。
- 如果因为缺少服务、凭据、网络问题或时间不足无法执行命令，需明确说明。
- 切勿暗示测试已通过而实际并未运行。

## 依赖管理
- 未经询问不得添加生产依赖。
- 请求依赖时，需解释现有工具为何无法满足需求。
- 仅开发工具的风险较低，但仍需与仓库现有工具保持一致。
- 禁止手动编辑生成文件、vendor 代码或锁文件。
- 通过项目文档中定义的命令重新生成生成文件和锁文件。

## Git 与 PR
- 仅在被要求时提交。
- 如果被要求提交且当前处于默认分支，应先创建功能分支或询问后再提交。
- 按文件名逐个添加文件。不要使用 `git add .` 或 `git add -A`。
- 提交时使用约定式提交前缀，如 `feat:`、`fix:` 或 `chore:`。
- 每次提交对应一个逻辑变更。
- 禁止运行 `push --force`、`reset --hard`、`branch -D`、`clean -f` 或 `--no-verify`。
- 除非被要求，不要修改、压缩或变基已推送的提交。
- 不要回退或覆盖不是你做的修改。

## 安全
- 禁止提交密钥、令牌、凭证或密码。
- 将 `.env*` 文件视为敏感内容。
- 不要输出机密值或将其写入日志。
- 在信任边界处验证外部输入。
- 当修改用户可见数据的访问权限时，检查授权路径。
- 不要记录 PII 或客户数据。

## 数据与迁移
- 将 schema 变更和迁移视为高风险操作。
- 除非任务明确要求，不要创建或修改生产环境的迁移。
- 在总结中标记破坏性变更，包括删除列、删除行、不可逆的回填操作。
- 在应用破坏性数据变更前等待确认。

## 何时停止并询问
在以下情况下暂停并询问：
- 添加生产依赖或新框架。
- 添加宽泛的新抽象。
- 操作生产数据、schema 或迁移。
- 对公共 API 或共享接口进行破坏性修改。
- 编辑共享配置、CI 或构建流水线。
- 任务与代码存在矛盾时继续执行。
- 在多个有效方案中无法明确选择最优解时。

## 报告反馈
每次任务结束时需包含：
- 按文件列出的修改内容。
- 验证方式，包括运行的命令及其结果。
- 未运行的内容及其原因。
- 风险或后续跟进事项。

这份模板不绑定具体技术栈，因此比前面那种硬编码 pnpm、Prisma、docs/api 的模板更具通用性。其核心思路是：让 Codex 先阅读项目、再推断命令、然后做最小化修改，最后输出验证结果和潜在风险。

如果你的项目已有明确的技术栈，可以在该模板基础上追加项目特有规则，例如：

- 修改 Prisma schema 后，执行 `pnpm db:generate`。
- API 变更必须同步更新 `docs/api` 下的文件。
- 前端变更必须通过 `pnpm test apps/web`。

换言之，这份模板适合作为项目级 AGENTS.md 的底座，再叠加本项目自己的命令和边界，形成既通用又具体的约束体系。

总结

AGENTS.md 本质上是面向 Codex 的项目规范手册。全局文件存放长期偏好，项目文件存放工程规则，子目录文件存放模块规则，AGENTS.override.md 用于覆盖同目录的正常规则。如果团队已有自己的说明文件，也可以通过配置 fallback 文件名来集成。

最关键的一点是：AGENTS.md 不应包含空话。“请保持代码优雅”“请遵循最佳实践”这类表述对 Codex 几乎没有约束力。真正有效的工程化约束，是那些能够影响 Codex 具体行为并且可由命令验证的规则。这才是本文的核心目标——让 Agent 真正“懂”你的项目，而非在每项任务中从头摸索。