生活分享

AGENTS.md 專案規則

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

閱讀時間約 12 分鐘 · 操作 20 分鐘

LINE 分享
實作順序示意圖,非產品介面截圖。
圖片:Mokaair (© Mokaair)
回總目錄:Codex 學習中心:完整教學目錄

入門 · Desktop / CLI / VS Code / JetBrains

本篇目錄
  1. 1. 讀完能做到什麼
  2. 2. 開始之前
  3. 3. 最少必要概念:規則從哪裡來
  4. 4. 第一步:確認位置與檔名
  5. 5. 第二步:寫入一份完整規則
  6. 6. 第三步:重新開始並驗證載入
  7. 7. 第四步:用小修改檢查行為
  8. 8. 常見問題與還原
  9. 9. 小練習與來源

讀完能做到什麼

規則文件適合保存每次都要重說的專案要求,例如測試命令與資料保留方式。它不是密碼保險箱,也不會替你開啟網路或提高檔案權限。需要調整授權時,另看;不要期待一句「允許所有操作」就改變執行環境。

開始之前

下載待辦網站練習材料,解壓縮後複製 expected 資料夾,將副本命名為 codex-practice。這一篇使用功能完整的參考版,避免把尚未完成的篩選功能誤當成規則問題。資料皆為虛構;先不要放入私人專案或更動全域規則。

副本根目錄應直接看得到 index.html、style.css、app.js、core.mjs、core.test.mjs。準備可執行的 Codex 桌面版或 CLI;測試使用 Node.js,本機預覽使用 Python 3。若只是建立規則檔案,可以先完成前半部,再回補上工具。

最少必要概念:規則從哪裡來

Codex 會組合全域與專案指引。全域位置預設在使用者目錄下的 .codex;設定 CODEX_HOME 時則以該位置為準。專案部分從根目錄沿路走到目前工作目錄,較接近工作位置的規則可以細化前面的要求。它不會因為某個子資料夾存在,就把所有子目錄的規則一次讀入。

同一個目錄優先選擇 AGENTS.override.md,再找 AGENTS.md,再考慮已設定的替代檔名;不是把同層這些檔案全部相加。一般 README.md 適合向人解釋專案,不會只因為是 Markdown 就自動變成規則。預設專案指引合計大小上限為 32 KiB;先移走重複說明與大型範例,比直接增加上限更容易維護。

本篇只新增練習專案的 AGENTS.md。全域偏好會影響其他專案,等你確定哪些要求真的通用,再參考及官方文件處理。

官方規則發現流程找不到專案根目錄時,只檢查目前目錄;所以本例必須從 codex-practice 根目錄開始,不能從它的任意子資料夾啟動後假定會往上找到規則。已有儲存庫的根目錄與子目錄比較見。需要拆分長文件時看。

第一步:確認位置與檔名

Windows 在檔案總管開啟 codex-practice,顯示副檔名,使用文字編輯器新增 AGENTS.md。確認它沒有變成 AGENTS.md.txt。若用 PowerShell,在資料夾空白處開啟終端機後輸入下方命令;結果應列出五個練習檔案。看到 expected 的上一層時,先進入正確目錄再繼續。

Windows PowerShell;目前位置應為 codex-practice · powershell
Get-Location
Get-ChildItem -Name

macOS 在 Finder 選取練習資料夾後開啟終端機,或在 Terminal 使用 cd 加上拖入的資料夾路徑。Linux 在檔案管理員使用「在終端機開啟」。兩者都用下面的命令確認位置,再以純文字編輯器建立同名檔案;大小寫保持一致,避免 Linux 找不到規則。

macOS / Linux 終端機;目前位置應為 codex-practice · bash
pwd
ls -a

如果目錄已經有 AGENTS.md,先讀取並保留原文,只合併本次需要的條目。練習副本應沒有該檔案;不要為了照抄步驟而覆蓋另一個專案的規則。

第二步:寫入一份完整規則

以下是完整檔案,不需要另外安裝套件。範例使用英文以便五語文章共用同一份內容;你也可以用自己熟悉的語言寫規則。真正重要的是命令存在、範圍具體,以及讀者能確認要求是否完成。

寫入 codex-practice/AGENTS.md;完整檔案內容 · markdown
# 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。指引在工作階段建立時讀取,不要只在原對話修改檔案後猜測它已重新載入。

貼到新的 Codex 任務或 CLI 對話;第一輪只讀取 · text
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,摘要測試、畫面與交付要求。回答只是第一個線索,還要開啟檔案核對實際內容。若它只複述你的提示詞、沒有正確路徑,先處理工作目錄與檔名問題,再做修改。

第四步:用小修改檢查行為

貼到同一個已核對規則的 Codex 任務 · text
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 個失敗。這只驗證命令與回報,不代表已實測所有規則分支。

同一個 Codex 任務;額外檢查測試命令 · text
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 規則載入宣稱為本機實測。接著可讀、及。

10. AGENTS.md 專案規則 — 實作順序示意圖,非產品介面截圖。 Global → Project → Working directory
10. AGENTS.md 專案規則 — 實作順序示意圖,非產品介面截圖。 Global → Project → Working directory · 圖片:Mokaair (© Mokaair)
閱讀完整文字說明

Global to Project to Working directory

覺得這篇整理實用嗎?分享給需要的朋友

LINE 分享

回總目錄

  • 生活分享

    Codex 學習中心:完整教學目錄

    從安裝、第一個任務到 MD 規則與進階整合,規劃 60 篇 Codex 教學、十個單元。依程度、平台、需求或指令搜尋下一篇;尚未公開的教學會標示狀態,方便安排學習路線。

  • 生活分享

    Worktree 與多任務隔離

    Worktree 讓同一個 Git 程式庫有不同的工作目錄,各自承接不同分支。它適合讓兩項工作分開改檔,但資料庫、連接埠與外部服務仍可能共用,不能把檔案隔離當成所有資源隔離。

  • 生活分享

    實戰:製作小網站

    從 brief.md 規劃並製作 Small Steps 待辦網站,完成新增、完成、刪除、篩選與本機資料保存。將 HTML、CSS、資料函式、畫面事件與測試分開,以 Node 測試和瀏覽器操作驗收,並留下可重新啟動與還原的交接紀錄。

  • 生活分享

    用量與效率:減少重工

    記錄任務條件、模型選項、時間與成果,找出能減少無效重試和過多上下文的調整。

資料來源

本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。

生活分享