交流群即將上線
05 · 用 AGENTS.md 交代專案規矩
為什麼需要它
第一天你會在每次對話開頭打一遍：「這個專案用 pnpm，改完 JS 要跑 npm test， 不要隨便加生產依賴。」第五天你會煩。第十天你會漏掉一條，然後它給你裝了個新包。
AGENTS.md 就是把這些話寫進倉庫，讓它每次自己讀。 Codex 在執行任何工作前都會讀 AGENTS.md。
它是怎麼找的
Codex 啟動時構建一條指令鏈（每次執行只構建一次；在 TUI 裡通常是每次開工作階段時構建一次），順序是：
第一層，全域性。 在 Codex 主目錄（預設 ~/.codex，除非你設了 CODEX_HOME）： 如果 AGENTS.override.md 存在就讀它，否則讀 AGENTS.md。 這一層只用按順序找到的第一個非空檔案。
第二層，專案。 從專案根目錄（通常是 Git 根）開始，沿目錄樹往下逐級走到當前工作目錄。 每一級依次找 AGENTS.override.md、AGENTS.md，再找 project_doc_fallback_filenames 裡配的回退名。 每個目錄最多納入一個檔案。 找不到專案根就只看當前目錄。
第三層，合併。 從根往下拼接，用空行分隔。 越靠近當前目錄的檔案在合併後出現得越晚，因此會覆蓋前面的指令。
空檔案會被跳過；合併後的大小一到 project_doc_max_bytes 上限（預設 32 KiB）就不再往裡加。
三層怎麼分工
~/.codex/AGENTS.md ← 你个人的习惯，跨所有仓库
<repo>/AGENTS.md ← 这个仓库的规矩，提交进版本库
<repo>/services/payments/AGENTS.override.md ← 这个子目录的特殊规矩全域性那份寫你自己的偏好，別寫專案相關的東西：
md
# ~/.codex/AGENTS.md
## Working agreements
- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.倉庫根目錄那份寫團隊約定，跟著程式碼一起提交：
md
# AGENTS.md
## Repository expectations
- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.子目錄那份只寫這塊地方跟別處不一樣的地方：
md
# services/payments/AGENTS.override.md
## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.從 payments 目錄啟動的話，它會先報告全域性檔案，然後是倉庫根的 AGENTS.md，最後是這份覆蓋檔案。
Codex 找到當前目錄就停了
所以覆蓋檔案要放在離相關工作最近的目錄裡。放在爺爺目錄上， 從孫子目錄啟動時它照樣能讀到（因為是從根往下走），但放太靠上就沒有「只對這塊生效」的意思了。
驗證它確實讀到了
bash
codex --ask-for-approval never "Summarize the current instructions."預期是它先引用 ~/.codex/AGENTS.md 裡的條目，再說方案。 想看得更細：
bash
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."AGENTS.override.md 是幹什麼的
需要臨時全域性覆蓋、又不想刪掉基礎檔案時用它——建一個 ~/.codex/AGENTS.override.md， 刪掉它就恢復原來的共享指令。同一層裡 override 存在就完全取代 AGENTS.md，不是疊加。
該寫什麼，不該寫什麼
該寫：
- 跑什麼指令（測試、lint、構建），特別是跟慣例不一樣的
- 硬性紅線（別改生成的檔案、別加依賴、別動某個目錄）
- 專案裡那些不成文的約定（錯誤處理風格、日誌格式、目錄職責）
別寫：
- 程式碼本身能說明的事（技術棧、目錄結構，它自己會看）
- 長篇的架構介紹——32 KiB 上限不是給你寫文件用的，寫多了後面的指令會被截掉
- 格式和 lint 規則——那是 CI 的活，寫進
AGENTS.md只是讓它多花 Token
順手加一節程式碼審查規則
如果你用 GitHub 上的 Codex 程式碼審查， 可以在最貼近相關程式碼的 AGENTS.md 里加一節 ## Code Review Rules：
md
## Code Review Rules
### Experiment cohorts
- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
Safe path: build cohorts from assignment or exposure; report conversion as an outcome.寫法上保持簡潔：說清楚要標記什麼行為、安全的做法是什麼或例外在哪。 倉庫範圍的檢查放根目錄，服務專屬的放巢狀檔案。
已經有別的檔名了
如果團隊已經在用 TEAM_GUIDE.md 之類的名字，把它加進回退列表：
toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536改完重啟 Codex 或跑一條新指令載入配置。之後每個目錄的檢查順序變成 AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md， 不在列表裡的檔名一律忽略。
順便一提：規則（rules）是另一回事
AGENTS.md 說的是「怎麼幹活」，規則管的是 「哪些指令能在沙盒外跑」——是權限，不是指令。規則檔案放在生效配置層旁的 rules/ 目錄裡（比如 ~/.codex/rules/default.rules），用 Python 風格的 prefix_rule 寫：
python
prefix_rule(
pattern = ["gh", "pr", "view"],
decision = "prompt",
justification = "Viewing PRs is allowed with approval",
)在 TUI 裡把某條指令加進允許列表時，Codex 就是把它寫進 ~/.codex/rules/default.rules。 這個功能還處於實驗階段，可能會變。