深入解析 AI 程式代理：指令檔大小限制與最佳實踐

每個程式代理都會讀取指令檔，但很少人會檢查實際讀取了多少內容。我們查閱了七款代理的說明文件和原始碼，以了解它們的讀取上限以及如何處理超出限制的內容。

簡而言之：沒有統一的限制。Codex 合併後的 AGENTS.md 總大小限制為 32 KiB，並會默默地截斷其餘部分，從最深層的檔案開始。Claude Code 會載入最高 4 MiB 的 CLAUDE.md 檔案，超過此大小則會跳過整個檔案，但建議保持在 200 行以下。

Windsurf 的規則檔案上限為 12,000 個字元。Cursor、Copilot、Gemini CLI 和 OpenCode 則沒有設定硬性上限。

以下是各代理的限制概覽：Codex CLI 的合併檔案上限為 32 KiB，會截斷最深層的檔案並發出警告。Claude Code 的 CLAUDE.md 檔案上限為 4 MiB，超過則跳過整個檔案，建議在 200 行以下。Windsurf 的規則檔案上限為 12,000 個字元。

Cursor、GitHub Copilot、Gemini CLI 和 OpenCode 則沒有硬性上限，但有建議的行數限制。

您可以花五分鐘檢查自己的檔案。對於 Codex，請在專案根目錄到工作目錄的每個 AGENTS.md 檔案上執行 wc -c 指令，如果總和超過 32,768 位元組，最深層的檔案就會被截斷。在 Claude Code 中，執行 /memory 指令可查看載入了哪些指令檔，並留意啟動時或 /status 中的長度警告。

如果您同時使用 CLAUDE.md 和 AGENTS.md，請檢查每個代理實際讀取了哪一個：Claude Code 在路徑中存在 CLAUDE.md 時會忽略 AGENTS.md，而 OpenCode 在 AGENTS.md 存在時會忽略 CLAUDE.md。

在 Gemini CLI 中，執行 /memory show；如果您依賴 AGENTS.md，請將其新增到 context.fileName。在 VS Code 中使用 Copilot 時，如果您的 AGENTS.md 檔案位於子資料夾中，請啟用 chat.useNestedAgentsMdFiles 設定。將任何僅適用於特定資料夾的內容從根檔案中移出，並放置在該資料夾旁邊。

指令檔感覺就像設定檔：您寫一次，然後假設代理已經讀取了它。但它不是設定檔。它是一段必須符合某處的文字，每個代理都自行決定能容納多少，以及超出部分如何處理。我們查閱了七款程式代理的說明文件，並在文件模糊不清時查閱了原始碼，這些代理包括 Claude Code、Codex CLI、Cursor、GitHub Copilot、Gemini CLI、Windsurf 和 OpenCode。

以下所有資訊均於 2026 年 10 月 20 日檢查，這些數字可能會隨版本更新而變化，因此每個數據都附有來源連結。

Codex：32 KiB，最具體的檔案反而被截斷。Codex 的限制是大多數人會實際遇到的唯一限制。它會從專案根目錄向下遍歷到您的工作目錄，每個資料夾最多讀取一個 AGENTS.md 檔案，然後將它們串聯起來。Codex 的 AGENTS.md 指南指出，一旦合併大小達到 project_doc_max_bytes（預設為 32 KiB），它就會停止新增檔案。

指南沒有詳細說明的是，當達到邊界時會發生什麼。在 agents_md.rs 中，超出預算限制的檔案會被截斷，唯一的提示是日誌警告。由於預算是從根目錄向下消耗的，因此被截斷的檔案是最深層的檔案：也就是最接近您正在更改的程式碼的資料夾特定指令。

還有兩個細節很重要：Codex 完全不會載入工作目錄以下的 AGENTS.md 檔案；它的基本指令會告訴模型在該處工作時尋找它們。除非您將 CLAUDE.md 列在 project_doc_fallback_filenames 中，否則它永遠不會讀取 CLAUDE.md。

您可以在 config.toml 中提高限制；文件本身的範例是 project_doc_max_bytes = 65536。

Claude Code：4 MiB，全有或全無，AGENTS.md 僅作為備用。Claude Code 的硬性限制非常寬鬆。其記憶體文件指出，它會完整載入最高 4 MiB 的 CLAUDE.md 檔案，並跳過更大的檔案。請注意「跳過」這個詞：超過限制的檔案不會被修剪，而是完全消失。

您應該關注的限制是建議的限制：每個 CLAUDE.md 檔案應少於 200 行，因為較長的檔案會消耗更多上下文並降低遵循度。當檔案超過建議長度時，Claude Code 會在啟動時發出警告。

經常被引用的 200 行或 25KB 數字是真實的，但它屬於自動記憶體 MEMORY.md 索引，而不是 CLAUDE.md。從 v2.1.277 版本開始，Claude Code 現在會自行讀取 AGENTS.md，但預設情況下，只有當您的工作目錄或其上層沒有 CLAUDE.md 時才會讀取，且 CLAUDE.local.md 也會計入。

新增個人本地檔案後，您的 AGENTS.md 就會默默停止載入。如果您希望兩者都載入，有一個設定可以讓它們一起載入，或者在 CLAUDE.md 中使用一行 @AGENTS.md 匯入。巢狀檔案是按需載入的：當 Claude 在子資料夾中讀取、寫入或編輯檔案時，該子資料夾的 CLAUDE.md 就會載入，並且規則會帶有路徑：當 Claude 觸及匹配的檔案時，前置碼會載入。

Windsurf 有上限；Cursor 和 Copilot 則有建議。Windsurf 的文件現在位於 Devin Desktop 下，它是這裡唯一一個發布了字元限制的代理：每個工作區規則檔案 12,000 個字元，全域規則檔案 6,000 個字元。

文件沒有說明超過此限制會發生什麼，因此請將 12,000 視為一道牆。根目錄的 AGENTS.md 始終啟用；子目錄中的 AGENTS.md 僅在 Cascade 讀取或編輯其下的檔案時才適用。

Cursor 沒有硬性上限，並建議將規則保持在 500 行以下。有兩種行為值得了解：CLAUDE.md 會應用於每次對話，無論 alwaysApply 設定如何；規則中的 @file 引用不會內聯，代理只會在它認為需要時才讀取該檔案。GitHub 的程式碼審查指南建議將任何單一指令檔案限制在大約 1,000 行，超過此限制可能會導致回應品質下降。

較舊的貼文引用 Copilot 程式碼審查的 4,000 字元上限；我們在 GitHub 目前的文件中找不到它。對於雲端代理，樹狀結構中最接近的 AGENTS.md 獲勝。在 VS Code 中，巢狀 AGENTS.md 支援位於 chat.useNestedAgentsMdFiles 後面，此設定預設為關閉。

Gemini CLI 和 OpenCode：沒有上限，因此成本由您承擔。Gemini CLI 在啟動時會從您的工作區及其父級讀取 GEMINI.md，並在工具觸及資料夾時即時載入更多內容。我們在其文件或記憶體探索程式碼中沒有找到大小上限，它找到的所有內容都會隨每個提示一起發送。

只有當您將 AGENTS.md 新增到 context.fileName 時，它才會讀取 AGENTS.md。OpenCode 會讀取 AGENTS.md，然後回退到 CLAUDE.md，並完整讀取每個檔案。當其 Read 工具打開檔案時，它會附加在該檔案附近找到的指令檔。

沒有上限意味著沒有內容被截斷，也意味著沒有任何東西可以阻止檔案增長，直到每次輪次都為所有內容付出代價。

匯入功能用於組織檔案；它們不會縮小檔案。解決長指令檔案的常用方法是使用匯入功能將其分割。在 Claude Code 中，@path 匯入最多可達四層，文件明確指出匯入的檔案會在啟動時載入，因此分割有助於組織，但不會縮小上下文。Gemini CLI 的匯入可達五層，同樣會被串聯起來。

Codex 和 OpenCode 完全不解析匯入，而 Cursor 的 @file 是一個代理可能遵循也可能不遵循的指標。因此，匯入樹只是將同一個檔案分割成更多部分。

唯一能改變代理讀取內容的結構是，當代理在該部分適用之處工作時才載入該部分：巢狀檔案、路徑規則、全域匹配。重要的限制是上限之前的那個點。很少有團隊會達到 4 MiB。許多團隊會達到這樣一個點：檔案在每個步驟都被讀取，但沒有一個步驟會權衡其成本。

這個點是以成本和遵循度來衡量，而不是位元組。我們對此進行了測量。在 PathruleBench 中，同一個代理在八個相同的會話中工作，而團隊的知識從 500 個項目增長到 2,000 個項目。CLAUDE.md 檔案在每個步驟都被完整讀取。

在 2,000 個項目時，透過路徑傳遞相同知識的成本約減少 55%，輸入 token 讀取量減少 2.7 倍，代理通過了更多的記憶體探測。在 500 個項目時，純檔案讀取成本低且難以超越；差距從大約 1,000 個項目開始拉大。這就是 Pathrule 背後的理念：為真正適用於所有地方的內容保留一個簡短的根檔案，將其餘內容放置在適用路徑上，以便每個代理都能收到其正在處理的程式碼片段。無論您使用何種工具，上述清單都會告訴您今天有多少檔案內容被實際讀取。