AGENTS.md 入門指南：建檔、驗證與沒生效排查

每次開一個新的 AI 任務，你都在重複同一段開場白：用繁體中文、原稿不要動、數字照抄不要改、成果存成新檔案。第一週你耐心重講，第二週你把這段話存進便利貼，第三週便利貼找不到，數字就被改掉了。這種浪費有一個檔案級的解法：把那些每次都要講的話寫進一份叫 AGENTS.md 的純文字檔，放在專案資料夾裡。支援這個格式的代理工具（例如 Codex）會在工作前自動讀取；Claude Code 與其他工具則要看版本與設定才會讀，這份指南後面會把差異講清楚。你少貼一段，它多一分穩定，而且這份說明可以版控、可以傳給同事、可以逐年演化。

整份指南按一次完整走查的順序展開：先把指示檔在解決什麼問題講清楚，處理建檔前的兩個決定（位置與檔名），然後用一份門市週報的虛構原稿走完三檔練習（原稿、指示檔、成果）。存檔之後進入多數教學略過的兩段：驗證它真的讀到，以及沒生效時的四步排查。後半處理兩個選型問題：CLAUDE.md 與 AGENTS.md 的主檔選擇與覆蓋語意、聊天指令與指示檔與 Skill 的三層分工；收在長度上限與維護節奏，以及 robots.txt、llms.txt 這個「給機器看的說明檔」家族。全程不需要程式背景，需要的是把要求寫成可核對規則的耐心。

一分鐘答案：AGENTS.md 是什麼、怎麼開始

AGENTS.md 是一份放在專案資料夾裡的純文字檔，副檔名 .md 代表 Markdown 格式，內容是你希望 AI 代理每次開工都知道的規則：資料在哪、怎麼處理、成果長什麼樣、哪些事絕對不能做。以 OpenAI 的 Codex 為例，它會在任務開始時自動讀取，不需要你在對話裡重新交代；但「支援這個格式」不等於「一定自動讀」，各家工具的支援方式不同，有些要設定後才會讀，換工具前先看該工具的官方文件。Claude Code 也加入直接讀取的行列，但會不會讀到，取決於版本、設定與路徑上有沒有既存的 Claude 指示檔，細節與陷阱放在後面格式比較節的進階補充。

第一次建檔只要三個動作：開一個練習資料夾，放進一份故意留了缺口的測試原稿；用文字編輯器寫十來條可核對的規則，存成 AGENTS.md；先用一個小任務驗證它讀到了、也照做了，再派正式工作。判斷什麼時候該建檔也只要一句話：同一句交代，你說到第三次，它就該進檔案。

指示檔在解決什麼問題：從口頭交代到書面規則

把要求留在對話裡，有三個結構性缺陷。其一是一次性：新開一個對話，上一輪交代過的用語、格式、禁改事項全部歸零，你得從頭再講。其二是不可核對：口頭交代沒有版本，出了事你無法回頭看「當時到底講了什麼」，只能憑記憶爭論。其三是每次都漏：一段五句話的交代，隔週重講時總會少一句，而少的那句往往是最關鍵的禁改事項。指示檔把這三個缺陷一次補掉：規則常駐在專案裡、檔案本身有版本、每次載入的都是同一份完整內容。

背景知識一段講完。AGENTS.md 是一個開放格式，它不是有固定欄位的設定檔，只是一份用 Markdown 慣例組織的說明文件，AGENTS.md 官方網站把它定位成「給代理看的 README」，由 OpenAI Codex、Google Jules、Cursor 等團隊的共同協作發起，規格目前由 Linux Foundation 底下的 Agentic AI Foundation 托管，超過六萬個開源專案已經放了一份。格式細節的完整介紹（分層放置、越近越優先、用指令生成起始版）站上的Codex 零起點工作流已經講過，這裡不重複。本篇的主軸錨定在另一件更基礎的事：第一次建檔的完整走查，從建檔、驗證到排查，把「寫了檔案」與「檔案生效」之間那段沒人講的距離補起來。

它與 README 的分工值得先分清楚。README 寫給人看，回答「這個專案是什麼」；指示檔寫給代理看，回答「可以在這裡做什麼、不可以做什麼、做完之後怎麼驗收」。兩份檔案可以並存，也可以互相連結，但把給機器的規則塞進 README，等於依賴代理「剛好去讀」的運氣。至於 Markdown，本質就是純文字：# 開頭當標題、- 開頭當清單條目，Windows 的記事本存檔就是純文字，macOS 的文字編輯器預設可能是 RTF 格式，請先從「格式」選單選「製作純文字」再存檔；內容可以直接寫中文，不需要先學任何程式語言。

位置上還有「個人層與專案層」的分別，早知道可以少走一段冤枉路。專案層就是專案資料夾裡的那份 AGENTS.md，跟著資料夾走，同事拿到資料夾就拿到同一套規則；個人層則放在你家的使用者目錄底下（Codex 是 .codex 資料夾裡的 AGENTS.md），屬於你這個人，所有專案共享，適合放跨專案的個人偏好，例如永遠使用繁體中文、金額不四捨五入。第一次練習只要管專案層，但要知道個人層存在：它會靜靜合併進每一次任務，排查「為什麼多出一條我沒寫的規則」時，別忘了它。分工原則一句話：說得出「只有這個專案才這樣」的進專案檔，所有專案都一樣的進個人檔，兩邊寫了矛盾的要求時，覆蓋規則就登場了，那是後面格式比較節的主戲。

建檔前的兩個決定：位置與檔名

第一個決定是放哪裡。把「專案」想成一個資料夾：這個資料夾裡放原稿、放指示檔、放成果，代理就在這個資料夾裡工作。第一次練習不要分層，全部放在同一層。原因與工具的發現機制有關：以 Codex 為例，官方的指示檔說明寫明它會從專案根目錄（通常是 Git 儲存庫的根）一路往下走到目前的工作目錄尋找指示檔；找不到專案根目錄時，只檢查目前目錄。全部同一層，就把「它在哪一層找工作」這個變數直接消掉了。

第二個決定是檔名，這是新手失敗率最高的一格。標準檔名是 AGENTS.md：開頭 AGENTS 六個英文字母全部大寫、結尾有複數的 S、副檔名 .md。打成 agent.md、agents.md 或 AGENTS.MD 都與標準名稱有出入，工具可能直接讀不到。另一個典型陷阱來自 Windows：檔案總管預設隱藏已知副檔名，你在存檔對話框輸入「AGENTS.md」，實際存成的檔名可能是 AGENTS.md.txt，畫面上看起來一模一樣，工具卻完全不認得。

對應的習慣只有一條：存檔之後，查看完整檔名。Windows 到資料夾選項打開「顯示副檔名」，macOS 用檔案簡介或終端機的 ls 指令看全名。要特別留意的是，檔名錯了不會有任何錯誤訊息：工具只是安靜地讀不到，任務照跑，規則照缺，你只會在成果裡隱約覺得「它好像沒照我說的做」。這種無聲失效，正是後面排查章節的第一步要抓的東西。

三檔練習：一份原稿、一份指示檔、一份成果

這個練習只需要一個資料夾與三個檔案，全程使用虛構資料。動手前先記一條安全規則：練習一律用副本，重要檔案先備份或加上權限限制，因為 AGENTS.md 是行為指示，不是權限鎖，「僅供讀取」寫得再明白，也擋不住一次誤存檔，這條界線後面的格式比較節會完整展開。用假資料有明確的目的：你要測的正是代理會不會把資訊缺口補成看似完整的內容，這種錯誤只有在「你知道標準答案」的原稿上才驗得出來。原稿經過刻意的缺口設計，練習本身就被設計成一個防幻覺測試；確定整理方式符合預期之後，再換成你有權使用的正式資料。

原稿：故意留缺口的測試設計

在電腦上建立一個叫 weekly-report-practice 的資料夾，用文字編輯器新增 store-week42.txt，把這份虛構週報存進去：

門市週報 第 42 週
本週營業額 386,400 元，比上週增加約 6%。
客單平均 412 元，來客數 938 人。
週三起試賣新飲品「桂花烏龍」，五天賣出 74 杯，反應不錯，
考慮月底轉入正規菜單。
店長提議下週推出滿額贈禮，門檻與贈品內容還沒討論。
下週營業目標尚未與區經理確認。
排班：週五人手吃緊，阿凱願意加班一天，等店長核准。

這份原稿埋了三個缺口，各對應一種真實的出事方式。滿額贈禮還在提議階段，門檻與贈品未定，看代理會不會把它寫成已定案的活動，甚至自行補上「滿 500 送好禮」這類細節；下週營業目標尚未核可，看它會不會自己算一個 400,000 元的目標填進去；阿凱的加班還在等核准，看它會不會把待核准直接寫成確定排班。三個缺口都是「資訊不完整但看起來應該要有」的欄位，這正是語言模型最有衝動補齊的地方，也是指示檔價值最高的戰場。

指示檔：把要求寫成可核對的規則

在同一個資料夾新增 AGENTS.md，貼入這份範例再存檔：

# 門市週報彙整規則

## 檔案與角色
- store-week42.txt 是本週原稿，僅供讀取，任何情況下不修改這個檔案。
- 彙整只能使用原稿出現過的資訊，不得引用外部資料，不得推估。

## 彙整規則
- 使用繁體中文。
- 金額、人數、杯數等數字逐字照抄原稿，不四捨五入、不換算單位。
- 成果依序分四節：本週表現、進行中的嘗試、待決定事項、待核准事項。
- 還在提議、尚未拍板的內容，一律放入待決定事項，不得寫成結論。
- 缺目標、負責人或日期的項目，標示「未定」，不得代為指定。
- 原稿有明顯錯字時保留原字，另在文末列「原稿疑義」清單。

## 輸出與驗收
- 成果存成 weekly-summary-v1.md；若已存在，改用下一個未占用版本號，不覆寫。
- 完成後回報實際存檔檔名，以及待決定與待核准事項的清單。
- 驗收基準：四節齊全、數字與原稿一致、所有未定事項仍標示未定。

這份範例的三個區塊，對應交代工作時永遠要講的三個問題：檔案從哪來、規則是什麼、成果怎麼驗。換成客服日誌、訪談逐字稿或採購明細，骨架照用，只換內容。規則句的寫法有一個共通點：每一條都可核對。「不得四捨五入」可以核對，「數字要精確」沒辦法；「放入待決定事項」可以核對，「提議不要當成結論」要靠猜。寫規則時自問「這條違反了我看得出來嗎」，看得出來的才留下，這個標準會自動幫你刪掉一半的空話。

成果：合格的輸出長什麼樣

照規則跑出來的合格成果有明確長相，完整的 weekly-summary-v1.md 會是這樣：

# 門市週報彙整：第 42 週

## 本週表現
- 營業額 386,400 元，比上週增加約 6%。
- 客單平均 412 元，來客數 938 人。

## 進行中的嘗試
- 週三起試賣新飲品「桂花烏龍」，五天賣出 74 杯，反應不錯；考慮月底轉入正規菜單（評估中，未定案）。

## 待決定事項
- 滿額贈禮：店長提議下週推出，門檻與贈品內容未定。

## 待核准事項
- 下週營業目標：尚未與區經理確認，未定。
- 排班：阿凱願意週五加班一天，待店長核准。

逐項核對這份成果，三個動作就夠。數字回原稿找：386,400、412、938、74 每一個都逐字存在，增減幅度照原文寫「約 6%」；狀態語被保留：「考慮月底轉入正規菜單」仍在評估中，沒有被升級成「將於月底上市」；三個缺口原封不動：滿額贈禮留在待決定事項、營業目標與加班留在待核准事項，沒有任何一個被補上「合理的」內容。對照之下，不合格的成果通常長得很漂亮：滿額贈禮出現在已定案區、目標被補上一個合理的數字、加班寫成確定行程，版面整齊，內容越權。學會看這條線，你就學會了驗收。

驗證讀取兩步法：先問它讀到什麼，再看它做對什麼

存檔完成不等於生效，而「有讀到」與「照著做」是兩個不同的檢查對象，順序不能顛倒。多數人的做法是直接派工，成果不對再回頭找原因，等於把兩種故障混在一起除錯。兩步法把故障先分開：第一步確認指示有進到它的脈絡，第二步確認規則有落實到實際產出。

第一步，先別讓它動工。在正確的資料夾開始新的代理任務，送出這段話：

請先不要動工。列出你這次已載入的指示檔檔名，並用自己的話說明
這個專案的資料來源、數字處理規則、未定事項的處理方式與輸出檔名。
說明完等我確認。

合格的回應會指名 AGENTS.md（或逐條複述規則要點：不改原稿、數字照抄、未定標示、版本命名）。如果它回答「沒有發現指示檔」，先停下來，跳到下一節的排查流程，繼續派工只是浪費一輪。這一步的成本是三十秒，價值是把「檔案沒被讀到」這個最常見的故障，從「成果不對勁」的模糊症狀裡剝出來。

第二步，派一個小任務，而且訊息裡不再複述任何規則：

請依本專案規則彙整 store-week42.txt，建立成果檔後告訴我檔名。

訊息裡不重貼規則是刻意的。如果你忍不住又貼了一遍，代表你還不相信那份檔案，而這份不信任正是這一步要處理的對象：指示檔的意義就是讓任務訊息只剩任務本身。完成之後打開實際成果，核對三件事。檔案有建立：資料夾裡找得到 weekly-summary-v1.md，而且打開 store-week42.txt 比對，原稿內容一個字都沒被改動。資訊有對上：隨機抽查兩三個數字（386,400、412、938、74）回到原稿能找到，分節與順序照規則走。缺漏有留下：三個未定事項仍然標著未定，沒有被補上任何「合理的」內容。聊天視窗裡的完成通知不算數，通知只會說做完，不會說它把「考慮轉入」寫成了「將於月底上市」。

Claude 陣營有對應的檢視畫面可以看。Claude Code 官方的記憶文件說明，/context 指令會展開本次 session 的 Memory files 清單，指示檔有沒有載入一目了然，比口頭詢問可靠；/memory 則列出所有指示檔位置。但兩個檢視畫面共用同一個版本條件：2.1.280 版起，/context 與 /memory 才會列出直接讀入的 AGENTS.md；更舊的版本上這份檔案不出現在任何清單，想確認它被讀到，只能直接問 Claude 它的 project instructions 內容，或改用 CLAUDE.md 第一行匯入 AGENTS.md 的接法，讓它以一般指示檔的身分現身。跨工具的通則由此浮現：有檢視畫面就用它，沒有才靠口頭詢問，而不管哪一種，最終的裁判都是實際成果，因為列得出規則不代表做得出規則。

先列指示再動工，還有一個常被忽略的經濟理由：它把除錯的單位從「一整個成果」縮小到「一句規則」。直接派工而成果出錯時，你要在四個可能（沒讀到、讀錯檔、規則含糊、模型誤解）裡同時搜尋；先花三十秒確認指示清單，四個可能立刻砍掉一半，剩下的修正都發生在「規則怎麼寫」這個你能控制的層次。代理的每一輪來回都在消耗時間與額度，驗證兩步法本質上是在替你省下最貴的那幾輪。

核對失敗時，走一個固定的修正迴圈。第一圈，指出具體錯誤，請它修正成果檔，用詞越具體越好：「滿額贈禮出現在已定案區，請移到待決定事項」就夠了，不需要長篇解釋。第二圈，回頭檢查規則句本身：如果指示檔裡只寫了「不要亂猜」，就趁現在補成「缺負責人或日期的項目標示未定，不得代為指定」，多數反覆出現的錯誤，源頭都是一條寫得含糊的規則。第三圈，用同一段原稿重測一次，確認同樣的錯誤不再出現，而不是換一段新原稿混淆變因。三圈走完，成果對了，規則句也變準了，這份指示檔從此比你的記憶可靠。

沒生效的四步排查：檔名、位置、衝突、重讀

成果明顯不照規則走時，與其在對話裡加重語氣寫「務必遵守」，先按順序查四個地方。多數沒生效的案例出在前兩步，後兩步處理的是進階配置才會遇到的覆蓋問題。四步的共同邏輯是：先確定「它讀的檔案」就是你「以為它讀的檔案」。

動手排查前，固定一條紀律：一次只改一個變因，每改一次就重跑驗證第一步。改了檔名又同時搬了資料夾，即使問題消失，你也不知道真正的原因是哪一個，下個月同樣的故障回來時還是兩眼一黑。實驗的控制組思維在這裡完全適用：固定原稿、固定任務訊息，只讓「懷疑的那一個東西」變動，觀察列指示的結果有沒有跟著變。看起來慢，實際上是排查裡最快的路，因為它讓每一次嘗試都產生確定的知識。

第一步，完整檔名。打開資料夾查看全名：複數 S 在不在、大小寫對不對、副檔名是不是被藏了一層 .txt。Windows 使用者到資料夾選項打開副檔名顯示；macOS 使用者點開檔案簡介確認。這一步十秒鐘，卻涵蓋了最高比例的失敗案例，因為它安靜、無錯誤訊息、畫面上完全看不出異狀。

第二步，工作位置。請代理顯示目前工作資料夾的完整路徑，與你存檔的資料夾比對。Codex 的搜尋範圍是專案根目錄到目前工作目錄這一條線，找不到專案根目錄時只看當前目錄；你的 AGENTS.md 若放在這條線以外的資料夾（例如桌面，而它在下載資料夾工作），它永遠讀不到。確認方式很樸素：讓它自己說出它在哪，與你以為的位置對照。

第三步，衝突指示檔。同一層目錄裡若有 AGENTS.override.md，Codex 會優先採用它，而且每個目錄最多只採用一份指示檔，兩份不會一起讀；全域層（家目錄下的 .codex 資料夾）同樣是 override 優先。你以為自己改的是生效中的 AGENTS.md，實際上真正餵給模型的是另一份。Claude 端則有兩個方向相反的陷阱：它不讀 AGENTS.override.md；而且只要工作目錄或任一上層出現任何一份 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md，預設就讀 Claude 指示檔、不再讀 AGENTS.md。同一份檔案在兩家工具手上命運不同，完整對照在下一節。

第四步，新任務重讀。Codex 的指示鏈在每次執行時重建（約等於每開一輪新對話重建一次），進行中的對話不會因為你改了檔案就回頭重讀。修改指示檔之後，在目標資料夾重新開一個任務，再跑一次驗證兩步法的第一步，確認新規則已經在它的說明裡。把「改完檔案、開新任務、重新驗證」綁成一個動作，就能避開大多數「我明明改了」的爭執。

CLAUDE.md 與 AGENTS.md：主檔怎麼選、衝突誰贏

CLAUDE.md 與 AGENTS.md 在做同一件事：把常駐指示放進檔案。差別在誰讀它、怎麼讀、衝突時誰贏。截至 2026 年 10 月的兩家官方文件，多數讀者需要的答案可以先濃縮成一張決策表：看你用的是哪種工具組合，再決定主檔給誰。

決策表的第三列值得展開，因為它最常被問錯。Codex 直接讀 AGENTS.md；Claude Code 在路徑上沒有任何 Claude 指示檔時，也會直接讀 AGENTS.md。但若專案已有 CLAUDE.md（或 .claude/CLAUDE.md、CLAUDE.local.md），Claude Code 預設就只讀 Claude 指示檔、不再讀 AGENTS.md，想兩份都讀有兩條路：在 CLAUDE.md 的第一行寫 @AGENTS.md 把它匯入，Claude 會先讀匯入內容再讀其餘；或到設定把 Project instructions 改成兩份並讀。官方文件推薦的是匯入寫法，Windows 團隊尤其適合：它避開了符號連結在 Windows 上需要管理員權限、且 Git 取出時可能變成一行純文字的麻煩。這個策略的本質是承認現實：格式之爭沒有贏家，一份主檔加一行匯入，比維護兩份平行內容誠實得多，CLAUDE.md 裡只留 Claude 特有的要求。

選完主檔之後，才需要理解兩家的覆蓋語意，因為衝突時的勝負規則完全不同。Codex 這一側是「拼接加就近覆蓋」：全域層先看家目錄 .codex 裡的 AGENTS.override.md，沒有才看 AGENTS.md；專案層從根目錄走到當前目錄，每個目錄至多取一份，全部由根往下拼接、以空行相接，越靠近當前目錄的內容越晚出現、覆寫力越強。空檔案會被略過，合併的大小有上限，留到後面維護一節講。官方網站的立場與此相容：離編輯中檔案最近的一份贏，而使用者在聊天裡的明確指示壓過一切檔案。換句話說，在 Codex 的世界裡，階層是有明確勝負的。

Claude 這一側是「串接不覆蓋」。官方記憶文件把指示檔定位為脈絡，明說它們被當成 context 看待，而非強制配置；多份 CLAUDE.md 會全部串進脈絡，從檔案系統根一路排到工作目錄，沒有哪一份宣告勝利。兩份指示互相矛盾時，官方沒有給出誰贏的保證，建議的解法直接而務實：把衝突消掉。

還有一個觀念必須在這裡釘死，它從 CLAUDE.md 陣營的文件看得很清楚，但對兩種格式一體適用：指示不等於權限。在指示檔裡寫「不可讀取某個檔案」，不會產生任何強制力，它只是願望的文字化；真正攔得住動作的，是工具的權限規則、沙箱與核准流程。Claude 官方文件直說，要無論如何擋下一個動作，該用的是事前掛鉤。所以重要原稿請留備份，機敏檔案放到任務用不到的位置，指示檔管行為的期望，權限設定管行為的邊界，兩層各自做好。這個分工的完整展開，在站上Claude Code 上手教學的權限章節。

進階補充：版本號與設定鍵

「Claude Code 直接讀 AGENTS.md」這句話，實際上有幾道版本與設定門檻。直接讀取需 2.1.277 版以上；2.1.281 之前，部分 session（例如走 Amazon Bedrock、或停用遙測的連線）仍只讀 CLAUDE.md，官方對這段版本的建議就是更新到 2.1.281 之後；在 /plugin 停用內建的 agents-md 外掛的話，同樣不會讀。想讓 CLAUDE.md 與 AGENTS.md 固定兩份並讀，到 /config 把 Project instructions 設成 claude-md-and-agents-md。過了這些門檻，前表的預設條件（路徑上有 Claude 指示檔時優先讀它）依然成立。

兩個進階檔名也順勢說明。AGENTS.override.md：Codex 把它當成同一目錄內優先於 AGENTS.md 的覆蓋檔，跨目錄時仍走「由根往下拼接」的一般規則，並非全專案最高優先；Claude Code 不讀。AGENTS.local.md：兩家預設都不會自動讀取；Codex 可以在設定裡把它列入 fallback 檔名清單（project_doc_fallback_filenames），但每個目錄最多仍只取一份，同層若有 AGENTS.override.md 或 AGENTS.md，它根本排不上，不會兩份並存載入。同一個檔名，兩家賦予的權重完全不同，這也是跨工具團隊把規則集中在一份 AGENTS.md 主檔的原因。

聊天指令、指示檔、Skill：三層怎麼分工

規則有了去處之後，下一個問題是每一條要求該放哪一層。判斷的軸只有兩根：這條要求活多久、跨不跨專案。只活這一次的，留在聊天；活在這個專案每次任務的，進指示檔；是一套跨專案的重複流程，封裝成 Skill。

聊天指令處理當次變因。「這次另加一段給主管看的摘要」「這次先給大綱再動工」這類要求，任務結束就失效，寫進檔案反而製造雜訊。指示檔處理專案常數：使用繁體中文、原稿禁改、數字照抄、成果用版本號命名，這些是這個資料夾裡每一次任務都成立的事實。Skill 處理流程本身的複用：當同一套步驟（例如每週把原始報表轉成固定格式的彙整、產出變更清單、回報未定事項）在多個專案反覆出現，把它連同範本與檢查清單封裝起來，讓每次啟用都自帶完整做法。Skill 的設計與封裝是另一門學問，站上的Skills 完整指南有深入教學。順序建議很明確：第一份指示檔還沒站穩之前，不要急著做 Skill，就像還不會寫工作說明書之前，先別急著開課。

三層之間存在一條升級路徑，而且由重複次數驅動。一條要求誕生在聊天裡；第二次遇到的時候，你從舊對話裡把那段話貼過來；第三次，它就該落進指示檔，因為你已經證明它是常數。指示檔裡的某一節如果慢慢長成「第一步到第七步」的固定流程，而且另一個專案也開始想用同一套，它就到了該封裝成 Skill 的年紀。降級也成立：某個 Skill 用了兩個月，發現只有一個專案在用，把它收回指示檔的一節，維護成本立刻減半。分層的判斷從來都是觀察出來的，靠的是使用紀錄，而非建置當下的一次性雄心，這也是為什麼資深使用者的指示檔都長得不太一樣：每份檔案背後都是不同形狀的工作史。

指示檔的維護：長度上限、百行索引與分層放置

指示檔會長胖，而長胖有代價。Codex 端的合併內容有明確上限：project_doc_max_bytes 預設 32 KiB，到上限就停止加入。32 KiB 換算成純中文大約一萬字上下（每個中文字在 UTF-8 編碼占三個位元組），聽起來很寬裕，但多層合併、中英夾雜、規則越列越細之後，後段內容被截掉是真實會發生的事，而且發生時同樣安靜。第二個代價更隱晦：規則越多，每一條被遵守的機率越低，模型對長文件的注意力會稀釋，你以為多寫多保險，實際上是把關鍵禁令淹沒在細則裡。

對應的解法，Codex 官方文件給的建議有兩個方向：碰上限時提高 project_doc_max_bytes，或把指示拆散到巢狀目錄分層放置。實務上常用的做法是把 AGENTS.md 寫成一份索引：常用規則留在檔內，各主題的細節分層放到對應文件，再用路徑指過去，代理需要時自己去讀。這個做法與「指南過載」這個失敗模式的完整分析，站上的指示檔工程與進階維護一文有系統性整理。非程式背景的版本可以更簡單：把「每次都要」的規則留在 AGENTS.md，把「偶爾要」的細節移到資料夾裡的說明文件，在指示檔裡指名路徑，需要時請它去讀。

維護的節奏感比維護的技巧重要。只收反覆出現的要求，一次性的交代留在聊天裡；同樣的錯誤出現第二次，就是回顧並補一條規則的時機，而補的規則要寫成可核對的句子，別寫成情緒化的「拜託仔細一點」。每隔一季把檔案讀一遍，刪掉過時的規則，合併重複的規則，因為互相矛盾的兩條規則，在 Claude 端沒有誰贏的保證，在 Codex 端則由位置決定勝負，兩種情況都值得避免。

專案再長大，就進入分層與接軌的領域：子資料夾各自放一份指示檔，越靠近工作現場的覆寫力越強；團隊若已有既存檔名（例如 TEAM_GUIDE.md），Codex 的設定可以把它納入探索清單；指示檔屬於團隊協議，該進版控跟著儲存庫走。這些工程細節，包含完整的磁碟位置地圖與備份策略，站上的Codex 進階操作有逐項展開。

給機器看的說明檔家族：robots.txt、llms.txt、AGENTS.md

拉遠一點看，AGENTS.md 屬於一個正在成形的家族：寫給機器看、讓機器自己來讀的說明檔。robots.txt 給搜尋引擎爬蟲，聲明哪些路徑可以抓、哪些不要碰，是站長與爬蟲之間幾十年的老協定，該擋什麼、不該擋什麼的決策邏輯在站上的robots.txt 決策指南。llms.txt 給語言模型，用一份清單告訴 AI 這個網站有什麼、哪些內容適合引用，它能不能真的讓你在 AI 搜尋裡被推薦，站上的llms.txt 迷思破解給了不迎合幻想的答案。AGENTS.md 給代理，規範它在你的資料夾裡怎麼做事。三份檔案的讀者不同、職責不同，格式哲學卻一致：與其每次互動重新解釋，把規則寫成檔案，讓機器在需要時自己取用。

家族裡三份檔的歸屬也值得分清。robots.txt 與 llms.txt 是站長的資產，服務對外，影響的是搜尋引擎與 AI 系統怎麼對待你的網站；AGENTS.md 是每一個知識工作者的資產，服務對內，影響的是你自己的產出品質。前兩份值得行銷團隊開會討論，第三份只需要你現在自己動手，十分鐘建檔，五分鐘驗證，今天下班前就能有第一份。

這個家族還共享同一條修養：寫了不等於被讀，被讀不等於被遵守。robots.txt 有部分爬蟲不理會的老問題，llms.txt 有各家 AI 支援度不一的現實，AGENTS.md 則有這份指南花了整篇篇幅處理的驗證與排查功夫。三份檔案都不是設完就收工的開關，它們是持續生效的承諾，差別只在驗證的對象：網站驗證爬取日誌與收錄狀態，工作驗證的是每一次成果裡那些數字與未定事項。把「驗證」當成家族的共同姓氏，你對這類檔案的期待就不會失準。

收尾判斷：誰該現在就建第一份

三種人有三種答案。每週都請 AI 整理同類文件的人（週報、會議紀錄、客服日誌、訪談稿），現在就建，你已經在為重複交代付利息；還停留在單次問答階段的人，先不用，等同一句交代說到第三次再動手，那個時機自然會出現；帶團隊協作的人，建檔之外多兩件事：指示檔進版控，以及約定誰有權限改規則，因為一份沒人負責的規則檔，會以最快的速度長成沒人相信的文件。

工具都還沒上手的讀者，路徑是清楚的：想先全面認識 Codex 的介面與雲端任務，看Codex 入門解析；連安裝都還沒開始，照四條路線的安裝指南走；學會建檔之後回頭補提問的框架，開頭提過的零起點工作流那篇的四欄卡片正好接上。第一週的練習菜單可以很具體：找三份不同性質的原稿（一份週報、一份客服日誌、一份採購明細），用同一份指示檔各跑一次兩步法驗證，觀察哪些規則三份都通用、哪些必須分家，這個觀察會自然教會你規則的作用域，比任何理論都快。

收在這份指南的立場上：指示檔真正的價值，從來都不在「寫了它就會聽話」這種幻想，而在它強迫你把模糊的期望翻譯成一條條可核對的規則，那個翻譯的動作，已經是工作品質的一半；剩下的另一半，是驗證的紀律與排查的耐心，這篇指南花了最多的篇幅在那裡，因為那才是非程式背景者真正的保障。