AGENTS.md 寫法：畀 Codex 跟住你 repo 規則做嘢（附香港團隊範本）

AGENTS.md 是寫給 coding agent 看的 README：一個放在 repo 內的普通 Markdown 檔，列明這個專案怎樣安裝、怎樣測試、有甚麼規矩不能碰。OpenAI 的官方文件說明，Codex 在做任何工作之前都會先讀 AGENTS.md；官方詞彙表亦列明它適用於 ChatGPT 桌面 app、CLI、IDE 擴充和 Cloud。寫好一份，之後每個任務都不用再重複交代「先跑 lint」「不要改這個資料夾」。

資料核對日期：2026 年 9 月 15 日。本文的讀取次序、指令和設定都以 OpenAI 的 Custom instructions with AGENTS.md 官方文件為準。文中三份「香港團隊範本」是本站按官方建議寫的示例，並非任何實際專案或測試結果。Codex 更新頻密，如與你電腦上的畫面不同，以官方文件為準。還未安裝 Codex 的話，先看 Codex CLI 安裝教學或 Codex 桌面版教學。

支援地區（2026 年 9 月 15 日核對）：香港、澳門和中國內地都不在 OpenAI 公開的 ChatGPT 支援國家／地區清單內，亦不在 OpenAI 的 API 支援國家／地區清單內。OpenAI 說明，在清單以外地區存取或提供其服務，可能導致帳戶被封鎖或停用。Codex 要用 ChatGPT 帳戶或 OpenAI API key 登入，兩者都屬於 OpenAI 服務。本文只講解 AGENTS.md 的官方寫法，並不代表你符合使用資格，也不提供任何繞過地區限制的方法。使用前請先閱讀 ChatGPT 香港使用指南；登入方式見 Codex CLI 安裝教學。

一分鐘答案：AGENTS.md 點寫

1. 生成草稿：在 repo 根目錄開 Codex，在 Codex 的輸入框（不是終端機 shell）輸入 /init，Codex 會在目前資料夾建立一份 AGENTS.md 草稿。
2. 按官方六項刪改：repo 結構、怎樣執行專案、build／test／lint 指令、工程慣例和 PR 要求、限制和禁止事項、怎樣才算完成。刪掉空泛句子，指令逐字寫對。
3. 放對位置：個人偏好放 ~/.codex/AGENTS.md，團隊共用規則放 repo 根目錄，個別服務的特別規則放該子資料夾。
4. 檢查有沒有讀到：重新開 Codex，問它「Summarize the current instructions.」，看它複述的規則是否正確。
5. commit 並持續修正：commit repo 內的 AGENTS.md；之後 Codex 重複犯同一個錯，才把對應規則加進去。

規則應該放在哪一個檔案？

AGENTS.md 係咩、Codex 幾時讀

AGENTS.md 是一個開放格式，官方網站把它形容為「README for agents」：專門給 AI coding agent 看的固定位置，放專案背景和工作指示。它只是標準 Markdown，沒有必填欄位，標題可以隨意命名。這個格式現時由 Linux Foundation 旗下的 Agentic AI Foundation 管理。

對 Codex 來說，有三點要先知道：

• 開工前讀：Codex 啟動時會建立一條「指示鏈」（instruction chain），每次執行建立一次；在終端機介面（TUI）通常即是每開一個 session 建立一次。
• 改完要重開：官方說明 Codex 每次執行和每個新 TUI session 開始時都會重建指示鏈，沒有 cache 要手動清除。換言之，你在 session 進行中改了 AGENTS.md，要在目標資料夾重新開 Codex 才會生效。
• 不是另外收費的功能：AGENTS.md 本身只是一個文字檔。官方 Codex 價格頁的功能表在 Plus、Pro、Business、Enterprise／Edu 和 API key 五欄都列明支援「Custom instructions with AGENTS.md」；該表沒有 Free 和 Go 欄，而 OpenAI Help Center 表示 Codex 已包含在各個 ChatGPT 方案，包括 Free 和 Go。要比較方案，請看 Codex 要用邊個 ChatGPT 方案。

Codex 點樣搵 AGENTS.md：全域、repo、子資料夾

按 OpenAI 官方文件，Codex 會由三個層級收集指示：

• 由上而下接駁：Codex 把找到的檔案由根目錄往下串連，中間以空行分隔。越接近目前資料夾的檔案排得越後，所以會蓋過較早的指引。
• 到目前資料夾就停：官方文件說明 Codex 找到你目前的工作資料夾就停止搜尋，所以要把 override 放在最接近專門工作的位置。要讓子資料夾的規則在開工前載入，就在該資料夾開 Codex，或用 --cd 指定。
• 找不到 project root：Codex 只會檢查目前資料夾。
• 每層最多一個檔：如果同一資料夾同時有 AGENTS.override.md 和 AGENTS.md，後者會被忽略。
• 空檔和上限：空檔案會被跳過；預設上限 32 KiB，超出會被截斷。

以下是按官方 payments 範例改寫的資料夾結構：

~/.codex/AGENTS.md                 ← 全域：你個人的習慣
my-shop/                           ← repo 根目錄（Git root）
├── AGENTS.md                      ← 團隊共用規則
└── services/
    ├── payments/
    │   ├── AGENTS.md              ← 被忽略（同層有 override）
    │   └── AGENTS.override.md     ← 付款服務專屬規則
    └── search/
        └── AGENTS.md              ← 搜尋服務規則

在 services/payments 開 Codex 時，官方範例的預期結果是：先列出全域檔，然後是 repo 根目錄的 AGENTS.md，最後是 payments 的 override。services/search/AGENTS.md 不在由根目錄到 payments 的路徑上，所以不會出現在這條指示鏈內。

第一步：用 /init 生成草稿

不用由零開始寫。Codex CLI 內建 /init 指令，官方說明它會在目前資料夾產生一份 AGENTS.md 草稿，讓你修改後 commit，供之後的 session 沿用。

1. 在終端機用 cd 進入 repo 根目錄。本站建議先執行 git status，確認沒有未 commit 的改動，或者先開一個新 branch。
2. 輸入 codex 進入 Codex 的互動介面。
3. 在 Codex 的輸入框輸入 /init。注意這是 Codex 的 slash command，要在 Codex 內輸入，不是在 macOS Terminal 或 Windows PowerShell 的 shell 輸入。
4. Codex 會在目前資料夾建立 AGENTS.md 草稿。用 git diff 或編輯器打開，逐行核對。
5. 按下一節的六項內容修改，確認內容符合團隊實際的 build、測試、審查和發佈方式，然後 commit。

用 ChatGPT 桌面 app 的話，OpenAI Help Center 說明在使用 Codex 時同樣可以輸入 /init，為目前專案生成 AGENTS.md 草稿，流程和 Codex CLI 相同。VS Code 等編輯器的 Codex IDE 擴充，官方指令表亦列有 /init（為目前專案生成 AGENTS.md 草稿），而且讀同一份 AGENTS.md，操作見 Codex VS Code 擴充教學。

官方 best practices 特別提醒：/init 只是起點，生成的內容要按團隊實際 build、測試、審查和發佈的做法修改。本站補充一句：草稿是由 Codex 讀你的 repo 猜出來的，可能會列出並不存在的指令，或者漏掉最重要的禁止事項，所以不要未看就 commit。

AGENTS.md 寫法：官方建議寫的 6 樣嘢

OpenAI 的 Codex best practices 列出一份好的 AGENTS.md 應涵蓋的六項內容。下表把每一項配上寫法示例（示例內容由本站撰寫）：

寫的時候，按官方的幾個原則：

• 短而準確：官方指短而準確的 AGENTS.md，比一份充滿空泛規則的長文件更有用。先寫基本內容，發現重複犯錯才加新規則。
• 寫指令，不寫口號：本站建議把「記得測試」「寫好 code」這類句子改成可以直接照做的指令和檔案路徑。
• 太大就拆：AGENTS.md 開始變得太大時，保持主檔精簡，把規劃、code review、架構等主題放到獨立的 Markdown 檔，在主檔引用。
• 加路線指引：官方的 Customization 文件提到，如果 Codex 找對了檔案但讀了太多文件，可以加「先看哪些資料夾或檔案」的路線指引。
• 放在最近的資料夾：只適用於某個資料夾的指引，放在該資料夾，不要全部塞進根目錄。

香港團隊範本（示例，請按你的 repo 修改）

以下三份是本站按上述官方建議，為香港常見的小型網站或網店團隊寫的示例，並非任何實際專案或 Codex 輸出。pnpm lint、make test-payments 等指令名稱只是示意，請換成你 repo 真正存在的 script；不存在的指令寫進去，只會令 Codex 白費時間。

範本一：repo 根目錄的 AGENTS.md（小型網站團隊）

# AGENTS.md

## 專案結構
- app/：頁面和 API route
- components/：共用 UI 元件
- lib/：商業邏輯和資料存取
- 不要修改 vendor/ 和自動生成的檔案

## 開發指令
- 安裝依賴：pnpm install
- 本機開發：pnpm dev
- 提交前必須通過：pnpm lint、pnpm typecheck、pnpm test

## 寫法慣例
- 程式碼、變數名稱和 code comment 用英文
- 介面文字用香港繁體中文，放在 messages/ 的翻譯檔，不要直接寫死在元件內
- 金額一律使用 lib/ 內現有的貨幣格式函式，不要自行拼接字串
- 日期顯示格式為 YYYY-MM-DD，時區用 Asia/Hong_Kong

## 限制
- 新增 production dependency 之前先問我
- 測試資料、fixture 和 prompt 不可使用真實客戶的姓名、電話、電郵或地址，一律用明顯虛構的資料
- 不要修改 .env 檔案，不要輸出或 commit 任何 API key、token 或密碼

## 完成標準
- 以上三個指令全部通過
- 新功能有對應的測試
- 最後列出新增或修改了哪些檔案，以及怎樣手動驗證

範本二：個人全域 ~/.codex/AGENTS.md

OpenAI 建議用全域檔調整 Codex 怎樣和你溝通，例如審查風格、詳略和預設習慣；團隊和程式碼規則則留在 repo 內。全域檔放在使用者主目錄下的 .codex 資料夾（預設 ~/.codex，如設定了 CODEX_HOME 就放在該資料夾）。官方示例用 mkdir -p ~/.codex 確保資料夾存在，這是 macOS／Linux 的寫法。

# ~/.codex/AGENTS.md

## 溝通方式
- 用香港繁體中文回覆；指令、檔案名稱和錯誤訊息保留英文原文
- 總結保持簡短：先講結論，再列出改動的檔案
- 大範圍改動或重構之前，先列出計劃，等我確認才動手

## 個人習慣
- 我慣用 pnpm；repo 沒有指定套件管理工具時先問我

注意：Codex home 資料夾同時存放設定、日誌和 session 等狀態；如果登入資料用檔案方式儲存（而不是作業系統的憑證儲存區），這裏還會有 auth.json。OpenAI 提醒要把 auth.json 當作密碼：它包含 access token，不要 commit、不要貼到工單、不要在聊天中分享。所以只把 AGENTS.md 放在這裏，不要把整個 .codex 資料夾複製給同事或放進 repo。

範本三：services/payments/AGENTS.override.md（較嚴格的子資料夾規則）

# services/payments/AGENTS.override.md

## 付款服務規則
- 這個資料夾用 make test-payments，不要用 pnpm test
- 除非任務明確要求，不要改動金額計算、退款或 webhook 驗證邏輯；要改之前先解釋影響
- log 和錯誤訊息不可輸出完整卡號、token 或客戶個人資料
- 任何 schema 或 migration 改動，都要附上回滾方法

用 override 之前要想清楚：同一資料夾有 AGENTS.override.md 時，該層的 AGENTS.md 會被忽略，所以 override 要包含這一層需要的全部規則。如果只想在根目錄規則之上補充幾條，在子資料夾放一般的 AGENTS.md 就夠了；根目錄的規則在兩種情況下都會照常載入。

加 Code Review Rules（GitHub 審查用）

AGENTS.md 還有一個專門段落 ## Code Review Rules，是為 Codex 在 GitHub 審查 pull request 而設的。放的位置跟本文前面講的一樣，看規則管哪一段程式碼：全 repo 適用的放根目錄那份，只關乎某個服務的放該子資料夾那份，段落內需要時用 ### 再分組。官方示例每條規則分兩行：上一行寫要標記的行為，下一行用 Safe path: 寫安全做法。骨架如下（括號內容請自行填寫）：

## Code Review Rules

### （規則分組名稱）
- （要標記的行為，以及為甚麼重要）
  Safe path: （正確做法或例外）

寫法只有一個提醒：規則不是越多越好，官方叫人由兩三條開始。至於每條規則怎樣寫、香港網店的實例、要先為 repo 設定 Codex cloud 的步驟，以及這個功能適用於哪些方案，全部見 Codex GitHub code review 教學；本文只負責告訴你這個段落應該住在哪一個 AGENTS.md 裏面。

檢查 Codex 有冇讀到你的規則

寫好之後一定要檢查，否則你不會知道規則是否真的生效。官方文件提供以下方法：

1. 在 repo 根目錄問它讀了甚麼：官方指令是 codex --ask-for-approval never "Summarize the current instructions."，Codex 應按優先次序複述全域和專案檔的指引。
2. 檢查子資料夾：官方示例是 codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."，預期先列全域檔，再列根目錄 AGENTS.md，最後是 payments 的 override。
3. 留一份審計 log：執行 codex -c log_dir=./.codex-log 開啟純文字 TUI log，再查看 ./.codex-log/codex-tui.log，可以看到實際載入了哪些指示檔。本站建議把 .codex-log/ 加進 .gitignore，不要 commit log。
4. 確認所在位置：在 CLI 的 Codex 內輸入 /status，確認目前的模型、approval policy 和可寫範圍（writable roots），看看是否就是你預期的 repo。（IDE 擴充也有 /status，但官方指令表列明它顯示的是 chat ID、context 用量和 rate limit，不包括可寫範圍。）

安全提示（本站建議）：--ask-for-approval never 會關閉審批提示。檢查指示不需要改任何檔案，所以本站建議加上唯讀 sandbox：codex --sandbox read-only --ask-for-approval never "Summarize the current instructions."。OpenAI 的權限文件把 --sandbox read-only --ask-for-approval never 列為「Read-only non-interactive」組合：Codex 只能在唯讀 sandbox 內讀檔和執行命令，亦不會詢問批准。另一個做法是照常開 Codex，在一般 session 內問同一個問題。

如果你用的是 ChatGPT 桌面 app 或 IDE 擴充，本站建議在新開的對話直接問「Summarize the current instructions.」。改完 AGENTS.md 後記得開新對話或 session，因為指示鏈只會在開始時建立。

常見問題排解

fallback 檔名和上限都在 Codex 的設定檔修改。以下是官方示例：

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

設定後，Codex 會在每個資料夾依次找 AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。改完設定要重開 Codex 或執行新指令才會載入。

AGENTS.md、Rules、Skills、Memories、CLAUDE.md 點分工

搜尋「Codex 專案規則」時，常會同時見到幾個名字相近的功能。OpenAI 的 Customization 文件說明它們是互補的：AGENTS.md 塑造行為，memories 延續本機脈絡，skills 封裝可重複的流程，MCP 則連接工作區以外的系統。

如果團隊同時用 Codex 和 Claude Code，Anthropic 的官方做法是在 repo 建立一個 CLAUDE.md，第一行寫 @AGENTS.md，下面再加 Claude Code 專用的補充，兩個工具便讀同一份規則，毋須複製兩份。不需要額外內容時，官方亦提到可以用 symlink；但 Windows 建立 symlink 需要系統管理員權限或開發人員模式，所以官方建議 Windows 用匯入。至於其他工具，AGENTS.md 官方網站列出 Cursor、Gemini CLI、Aider 等相容工具，但讀取方式各有不同，例如 Aider 和 Gemini CLI 要在各自的設定檔指定 AGENTS.md；本文的讀取次序只適用於 Codex。兩個工具的整體分工，見 Codex vs Claude Code 比較。

保持精簡：規則點樣越寫越準

OpenAI 把 AGENTS.md 形容為一個回饋循環：Codex 對你的 codebase 作出錯誤假設時，在 AGENTS.md 修正，並叫它更新檔案，讓之後的 session 沿用這個修正。實際做法：

• 重複犯錯才加規則：同一個錯誤出現兩次，官方建議叫 Codex 做一次回顧（retrospective），再更新 AGENTS.md。
• 重複的 PR 意見：同一句審查意見講過不止一次，就把它寫成規則。
• 在 GitHub 直接交代：在 pull request 留言中 tag @codex，例如 @codex add this to AGENTS.md，會交由一個雲端對話處理更新。這需要 repo 已設定 Codex cloud，完成後照常審查它提交的改動。
• 用工具強制執行：官方建議把 AGENTS.md 配合 pre-commit hooks、linter 和 type checker 使用，由工具在你看到之前擋住問題，不要只靠文字提醒。
• 控制大小：官方價格頁在「令用量上限用得更耐」的建議中，列出縮減 AGENTS.md 的大小：大型專案可以把檔案分拆到 repo 內不同資料夾，控制每次注入多少 context。

保安底線（本站建議）：AGENTS.md 會 commit 到 Git，所有有權限的人都看得到，而且每次都會作為指示交給模型。不要把 API key、token、密碼、內部網址清單或客戶個人資料寫進去；需要時只寫「用哪個環境變數」。Codex 的登入檔 auth.json 不可分享或轉交他人，共用登入資料並不安全。懷疑外洩時，按 帳戶安全檢查表逐項處理。

方案同下一步

AGENTS.md 不用額外付費，任何你可以合規登入的 Codex 入口都會讀它。GitHub 自動審查等雲端功能則按方案而定，比較見 Codex 方案指南，用量機制見 ChatGPT Plus、Pro 與 Codex 用量指南；想按工作量縮窄選擇，可以用 AI 方案比較器。

本站亦有 Codex 方案服務（Codex 跟 ChatGPT 方案行）。本站價格是獨立服務價，並非 OpenAI 官方價格；使用前請先確認自己符合 OpenAI 的使用資格，並了解 代充與成品號的帳戶控制和停權風險。本站與 OpenAI／Anthropic 並無從屬關係；付款前請閱讀 服務條款。

• 未安裝：Codex CLI 安裝教學。
• 在編輯器內用：Codex VS Code 擴充教學，IDE 擴充讀同一份 AGENTS.md。
• 讓 Codex 審查 PR：Codex GitHub code review 教學。
• 封裝重複流程：Codex Skills 教學。
• 更多開發工具文章：開發工具主題。

一份好的 AGENTS.md 不是一次寫成的：先用 /init 起草，只保留真正會用到的指令和紅線，放在正確的資料夾，檢查 Codex 真的讀到，之後每次它重複犯錯，就補一條規則。