我自行開發了一款免費應用程式,歡迎試用。當你開始使用兩個 AI 程式碼代理時,你會發現自己有兩個指令檔。Claude Code 讀取 CLAUDE.md,而 Codex 則讀取 AGENTS.md。
一旦你同時維護這兩個檔案,它們就會開始產生差異。本文將介紹一種配置方式,讓所有路徑都指向同一個原始檔案,並說明如何在該檔案中為每個代理進行區分。
當同時使用 Claude Code 和 Codex 等多個 AI 程式碼代理時,維護各自的指令檔容易導致內容分歧。本文提出一種解決方案,透過讓所有代理指向單一原始指令檔,有效避免重複與不一致。文章詳細說明了如何利用工具的引入功能或符號連結來實現統一管理,並探討如何在單一檔案中處理不同代理的語法和能力差異。

我自行開發了一款免費應用程式,歡迎試用。當你開始使用兩個 AI 程式碼代理時,你會發現自己有兩個指令檔。Claude Code 讀取 CLAUDE.md,而 Codex 則讀取 AGENTS.md。
一旦你同時維護這兩個檔案,它們就會開始產生差異。本文將介紹一種配置方式,讓所有路徑都指向同一個原始檔案,並說明如何在該檔案中為每個代理進行區分。
最簡單的解決方法是複製檔案。複製當天,兩個檔案內容完全相同,但問題出在你只編輯其中一個檔案的那一天。通常,你會在代理違反規則後才注意到不一致。屆時,也很難判斷哪個版本才是最新的。
我檢查了自己的家目錄,發現兩個路徑下的指令檔具有相同的 MD5 值。它們是獨立的檔案,而非連結。這表示我一直手動保持它們同步,而下一次單方面編輯就會導致它們分歧。
檔案本身寫著「如果兩者不相同,之後將透過 Git 合併」,這句話正說明了基於複製的管理方式所付出的代價。核心原則只有一個:保留一個原始檔案,並讓所有其他路徑都指向它。整個工作的關鍵在於每個工具指向的方式有所不同。
這兩個工具讀取檔案的方式並不對稱。Claude Code 支援從其內部引入另一個檔案,而 Codex 則無法,它會擴展其讀取檔案名稱的列表。因此,如果你是從頭開始,請將 AGENTS.md 作為原始檔案。
支援引入的工具可以透過一行指令來跟隨。例如,在 CLAUDE.md 中加入 @AGENTS.md,然後在下方加上「## Claude Code only - Everything from here is read by Claude alone.」這樣 CLAUDE.md 就只剩下這兩行。
如此一來,共享指令就存在於 AGENTS.md 這一個地方。你可以在引入指令下方繼續撰寫僅限 Claude 的內容,這也是它與符號連結(symlink)的區別。
如果你的原始設定已經是 CLAUDE.md,那麼就改動 Codex 的設定。在 ~/.codex/config.toml 中加入一行:project_doc_fallback_filenames = [ "CLAUDE.md" ]。
Codex 每個目錄只會選擇一個檔案。它會依序尋找 AGENTS.override.md、AGENTS.md,然後是備用檔案,並使用找到的第一個。因此,在一個旁邊有 AGENTS.md 的目錄中,CLAUDE.md 將不會被讀取。
不要將兩個檔案放在同一個資料夾中,並期望兩者都會被讀取。同一個位置的 AGENTS.override.md 會暫時覆寫該目錄的指令,但原始檔案不會被刪除。當你希望在不同規則下運行一個專案一段時間時,原始檔案保持不變。
第三種選擇是使用符號連結(symlink)。它可以在檔案系統層面解決問題,而無需修改任何工具的配置。你可以使用指令 ln -s AGENTS.md CLAUDE.md 來建立。
在 Windows 上,建立符號連結需要管理員權限或開發者模式。Claude Code 自己的文件建議在 Windows 上使用 @AGENTS.md 引入方式,而非符號連結。
Git 會以 mode 120000 儲存符號連結,因此你可以提交連結本身。然而,更簡潔的做法是只將原始檔案放入儲存庫,並讓每台機器自行建立連結。
一旦配置完成,一個檔案將被兩個模型讀取。該檔案本身並不會告知讀取者是哪個模型正在讀取它。因此,請在檔案的最頂端明確說明這一點。
例如:「- 此檔案被 Claude Code 讀取為 CLAUDE.md,並被 Codex 讀取為 AGENTS.md。如果你是 Codex,請將此文件中的任何 /xxxx 技能調用讀取為 $xxxx,因為在 Codex CLI 輸入中,/xxxx 會首先被視為斜線指令。」
這兩行將成為後續所有條件判斷的前提。模型知道自己是哪個工具,因此像「如果你是 Codex」這樣的條件判斷確實有效。工具名稱或調用語法上的差異,只需一行條件判斷即可解決。
對於能力而非語法上的差異,無法透過條件判斷來處理。例如,當一個子代理在任務執行中發現指令矛盾時如何停止,就是其中一種情況。
Claude 子代理與主會話之間有即時的雙向通道,因此它可以當場提出詢問。而 Codex 子代理是無頭(headless)且一次性的,因此沒有這樣的通道。在相同情況下,它們採取的行動截然不同。
如果將規則寫兩次,則會分散觸發條件。解決方法是將判斷標準放在共享區塊,而具體執行方式則放在各工具專屬區塊。
將觸發條件列表複製到每個工具專屬區塊中,之後其中一個可能會單獨更新。這會將你原本避免的重複問題帶回檔案內部。
一旦工具專屬區塊超過三個,該項目可能就是工具差異,而非指令本身。此時,最好調整你使用一個工具的方式以配合另一個工具,而不是繼續擴展文件。
不要複製指令檔。保留一個原始檔案,並讓其他所有檔案都指向它。支援引入功能的 Claude Code 是負責連結的一方。
將 AGENTS.md 作為原始檔案,而 CLAUDE.md 則只包含一行 @AGENTS.md。如果原始檔案已經是 CLAUDE.md,則透過 Codex 的 project_doc_fallback_filenames 來匹配。
在單一檔案內部,語法差異可透過條件判斷處理,而能力差異則使用共享規則加上各工具專屬區塊。如果你更改了配置,請在最後確認載入情況。
在 Claude Code 中,於會話中執行 /context 並檢查檔案是否出現在「Memory files」列表中。連結已存在但檔案未被讀取是最常見的失敗情況。
覺得值得一看?分享給朋友。
以上為 AI 自動翻譯導讀。原文版權歸 DEV Community (Claude Code) 所有, 建議透過「閱讀原文」前往原始網站,以取得最完整資訊並支持原作者。
43 個來源、每 2 小時更新,太多看不完。電子報每週挑最值得看的幾則,附上 Max 的看法。