AGENTS.md 怎么写？Codex 仓库规则、作用域与团队协作实践

AGENTS.md 适合记录什么

优先记录稳定、可执行且与仓库直接相关的信息。典型内容包括项目结构、安装与测试命令、代码风格、生成文件规则、数据库迁移要求和安全注意事项。临时任务细节仍应写在当次提示中，不要把规则文件变成不断增长的聊天记录。

• 项目入口与关键目录的职责
• 准确可复制的安装、测试和构建命令
• 命名、格式、依赖和兼容性约定
• 提交前的完成标准与禁止事项

理解全局、仓库和子目录作用域

个人层面的通用偏好可以放在 Codex 配置目录中的 AGENTS.md；项目共享规则通常放在仓库根目录；某个子系统有特殊要求时，可在相应子目录继续放置更具体的 AGENTS.md。Codex 会根据当前工作目录组合适用规则，越靠近目标文件的说明越具体。

这种分层方式适合 monorepo：根目录只写全局约定，前端、后端和基础设施目录分别补充自己的命令与限制，避免所有内容堆在一个超长文件里。

用可执行表述替代模糊口号

“保持高质量”“注意性能”很难直接执行。更好的写法是列出具体命令和判断条件，例如修改 API 后运行哪组测试、组件必须使用现有设计令牌、数据库结构变化必须带迁移文件。规则越能被命令或代码差异验证，越不容易产生歧义。

• 模糊：完成后充分测试
• 具体：运行 npm test 与 npm run build
• 模糊：保持风格一致
• 具体：复用 src/ui 中的组件，不新增第二套颜色变量

保持短小并定期验证

AGENTS.md 应随着仓库变化一起维护。命令改名、目录迁移或依赖更新后，旧规则会比没有规则更危险。可以在评审中把规则文件视为工程配置：修改后实际执行其中的命令，并删除已经失效或与其他层级重复的内容。

团队还可以给常见任务准备模板，例如修复缺陷时先复现、增加测试、实现最小修复，再运行回归。模板负责过程，任务提示负责当次目标，两者不要混在一起。