AGENTS.md 怎么写，Codex 才照做？

AGENTS.md 是 Codex 开工前先读的指令文件，只写本仓库特有、每次会话都要遵守的 Codex 项目规则，例如跑哪条测试命令、哪些目录不能动、提交前要跑什么检查、加生产依赖前先确认。写规则时一条一行，写成可以检查的动作。全仓通用的放根目录，模块专门的放子目录，流程很长且只在特定任务用到的做成技能，写完进目标目录让 Codex 总结指令验证生效。

Codex 按什么顺序读 AGENTS.md

Codex 开工前先读 AGENTS.md，每次运行时建一次指令链，在终端界面里通常是每次启动会话建一次。读取先从全局层开始：程序去 Codex 主目录（默认 ~/.codex）查找，有 AGENTS.override.md 就读它，没有再去读 AGENTS.md，全局这一层只用第一个非空文件。团队如果同时用多款研发工具，不同工具读的规则文件和分工见 Claude Code 和 Codex：什么活给谁。

读完全局层再走项目层。程序从项目根目录（通常是 Git 根目录）往下走到当前工作目录，每一级目录依次找 AGENTS.override.md、AGENTS.md 以及配置里的备用文件名，每个目录最多取一个文件，空文件直接跳过。

命中的文件从根往下拼接，离当前目录越近的文件排在越后面，覆盖前面的规则。合并后总大小到 project_doc_max_bytes 设定的上限（默认三十二 KiB）就不再往里加；超了要么去配置里调高上限，要么把规则拆到子目录里。

Codex 项目规则怎么写才照做

「代码要优雅」这类话没法核对，还占文件大小。写 Codex 项目规则时，只留本仓库特有、每次改代码都要执行的动作，一条规则一行：

• 改完文件跑测试：写明改了某类源码或配置文件后跑哪条测试命令，让每次修改都有验证步骤。
• 包管理与依赖确认：写明装依赖优先用指定的包管理器，新加生产依赖前先停下来向维护人确认。
• 禁改目录与提交前检查：列清哪些构建产物目录或核心配置目录不能动，以及提交前要跑什么检查。
• 代码评审规则：在离业务代码最近的 AGENTS.md 里加一个代码评审规则小节，简洁说明要标出的行为和安全做法或例外；格式和代码风格检查交给持续集成。

根目录、子目录和技能怎么分

同一个 Git 仓库里不同模块常有不同的测试跑法，把全仓通用的包管理器约定和基础提交检查放在根目录的 AGENTS.md 即可；某个子目录有本模块的专门规则，比如要用专门的测试命令或者有单独的模块评审要求，就在那个子目录放文件，或者用 AGENTS.override.md 写本模块的专门规则来覆盖上层约定，避免把全部模块的细节都堆在根目录里撞上默认三十二 KiB 的大小上限。

同时要把每次开工都读的 Codex 项目规则同长流程拆开。AGENTS.md 每次启动会话都会读入指令链；流程很长、只在特定任务里才用到的操作说明，别塞进 AGENTS.md，应当单独做成按需加载的技能；技能的安装和调用见 Codex 技能怎么装？装好后怎么调用。

写完后怎么验证规则生效

规则文件提交进仓库后，不要等改错了代码再回头排查，直接通过会话提问就能验证读取顺序和覆盖关系。维护人先在仓库根目录启动 Codex，让它总结当前收到的全部指令，核对它是否按从上到下的顺序复述出全局主目录文件和项目根目录文件里的规则条目。

接着切进放了模块规则或 AGENTS.override.md 的子目录，重新启动会话再问一次同样的问题，检查子目录里的专门测试命令或评审要求有没有排在后面并覆盖上层约定。如果复述出来的规则看起来没更新，按官方说明退出并在目标目录重启 Codex，指令链会在启动时重新构建。

AGENTS.md：常见问题

改了仓库里的 AGENTS.md，为什么当前会话没按新规则执行？

在终端界面里，指令链在启动时构建。保存修改后，按官方说明退出当前会话，在目标工作目录重启 Codex，再让它总结一次当前指令确认生效。

同一个目录里既有 AGENTS.override.md 又有 AGENTS.md，两个都会读吗？

不会两个都读。无论在全局主目录还是项目每一级目录，每个目录最多只取一个非空文件，依次先找 AGENTS.override.md，没有才读 AGENTS.md。需要覆盖同级默认规则时才放 override 文件，平时维护一份非空文件即可。

Codex 项目规则写在 AGENTS.md 还是写成技能？

每次开工都要遵守的写成 Codex 项目规则放进 AGENTS.md，比如默认包管理器、禁改目录和改完文件必跑的测试命令；只在某类任务里用、步骤又长的写成技能，按需加载。两者职责分清，别把同一条规则重复写两遍。