AGENTS.md:寫一次專案說明書,Codex 從此不用每次重講

用 Codex 改專案改了幾天,你大概會開始煩一件事:每次開新的一段對話,都要重新交代一遍「這是 Next.js 專案、測試用 npm test、legacy/ 資料夾不要碰、回答請用繁體中文」。講一次沒事,講第十次就會懷疑人生——這些明明是不會變的事實,為什麼要一直重打?

解法是一個檔案:AGENTS.md。把這些規矩寫進去一次,放在專案根目錄,Codex 每次啟動就會自動讀進來,當成這個專案的行為準則。這堂課就是教你把這份「專案說明書」寫對、放對位置,讓 Codex 從第一句話就知道你的專案長什麼樣。

這堂學什麼

• AGENTS.md 到底是什麼、Codex 什麼時候會讀它、跟你用過的 CLAUDE.md 是什麼關係
• 讀取順序:從全域 ~/.codex/AGENTS.md 到專案根目錄、再到子資料夾,層層疊加、由遠到近覆蓋,還有一個 32 KiB 的上限要注意
• 用 /init 一鍵生出 AGENTS.md 草稿,再手動修成真正有用的版本
• 該寫什麼、不該寫什麼:寫「程式碼看不出來的規矩」,不要把 README 整篇貼進去
• 一份可以直接複製改用的 AGENTS.md 範本
• 三個新手最常踩的坑(含真實錯誤現象與解法)

觀念一:AGENTS.md 是專案的「新人須知」

AGENTS.md 是一份放在專案根目錄的 Markdown 檔,檔名固定就叫 AGENTS.md(全大寫)。Codex 在開始做事之前會先把它讀進去,當成這個專案的預設脈絡。你把規矩寫一次,以後每次開對話都不用重講。

最好的比喻是新人到職須知。一個新同事進來,你不會每次交辦任務都從頭解釋「我們用什麼框架、commit 訊息寫中文、這個舊資料夾別動」——你會給他一份文件,他自己看完就上手了。AGENTS.md 就是 Codex 的那份文件。

要特別記住一件事:Codex 是在啟動一段工作時讀 AGENTS.md,而且一次工作只讀一次(在互動式 TUI 裡,通常是每次啟動 session 時載入)。也就是說,你在對話進行到一半才去改 AGENTS.md,當下這段對話不會馬上生效——要離開重開,或開新的一段,新內容才會被讀進去。這點後面常見坑會再提醒。

觀念二:讀取順序——全域、專案、子資料夾層層疊加

這是新版 Codex 最容易被忽略、但威力最大的設計。Codex 不是只讀一個 AGENTS.md,而是會沿著路徑收集一整條「指令鏈」,把它們串起來一起餵給模型。順序是這樣的:

1. 全域層:你的 Codex 家目錄(預設 ~/.codex,可用環境變數 CODEX_HOME 改)裡的 AGENTS.md。這裡寫「不管哪個專案都適用」的個人偏好,例如「回答一律繁體中文」「不要主動幫我 git commit」。
2. 專案根目錄層:從 git 根目錄開始。這裡寫這個專案共用的規矩,會被 commit 進版本庫、團隊共享。
3. 子資料夾層:從 git 根目錄一路往下走到你目前所在的資料夾,沿途每一層的 AGENTS.md 都會被收進來。

關鍵原則:愈靠近你當前位置的,優先權愈高。全域的規矩打底,專案根目錄的疊上去,子資料夾的最後覆蓋。所以你可以在 frontend/AGENTS.md 寫「這個模組用 2 空格縮排」,即使根目錄寫的是 4 空格,在 frontend/ 裡工作時就以子資料夾的為準——細節覆蓋通則,跟 CSS 一樣。

還有兩個進階但實用的機制,知道就好:

• AGENTS.override.md:同一層如果同時有 AGENTS.override.md 和 AGENTS.md,Codex 只讀 override 那份。適合臨時想蓋掉現有規矩、又不想動到原檔的時候(例如 debug 某個問題時暫時放寬限制)。
• 後備檔名:如果團隊習慣用別的檔名,可以在設定裡用 project_doc_fallback_filenames 指定,Codex 在找不到 AGENTS.md 時會去找這些後備名字。

觀念三:該寫什麼、不該寫什麼

寫 AGENTS.md 最常見的失敗,是把它寫成第二個 README。README 是給人看的專案介紹,AGENTS.md 是給 AI 看的行為指令——兩者目的不同。判斷標準只有一句話:寫「AI 從程式碼看不出來、但每次都需要知道」的事。

該寫(程式碼看不出來,或看得出來但很花時間確認的):

• 技術棧:前端什麼框架、後端什麼、資料庫是什麼。讓 Codex 不用翻半天 package.json 猜。
• 常用指令:怎麼跑開發伺服器、怎麼跑測試、怎麼做型別檢查。這是投報率最高的一段,寫清楚 Codex 就不會亂猜指令。
• 慣例:命名規則、縮排、要不要分號、錯誤處理格式。這些是「口味」,程式碼裡零散地散著,寫成一條規矩最省事。
• 禁區:哪些資料夾別碰、哪些檔案不要動、什麼操作要先問過你。這是保護你專案的護欄。

不該寫(浪費那寶貴的 32 KiB):

• 把 README 或安裝教學整篇貼進來——那些網路上到處有,AI 本來就會。
• 專案的行銷介紹、發展歷史、感謝名單——對做事一點幫助都沒有。
• 一大段程式碼範例——需要的時候 Codex 自己會去讀原始碼。

一個好用的心態:當成寫給一位很強、但完全沒看過你專案的資深工程師的一張 A4 便條。他技術很好(不用教他 React 是什麼),但他不知道你們家的規矩(這才是你要寫的)。

手把手實戰:用 /init 生出草稿再修

你不用從一張白紙開始。Codex 內建一個 /init 指令,會掃一遍你的專案、自動生出一份 AGENTS.md 草稿。我們的流程是:讓它生草稿 → 刪廢話、補真正的規矩 → 驗證有沒有被讀到。

cd ~/my-project
codex

/init

# 專案說明

電商後台。前端 Next.js(App Router)+ TypeScript,
後端 Node.js + PostgreSQL(Prisma)。

## 常用指令
- 開發:npm run dev
- 測試:npm test(改完程式碼一定要跑,綠了才算完成)
- 型別檢查:npm run typecheck
- 建置:npm run build

## 慣例
- 元件放 src/components/,一個元件一個資料夾
- 用 2 空格縮排、不加分號
- API 錯誤一律回 { error: string }
- commit 訊息用繁體中文

## 禁區
- 不要碰 legacy/ 資料夾(舊系統,勿動)
- 不要自己執行 git push,改完等我確認
- 動到資料庫 schema 前先問我

根據目前載入的專案指令,我們的測試指令是什麼?哪些資料夾不能碰?

codex exec --sandbox read-only "用一句話總結目前載入的專案指令"

my-project/
├── AGENTS.md          # 全專案通則
├── frontend/
│   └── AGENTS.md      # 只寫前端規矩(覆蓋通則)
└── backend/
    └── AGENTS.md      # 只寫後端規矩

進階:全域 AGENTS.md 設定個人偏好

專案層的 AGENTS.md 是團隊共享的(會進版本庫),但有些偏好是你個人的、跨所有專案都想要的——這種寫進全域檔:

# 用編輯器打開(沒有就新建)
code ~/.codex/AGENTS.md

裡面適合寫這類「我這個人的習慣」:

# 個人偏好
- 回答與註解一律用繁體中文(台灣用語)
- 動任何檔案前,先用一兩句話說明你要做什麼
- 不要主動幫我 git commit / push,除非我明講
- 解釋概念時給類比,不要只丟術語

這份不會進任何專案的版本庫,是你自己的 Codex「個人設定」。它打底、每個專案的 AGENTS.md 再往上疊,這就是觀念二那條指令鏈的最底層。

常見坑

坑 1:改了 AGENTS.md,但 Codex 好像沒理它

最常見的原因是:你在同一段 session 進行中改檔。Codex 一次工作只讀一次 AGENTS.md(TUI 通常是啟動 session 時載入),進行到一半改檔不會即時生效。解法很簡單:離開 Codex、重新啟動,或開新的一段對話,新內容才會被讀進去。

第二個原因是檔名或位置錯了。檔名必須是全大寫的 AGENTS.md(不是 agents.md、不是 AGENT.md),而且要放在 git 根目錄或你當前工作路徑上。放在一個 Codex 根本不會走過的旁支資料夾,它當然讀不到。

坑 2:寫了一大堆規矩,後面的完全被無視

你洋洋灑灑寫了幾百行,結果發現寫在後半段的規矩 Codex 好像沒看到——這是撞到 32 KiB 上限(project_doc_max_bytes)了。整條指令鏈(全域 + 專案根 + 各層子資料夾)加起來超過 32 KiB,後面的會被截斷。解法:砍掉廢話(README 式的介紹、程式碼範例整段貼),真的內容多就拆到子資料夾分層放。記住 AGENTS.md 是「一頁須知」不是「文件庫」。

坑 3:/init 生出來的草稿直接拿去用,結果指令是錯的

/init 是用猜的——它從 package.json 之類推測你的指令,但如果你的專案有客製化的 script 名稱(例如測試指令其實是 npm run test:unit 而不是 npm test),它可能猜錯。之後 Codex 就會照著錯的指令跑,你會看到類似:

npm error Missing script: "test"

這代表 AGENTS.md 裡寫的指令在你專案根本不存在。解法:/init 生完務必自己核對一遍每一條指令,打開 package.json 的 scripts 區塊對照,把猜錯的改對。草稿是半成品,不是成品——這是 /init 最大的陷阱。

坑 4:把密碼、API 金鑰寫進 AGENTS.md

AGENTS.md 通常會被 commit 進版本庫、跟團隊共享,所以它跟 README 一樣是「公開」的。千萬不要把資料庫密碼、API 金鑰之類的秘密寫進去——那些屬於環境變數(.env,而且要放進 .gitignore)。AGENTS.md 只寫「規矩」,不寫「秘密」。這個坑一旦踩了,金鑰就跟著 git 歷史外洩,後果很嚴重。

作業

1. 挑一個你手邊的專案,在根目錄跑 /init 生一份 AGENTS.md,然後手動修:砍掉所有 README 式的廢話,補上「常用指令、慣例、禁區」三個區塊,每一行都要是程式碼看不出來的資訊。
2. 核對 /init 猜的指令對不對:打開 package.json 的 scripts,把 AGENTS.md 裡的指令逐條對照改正。
3. 建一份全域 ~/.codex/AGENTS.md,寫進至少三條你的個人偏好(例如語言、commit 習慣、解釋風格)。
4. 驗證:重開 Codex,用 codex exec --sandbox read-only "總結目前載入的專案指令" 確認它讀到了你寫的規矩。
5. 進階:如果你的專案夠大,挑一個子模組加一份自己的 AGENTS.md,寫一條跟根目錄不同的慣例,測試「近的覆蓋遠的」有沒有生效。

下一課預告

規矩設好了,來點真的。第 5 課是一場完整實戰:我們從零開始,用 Codex 幫一個專案加一個小功能、再修掉一個 bug,把前面四堂學過的東西——核准模式、編輯工作流、還有這堂的 AGENTS.md——全部串成一條完整的作業流程。你會看到一份寫好的 AGENTS.md 如何讓 Codex 從第一句話就進入狀況,少掉大量來回溝通。準備好把工具箱裡的東西真的用起來了。