编写项目规则文件
基于官方 Codex AGENTS.md 和 Rules 教程，面向新手讲清全局规则、项目规则、嵌套覆盖、fallback 文件名和排障方式。
Codex 在开始工作前会读取项目指导文件。你可以把全局工作习惯和项目规则叠加起来，让每个仓库都带着一致的约定进入任务。
新手要先理解：规则文件不是越长越好。它的价值是减少反复解释，让 Codex 在每次任务开始时知道稳定事实、禁止事项和验证方式。
先理解：AGENTS.md 解决什么问题
AGENTS.md 是项目和 Agent 之间的协作接口。它适合写项目结构、常用命令、测试方式、代码风格、禁止事项、目录边界、提交前检查。
它不适合写一次性任务、长篇教程、随手灵感、个人偏好和敏感信息。
如果你每次都要对 Codex 重复同一句规则，说明这条规则应该进 AGENTS.md 或更细的规则文件。
怎么判断放全局还是项目
全局规则放在 Codex home 里，适合你的个人稳定习惯。例如沟通风格、默认测试习惯、不要主动安装依赖、改动前先说明计划。
项目规则放在仓库里，适合所有协作者都应该知道的事实。例如启动命令、测试命令、目录职责、数据库迁移规则、受保护路径。
本地临时偏好不要进团队项目规则。团队文件应该能被 PR review，不能被个人习惯污染。
嵌套规则怎么理解
Codex 会从项目根一路读到当前工作目录。越靠近当前目录的规则越晚进入上下文，因此更能影响局部任务。
根目录适合放全仓规则。子目录适合放模块规则，例如前端、后端、支付、搜索、移动端。
同一目录里，override 文件会优先于普通规则文件。它适合临时或强覆盖，但不要滥用。过多 override 会让团队难以理解最终规则来源。
fallback 文件名什么时候用
如果你的仓库已有 TEAM_GUIDE.md、.agents.md 这类文件，可以通过 fallback 配置让 Codex 识别它们。
但新手默认不要扩展太多文件名。统一使用 AGENTS.md 更清楚，也更利于跨工具协作。
只有在历史仓库已有稳定规则文件、短期不想重命名时，才配置 fallback。
规则应该怎么写
写事实，不写口号。比如“修改 API handler 后运行某个测试命令”，比“保持高质量”有用。
写禁止事项。比如不要改某个目录、不要重写迁移历史、不要提交 generated 文件。
写验证方式。Codex 完成任务后应该知道跑什么命令，失败时怎么处理。
写路径边界。告诉它哪些目录是源码、文档、生成物、实验区、敏感区。
写更新规则。比如改公共工具行为时要同步 docs，改 API 时要同步 tests。
新手常见坑
- 把
AGENTS.md写成大百科：上下文变重，关键规则反而不突出。 - 写抽象口号：模型无法验证，也无法稳定执行。
- 把 secret、账号、token 写进去。
- 每个子目录都放一份重复规则：冲突和过期会越来越多。
- 修改规则不走 review：团队共识被悄悄改掉。
- 忘记 Codex 每次新会话才重新构建指令链，以为当前会话会自动读到刚改的规则。
怎么排障
如果什么规则都没加载，确认你在目标仓库里，文件有内容，且 Codex 识别的 workspace root 正确。
如果加载了错误规则，检查上级目录或 Codex home 是否有 override。
如果 fallback 文件没生效，确认 fallback 配置拼写正确，并重启 Codex 或开启新会话。
如果规则被截断，说明内容过大。应该删掉低价值说明，或把局部规则拆到更靠近对应目录的位置。
如果 profile 混乱，检查 CODEX_HOME 是否指向了另一个 home 目录。
怎么验收
在仓库根目录让 Codex 总结当前加载到的项目规则。它应该能复述全局和项目规则的关键点。
在子目录启动 Codex，让它说明局部规则是否覆盖了根规则。
让 Codex 做一个小任务，检查它是否按规则运行验证、遵守禁止事项、没有改错目录。
团队场景里，修改 AGENTS.md 应该像改代码一样走 PR review。