把重複交代的內容留在專案裡

每次交付任務時，開發者常要重複說明套件管理工具、測試命令、命名方式與不可修改的目錄。這些資訊若只留在單次提示詞（Prompt）中，新工作階段開始後仍要重新輸入，也可能因為少寫一項規則，讓 Codex 採用不同做法。

AGENTS.md 是提供給 Codex 的專案指令檔，適合記錄跨任務都成立的背景與工作規則，例如專案用途、目錄責任、正式指令、程式風格、安全限制與交付格式。

單次任務的目標、錯誤現象與驗收條件則保留在當次提示內容中，兩者共同提供 Codex 執行任務所需的背景。

Codex 開始工作前會讀取這類檔案，並依全域與專案層級組成指令鏈。規則隨儲存庫一起保存後，團隊也能透過版本控制（Version Control）追蹤與審查修改紀錄。

我們繼續延續 codex-hands-on 練習專案，在儲存庫根目錄建立一份 AGENTS.md。內容會整理專案簡介、常用命令、測試方式、命名規則、禁止修改區域、程式碼拉取請求（Pull Request, PR）格式與安全限制，最後請 Codex 回報讀到的規則，確認設定已生效。

先理解 Codex 會讀取哪一份規則

Codex 啟動時會先讀取 Codex 家目錄中的全域規則，預設位置是 ~/.codex/AGENTS.md。接著從專案根目錄一路往目前工作目錄查找同名檔案。根目錄中的規則適用整個儲存庫，子目錄則可以加入該區域專用的工作要求。

規則會依照上層到下層的順序合併，距離目前工作目錄較近的內容具有較高優先順序。若同一個目錄同時存在 AGENTS.override.md 與 AGENTS.md，Codex 會採用 AGENTS.override.md。這類覆寫檔可以用於臨時指令，或完整替代特定模組的既有規則。使用後應移除，或正式納入 AGENTS.md 管理。

Codex 會先確認專案根目錄，再從專案根目錄一路檢查到目前工作目錄，讀取沿途的 AGENTS.md。例如從儲存庫根目錄啟動時，只會取得全域規則與根目錄規則。從 services/payments/ 啟動時，還會取得 services/ 與 services/payments/ 中的規則。平行目錄的 AGENTS.md 不在這條路徑上，因此不會被載入。

Codex 會在每次執行或終端使用者介面（Terminal User Interface, TUI）工作階段開始時建立指令鏈。新增或修改 AGENTS.md 後，重新啟動工作階段，可以確保新的規則被重新讀取。

寫入穩定、能夠執行的專案資訊

一份有用的 AGENTS.md，應讓 Codex 知道如何在這個專案中安全完成工作。README.md 可以保留安裝教學與使用者文件，AGENTS.md 則集中記錄代理人執行任務時需要遵守的操作規則。兩份文件可以引用相同命令，各自描述的使用情境與讀者不同。

專案簡介應說明產品用途、主要語言與關鍵目錄的責任。命令需要寫成可直接執行的完整形式，例如 npm test 或 npm run lint，並註明使用時機。程式碼風格規則也要具體，例如「函式採 camelCase，測試檔名使用 *.test.js」，避免只寫「遵守既有風格」。

禁止修改區域需要附上實際路徑與處理方式。例如 fixtures/expected/ 存放已審核的預期結果，就應明確寫出未取得人工同意不得更新。若某些產生檔必須透過指令重建，也要記錄對應命令，避免 Codex 直接修改輸出檔。安全限制則可以涵蓋正式憑證、部署操作、套件新增與資料刪除。

規則應保持精簡且明確。只適用於單一議題的檔名、暫時除錯結論與本次要修改的函式，留在任務提示中即可。若 AGENTS.md 長期保留過期命令，Codex 可能直接依照錯誤流程執行，因此團隊調整建置或測試流程時，也要同步更新這份文件。

在儲存庫根目錄建立 AGENTS.md

先進入 codex-hands-on 的根目錄，確認目前位置與工作目錄狀態。若專案已經有 AGENTS.md，先請 Codex 讀取並整理現有規則，不要直接覆蓋。我們先假設專案尚未建立這個檔案，並使用前一篇探索取得的命令與目錄資訊作為素材。

cd /path/to/codex-hands-on
pwd
git status --short
find .. -name AGENTS.md -o -name AGENTS.override.md

接著將任務交給 Codex。提示要求它先從 package.json、README、現有程式與測試核對專案資訊，再建立檔案，避免依照一般 node.js 專案慣例補入實際不存在的命令或規則。

請在 codex-hands-on 儲存庫根目錄建立 AGENTS.md。

開始修改前，先讀取 package.json、README、主要程式目錄與測試目錄，確認專案實際使用的啟動、測試與檢查命令。不要猜測不存在的指令。

AGENTS.md 請包含：
1. 專案簡介與主要目錄責任。
2. 安裝、執行、測試與檢查命令，以及各命令的使用時機。
3. 從現有程式和測試歸納出的命名規則。
4. 禁止直接修改的目錄或檔案；若專案沒有證據，請標示待確認。
5. PR 說明應包含的修改摘要與驗證結果。
6. 安全限制：不要讀取或輸出密鑰，不要執行部署，不要操作正式資料，新增套件前必須取得人工同意。

內容使用簡短、可執行的指令。只新增 AGENTS.md，不要修改其他檔案，不要安裝套件、建立提交或執行會改變外部環境的命令。
完成後說明每條規則的專案證據，並顯示 git diff。

Codex 回覆計畫後，先確認它準備讀取的檔案是否涵蓋命令來源、主要程式與測試。若計畫中出現其他無關的行為，例如部署、發布或資料庫操作，應在開始修改前移除這些步驟。

確認範圍後再讓 Codex 建立 AGENTS.md，並檢查最後的差異是否只包含這個檔案。這樣可以把專案規則的建立限制在明確範圍內，也方便後續逐條核對規則與專案現況是否一致。

一份適合入門專案的內容範例

下列範例展示儲存庫根目錄 AGENTS.md 的寫法，命令與路徑必須以實際專案為準。

# AGENTS.md

## Project overview

This repository contains a Node.js CLI that reads issue data,ranks issues, and prints label statistics.

## Repository map

- Keep application code in `src/`.
- Keep automated tests in `test/`.
- Treat files under `fixtures/` as test input data.

## Commands

- Install dependencies with `npm ci`.
- Run the CLI with the script defined in `package.json`.
- Run the full test suite with `npm test` after code changes.
- Run the configured lint command before reporting completion.
- Do not invent a command when it is absent from `package.json`.

## Code conventions

- Follow the module style already used in the file being edited.
- Use camelCase for JavaScript functions and variables.
- Name test files with the existing `*.test.js` pattern.
- Keep parsing, ranking, statistics, and output formatting responsibilities separate.

## Protected areas

- Do not edit generated files or lockfiles unless the task requires it.
- Do not change fixtures solely to make a failing test pass.
- Ask before changing public CLI output or exported function signatures.

## Pull request notes

- Summarize the behavior changed and the files modified.
- List the exact verification commands and their results.
- Record skipped checks, known limitations, and remaining risks.

## Safety

- Never read, print, commit, or modify secrets and credential files.
- Do not run deployment, publishing, or production data commands.
- Ask for approval before adding a dependency.
- Keep edits inside this repository unless the task explicitly says otherwise.

範例使用英文，方便將程式識別字與命令直接嵌入句子。專案團隊也可以使用繁體中文，語言沒有固定要求。每項命令、路徑與限制都應能追溯到專案檔案或團隊已確認的決定。

「不要修改 fixture 只為了讓失敗的測試通過」是一條可直接判斷的限制。Codex 準備修改測試資料時，可以依照這項規則停止操作並要求確認。「請小心修改測試」則沒有說明具體禁止行為，執行時仍可能產生不同解讀。

PR 區段要求列出實際執行的驗證命令與結果，讓審查者能直接確認哪些項目已完成驗證，哪些檢查尚未執行。跳過的檢查、已知限制與剩餘風險也應一併記錄，避免只留下「測試已通過」這類缺少範圍的描述。

若專案尚未確認禁止修改的區域，可以先標示 待確認，再由維護者補齊。不要把推測內容寫成既定規則。初稿可以交給 Codex 整理，完成後仍需要由熟悉儲存庫的人逐項確認，尤其是安全限制、公開介面與正式環境操作相關規則。

區分全域偏好、專案規則與模組規則

全域 ~/.codex/AGENTS.md 適合保存個人的通用工作習慣，例如修改前先執行 git status、完成後回報測試結果，以及加入正式環境套件前先詢問。

語言框架、目錄結構與專案命令會隨儲存庫不同，放在專案根目錄較方便團隊共同維護與審查。

大型單一儲存庫（Monorepo）可以在各自專案子目錄中加入 AGENTS.md，補充特定模組的測試命令與限制。

例如根目錄規定所有修改都要回報測試結果，services/payments/AGENTS.md 再指定付款模組使用的測試指令。從付款目錄啟動 Codex 時，兩層規則會依序合併。

AGENTS.override.md 會取代同一目錄中的 AGENTS.md，上層目錄的規則仍會保留。它適合暫時套用另一套目錄規則，又不想修改原有的 AGENTS.md。移除覆寫檔並重新啟動 Codex 後，該目錄便會恢復使用原本的 AGENTS.md。

若規則預計長期保留並提供團隊共同使用，直接更新 AGENTS.md 會比較清楚。

規則衝突應透過適用範圍寫清楚。例如根目錄指定 npm test，付款模組指定 make test-payments，子目錄檔案就應註明該命令只適用於 services/payments/。這樣開發者與 Codex 都能看出規則的優先關係，也能減少同一項設定散落在多個檔案中重複維護。

驗證規則真的被載入

建立 AGENTS.md 後，先檢查完整差異，確認 Codex 只新增預期內容。特別核對命令是否真的存在於 package.json、路徑是否與專案結構一致，以及「禁止修改」規則是否涵蓋了日常需要維護的檔案。

git diff -- AGENTS.md
git status --short

接著重新啟動 Codex，要求它摘要目前載入的指令來源與專案規則。可以在儲存庫根目錄執行下列命令。--ask-for-approval never 表示這次操作不要求執行需要批准的動作，適合用來讀取並整理規則。

codex --ask-for-approval never "請列出目前載入的指令來源，並摘要專案規則。不要修改檔案。"

回覆應能看到根目錄 AGENTS.md 中定義的專案用途、測試命令、保護區域、PR 格式與安全限制。

若某項規則沒有出現，先確認檔名為大寫複數 AGENTS.md、檔案內容不是空白，並確認 Codex 從預期的儲存庫位置啟動。也要檢查沿途目錄是否存在會影響載入結果的 AGENTS.override.md。

有子目錄規則時，也可以進一步驗證指令鏈。使用 codex --cd path/to/subdir 從指定子目錄啟動，再要求 Codex 列出目前載入的指令來源，確認根目錄與子目錄規則是否依預期順序生效。

修改 AGENTS.md 或 AGENTS.override.md 後，應重新開啟工作階段，讓 Codex 重新建立指令鏈並載入最新內容。

用一個小任務檢查規則是否可用

摘要規則只能確認 Codex 已讀取檔案，還需要透過低風險任務觀察這些規則是否真的影響它的判斷。

可以請 Codex 找出一個現有測試的目的、說明會使用哪條測試命令，並提出修改計畫。

請依照目前載入的 AGENTS.md，閱讀一個與標籤統計相關的測試。
說明該測試保護的行為、若要修改統計邏輯可動到哪些檔案、哪些區域需要先取得確認，以及完成後應執行的驗證命令。

請引用你採用的 AGENTS.md 規則。這一輪只做分析，不要修改檔案或執行安裝。

接著檢查 Codex 是否採用文件中定義的實際測試命令、遵守 fixture 與公開輸出的限制，並清楚標示尚未執行的檢查。

若規則沒有反映在它的計畫中，通常表示文字過於抽象、適用範圍不清楚，或缺少具體路徑與命令。這時可以直接修訂對應段落，再重新驗證。

最後應由開發者審查 AGENTS.md，再決定是否提交。這份檔案會影響往後從儲存庫啟動的 Codex 工作，因此修改時應保留差異審查與團隊共識。

完成後的版本將讓後續 Codex 的工作階段快速取得共同規則，也讓每項限制都能追溯到專案檔案或團隊決定。