OpenAI Codex CLI：AGENTS.md 代理指令範本與運作解析

OpenAI Codex 在執行任何任務之前都會先讀取 AGENTS.md 檔案。這個檔案包含了 Codex CLI 代理的專案指令，例如技術堆疊、可用指令、嚴格禁止事項以及「完成」的定義。簡短且具體的檔案會被確實遵循，而冗長的內容則容易被忽略。

本指南提供一個可立即使用的 Codex AGENTS.md 範本，並解釋 Codex 實際如何發現這些檔案，以及它與 CLAUDE.md 和 Cursor 規則的差異。Codex 會在每次執行時（在 TUI 中，則為每個會話）建立一個指令鏈。

全域指令會先讀取：如果存在，則為 ~/.codex/AGENTS.override.md，否則為 ~/.codex/AGENTS.md。這些是個人預設值，而非專案規則。專案指令則從專案根目錄（通常是 Git 根目錄）向下到目前工作目錄，每個目錄中，它會優先選擇 AGENTS.override.md，然後是 AGENTS.md，每個目錄最多一個檔案。

檔案會從根目錄到目前工作目錄依序串聯合併。越接近工作目錄的檔案會越晚出現，因此它們會覆寫較廣泛的指導原則。空檔案會被跳過。預設情況下，合併後的專案指令總大小上限約為 32 KiB（project_doc_max_bytes）。建議根目錄檔案保持簡短，將專業規則放在巢狀目錄中，而不是一個巨大的 README 檔案。

官方發現說明指出，自訂指令是透過 AGENTS.md 實現的。Codex 不會讀取 CLAUDE.md 或 .cursor/rules/*.mdc。如果這些是您唯一的指令檔案，Codex 將會進行猜測。

您可以將以下範本貼到專案根目錄作為 AGENTS.md 檔案，並填寫所有 <<FILL>> 部分。Codex 的 /init 指令可以生成一個入門範本，您可以同樣方式編輯它，因為精確的指令勝過模糊的感覺。

AGENTS.md

<!-- OpenAI Codex CLI 代理指令。請填寫所有 <<FILL>>。 -->

專案

• 應用程式：<<FILL: 名稱和一行目的>>
• 技術堆疊：<<FILL: 例如 Next.js 15 App Router, Supabase, Stripe, pnpm>>
• 版面配置：<<FILL: 例如 app/, lib/, tests, 和生成的類型檔案在哪裡>>

指令

• 開發：<<FILL: 例如 pnpm dev>>
• 測試：<<FILL>>
• Lint：<<FILL>>
• 型別檢查：<<FILL>>

硬性規定

• 絕不列印、記錄或提交機密資訊。絕不將機密資訊加上 NEXT_PUBLIC_ 前綴。
• 絕不為通過測試而禁用測試、型別檢查、RLS 或其他安全檢查。
• 保持差異檔案（diffs）小巧。絕不手動編輯生成的檔案。
• 對於身份驗證、支付或資料庫遷移：請撰寫簡短計畫並等待核准。

工作流程

1. 用一行話重述目標，並列出您將會修改的檔案。

2. 進行一個小改動，然後執行您列出的測試/型別檢查。

3. 報告您驗證了什麼，以及無法驗證什麼。

完成的定義

上述指令都通過，變更以簡潔的文字描述，且您沒有擴大範圍。當代理將呼叫工具或讀取不受信任的內容時，請從免費的 agent-guardrails.md (MIT 授權) 貼上安全部分。對於 Next.js + Supabase 專案，免費的 nextjs-supabase-rls.mdc 是一個 Cursor 格式的規則；請將其要點複製到 AGENTS.md（或巢狀的 supabase/AGENTS.md）中，以便 Codex 也能看到。

以下是 AGENTS.md 與 CLAUDE.md 和 Cursor 規則的差異比較：AGENTS.md 是由 OpenAI Codex CLI、Cursor 和其他支援 AGENTS.md 的工具讀取，採用純 Markdown 格式，巢狀檔案會從根目錄到目前工作目錄串聯。它作為共享的真相來源，定義技術堆疊、指令、禁止事項和完成標準。

CLAUDE.md 則是由 Claude Code 讀取，也是 Markdown 格式，可以透過 @path 導入檔案。它通常是一個簡潔的檔案，以 @AGENTS.md 開頭，然後是僅限 Claude 的註記。.cursor/rules/*.mdc 是由 Cursor 讀取，採用 Markdown 加上 YAML 前置碼（包含 globs 和 alwaysApply），用於路徑範圍的規則，只有當匹配的檔案在上下文中時才會載入。

建議的佈局是：首先撰寫 AGENTS.md，讓 Codex 擁有指令。然後添加一行 CLAUDE.md 來導入它。最後，為身份驗證、RLS 或 Stripe 等功能添加範圍化的 Cursor .mdc 檔案，避免將所有內容都貼到每種格式中。

完整的比較請參考：AGENTS.md vs CLAUDE.md vs Cursor rules。Claude 專用的範本請參考：CLAUDE.md template。

當子目錄有不同的指令或禁止事項時，可以在該目錄中放置第二個 AGENTS.md 檔案。Codex 從該目錄執行時，會先載入根目錄檔案，然後是巢狀檔案。如果您需要替換目錄中的檔案而不刪除它，可以在該資料夾中使用 AGENTS.override.md，Codex 將會使用這個覆寫檔案並忽略同級的 AGENTS.md。

以下是佈局草圖：

repo/

AGENTS.md # 共享的真相來源 (Codex + 其他工具)

CLAUDE.md # @AGENTS.md + 僅限 Claude 的註記

.cursor/rules/ # 僅限 Cursor，路徑範圍的規則

services/payments/

AGENTS.md # 支付相關指令和禁止事項

所有這些免費檔案（MIT 授權）都可以在公開的 eli-alvarado/agentkit-drawer 儲存庫中找到，包括：agent-guardrails.md（防注入、詢問與執行、不確定性處理）、nextjs-supabase-rls.mdc（可鏡像到 AGENTS.md 的 RLS 要點）、godot-jam-timeline.md 和 agents-md-game-modding.md（遊戲相關的 AGENTS.md 入門範本）。

常見問題：OpenAI Codex 讀取哪個檔案？Codex CLI 在開始工作前會讀取 AGENTS.md（如果存在，也會讀取 AGENTS.override.md）。個人預設值可以放在 ~/.codex/AGENTS.md。它不讀取 CLAUDE.md 或 Cursor .mdc 規則。

Codex 會讀取 CLAUDE.md 或 .cursor/rules 嗎？不會。請將共享規則放在 AGENTS.md 中。使用 @AGENTS.md 將 Claude Code 指向該檔案。將 Cursor 路徑規則放在 .cursor/rules/*.mdc 中。

Codex AGENTS.md 範本應該放在哪裡？放在專案根目錄，與您的鎖定檔案（lockfile）並列。巢狀的 AGENTS.md 檔案會針對子目錄精煉根目錄檔案的指令。Codex 會從 Git 根目錄向下到工作目錄串聯這些檔案。

AGENTS.override.md 是什麼？在給定目錄中，它會優先於 AGENTS.md。當您需要進行本地或臨時覆寫，而不想刪除共享檔案時，可以使用它。Codex 每個目錄仍然只讀取一個指令檔案。

這與 Cursor 規則有何不同？AGENTS.md 是無範圍的純 Markdown 檔案。Cursor .mdc 檔案則添加了前置碼，因此只有當匹配的路徑在上下文中時，規則才會載入。共享的事實應放在 AGENTS.md 中；路徑範圍的額外內容則應放在 Cursor 規則中。

想要整個工具包嗎？Vibe Starter Rules Pack（19 美元）包含一組現成的 AGENTS.md + CLAUDE.md、8 個範圍化的 Cursor 規則、12 個斜線指令提示詞，以及 Next.js + Supabase + Stripe 的啟動清單，這些都是 Codex 實際讀取的檔案，以及工具特定的額外內容。

Agent Builder Prompt Pack（29 美元）則是適用於 Codex 級代理的系統提示詞和評估套件。

購買 Vibe Starter（19 美元），購買 Agent Builder（29 美元）。如果還不需要完整套件，可以從 One-File Agent Rules（9 美元）開始，這是一個適用於任何技術堆疊的通用 AGENTS.md，或者透過電子郵件獲取免費的 Starter AGENTS.md。

發布週期間，使用 Stripe 結帳代碼 LAUNCH 可享任何套件 7 折優惠，活動至 2026 年 10 月 28 日止。14 天退款保證。原文發布於 agentkitdrawer.com。