AGENTS.md 層級與覆寫驗證

返回 Codex 教學總目錄

目標與準備

AGENTS.md 保存對工作的指示，config.toml 保存應用設定；兩者不是同一個覆寫機制。這次用回覆標記與必須保留的共同要求觀察規則，不提高沙盒權限，也不要求模型執行未知命令。能複述某個檔案，仍不等於它在啟動時自動載入，所以要同時看實際回覆行為與工作目錄。

先看載入順序

全域規則預設位於使用者目錄的 .codex；若已有 CODEX_HOME，則以其指向位置為準。專案規則從辨識到的根目錄往目前工作目錄走，不會一次遍歷所有兄弟資料夾。每一層依檔名優先檢查 AGENTS.override.md，再找 AGENTS.md，最後才是已設定的備援檔名；同層最多取一份。較深層的指示可覆寫前面衝突項目，沒有衝突的共同要求仍保留。

步驟一：建立獨立規則實驗室

在自己的練習位置建立新的 codex-rules-lab，裡面再建 ui 與 data 子資料夾。先不要建立 override。用編輯器開啟這個新資料夾，在整合終端機確認位置：PowerShell 用 Get-Location，macOS／Linux 用 pwd。確認沒有同名既有專案後，在這個新資料夾執行下列 Git 初始化；它只用來讓練習有明確專案根目錄，不需要提交或連接遠端。

git init
git rev-parse --show-toplevel

在根目錄新增 AGENTS.md，貼入第一份完整內容。ROOT-LAB 是方便觀察的回覆前綴，KEEP-DATA 則是各子目錄都應保留的共同要求。這些標記只服務練習，正式規則應改寫成實際測試、資料保留與交付要求。

# Root practice instructions

- Start the final answer with ROOT-LAB.
- Include KEEP-DATA in the final answer.
- Do not change any files for the rule-discovery exercise.
- Report checks that were actually performed separately from unverified claims.

在 ui/AGENTS.md 放第二份完整內容，在 data/README.md 放下面的資料說明。README 刻意不是 AGENTS 檔，沒有另外設定備援檔名時，不應只因為同為 Markdown 就加入啟動指示。先檢查每份檔名大小寫與副檔名，避免 Windows 編輯器默默補上 .txt。

# UI practice instructions

- Start the final answer with UI-LAB instead of ROOT-LAB.
- Include UI-BASE in the final answer.

# Data notes

This folder describes fictional practice data.
DATA-NOTE is a document marker, not a required answer prefix.

步驟二：從兩個目錄各啟動一次

在實驗室根目錄的系統終端機先執行第一個啟動命令；它把這次 CLI 限制為唯讀。進入 Codex 後送出下方自然語言要求，不另外貼規則內容或指定應有前綴。預期回覆從 ROOT-LAB 開始並包含 KEEP-DATA。再用 /exit 回到系統終端機，不要用 resume 接續剛才任務，改執行第二個命令從 ui 開全新工作階段。

codex --cd . --sandbox read-only

Without changing files, report the current working directory and the project instruction sources already available to this session. Follow the active response-format instructions. Do not search unrelated sibling folders just to collect more rules. Distinguish known loaded instructions from files you have not inspected.

codex --cd ui --sandbox read-only

在 ui 工作階段送出完全相同要求。預期前綴改成 UI-LAB，仍有 KEEP-DATA，並增加 UI-BASE。這代表子目錄覆寫前綴，根目錄不衝突的要求仍在。若它只能在你要求手動讀檔後才說出規則，請把「手動讀到」和「啟動已載入」分開記錄；模型自述不是載入日誌，不要把不確定的狀態標成成功。

步驟三：加入同層 override 再比較

退出 ui 工作階段，保留 ui/AGENTS.md，再新增 ui/AGENTS.override.md，內容如下。回實驗室根目錄，重新執行 codex --cd ui --sandbox read-only，送出同一個要求。預期 UI-OVERRIDE 與 KEEP-DATA，這次不應因同層 AGENTS.md 而加入 UI-BASE。override 取代的是同一層候選，不是把根目錄與所有全域要求全部清空。

# UI override practice

- Start the final answer with UI-OVERRIDE instead of ROOT-LAB.
- Include OVERRIDE-ACTIVE in the final answer.

多做一個邊界檢查：保留 override 備份後清空、儲存並開新工作階段，記錄實際載入結果。本機 codex-cli 0.154.0-alpha.6.2 的診斷輸入顯示，空 override 不提供內容，但也沒有接著載入同層 AGENTS.md，只留下根目錄規則；不要把空檔當作可靠的停用方法。要恢復 ui 規則，將 override 改名為不在備援清單內的 override.saved.md，再開全新工作階段確認 UI-LAB、UI-BASE、KEEP-DATA。不要刪除全域檔或整個設定目錄。

用一張觀察表分開載入與遵循

每次新啟動都填下面欄位，分別記 ROOT-LAB、UI-LAB、UI-OVERRIDE、空 override 與改名還原。不要把期望值先寫進「實際回覆」。例如診斷輸入包含 ui override，但回覆沒有 OVERRIDE-ACTIVE，只能說來源已出現在輸入、回覆格式未通過；不能因此說檔案沒載入，也不能把模型自述當成診斷輸入證據。私人的完整輸入可能含其他規則，只保存本練習需要的摘要。

Case: [root / UI / override / empty override / renamed restoration]
CLI version and start directory: [actual values]
New session: [yes / no / unverified]
Instruction-file state: [paths, nonempty/empty/renamed]
Expected markers: [prediction]
Instruction-source evidence: [observed input/log / model statement only / unavailable]
Actual answer markers: [observed values / no model run]
Conclusion: [discovery verified? response verified? remaining uncertainty]

失效排查與完成判準

完全沒出現標記時，確認真正副檔名、非空內容、Git 根目錄與 --cd 位置；總是顯示舊標記時，確認已退出並新啟動，不是 resume 舊上下文；只有某段消失時，找同層 override、全域偏好或更高優先級的環境指示。不能把較深 AGENTS.md 當作越過組織政策、工具權限或使用者要求的通行證。若有衝突，先說明來源，再調整自己可控制的規則。

文件很長時還要考慮合計大小上限，官方預設是 32 KiB，計算的是位元組，不是中文字數。先保留必要規則，把長設計和範例移到普通文件並在需要時明確讀取；不要以為切成大量兄弟目錄就會自動載入全部內容。備援檔名和上限屬設定項，留到設定教學處理，改完同樣要重啟驗證。

完成時保存根目錄、ui、override、空 override、改名還原五種情況的啟動位置、檔案狀態與實際標記。共同的 KEEP-DATA 應持續保留，移除 override 後可回到原 ui 行為。上述本機證據使用 debug prompt-input 檢查真正組成的輸入，沒有送出模型請求，也未聲稱模型一定遵從。官方來源與實際版本差異都要記錄；回覆行為需由新工作階段另行驗證。接著看規則與文件分工，把容易膨脹的 AGENTS.md 改成可維護的入口。

返回 Codex 教學總目錄

閱讀完整文字說明

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 工具
• 教學
• Codex