2026年 Codex AGENTS.md 怎么写？项目规则、测试命令和代码审查最佳实践

AGENTS.md 不是给人看的普通 README，而是给 Codex 开始工作前读取的一份项目说明书。写得好，Codex 会知道项目怎么安装、怎么测试、哪些目录不能乱动、改完代码要按什么标准自查；写得乱，后面就容易出现命令跑错、风格不一致、审查重点偏掉的问题。

很多团队第一次写 AGENTS.md，会把所有规则一股脑塞进去，结果文件越来越长，Codex 真正需要的内容反而被淹没。更实用的写法，是只留下对开发任务有直接影响的信息：环境准备、常用命令、代码风格、测试范围、提交前检查和安全边界。

开头可以先写项目定位。比如这是前端组件库、后台服务、CLI 工具还是多端仓库。Codex 不需要看一段宣传介绍，它需要知道代码的主要入口、常见改动位置和不要误碰的区域。三五句话把项目说清楚，比一大段愿景更有用。

第二部分建议写 setup 命令。依赖安装用 npm、pnpm、uv、pip 还是 go mod，都要写明确。若项目需要特定 Node、Python 或 SDK 版本，也应该放在这里。不要只写“安装依赖”，最好写出团队日常真的会运行的命令。

第三部分写测试命令，而且要分层。改普通业务逻辑跑什么，改 UI 组件跑什么，改后端接口跑什么，改公共工具函数跑什么。Codex 最怕拿到一个巨大项目后只知道“运行全部测试”，结果耗时过长，或者因为环境不全直接失败。

代码风格不要写成抽象口号。少写“保持优雅”“注意可维护性”，多写具体规则：不要改格式化工具配置，新增 API 要补类型，公共函数要有测试，数据库迁移不能和业务代码混在同一个提交里。越具体，执行越稳定。

如果仓库有多个子目录，可以在根目录放一份 AGENTS.md，再在特殊模块下放更贴近的规则。支付、权限、数据同步、部署脚本这类目录，往往需要更严格的说明。离当前目录更近的规则能补充或覆盖更通用的规则。

如果大家想体验一线 AI 编程模型 codex 和 claude，用它们帮你完成工作、改代码、跑测试和做审查，可以参考以下教程文档进行接入配置，接入配置好后即可使用。文档教程：https://my.feishu.cn/wiki/NIgLwuuj1ibzJIkLGM0cgVNinzg

代码审查要求也适合写进 AGENTS.md。可以告诉 Codex 审查时先看边界条件、错误处理、权限校验、并发问题和测试遗漏，再看命名和格式。这样它做 review 时会更贴近团队习惯，而不是给出一堆泛泛的建议。

安全规则必须直接。不要读取 .env，不要打印 token，不要把客户数据放进示例，不要在没有确认的情况下改 CI、部署脚本和权限配置。AI 编程工具越能自动执行，越需要在规则里提前写清楚哪些事情必须停下来问人。

AGENTS.md 也要避免过度控制。把每一种小偏好都写进去，会让 Codex 在执行时变得迟疑，甚至为了满足无关要求绕远路。真正值得写的，是那些经常导致返工、风险较高、团队成员也容易忘记的规则。

写完以后要做一次验证。打开一个小任务，让 Codex 先总结它读取到的项目规则，再让它改一个低风险文件，最后看它是否按要求运行测试和说明 diff。能执行起来的 AGENTS.md，才算真的有用。

团队维护时，可以把 AGENTS.md 当成工程规范的一部分。项目命令变了、测试脚本改名了、目录结构调整了，都要同步更新。很多 AI 工具表现不稳定，不是模型突然变差，而是它拿到的项目规则已经过期。

比较稳的写法，是先从一页纸开始：项目说明、安装命令、测试命令、代码风格、审查重点、安全边界。等团队真正遇到重复问题，再逐条补充。这样写出来的 AGENTS.md 短、准、能落地，也更像一份工程协作说明。

实际写 AGENTS.md 时，可以把内容分成“必须执行”和“参考习惯”两类。必须执行的规则要短而明确，例如运行指定测试、禁止提交密钥、改公共 API 要补说明；参考习惯可以放在后面，避免干扰核心任务。

不要在 AGENTS.md 里写过期命令。很多项目最初用 npm，后来迁到 pnpm，文档却没改。Codex 一旦照着旧命令跑，失败信息会把注意力带偏，真正要修的代码反而被耽误。

如果项目依赖本地服务，也要写明启动顺序。先起数据库、再起后端、最后起前端，还是只需要 mock 服务，都应该说清楚。代理不知道这些背景，就容易把环境问题当成代码问题。

代码审查部分可以给出优先级。安全、数据一致性、错误处理和测试遗漏排前面，命名和小格式排后面。这样 Codex 做 review 时会先看真正影响质量的地方。

维护 AGENTS.md 最好的时机，是每次出现重复返工之后。只要团队连续两三次因为同一条规则没写清而返工，就把它补进去；没有造成实际问题的偏好，暂时不要急着加入。

还可以在 AGENTS.md 里写明“改完后怎么汇报”。比如列出修改文件、测试命令、失败原因和需要人工确认的地方。Codex 最后输出越稳定，团队 review 越省时间。

如果项目规模很大，AGENTS.md 不必一次覆盖全部模块。先覆盖最常改、最容易出错的部分，之后随着任务增加慢慢补齐。规则跟着真实工作增长，会比一次性编一份大全更自然。

一个容易忽略的细节，是把“不要做什么”写得比“要做什么”更清楚。比如不要重排整个文件、不要顺手升级依赖、不要改自动生成代码，这些规则能显著减少无关 diff。

如果仓库里有历史包袱，也可以写明暂时不要碰的地方。Codex 看到旧模块时，可能会主动建议重构，但真实项目里未必允许。提前标注，能避免它把任务范围越扩越大。

AGENTS.md 还适合记录验证口径。测试失败时是允许提交说明，还是必须继续修到通过；快照更新是否需要人工确认；外部服务不可用时怎么处理。这些都应该提前定好。

最后要记住，AGENTS.md 的读者虽然是工具，但它服务的是团队协作。写得像给新同事看的项目交接说明，Codex 通常也能理解得更好。