编写项目规则文件

Codex 在开始工作前会读取项目指导文件。你可以把全局工作习惯和项目规则叠加起来，让每个仓库都带着一致约定进入任务。

规则文件不是越长越好。它的价值是减少重复解释，让 Codex 稳定知道事实、边界和验证方式。

AGENTS.md

官方项目指导文件发现顺序和层级规则。

Rules

控制 Codex 哪些命令可以在 sandbox 外运行。

Config basics

规则加载依赖 active config layer 和 trust 边界。

两类规则别混

flowchart TD
    Global["global AGENTS.md"] --> Chain["instruction chain"]
    Project["project AGENTS.md"] --> Chain
    Nested["nested AGENTS.md / override"] --> Chain
    Rules[".codex/rules/*.rules"] --> Approval["command approval policy"]

AGENTS.md 约束 Codex 怎么理解项目、怎么工作、怎么验证。

.rules 控制 Codex 哪些命令可以在 sandbox 外运行。官方把 rules 标为 experimental，所以不要把它当成永久稳定接口；关键安全策略仍要用 sandbox、approval、managed configuration 和人工 review 兜底。

放全局还是项目

全局规则放在 Codex home，适合个人稳定习惯：

交互语言。
默认测试习惯。
不主动安装依赖。
改动前先说明计划。
输出格式偏好。

项目规则放在仓库，适合所有协作者都应该知道的事实：

启动命令。
测试命令。
目录职责。
数据库迁移规则。
受保护路径。
改公共 API 后要同步的测试和文档。

本地临时偏好不要进团队项目规则。团队文件应该能被 PR review，不能被个人习惯污染。

嵌套和覆盖

Codex 会从项目根一路读到当前工作目录。越靠近当前目录的规则越晚进入上下文，因此更能影响局部任务。

根目录适合放全仓规则。子目录适合放模块规则，例如前端、后端、支付、搜索、移动端。

同一目录里，override 文件会优先于普通规则文件。它适合临时或强覆盖，但不要滥用。过多 override 会让团队难以理解最终规则来源。

fallback 文件名

如果仓库已有 TEAM_GUIDE.md、.agents.md 这类文件，可以通过 project_doc_fallback_filenames 让 Codex 识别它们。

新项目默认不要扩展太多文件名。统一使用 AGENTS.md 更清楚，也更利于跨工具协作。

只有在历史仓库已有稳定规则文件、短期不想重命名时，才配置 fallback。

规则应该怎么写

写事实，不写口号：

“修改 API handler 后运行 pnpm test api。”
“不要改 migrations/ 里的历史文件。”
“UI 改动检查 375px 和 1440px。”
“改公共工具行为时同步 docs 和 tests。”

写路径边界。告诉 Codex 哪些目录是源码、文档、生成物、实验区、敏感区。

写验证方式。Codex 完成任务后应该知道跑什么命令，失败时怎么处理。

写更新规则。文档站、SDK、CLI、主题这类项目尤其需要同步上下游文件。

`.rules` 文件怎么用

.rules 文件放在 active config layer 旁边的 rules/ 目录下。例如用户级：

~/.codex/rules/default.rules

项目级：

.codex/rules/default.rules

项目本地 rules 只有在项目 .codex/ 层被信任后才加载。

规则要匹配命令参数前缀，并明确 decision：

allow：允许匹配命令在 sandbox 外运行。
prompt：每次匹配都询问。
forbidden：直接阻止。

给高风险规则写 match 和 not_match 示例，用它们当作内联测试，避免前缀匹配过宽。

常见坑

把 AGENTS.md 写成大百科：上下文变重，关键规则反而不突出。
写抽象口号：模型无法验证，也无法稳定执行。
把 secret、账号、token 写进去。
每个子目录都放重复规则：冲突和过期会越来越多。
修改规则不走 review：团队共识被悄悄改掉。
忘记新会话才会重新构建 instruction chain。
.rules 前缀写太宽，意外放行高风险命令。

排障方式

如果什么规则都没加载，确认你在目标仓库里，文件有内容，且 Codex 识别的 workspace root 正确。

如果加载了错误规则，检查上级目录、Codex home 和 override 文件。

如果 fallback 文件没生效，确认 fallback 配置拼写正确，并开启新会话。

如果规则被截断，说明内容过大。删掉低价值说明，或把局部规则拆到更靠近对应目录的位置。

如果 profile 混乱，检查 CODEX_HOME 是否指向另一个 home 目录。

验收

在仓库根目录让 Codex 总结当前加载到的项目规则。它应该能复述全局和项目规则关键点。

在子目录启动 Codex，让它说明局部规则是否覆盖根规则。

让 Codex 做一个小任务，检查它是否按规则运行验证、遵守禁止事项、没有改错目录。

团队场景里，修改 AGENTS.md 应该像改代码一样走 PR review。