---
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="/zh-Hant/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)
