建立 2026-09-15 更新 2026-09-15

AGENTS.md

AGENTS.md 是 Codex 開工前會讀的專案說明。它跟聊天記錄不同：換 session、換同事、換 Cloud 容器，只要檔案在，規則就還在。

官方說明：Custom instructions with AGENTS.md。CLI 裡可用 /init 依目前 repo 產生初稿，再自己刪到只剩真正要執行的規則。

它會讀哪些檔

每次啟動（TUI 通常是每個 session 一次）會組一條指令鏈：

全域：~/.codex/AGENTS.override.md（若存在）否則 ~/.codex/AGENTS.md。這層只取第一個非空檔。
專案：從 repo 根目錄往下走到你的工作目錄。每個目錄最多納入一個檔，順序是 AGENTS.override.md → AGENTS.md → 你在設定裡列的後備檔名。
合併：由根到葉串起來，越靠近目前目錄的內容越後面，因此可以覆寫上層。

預設合計約 32 KiB（project_doc_max_bytes）。空檔會跳過。檔案請保持短：寫「做什麼／不要做什麼」，不要貼整本風格指南。

全域（~/.codex/AGENTS.md）放你個人習慣，例如慣用的套件管理器、改完要跑哪些指令。

專案根目錄放這個 repo 的契約：

# AGENTS.md

## 開發慣例

- 套件管理用 `uv`，不要新增 `requirements.txt`。
- 改 Python 後跑 `uv run pytest`。
- 不要提交 `.env` 或真實密鑰。

## 程式碼審查

- 優先標出行為錯誤與安全問題；格式交給 CI。

子目錄需要不同規則時，在該目錄放 AGENTS.override.md。例如金流服務改跑 make test-payments，不要沿用根目錄的 pytest。

GitHub 的 Codex review 會看最接近該程式的 ## Code Review Rules。把「什麼算錯、安全路徑是什麼」寫清楚；lint 仍交給 CI。

codex --ask-for-approval never "Summarize the current instructions."

預期它會引用全域與專案檔，且順序正確。若從子目錄啟動，應看到該層 override。

指令看起來過期時，在目標目錄重開一次 Codex 即可；它不會永久快取這條鏈。