生活分享
AGENTS.md 專案規則
AGENTS.md 是讓 Codex 在開始工作前取得專案規則的檔案。全域規則、專案根目錄與工作目錄路徑中的子目錄規則會形成一條指令鏈;同一層有 AGENTS.override.md 時優先讀取它。規則愈具體愈容易遵循,仍需要驗證實際載入。
閱讀時間約 12 分鐘 · 操作 20 分鐘

本篇目錄
返回 Codex 教學總目錄Codex 學習中心:完整教學目錄從安裝、第一個任務到 MD 規則與進階整合,規劃 60 篇 Codex 教學、十個單元。依程度、平台、需求或指令搜尋下一篇;尚未公開的教學會標示狀態,方便安排學習路線。閱讀全文
讀完能做到什麼
規則文件適合保存每次都要重說的專案要求,例如測試命令與資料保留方式。它不是密碼保險箱,也不會替你開啟網路或提高檔案權限。需要調整授權時,另看權限與沙盒權限、沙盒、網路與金鑰沙盒決定工具技術上能碰哪些檔案或網路,授權政策決定什麼時候需要詢問。兩層設定不能混為一談:不顯示詢問不代表動作一定被允許,能讀檔也不代表可以寫入所有地方。閱讀全文;不要期待一句「允許所有操作」就改變執行環境。
開始之前
下載待辦網站練習材料,解壓縮後複製 expected 資料夾,將副本命名為 codex-practice。這一篇使用功能完整的參考版,避免把尚未完成的篩選功能誤當成規則問題。資料皆為虛構;先不要放入私人專案或更動全域規則。
副本根目錄應直接看得到 index.html、style.css、app.js、core.mjs、core.test.mjs。準備可執行的 Codex 桌面版或 CLI;測試使用 Node.js,本機預覽使用 Python 3。若只是建立規則檔案,可以先完成前半部,再回第一個練習專案完成第一個小專案使用 Small Steps 待辦網站的獨立副本,修改主標題與背景色。辨識五個練習檔案的用途,比對修改前後差異、核心測試與兩種視窗寬度,確認原有功能及資料保留。閱讀全文補上工具。
最少必要概念:規則從哪裡來
Codex 會組合全域與專案指引。全域位置預設在使用者目錄下的 .codex;設定 CODEX_HOME 時則以該位置為準。專案部分從根目錄沿路走到目前工作目錄,較接近工作位置的規則可以細化前面的要求。它不會因為某個子資料夾存在,就把所有子目錄的規則一次讀入。
同一個目錄優先選擇 AGENTS.override.md,再找 AGENTS.md,再考慮已設定的替代檔名;不是把同層這些檔案全部相加。一般 README.md 適合向人解釋專案,不會只因為是 Markdown 就自動變成規則。預設專案指引合計大小上限為 32 KiB;先移走重複說明與大型範例,比直接增加上限更容易維護。
本篇只新增練習專案的 AGENTS.md。全域偏好會影響其他專案,等你確定哪些要求真的通用,再參考config.toml 設定config.toml 設定教學config.toml 控制 Codex 的設定值,與 AGENTS.md 的自然語言工作規則不同。使用者設定在 Codex home,受信任專案也能有 .codex/config.toml。設定可能被 CLI 參數、專案層或組織政策影響,不能只看一個檔案就斷言生效。閱讀全文及官方文件處理。
官方規則發現流程找不到專案根目錄時,只檢查目前目錄;所以本例必須從 codex-practice 根目錄開始,不能從它的任意子資料夾啟動後假定會往上找到規則。已有儲存庫的根目錄與子目錄比較見規則層級AGENTS.md 層級與覆寫驗證用根目錄與子目錄案例追蹤規則來源、衝突與 override,確認實際選入的文件。閱讀全文。需要拆分長文件時看規則與參考資料分工規則、說明與上下文文件怎麼分把工作規則、專案入口、設計條件與交接狀態分開保存,用實檔與測試驗證過期猜測。閱讀全文。
第一步:確認位置與檔名
Windows 在檔案總管開啟 codex-practice,顯示副檔名,使用文字編輯器新增 AGENTS.md。確認它沒有變成 AGENTS.md.txt。若用 PowerShell,在資料夾空白處開啟終端機後輸入下方命令;結果應列出五個練習檔案。看到 expected 的上一層時,先進入正確目錄再繼續。
Get-Location
Get-ChildItem -Name
macOS 在 Finder 選取練習資料夾後開啟終端機,或在 Terminal 使用 cd 加上拖入的資料夾路徑。Linux 在檔案管理員使用「在終端機開啟」。兩者都用下面的命令確認位置,再以純文字編輯器建立同名檔案;大小寫保持一致,避免 Linux 找不到規則。
pwd
ls -a
如果目錄已經有 AGENTS.md,先讀取並保留原文,只合併本次需要的條目。練習副本應沒有該檔案;不要為了照抄步驟而覆蓋另一個專案的規則。
第二步:寫入一份完整規則
以下是完整檔案,不需要另外安裝套件。範例使用英文以便五語文章共用同一份內容;你也可以用自己熟悉的語言寫規則。真正重要的是命令存在、範圍具體,以及讀者能確認要求是否完成。
# Small Steps practice instructions
- Work only inside this practice folder.
- Keep the existing task data format and localStorage key unchanged.
- Do not add packages or external network requests for this exercise.
- Run `node --test core.test.mjs` after changing JavaScript.
- After changing HTML or CSS, check the page at 390px and 1280px widths.
- Preserve visible keyboard focus and accessible form labels.
- In the final response, list changed files, checks run, and checks not run.
- Say why a check could not be run; do not report it as passed.
不要把「品質要好」當成唯一要求。這份範例把品質轉成可觀察項目:測試命令、兩個畫面寬度、鍵盤焦點與明確交付紀錄。也不要貼入 npm test:本材料沒有 package.json,使用不存在的命令只會讓後續每次任務都卡住。
第三步:重新開始並驗證載入
儲存後,從練習資料夾開啟一個新的 Codex 工作階段。桌面版選擇這個專案並建立新任務;CLI 則離開舊互動階段,在該資料夾重新執行 codex。指引在工作階段建立時讀取,不要只在原對話修改檔案後猜測它已重新載入。
List the AGENTS.md or AGENTS.override.md files loaded for this task.
Summarize the rules that apply to this practice folder.
Do not modify any files. If you cannot establish a source, say so.
預期能指出練習資料夾的 AGENTS.md,摘要測試、畫面與交付要求。回答只是第一個線索,還要開啟檔案核對實際內容。若它只複述你的提示詞、沒有正確路徑,先處理工作目錄與檔名問題,再做修改。
第四步:用小修改檢查行為
In index.html, change the main heading to "Small steps, clear progress."
Keep the todo behavior, stored data, and other visible text unchanged.
Follow the project instructions. Show the changed file and report the checks.
預期差異主要是 index.html 的標題文字。啟動預覽:Windows 執行 py -m http.server 4173 --bind 127.0.0.1;macOS/Linux 執行 python3 -m http.server 4173 --bind 127.0.0.1。瀏覽器開啟 http://127.0.0.1:4173,確認標題、兩個寬度與 Tab 焦點,再新增 Read 並完成它。瀏覽器未提供給 Codex 時,你可以自行檢查,並讓它明列未執行的檢查。
正常案例是修改範圍正確、既有資料仍在、交付紀錄符合規則。邊界案例是在無瀏覽器環境中要求檢查:合格回應應說明限制及待手動確認項目,不能捏造截圖或通過結果。這也說明規則是工作指引,仍需要人或工具核對證據。
把規則逐條對到證據
| 本次情況 | 規則要求 | 可以核對的證據 |
|---|---|---|
| 只改 HTML 標題 | 畫面寬度、焦點、交付紀錄 | 指定文字與實際畫面;未執行項目明列 |
| 改動 JavaScript | 執行既有資料測試 | 實際命令、退出狀態與測試數量 |
| 工具不可用 | 回報原因,不寫成通過 | 原始錯誤及 NOT RUN;沒有捏造結果 |
本次只改 HTML,沒有觸發「改 JavaScript 後測試」的條件,不能因此認定 Codex 漏做。若要確認測試命令可用,可另外送出下列唯讀要求;expected 副本應是 3 個通過、0 個失敗。這只驗證命令與回報,不代表已實測所有規則分支。
Run node --test core.test.mjs from this practice folder without editing any files.
Report the working folder, command, exit status, and test counts.
If the command cannot run, quote the error and mark the check NOT RUN.
常見問題與還原
找不到規則時,依序檢查目前專案、真正副檔名、檔案是否為空,以及同層是否存在 override。Windows 能讀到不代表大小寫不同的名稱在 Linux 也會生效。修正後開新工作階段重試。
規則彼此矛盾時,先查來源層級,尤其是較深目錄或全域 override。把「全站統一」與「此資料夾例外」寫清楚;不要新增更多互相否定的句子。深層規則的逐層追蹤會在後續專篇展開,本篇先保持單一專案檔案。
Codex 沒有執行測試時,先看這次是否真的改了 JavaScript,再確認 node --version 可用及 core.test.mjs 位於工作目錄。缺少執行環境與規則沒載入是兩種不同問題;要求它回報實際錯誤,不要用「應該通過」代替結果。
停止預覽用 Ctrl+C。還原標題時只恢復本次文字修改;若 AGENTS.md 是本篇新建,可將它移出練習資料夾保存。若修改的是原有規則,恢復自己的條目即可。移除規則不會撤銷它先前造成的檔案修改,新的規則狀態也要在新工作階段驗證。
| 範圍 | 位置 | 本篇的處理 |
|---|---|---|
| 全域 | CODEX_HOME,預設為使用者的 .codex | 先保留原設定 |
| 專案 | codex-practice/AGENTS.md | 新增並用新工作階段驗證 |
| 同層替代 | AGENTS.override.md | 檢查是否優先選入 |
小練習與來源
追加一條「最終回覆先列出待手動確認事項」,再開新工作階段做一次不同標題的小修改。完成判準是能找到來源、差異僅含指定標題,而且交付順序符合新要求。練完移除新增條目,觀察下一個新工作階段的差異。
查證日為 2026-09-14;規則發現與大小限制依 AGENTS.md 官方文件查證。練習網站與資料操作測試已在 Windows/Edge 驗證;本文未將 macOS、Linux 或 Codex 規則載入宣稱為本機實測。接著可讀Markdown 入門Markdown 與 MD 檔入門Markdown 是用純文字標記標題、清單、連結與程式碼的格式,常見副檔名是 .md。README.md 通常用來說明專案,AGENTS.md 提供代理工作規則,SKILL.md 描述可重用技能;不是所有 MD 檔都會被 Codex 自動當作指令。閱讀全文、工作交接上下文與工作交接長工作需要把決策與證據留下,不能只依靠對話長度。README 說明怎麼使用專案,設計文件記錄為何這樣做,交接文件整理目前做到哪裡;AGENTS.md 則放持續有效的工作規則,避免把所有進度塞成規則。閱讀全文及SkillsSkills 與 SKILL.mdSkill 將固定工作流程整理成可重用的指示與資源。最小結構是一個資料夾與 SKILL.md,檔案前段需要 name 和 description,正文描述操作與輸出。安裝技能不代表每個任務都必然使用,還要檢查是否載入。閱讀全文。
返回 Codex 教學總目錄Codex 學習中心:完整教學目錄從安裝、第一個任務到 MD 規則與進階整合,規劃 60 篇 Codex 教學、十個單元。依程度、平台、需求或指令搜尋下一篇;尚未公開的教學會標示狀態,方便安排學習路線。閱讀全文
閱讀完整文字說明
Global to Project to Working directory
覺得這篇整理實用嗎?分享給需要的朋友
同主題延伸閱讀
生活分享
Codex 學習中心:完整教學目錄
從安裝、第一個任務到 MD 規則與進階整合,規劃 60 篇 Codex 教學、十個單元。依程度、平台、需求或指令搜尋下一篇;尚未公開的教學會標示狀態,方便安排學習路線。
生活分享
Worktree 與多任務隔離
Worktree 讓同一個 Git 程式庫有不同的工作目錄,各自承接不同分支。它適合讓兩項工作分開改檔,但資料庫、連接埠與外部服務仍可能共用,不能把檔案隔離當成所有資源隔離。
生活分享
實戰:製作小網站
從 brief.md 規劃並製作 Small Steps 待辦網站,完成新增、完成、刪除、篩選與本機資料保存。將 HTML、CSS、資料函式、畫面事件與測試分開,以 Node 測試和瀏覽器操作驗收,並留下可重新啟動與還原的交接紀錄。
引用本文的文章
資料來源
- AGENTS.md instructions查證日期:
- Configuration basics查證日期:
本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。