---
title: "编写项目规则文件"
description: "基于官方 Codex AGENTS.md 和 Rules 教程，讲清全局规则、项目规则、嵌套覆盖、fallback 文件名和排障方式。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

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

<Cards>
  <Card title="AGENTS.md" href="https://developers.openai.com/codex/guides/agents-md">
    官方项目指导文件发现顺序和层级规则。
  </Card>
  <Card title="Rules" href="https://developers.openai.com/codex/rules">
    控制 Codex 哪些命令可以在 sandbox 外运行。
  </Card>
  <Card title="Config basics" href="/docs/codex/official/02-config-security/06-basic-config">
    规则加载依赖 active config layer 和 trust 边界。
  </Card>
</Cards>

## 两类规则别混

```mermaid
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/` 目录下。例如用户级：

```text
~/.codex/rules/default.rules
```

项目级：

```text
.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。

## 官方资料

- [AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
- [Rules](https://developers.openai.com/codex/rules)
- [Advanced config: project instructions discovery](https://developers.openai.com/codex/config-advanced#project-instructions-discovery)
- [Config reference](https://developers.openai.com/codex/config-reference)
