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 通常也能理解得更好。
