AGENTS.md怎麼寫？作用域、優先級、測試與範本

AGENTS.md是給Codex與AI Coding Agent讀取的專案工作說明，用來保存Repository結構、常用命令、程式規則、禁止事項與驗收方式。它能降低每次任務重新解釋專案的成本，但不能取代當次Task、測試、Sandbox、Code Review與人工核准。

Codex會在開始工作前建立指令鏈：先讀取全域AGENTS.override.md或AGENTS.md，再從專案根目錄一路走到目前工作目錄；同一層最多採用一個檔案，越接近工作目錄的規則越晚加入，因此能覆蓋上層廣泛指引。這種分層適合Monorepo與多服務專案，但也要求團隊管理規則衝突與總長度。

重點快讀

全域規則放在Codex Home，專案規則放在Repository，子目錄規則靠近實際程式。
AGENTS.override.md可覆蓋同層AGENTS.md，適合臨時或專用規則。
越接近目前工作目錄的檔案優先級越高。
穩定規則放進AGENTS.md；臨時需求、Issue內容與一次性限制放在Task。
文字規則不是硬性安全層，權限、Sandbox與禁止命令仍要由設定和工具強制。

Codex如何尋找AGENTS.md？

全域層：在預設的~/.codex中，先檢查AGENTS.override.md，沒有時再讀AGENTS.md。
專案層：從Git或專案根目錄往目前工作目錄逐層搜尋。
同層選擇：先檢查AGENTS.override.md，再檢查AGENTS.md與設定的Fallback檔名。
合併順序：從根目錄到子目錄依序串接，較接近目前工作目錄的規則位於後方。
長度限制：達到設定的專案指令上限後停止加入，過長時應拆到更接近工作範圍的子目錄。

~/.codex/
├── AGENTS.md                  # 個人或全域工作習慣

repository/
├── AGENTS.md                  # 全專案規則
├── apps/
│   ├── web/
│   │   └── AGENTS.md          # 前端專用規則
│   └── api/
│       └── AGENTS.override.md # API服務覆蓋規則
└── packages/
    └── shared/
        └── AGENTS.md          # 共用套件規則

若API服務目錄同時存在AGENTS.md與AGENTS.override.md，Codex會使用Override檔。團隊應避免長期保留不明用途的Override，否則正式規則可能被默默遮蔽。

哪些內容適合放進AGENTS.md？

內容	範例
專案概覽	架構、主要服務與核心目錄
安裝與執行	套件管理器、啟動、Build與環境要求
測試命令	單元、整合、E2E、Lint、Type Check
程式規則	命名、錯誤處理、資料存取與依賴限制
禁止事項	不得修改生成檔、Secrets、正式設定與特定模組
變更流程	Branch、Commit、PR與Migration規則
完成回報	修改檔案、測試結果、風險與未完成項目
Code Review規則	領域特定的錯誤與安全檢查

哪些內容不該放進AGENTS.md？

單一Issue或當次任務的臨時要求。
容易過期的版本、網址、帳號與環境狀態。
API Key、密碼、Token與其他秘密資料。
無法驗證的形容詞，例如「寫高品質程式」。
完整聊天紀錄與未確認推論。
可以由Lint、CI、權限或Sandbox硬性強制的規則。

AGENTS.md應保存穩定工作協議。一次性需求放進Task Contract；領域流程放進Skill；硬性權限放進Codex設定、Sandbox與系統政策；文件規格則連到正式來源，避免複製後過期。

可直接套用的AGENTS.md範本

# Repository Guide

## Project overview
- This repository contains the web app, API service, and shared packages.
- Prefer the smallest change that satisfies the issue.

## Setup
- Use `pnpm`; do not use npm or yarn.
- Install dependencies with `pnpm install --frozen-lockfile`.

## Commands
- Development: `pnpm dev`
- Lint: `pnpm lint`
- Type check: `pnpm typecheck`
- Unit tests: `pnpm test`
- Full build: `pnpm build`

## Code rules
- Reuse existing abstractions before adding new dependencies.
- Keep public API changes backward compatible unless the task approves a breaking change.
- Do not weaken tests to make a patch pass.

## File boundaries
- Do not edit generated files under `dist/` or `generated/`.
- Do not modify migrations unless the task explicitly requires it.
- Never add secrets or production credentials.

## Validation
- Run the smallest relevant test first.
- Before finalizing, run lint, typecheck, and affected tests.
- Report commands that could not be run and explain why.

## Final response
- Summarize changed files.
- List tests and results.
- Call out remaining risks and follow-up work.

範本應依專案調整。若Repository包含不同語言或服務，把共用規則留在根目錄，把特定命令與限制放在對應子目錄，避免每次工作載入所有細節。

子目錄規則怎麼拆？

位置	適合內容
Repository根目錄	共同Branch、依賴、基本測試與安全規則
前端目錄	UI元件、Accessibility、Snapshot與前端測試
API目錄	Schema、資料庫、錯誤碼與相容性
基礎設施目錄	Terraform、部署、雲端權限與禁止操作
安全模組	威脅模型、秘密處理與審查規則
文件目錄	格式、連結、範例與發布規則

規則應靠近它所管理的程式。把付款服務的限制放在根目錄，會讓所有任務都承擔無關Context；只放在付款目錄，又能確保處理該服務時才載入。

AGENTS.override.md何時使用？

臨時提高某個模組的安全限制。
在特定工作區或分支使用不同測試方式。
為高風險服務覆蓋一般規則。
在全域層暫時取代個人預設。

Override應有明確原因、Owner與移除日期。長期規則應回寫正式AGENTS.md，避免團隊忘記同層一般檔案已被忽略。

測試指令怎麼寫才有用？

寫出可直接執行的完整命令。
區分局部測試與完整測試。
說明什麼變更需要哪些測試。
記錄預期工作目錄與環境需求。
無法執行時要求回報原因，不得假裝通過。
禁止為了讓Patch通過而刪除或弱化Assertion。

「請確認沒有問題」無法驗收；「修改API後執行pnpm test api、pnpm typecheck與Contract Test」才能讓Agent與人使用相同完成標準。

Code Review規則應靠近程式

Codex官方建議把Code Review Rules放在最接近受規則管理程式的AGENTS.md。全Repository規則放根目錄，服務或領域特定檢查放進子目錄。

安全：認證、授權、Secrets與輸入驗證。
資料：Schema、Migration、交易與資料保留。
產品：Feature Flag、相容性與使用者行為。
效能：N+1 Query、快取、記憶體與延遲。
測試：Regression、Snapshot、E2E與失敗路徑。

文字規則和硬性設定的邊界

AGENTS.md會影響模型行為，但不是不可繞過的政策層。以下項目應由系統設定強制：

禁止工具、命令與檔案路徑。
Sandbox與網路隔離。
正式Secrets與身份驗證。
部署、付款、刪除與管理核准。
最大成本、時間、步數與併發。

專案規則說明「應該怎麼做」，權限與Sandbox決定「實際能不能做」。兩層需要同時存在。

維護AGENTS.md的檢查表

規則是否仍符合目前架構與工具？
命令能否在乾淨環境執行？
是否包含已廢棄API、目錄或套件？
上下層檔案是否互相矛盾？
是否有能轉成測試、Lint或設定的文字規則？
是否過長，應拆到子目錄或Skill？
Override是否仍有必要？

每次架構、測試、套件管理器或發布流程改變時，都應檢查AGENTS.md。過期規則比沒有規則更危險，因為Agent會以為它仍代表團隊現況。

AI Skills與專案規則的分工，可閱讀AI Skills是什麼？SKILL.md、Prompt、Tool與MCP；多Agent平行開發的Branch、Worktree與Merge Gate，可閱讀多代理平行開發怎麼做？。

常見問題

AGENTS.md和README一樣嗎？

不一樣。README主要服務開發者理解與使用專案；AGENTS.md聚焦Agent執行任務時的規則、命令、限制與驗收。

AGENTS.md寫得越長越好嗎？

不是。過長會增加Context與衝突。應保留穩定、高價值規則，把專用內容拆到子目錄或Skill。

AGENTS.md可以保證Codex不犯錯嗎？

不能。它能降低規則遺漏，但結果仍需測試、Diff、Code Review、Sandbox與人工驗收。

官方資料與延伸閱讀

AGENTS.md最好的用途，是讓穩定專案規則有清楚作用域、來源與優先級。它讓Agent更快進入工作，但真正可靠的完成仍由測試、權限與人類審查決定。

AGENTS.md怎麼寫？作用域、優先級、測試指令與完整範本