同一個 repo 兩個 agent：Codex 讀 AGENTS.md，Claude Code 不讀

先問你一個問題：你在 repo 根目錄放了一份 AGENTS.md，寫了專案的建置指令、程式碼風格、測試規範。你手上兩個 agent 都會讀到它嗎？

如果你的答案是「應該會吧，那是開放標準」，這篇後面幾段對你有用。

第一個判準：檔名。而這一題沒有模糊空間

Anthropic 官方文件寫得很白：

Claude Code reads CLAUDE.md, not AGENTS.md.

不是「優先讀 CLAUDE.md」，是不讀。

我一開始不太相信，所以去查了 agents.md 官方頁面的支援工具清單。那份清單有 23 個工具：Codex、Jules、Factory、Aider、goose、opencode、Zed、Warp、VS Code、Devin、Junie、Amp、Cursor、RooCode、Gemini CLI、Kilo Code、Semgrep、GitHub Copilot 的 coding agent、Windsurf、Augment Code 等等。

Claude Code 不在裡面。

派去查證的 agent 不放心 WebFetch 的摘要可能漏抄，直接把原始 HTML 抓下來 grep：整份 81,690 bytes 裡，claude 這個字串出現 0 次，而且是 grep -i 不分大小寫比對出來的 0。

三個獨立來源指向同一件事：Anthropic 官方明文說不讀、對方的支援清單沒有它、對方的網頁原始碼裡連提都沒提。

這個坑的殺傷力在於它是靜默的。你把規範寫進 AGENTS.md，Claude Code 不會報錯、不會警告，只是完全照它自己的方式做事，而你以為它讀過了。

官方給的兩個解法，照抄就能用

Anthropic 自己在文件裡給了解法，兩種：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

CLAUDE.md 第一行用 @ 把 AGENTS.md import 進來，下面接 Claude 專屬的補充。這是官方原文的範例。

或者更直接：

1	ln -s AGENTS.md CLAUDE.md

一個 symlink 解決。官方附註提醒這行指令成功時不會有任何輸出，要驗證的話下次開 session 跑 /context，看 CLAUDE.md 有沒有出現在 Memory files 底下。

兩個怎麼選？要加 Claude 專屬段落就用 import；Windows 上建 symlink 需要管理員權限或開發者模式，跨平台的團隊直接選 import 省事。

順帶一個很細但好用的點：/init 預設不會讀 AGENTS.md。官方原文說要設 CLAUDE_CODE_NEW_INIT=1，它才會連 AGENTS.md、.devin/rules/、.windsurf/rules/、.clinerules 一起讀進來生成 CLAUDE.md。預設只讀 Cursor 跟 Copilot 的規則檔。

第二個判準：檔案有多肥

這一題兩邊的行為差很多，而且差在「超標之後會怎樣」。

Codex 的官方說明：

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).

注意動詞是 stops adding files，不是截斷檔案內容。累計超過 32 KiB，後面的檔案整份不再納入。

Claude Code 那邊：

CLAUDE.md files are loaded in full regardless of length, though shorter files produce better adherence.

官方確實建議每份控制在 200 行以內，但那是為了讓模型更聽話的建議，不是硬上限，不會截斷。

為什麼 Codex 這個特別會咬人？因為它的合併順序是從 root 往下依序累加。超標時被丟掉的是最後才輪到的那幾份，也就是離你當前目錄最近、最專屬的那幾份。假設你 cd 到 packages/billing/ 才啟動 Codex，這條路徑上每一層都會依序納入，而路徑末端那份最貼身的規範正好是最先被犧牲的。一樣沒有任何提示。

（要是你根本沒 cd 進去，那份規範連被犧牲的機會都沒有，因為它壓根不在掃描路徑上。那是另一個坑，下一節講。）

第三個判準：它從哪裡開始找

這一題我覺得最容易被忽略，因為兩邊的心智模型長得很像，實際起點卻不同。

Codex：專案層是「從 Git root 往下走到當前工作目錄」，路徑上每個目錄最多取一份檔案。
Claude Code：「walking up the directory tree from your current working directory」，內容排序是從檔案系統 root 往下到工作目錄。

差別在哪？假設你的目錄長這樣：

1 2	~/work/CLAUDE.md ← 共用規範放在 repo 的上一層 ~/work/myrepo/ ← git repo 在這裡

Claude Code 一路往上走，讀得到 ~/work/CLAUDE.md。Codex 的專案層從 git root 起算，~/work/ 在 git root 之外，讀不到，只有 ~/.codex/AGENTS.md 那個全域層會生效。

多 repo 的 workspace 特別容易中這個。共用規範放在外層目錄，一邊吃得到一邊吃不到。

monorepo 也有類似的落差。Codex 只掃 git root 到 cwd 這一條路徑，你在 repo 根目錄啟動它，packages/foo/AGENTS.md 不在那條路徑上，不會被載入。agents.md 官網說「agents automatically read the nearest file in the directory tree」，這句話對 Codex 成立的前提是你先 cd 進那個子目錄再啟動。

Claude Code 這邊子目錄的 CLAUDE.md 會在它實際去讀那個目錄的檔案時才載入，是 on demand 的。

第四個判準：override 跟 local 的語意剛好相反

這一組最陰險，因為名字看起來都像「補充」。

	Codex `AGENTS.override.md`	Claude Code `CLAUDE.local.md`
語意	取代同目錄的 `AGENTS.md`	附加在 `CLAUDE.md` 後面
官方原文	at most one file per directory；只取第一個非空檔	在每個目錄內，`CLAUDE.local.md` appended after `CLAUDE.md`

從 Claude Code 的習慣過去，你會以為 AGENTS.override.md 是「我再補幾條」，結果它把整份 AGENTS.md 換掉了，原本的規範全部消失。

還有一個不對稱：@path import 這個機制目前只有 Claude Code 那邊有官方說明（最多遞迴四層）。截至 2026-08-07，Codex 官方的 AGENTS.md 說明頁與 config reference 都沒有提到 import 或 @path 機制。這裡的措辭要小心，文件沒寫不等於不存在，我只能說沒查到。

但這個不對稱有個實務後果：Claude Code 那招 @AGENTS.md 之所以成立，正是因為它有 import。反過來要 Codex 去 include CLAUDE.md，官方沒有對應機制。

所以方向性很清楚：規範本體寫在 AGENTS.md，CLAUDE.md 當轉接頭，不是反過來。

這個判斷還有另一個理由。agents.md 首頁現在寫著：

AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation.

它已經不只是某一家提出來的格式，而是移交給中立基金會治理的標準。押這一邊比較不會被單一廠商的方向改變綁架。（基金會的成員名單、Anthropic 有沒有加入，我沒有查，這裡只引用 agents.md 首頁那一句。）

分工：寫的人不能當驗收的人

設定檔講完了，來講為什麼要同時養兩個。

codex review 是 Codex CLI 的內建子指令，不需要裝任何外掛。它用三個互斥的旗標決定審什麼：

1
2
3

codex review --uncommitted        # 審 staged、unstaged、untracked 的改動
codex review --base main          # 審整條分支對 base 的總 diff
codex review --commit a1b2c3d     # 審某一顆 commit 帶進來的改動

這三個旗標剛好對上另一個 agent 產出的三個時間點：剛寫完還沒 commit、整條分支要合併前、事後回頭補審。

[PROMPT] 參數可以帶自訂的審查重點，而且官方說明寫著 - 可以從 stdin 讀：

1	codex review --uncommitted "只看併發安全與 SQL injection，不要評論命名風格"

我自己的用法是拿 Codex 做開發，也拿它審 Claude Code 的產出。這條分工線的說服力不在「哪個模型比較強」，在於跨廠商等於真正的 fresh context：同一個模型自我審查會繼承自己的假設，換一家的模型來審，連 tokenizer 跟訓練資料都不一樣。

權限模型：一個是兩維，一個是一維

要拿 Codex 當審查員，權限得設對，不然它會邊審邊改。

Codex 這邊是兩個獨立維度：

sandbox_mode：read-only、workspace-write、danger-full-access（三個值，CLI 的 possible values 與官方文件兩處一致）
approval_policy：untrusted、on-request、never

「能做什麼」跟「什麼時候問你」是分開的，可以自由組合。純審查場景就是唯讀加上不要問我：

1	codex review --uncommitted -c sandbox_mode="read-only" -c approval_policy="never"

Claude Code 那邊是一個維度，defaultMode 一個列舉把兩件事綁在一起。截至 2026-08-07 官方表格是六個值：default、acceptEdits、plan、auto、dontAsk、bypassPermissions。

這裡要特別提醒一下：不少既有文章（包括我自己早期寫的）只列四個，漏掉 auto 跟 dontAsk。這種列舉最容易憑印象抄舊的，查官方表格最快。

想在 Claude Code 做到「純唯讀探索」最接近的是 plan 模式，但它同時改變了 Claude 的行為（會產出計畫），不是單純的權限開關。Codex 那個兩維設計在這個場景確實比較乾淨。

Claude Code 自己那套 sandbox 怎麼設定，我之前寫過一篇完整教學，這裡不重複。

一個只有兩個都用才會遇到的問題

最後這個坑，官方文件不會寫，因為它不屬於任何一邊。

我在跑 Codex 的那套 skill 包裝裡，每次呼叫都會強制前置一段話，大意是：不要讀 ~/.claude/、.claude/skills/、agents/ 底下的任何檔案，那些是另一個 AI 系統的技能定義，裡面全是 bash 腳本跟 prompt 模板，讀了只是浪費你的時間。

為什麼需要這句？因為兩個 agent 住在同一個 repo，對方的設定檔在檔案系統上就是普通的 markdown 跟 shell script。Codex 掃到 .claude/skills/ 底下幾百行的 prompt 模板，它不知道那是別的 AI 的指令，只會當成專案的一部分讀進去、推理、燒 token。

反過來也一樣。你在 repo 裡放的 Codex 設定，對 Claude Code 來說也只是一堆文字。

這是雙 agent 環境的獨有稅金，而且會隨著兩邊的設定檔越長越明顯。目前我能做的就是在 prompt 層面畫邊界。

所以規範到底寫在哪

給一個不騎牆的答案。

**規範本體寫在 AGENTS.md**，因為那是 Linux Foundation 底下的標準、官方清單上有 23 個工具宣稱支援（各家的行為細節不保證一致，前面 Codex 那幾個坑就是例子），而且 Codex 那邊我沒查到能反向引用 CLAUDE.md 的機制。寫的時候盯著 32 KiB 這個數字，別讓它肥到把子目錄的規範擠掉。

CLAUDE.md 只當轉接頭：不需要 Claude 專屬內容就 ln -s AGENTS.md CLAUDE.md；需要就寫 @AGENTS.md 再往下接專屬段落，跨 Windows 團隊直接選後者。

改完一定要驗，別相信「應該有載入」。Claude Code 這邊跑 /context 看 Memory files 有沒有 CLAUDE.md。Codex 那邊我沒找到等價的檢查指令，codex doctor 的官方說明是診斷安裝、設定、認證與執行環境健康度，沒提到列出已載入的指示檔，我也沒實跑確認過。

最後補一句這篇的邊界：上面所有指令與參數，來自本機實跑 codex --help 與 codex review --help（版本 codex-cli 0.144.5，官方最新已到 0.147.0，兩者差異我沒有比對），以及兩邊的官方文件，查詢日 2026-08-07。文章裡列的這些指令組合我沒有為了寫這篇逐一重跑驗證，所以不描述 codex review 的輸出格式長什麼樣。權限那組 -c 覆寫的組合是照官方欄位名拼出來的，官方文件沒有這個範例。

真正想留給你的判準只有一句：當兩個工具宣稱支援同一份「標準」時，先去對方的官方清單裡找自己的名字。 找不到，那份標準對你就不存在，不管它多開放。

參考來源