編寫專案規則檔案

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。