OpenAI Codex 官方 AGENTS.md：大型專案怎麼寫給 AI 看的規則

AGENTS.md 是寫給 AI coding agent 的「README」。想知道一個真實在跑的大型 OSS 專案怎麼寫？直接抄 OpenAI 自家 codex 倉庫的版本——它把「測試怎麼跑、commit 怎麼下、模組不能超過幾行、API 怎麼命名」全寫死，agent 一看就照做。

[ 登入後可看完整內容 ]

## 這是什麼／解決什麼痛點 AGENTS.md 是放在程式倉庫根目錄、專門寫給 AI coding agent（Codex、Claude Code 等）讀的「機器版 README」。痛點很實際：當你叫 AI 改一個有規模的專案，它不知道「測試要用哪個指令跑、commit 訊息怎麼下、哪些檔案碰不得、單一檔案不能膨脹到幾行、API 要怎麼命名」——結果就是它寫出風格不一致、踩到地雷、或 PR 大到沒人想 review 的程式碼。AGENTS.md 就是把這些「團隊默契」白紙黑字寫成 agent 看得懂、會照做的指令。 ## 為什麼這個來源值得用 這篇策展的不是教學文，而是 **OpenAI 官方 codex 倉庫自己正在用的那份 AGENTS.md**——一個真實、大型、多 crate 的 Rust/TypeScript/Python 混合專案。它的價值在於「真的在跑」：你看到的每一條規則都是 OpenAI 團隊踩過坑後沉澱下來的，不是憑空想像。它示範了一份成熟 AGENTS.md 該涵蓋哪些面向。 ## 原檔涵蓋的重點（節錄觀察） - **格式與 lint**：改完自動跑 `just fmt`、內聯 `format!` 參數、`match` 要窮舉不留萬用分支。 - **測試紀律**：用 `just test` 不用 `cargo test`、比較「整個物件」而非單一欄位、UI 變更一律要附 insta 快照。 - **模組大小硬上限**：目標每個模組 500 LoC 以下、~800 LoC 就該拆；明令不要養大 `chatwidget.rs`／`app.rs` 這種 orchestration 巨檔。 - **變更大小**：一般變更上限 800 行、複雜邏輯 500 行以內，更大的要拆成可 review 的片段。 - **API 命名公約**：新介面只進 v2、`*Params`／`*Response`／`*Notification` 命名、serde camelCase 等——示範了如何把「團隊 API 慣例」也寫進 agent 規則。 - **碰不得清單**：明確標記與 sandbox 環境變數相關的程式碼「永遠不要改」。 ## 怎麼用 1. 在你的 repo 根目錄建 `AGENTS.md`（子目錄可放更貼近該層的覆寫版，agent 會就近採用）。 2. 套用右側 full_prompt 範本，把 `{{TOOLCHAIN}}`、`{{TEST_CMD}}`、`{{FORMAT_CMD}}`、行數上限等佔位符換成你專案的真實值。 3. 重點放在「可機械執行」的條列——指令、數字上限、命名規則——而不是「請寫乾淨的程式碼」這種抽象口號。 4. 把「絕對不要碰的檔案／設定」明確列出，這是省下最多災難的一條。 ## 何時用 任何你打算讓 AI agent 反覆動手的專案都該有一份。專案越大、貢獻者越多、慣例越多，AGENTS.md 的回報越高。 📎 來源：openai/codex 倉庫的 AGENTS.md（作者 OpenAI，Apache-2.0 授權）— 本篇為繁中改寫整理，內容經改寫、非逐字轉載，原始檔案見上方連結。