AGENTS.md 與專案記憶

AGENTS.md 是一份你親手寫、Codex「動手做任何事之前」一定先讀一遍的「工作守則手冊」。

想像你請了一位很厲害、但完全不認識你公司的新同事。他能力很強，可是不知道「我們這個專案要先跑哪個測試」「commit 訊息要怎麼寫」「哪幾個資料夾碰不得」。你總不能每次交辦工作都把這些規矩從頭講一次吧？

AGENTS.md 就是你放在桌上的那張守則便條。新同事（Codex）每次開工前都會先把它讀過一遍，自動照規矩辦事。你只要寫一次，之後它就一直記得。

放對位置、寫得精簡，守則就生效；放錯地方、寫太長，它就讀不到或讀不完。這一章就教你把這張便條放對、寫對。

你會學到：

• 「幫我修這個 bug，但記得改完 JS 一定要跑 npm test。」——這種規矩寫進 AGENTS.md，以後就不用每次再講。
• 「這個專案前端跟後端規矩不一樣。」——用不同層級的 AGENTS.md 分開管。
• 「我已經有 Claude Code 的 CLAUDE.md 了，不想重寫。」——教你怎麼沿用。
• 「Codex 自己會記住我們聊過什麼嗎？跟 AGENTS.md 是不是同一件事？」——分清楚 Memories 跟你手寫的守則是兩回事，還有第三層 Skills 藏在哪裡。

5.1 AGENTS.md 是什麼、何時被讀

先記住一句官方原話：

Codex reads AGENTS.md files before doing any work.
（Codex 在做任何工作之前，會先讀 AGENTS.md。）

來源：官方 AGENTS.md 指南

把這句話拆開看，有兩個重點：

1. 它是「持久化」的指令檔。 你寫一次，存進專案，以後每次跑 Codex 它都會自動讀。不是這次對話講完就忘，而是長期生效的「專案慣例」。
2. 它在「動手前」就被讀。 Codex 每跑一次（每個 session 開始時）都會重新建構一次指令鏈（rebuild the instruction chain），把守則讀進去當這次工作的背景知識。你不用手動清快取、不用提醒它「記得看守則」。

那裡面通常放什麼？ 官方與社群常見的內容是這些「工作約定（working agreements）」：

5.2 三層探索順序與「近者覆寫」

這一節是本章最關鍵、也最容易搞混的地方。請慢慢看，搞懂這套規則，你就能自由設計專案的守則層級。

Codex 找守則檔，分成全域和專案兩個範圍（scope），而且有一個非常明確的順序。

全域範圍（你的個人預設）

Codex 先檢查你家目錄下的全域檔，順序是：

1. 先看 ~/.codex/AGENTS.override.md（如果有，優先用它）
2. 沒有的話，才看 ~/.codex/AGENTS.md

官方原話：「Codex checks ~/.codex/AGENTS.override.md first, then ~/.codex/AGENTS.md. Only the first non-empty file at this level is used.」
（這一層只會用「第一個非空的檔」。）

這一層放的是你個人跨所有專案的偏好，例如「回答用繁體中文」「我習慣用 pnpm 不用 npm」。

專案範圍（從 Git 根目錄一路走到你現在的位置）

接著，Codex 從專案根目錄（通常是 Git 根目錄，也就是有 .git 的那一層）開始，一路往下走到你目前所在的工作目錄。沿途每一層資料夾都依序檢查：

1. AGENTS.override.md
2. AGENTS.md
3. project_doc_fallback_filenames 裡設定的備用檔名（預設沒有，5.3 節會講）

這裡有一條官方鐵則，務必記牢：

Codex includes at most one file per directory.
（每一層資料夾，最多只納入一個檔。）

意思是：同一層資料夾如果同時有 AGENTS.override.md 和 AGENTS.md，Codex 只取第一個命中的（override 優先），不會兩個都讀。

串接方向與「近者覆寫」

把沿路收集到的檔湊在一起時，Codex 怎麼排？官方原話：

Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt.

翻成白話：

• 方向：從根目錄往下接合，中間用空行隔開。
• 誰贏：越靠近你目前位置的檔，排在越後面；後面的指令會蓋過前面的。所以衝突時，近者（子目錄）贏。

來看一個實際例子。假設你的專案長這樣，而你現在人在 frontend/ 裡工作：

my-project/            ← Git 根目錄
├── AGENTS.md          ← 「全專案用 TypeScript」
└── frontend/
    └── AGENTS.md      ← 「前端額外：元件用 PascalCase」

Codex 會把兩個檔都讀進來（根目錄的 + frontend/ 的），用空行接起來。如果兩份有衝突，frontend/AGENTS.md 因為排在後面而勝出。

於是，三種檔各自的角色就很清楚了：

5.3 放什麼、32 KiB 上限、相關 config 鍵

守則放對位置之後，還要寫得精簡。這一節講三件事：大小上限、寫作建議、可調的設定鍵。

32 KiB 上限：寫太長後面會被切掉

Codex 把所有層級的守則接合起來時，有一個預設組合上限：32 KiB（由設定鍵 project_doc_max_bytes 控制，預設值 32768 位元組）。行為是：

• 空檔直接跳過（skips empty files）——空的 AGENTS.md 不佔額度也不生效。
• 一旦組合大小達到上限，就停止再加檔（stops adding files once the combined size reaches the limit）。

官方原話：「Codex skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default).」

寫什麼比較有用

新手起步，守則只要回答「Codex 在這個專案最該知道的事」就好。給你一份可以照抄改的範本：

# AGENTS.md

## 開發指令
- 改完 JavaScript / TypeScript 後，一律跑 `npm test`
- 提交前要過 `npm run lint`

## 路徑禁區
- 不要修改 `legacy/` 與 `vendor/` 資料夾

## Commit 規範
- commit 訊息用英文，開頭加類型（feat / fix / docs）

## 慣例
- 元件命名用 PascalCase
- 樣式統一用 Tailwind，不要寫 inline style

相關 config.toml 設定鍵

如果你想微調 AGENTS.md 的行為，以下幾個鍵寫在設定檔（~/.codex/config.toml，詳見第 8 章）。這幾個鍵的名稱與預設值都經過官方文件查核：

一份對應的 config.toml 範例：

# ~/.codex/config.toml

# 把守則組合上限調高到 64 KiB（預設 32768）
project_doc_max_bytes = 65536

# AGENTS.md 不存在時，改找這些檔名
project_doc_fallback_filenames = ["TEAM_GUIDE.md", "CLAUDE.md"]

# 哪些標記代表專案根目錄（預設只有 .git）
project_root_markers = [".git"]

5.4 /init 生成、Memories 差異、驗證生效

最後三招，讓你從零起步、分清兩種「記憶」、確認守則真的生效。

用 /init 自動生成骨架

不知道從何下手？別怕，Codex 內建一個指令幫你生骨架（scaffold）。在 Codex 的互動模式裡輸入：

/init

官方對它的說明是「Generate an AGENTS.md scaffold in the current directory.」——也就是在你當前所在的目錄生出一份 AGENTS.md 草稿。

官方建議的用法很重要：

Run /init in the directory where you want Codex to look for persistent instructions. Review the generated AGENTS.md, then edit it to match your repository conventions.

白話三步驟：

1. 先 cd 到你要放守則的目錄（通常是專案根目錄），再開 Codex。
2. 輸入 /init，讓它生出草稿。
3. 檢查並修改這份草稿，改成符合你專案的真實慣例，然後 commit 進 Git 供未來 session 使用。

Memories 是另一回事，別搞混

你可能會在 Codex 裡看到 /memories 這個指令，以為跟 AGENTS.md 是同一件事。不是。 兩者是不同層、不同機制：

官方對 /memories 的說明是「Configure memory use and generation.」（設定記憶的使用與產生）。注意有「generation（產生）」這個字——代表記憶是由 Codex 自己生的，跟你手寫的守則完全不同。

新手到這裡先有個印象就好；如果你想再多懂一點 Memories 實際怎麼運作，下面補三件事：它怎麼被產生、存在哪裡、跟 AGENTS.md 衝突時聽誰的。

Memories 的產生分成兩階段的背景任務，都是非同步跑、不會擋住你當下的操作：

1. 第一階段：逐 session 摘要。 一個對話「結束且閒置夠久」之後，Codex 才會把那個 session 摘要成記憶素材。閒置門檻官方沒有逐字列出確切小時數，第三方分析報告估計約 6 小時，以你實機觀察到的行為為準。用 --ephemeral（不持久化 session rollout）跑的、或還在進行中的 session，不會被納入。
2. 第二階段：全域彙整。 這一階段序列化執行（同一時間只跑一份），依「使用次數」與「新舊程度」決定哪些記憶留下來，太久沒被用到的舊條目會被過濾掉（第三方報告推估約 30 天，同樣未經官方逐字確認）。彙整完，才把增／留／刪的差異寫回磁碟。

存放位置在 $CODEX_HOME（沒特別設定就是 ~/.codex/）底下的 memories/ 資料夾，長這樣：

~/.codex/memories/
├── MEMORY.md              # 較完整的可查詢知識登記
├── memory_summary.md      # 精簡摘要，主要注入點，依 context 預算截斷
├── raw_memories.md        # 合併後的原始擷取，暫存用
├── rollout_summaries/     # 每個 session 各自的摘要
├── skills/                # 從經驗中學到的可重用程序
└── memories_extensions/   # 外掛／來源專屬輸入

其中 memory_summary.md 是真正每次 session 開始時會被讀進 context 的主要檔案；MEMORY.md 比較像一份「詳細目錄」，官方引導的用法是讓 Codex 用類似 grep 的方式在需要時去查細節，而不是整份塞進 context。這幾個檔都是產生出來的狀態檔，官方建議當成自動生成的結果看待，不建議手動編輯當成主要控制手段——真的要「教」Codex 記住什麼，正常管道是讓它在對話中自然累積，或者乾脆寫進 AGENTS.md。

要開啟這個功能、細調行為，設定寫在 config.toml：

# ~/.codex/config.toml

[features]
memories = true

[memories]
generate_memories = true        # 新 session 要不要納入記憶素材
use_memories = true             # 既有記憶要不要注入未來 session
extract_model = "gpt-5.2-codex"        # 逐 session 摘要用的模型
consolidation_model = "gpt-5.3-codex"  # 全域彙整用的模型

[memories] 底下還有幾個可以細調的鍵，例如 disable_on_external_context（把有用到 MCP、網路搜尋的 task 排除在記憶素材外）和 min_rate_limit_remaining_percent（配額低於某個門檻時就跳過記憶生成，避免記憶功能反過來吃光你的用量）。這幾個鍵的預設值官方未逐字列出，以實機 codex --help 與官方 Memories 說明為準。

互動模式裡的 /memories 除了設定，還能對目前這個 thread（對話）做操作：切換這段對話要不要貢獻記憶素材、檢視目前有哪些記憶被注入這次 session、或強制刷新。確切選單項目請以實機 /memories 畫面為準。

最後回到最重要的一句話：Memories 是輔助回憶層，不是必須遵守之規則的唯一來源。 凡是你希望 Codex 每一次都不能違反的規矩，還是得放進 AGENTS.md 這種進版控、團隊共用的文件；Memories 更適合放「有它更好、沒它也不會出事」的個人化背景，例如它記得你偏好的除錯路數、或上次繞過某個環境陷阱的做法。如果你的場景需要一切決策都能被稽核（例如正式的團隊協作環境），一個穩妥的做法是乾脆把 generate_memories 設回 false，逼自己把所有「該被記住的知識」都走人工審查、進版控的 AGENTS.md，而不是散落在本機、無法稽核的記憶檔裡。

怎麼確認守則「真的被讀到了」

寫好守則，怎麼知道 Codex 有沒有乖乖照辦？官方提供一個簡單的驗證招數——直接問它「現在的指令是什麼」：

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

如果回應裡出現你在 AGENTS.md 寫的內容（例如它複述了「改完 JS 要跑 npm test」），就代表守則確實被讀進去了。

5.5 🎓 高手進階

前面四節讓你把 AGENTS.md 放對、寫對、驗對。這一節給已經上手的你幾件「老手才知道」的事：怎麼寫才不會越寫越爛、三層怎麼分工、這套機制反過來可能被怎麼利用、32 KiB 怎麼省、還有怎麼用環境變數隔離不同人格。心法層的完整推演（為什麼 short > long、reward hacking 怎麼防）會在第 13 章深談，本節先把機制講清楚，讓你立刻能用。

簡潔哲學：short > long，而且「事後才加規則」

先記官方這句最關鍵的話：

A short, accurate AGENTS.md is more useful than a long file full of vague rules. Start with the basics, then add new rules only after you notice repeated mistakes.
（一份簡短、準確的 AGENTS.md，比一份塞滿模糊規則的長檔有用。先寫基本款，只有當你注意到反覆出錯，才補上新規則。）

來源：官方 AGENTS.md 指南

這句話翻成老手心法是兩條：

1. AGENTS.md 不是一次寫滿的「開發聖經」。 一開始就把所有想得到的規則全塞進去，反而害事——規則越多、可以被鑽的字面空間越大，Codex 越容易挑一條對它最省力的合法讀法交差。
2. 規則是「事後長出來」的。 正確姿勢是：先放最基本的（怎麼跑測試、怎麼 commit），然後觀察——當你發現 Codex 反覆犯同一個錯，才針對那個錯加一條規則。沒看到錯就先加的規則，多半是無效的猜測。

三層分工：Global / Repo / Subdir override 各放什麼

5.2 節你已經學會三層的讀取順序（全域 → 根目錄 → 子目錄，近者覆寫）。老手還要知道每一層該放哪一類規則，官方對這三層各有明確定位：

來看一個更貼近真實專案的例子——一個有多個子套件的 monorepo：

repo-root/AGENTS.md          # PR 慣例、安全紅線、分支策略
├── apps/web/AGENTS.md       # Next.js 專屬細節
├── apps/api/AGENTS.md       # FastAPI 專屬細節
├── packages/ui/AGENTS.md    # 設計系統規則
└── infra/AGENTS.md          # Terraform／機密管理規則

在 apps/web/components 底下工作時，依 5.2 節的探索順序，Codex 會沿路吃進 ~/.codex/AGENTS.md（若有）→ repo-root/AGENTS.md → apps/web/AGENTS.md，不會吃到 apps/api、packages/ui 這些旁支目錄的檔案——因為它們不在「根目錄到你目前位置」這條路徑上。這正是「近者覆寫」機制的自然副作用：每個子套件只需要煩惱自己的技術細節，不用擔心被隔壁套件的規則污染，也不用手動排除。 Root 那份只放跨子專案都適用的共通規則（PR 慣例、安全紅線、分支策略），細節下放給各自的子套件，是老手管理大型 repo 的標準分工。

近者覆寫也是攻擊面：小心被污染的 AGENTS.md

「越靠近你目前位置的檔案權重越高」這個機制方便，但反過來想：如果有人能在你的工作目錄裡偷偷塞一份 AGENTS.md，等於直接在你 Codex 的指令鏈裡插話。 這不是憑空想像——NVIDIA 的 AI Red Team 曾經公開一個概念驗證（PoC），並已通報 OpenAI：一個惡意的相依套件，在 build 階段（例如觸發 go mod tidy 這類指令時）偵測到 Codex 的執行環境，動態寫入一份偽造的 AGENTS.md，內容要求 Codex 插入隱藏的惡意程式碼，還在程式碼註解裡進一步指示「摘要模型別提到這處修改」，企圖連 PR 摘要都一起隱瞞。

前提是攻擊者已經能透過惡意套件執行程式碼——OpenAI 官方當時的立場是，這個風險並不比「相依套件本身已經被攻陷」更高，因此沒有針對這個案例額外加防護（此為 PoC 揭露當下的官方立場，後續是否調整以官方公告為準）。對你的實務意義是：

• 對外部、第三方觸碰過的 AGENTS.md 內容，當成不可信輸入看待，尤其是透過 npm install／go mod tidy 這類會執行第三方程式碼的指令帶進來的相依套件。
• 開工前用第 1 章教的 git status / git diff 習慣，順手也掃一眼有沒有非預期出現的 AGENTS.md 或 AGENTS.override.md，尤其是安裝新套件之後。
• 敏感的自動化流程，考慮限制哪些流程／使用者能寫入設定檔案，並監控非預期的檔案差異——這一塊跟第 6 章談的沙箱與核可機制是同一條防線的兩端：一個管「Codex 能碰什麼」，一個管「誰能餵給 Codex 什麼指令」。

偷學 OpenAI 自家的 AGENTS.md：規則「密度」怎麼抓

想知道一份高手級的 AGENTS.md 長怎樣？最好的範本就是 Codex 開發團隊自己用的那一份（放在 openai/codex 的 GitHub repo）。拆解它的寫法，你會看到三個值得抄的習慣：

• 規則用不同「強度」表述，不是每條都喊「絕對禁止」。 有絕對指令（「Never…」永遠不要）、有偏好（「Prefer X over Y when…」優先用 X）、也有帶例外的（「Do not… Exception: …」原則上不要，除了某情況）。強弱分明，Codex 才知道哪些是紅線、哪些是傾向。
• 粒度從「微觀」到「宏觀」並存。 既有很細的程式風格（例如「字串格式化的參數一律寫成 inline」），也有架構級的方向（例如「克制把程式碼往核心模組塞」），還有流程（例如「改完自動跑格式化」）。
• 多數規則都附「為什麼」與「可驗門檻」。 重點來了：它不寫「檔案不要太大」這種模糊話，而是給數字——「Rust 模組目標控制在 500 行以下（不含測試）」「檔案超過大約 800 行就考慮拆分」。

32 KiB 撞上限了？拆檔或調高，別硬塞

5.3 節提過 32 KiB 上限會「達標即停止加檔」。老手遇到守則確實寫不下時，官方給兩條正解（別硬塞成一坨）：

1. 拆檔到巢狀子目錄（split large files across nested directories）：把冷門、只在特定子目錄才需要的規則，下放到該子目錄的 AGENTS.md。這樣它只在你工作路徑經過那層時才載入，不佔用全域額度。
2. 調高位元組上限：在 config.toml 把 project_doc_max_bytes 設大（見 5.3 範例）。

老手的取捨原則：重要、通用的規則放會先被讀到的層（全域 / 根目錄）；冷門、局部的規則下放子目錄。 這樣既不會撞上限，也讓最關鍵的守則一定載入得到。

自訂指令檔：model_instructions_file 與 project_doc_fallback_filenames 再看一眼

這兩個鍵 5.3 節已經出現，這裡補老手的用法分界：

• project_doc_fallback_filenames（沿用既有檔名）： 你有一份既存的 TEAM_GUIDE.md 或 CLAUDE.md，不想改檔名，就把它加進這個清單——Codex 找不到 AGENTS.md 時會改讀它。本體還是走正常的 AGENTS.md 三層發現流程，只是換個檔名認。
• model_instructions_file（完全接管）： 這個更重——它讓 Codex 完全取代內建指令發現流程，不再走 AGENTS.md 那套三層串接，改用你指定的那一個檔當整份指令。用在你要精準控制整個 system prompt、不想要任何自動串接行為的場景。

老手工具：用 CODEX_HOME 隔離不同的守則人格

目前為止談的都是同一個 ~/.codex/ 底下的探索規則。但如果你想徹底隔開兩套環境——例如「工作用的守則與記憶」跟「個人練習用的守則與記憶」互不干擾，或是想乾淨測試某組 config.toml 設定會不會撞到既有習慣——有一個更狠的招數：整個換掉 Codex 的家目錄。

# 用當前資料夾底下的 .codex/ 當這次執行的家目錄，不去動平常的 ~/.codex/
CODEX_HOME=$(pwd)/.codex codex exec "..."

CODEX_HOME 這個環境變數決定 Codex 去哪裡找全域 AGENTS.md、config.toml、memories/ 這一整包東西。指定成專案資料夾底下的 .codex/，就等於幫這次執行套上一個全新、乾淨的「人格」，跑完也不會汙染你平常用的全域設定。適合拿來做「這條新規則會不會有副作用」的隔離測試，或是同一台機器要分飾工作／個人兩種身分時使用。

驗證守則「真的生效」（老手版）

5.4 節給過驗證指令，這裡講它的進階用法。官方的驗證招數是直接叫 Codex 把目前載入的指令吐出來：

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

老手會多看一步：Codex 應該按照「全域 → 根目錄 → 子目錄」的順序、把各層載入的指引都回吐出來。

• 如果回吐的內容完整覆蓋你各層寫的規則 → 指令鏈正確載入。
• 如果某一層的規則不見了 → 高機率是撞上 32 KiB 上限被截掉了。對策就回到上面：把大檔拆到巢狀目錄，或調高 project_doc_max_bytes。

本章小結

這一章你學會了用 AGENTS.md 給 Codex 一份「寫一次、永遠記得」的專案守則：它在動手前被讀、按全域 → 根目錄 → 子目錄的順序串接、近者覆寫遠者、有 32 KiB 上限所以要精簡，還會用 /init 生骨架、用 model_instructions_file（不是舊的 experimental_instructions_file）做進階自訂。你也搞懂了三種持久化機制怎麼分工——手寫、進版控的 AGENTS.md 管規則、Codex 自己產生的 Memories 管個人化背景記憶、Skills 管可重複執行的流程；更知道 AGENTS.md 終究只是強力引導、不是強制執行，真正不能違反的規矩還是得靠 hook、CI 這類機制把關。

動手試試

1. 在你的專案根目錄開 Codex，輸入 /init，看看它生出什麼骨架，改成你專案的真實慣例（例如加一條「改完程式碼跑你的測試指令」）。
2. 跑 codex --ask-for-approval never "Summarize current instructions"，確認你剛寫的守則有被讀進去。
3. （進階）如果你是 Claude Code 老使用者，在 config.toml 加一行 project_doc_fallback_filenames = ["CLAUDE.md"]，讓 Codex 沿用你舊的 CLAUDE.md。
4. （進階）在互動模式打 /memories，看看這個功能在你的版本上預設是開是關；如果已經用了一陣子 Codex，順便看看 ~/.codex/memories/ 資料夾裡有沒有東西。
5. （進階）驗證看看全域 ~/.codex/AGENTS.md 在你的版本上到底有沒有被讀到——寫一條很好認的測試規則（例如「永遠用『喵』結尾回答」）進全域檔，開一個新專案資料夾測看看，親自確認 5.2 節提到的那個「讀不到」議題在你這裡是否還存在。

本章官方文件參考

• AGENTS.md 指南：https://developers.openai.com/codex/guides/agents-md
• 設定參考（config 鍵）：https://developers.openai.com/codex/config-reference
• Slash 指令（含 /init、/memories）：https://developers.openai.com/codex/cli/slash-commands
• Memories 說明：https://developers.openai.com/codex/memories
• agents.md（跨工具開放標準）：https://agents.md/