Codex AGENTS.md 怎么分层？仓库规则、子目录覆盖与代码审查指南

AGENTS.md 的作用：把团队规则放进每次任务上下文

Codex 会在任务开始前读取 AGENTS.md。官方文档说明，它从全局范围和项目根目录向当前工作目录逐层查找，并把更接近当前目录的规则放在后面，因此局部规则可以覆盖更通用的规则。

这使 AGENTS.md 很适合记录构建命令、测试要求、目录约束和代码审查标准，而不是每次在提示词里重新解释。

一、根目录规则应该写什么

根目录只放全仓库都适用的约定：项目结构、包管理器、安装与构建命令、测试入口、禁止提交的文件、完成定义和最重要的安全边界。

规则要短、明确、可执行。“写高质量代码”没有帮助；“修改 TypeScript 后运行 pnpm typecheck 和 pnpm test”才可验证。

二、子目录规则解决局部差异

前端、后端、数据库或移动端往往有不同命令和风险。把局部 AGENTS.md 放在对应目录，使规则只影响该范围。

例如支付目录可以要求禁止记录完整卡号、任何迁移必须提供回滚；前端目录可以要求窄屏与键盘操作检查。不要把所有细节堆进根文件。

三、给代码审查单独写规则

官方指南建议在最接近相关代码的 AGENTS.md 中加入 Code Review Rules。审查规则应说明需要标记的高风险行为，以及安全做法或允许的例外。

格式、拼写和 lint 应交给 CI；AGENTS.md 更适合业务不变量、权限边界、实验分组、隐私与数据一致性等机器难以从语法推断的规则。

四、避免规则互相冲突

先画出从仓库根到工作目录的规则链，确认相同主题只在最合适层级定义。局部覆盖要明确说明差异，不要复制整份根规则。

如果规则过长，应把详细流程放入独立文档，并在 AGENTS.md 中给出阅读条件与准确路径。这样能减少上下文噪音。

五、把重复错误变成长期规则

当 Codex 两次犯同一种错误，就把修正整理成一条可执行规则：触发场景、禁止行为、正确做法与验证方法。

同时用测试、类型检查或预提交钩子强制执行能自动检查的部分。文档告诉代理为什么和何时，工具负责持续阻止错误。

六、验证规则真的被加载

在仓库根目录或目标子目录启动新任务，让 Codex总结当前生效的指令，检查它是否识别构建命令、测试与局部约束。

注意规则通常在任务开始时加载；修改后应在新任务中验证。站内更多 Codex 实践可访问 https://gptupcn.com/codex/ 。

结语

好的 AGENTS.md 不是越长越好，而是让每次任务都有一致的起点、清楚的边界和可验证的完成标准。