AGENTS.md vs AGENTS.override.md：差異與用途一次看懂

隨著 Codex、Cursor、Gemini CLI、OpenCode 等 AI Coding Agent 越來越成熟，使用 AI 寫程式已經不只是「問一句、產生一段 Code」。

當 AI 開始可以讀取整個 Repository、修改多個檔案、執行測試、修正錯誤甚至完成一整個開發任務後，一個新的問題也逐漸浮現：

我們要怎麼告訴 AI，這個專案應該遵守哪些開發規則？

這時就會看到一個越來越重要的檔案：

AGENTS.md

而如果使用 OpenAI Codex，還可能遇到另一個檔案：

AGENTS.override.md

兩個到底有什麼不同？

如果只想先記住一句話，可以這樣理解：

AGENTS.md＝一般、長期的 Agent 開發規範

AGENTS.override.md＝在特定層級取代 AGENTS.md 的高優先權規範

一、AGENTS.md 是什麼？

可以把 AGENTS.md 想成：

「專門寫給 AI Coding Agent 閱讀的 README。」

一般 README.md 主要告訴開發者這個專案如何安裝、啟動與使用。

AGENTS.md 則是告訴 AI：

「你在這個專案工作時，應該怎麼做。」

裡面可以放入：

• 專案架構與技術說明
• Coding Style
• Build 指令
• Test 指令
• Lint 規範
• Git 與 Pull Request 規則
• 哪些目錄可以修改
• 哪些檔案不能修改
• 套件使用限制
• 資安要求
• 任務完成前需要進行哪些驗證
• Definition of Done

例如：

# AGENTS.md

## Project

This is a React + TypeScript application.

## Development

- Use TypeScript strict mode.
- Prefer functional components.
- Do not use `any`.
- Do not modify generated files.

## Testing

Before completing a task:

- Run npm run lint
- Run npm test

## Git

- Do not commit directly to main.
- Use Conventional Commits.

如此一來，每一次 Codex 進入專案，都可以先取得一致的開發規則，而不需要每次重新在 Prompt 裡描述。

二、AGENTS.md 解決的是「長期規則」

過去我們可能會這樣告訴 AI：

「請不要使用 any。」

下一次又要重新說：

「修改完成後記得跑 Test。」

換另一個 Session，又要再提醒：

「不要修改 generated files。」

這些其實都不是「這一次任務的需求」，而是：

專案長期存在的開發規範。

因此更適合放進：

AGENTS.md

概念可以整理成：

Prompt

→ 告訴 AI「這一次要做什麼」

AGENTS.md

→ 告訴 AI「在這個專案裡應該怎麼做」

把「任務」和「規則」分開之後，AI Coding 的上下文會清楚很多。

三、什麼是 AGENTS.override.md？

接下來是最容易混淆的部分：

AGENTS.override.md

Override 的意思就是：

覆寫、取代。

依照 OpenAI Codex 目前官方文件，在每一個目錄尋找 Agent Instructions 時，順序會先檢查：

AGENTS.override.md

接著才是：

AGENTS.md

如果還設定了其他 fallback filename，才會繼續往後尋找。

因此同一個目錄如果同時存在：

project/
├─ AGENTS.md
└─ AGENTS.override.md

Codex 在這一層會選擇：

AGENTS.override.md

而不是：

AGENTS.md

四、最重要的觀念：Override 是「同層替換」

這點非常重要。

很多人可能會把 AGENTS.override.md 理解成：

「先讀 AGENTS.md，再把 override 裡面的規則加上去。」

但以 Codex 的載入邏輯來看，更精確的理解應該是：

在同一個目錄層級中，AGENTS.override.md 取代 AGENTS.md。

例如：

project/
├─ AGENTS.md
└─ backend/
   ├─ AGENTS.md
   └─ AGENTS.override.md

如果 Codex 從：

project/backend/

開始工作，規則鏈可以理解為：

project/AGENTS.md
        ↓
backend/AGENTS.override.md

這時：

backend/AGENTS.md

因為同層已經存在 AGENTS.override.md，所以不會被選入。

但是要注意：

project/AGENTS.md 仍然存在。

也就是說，override 並不是把整個 Repository 裡所有 AGENTS.md 全部取消，而是取代它所在目錄那一層原本要使用的規則檔。

五、什麼是巢狀 AGENTS.md？

AGENTS.md 很實用的一個設計，就是可以依照 Repository 的不同層級建立規範。

例如：

my-project/
│
├─ AGENTS.md
│
├─ frontend/
│  └─ AGENTS.md
│
├─ backend/
│  └─ AGENTS.md
│
└─ database/
   └─ AGENTS.md

最上層的 AGENTS.md 可以定義整個 Repository 的共通規則。

例如：

不要提交 Secrets
所有修改完成後都要測試
遵守專案 Git 規範

而 Frontend 可以另外規定：

使用 React
使用 TypeScript
使用 Vitest
遵守 Component 命名規則

Backend 則可以規定：

使用 Python
遵守 API 規範
執行 pytest
遵守 Logging 規範

這種設計特別適合：

• Monorepo
• 前後端分離專案
• Microservices
• 大型企業系統
• 多語言專案
• 多團隊共同維護的 Repository

六、Layering 與 Override 有什麼不同？

這是理解 AGENTS.md 最重要的概念之一。

巢狀 AGENTS.md：Layering

假設：

project/
├─ AGENTS.md
└─ frontend/
   └─ AGENTS.md

Codex 從 Frontend 工作時，可以形成：

Repository Rules
        ↓
Frontend Rules

也就是從專案根目錄一路往目前工作目錄建立 instruction chain。

越靠近目前工作目錄的規則越具體，如果規則發生衝突，較靠近目前工作目錄的內容具有較高優先性。

這可以稱為：

Layering，階層式疊加。

AGENTS.override.md：Replacement

如果同一層變成：

frontend/
├─ AGENTS.md
└─ AGENTS.override.md

那麼這一層會選擇：

AGENTS.override.md

因此可以稱為：

Replacement，同層替換。

最簡單的記法：

Nested AGENTS.md
＝ Layering
＝ 階層式疊加
AGENTS.override.md
＝ Replacement
＝ 同層替換

七、AGENTS.override.md 可以用在哪些情境？

了解機制之後，接下來看幾個實際使用情境。

情境一：暫時 Debug

平常專案可能規定：

每次修改完成都要跑完整 Test Suite。

但現在正在 Debug Payment 模組，希望暫時只跑 Payment 相關測試。

就可以使用：

# AGENTS.override.md

## Debug Mode

- Only run payment-related tests.
- Do not run the full integration test suite.
- Add verbose logging when diagnosing failures.

Debug 完成後移除 override，就可以重新回到一般規則。

八、Production Incident

正式環境出現問題時，平常允許的開發方式可能不再適用。

一般開發可能允許：

• Refactoring
• Dependency Update
• Optimization
• 新功能

但 Production Incident 最重要的是：

縮小修改範圍並降低風險。

此時可以設定：

# AGENTS.override.md

## Production Incident Mode

- Bug fixes only.
- Do not perform refactoring.
- Do not upgrade dependencies.
- Minimize the change scope.
- Include a rollback plan.
- Run regression tests.

讓 Agent 暫時進入更嚴格的工作模式。

九、Release Freeze

產品準備正式發布前，也可以使用類似方式。

例如：

# AGENTS.override.md

## Release Freeze

- Do not add new features.
- Bug fixes only.
- Do not update dependencies.
- Do not modify public APIs.
- Run the full regression suite.

如此就可以把 AI Agent 的工作範圍限制在：

修 Bug，而不是順便增加功能或重構。

十、特殊敏感模組

Override 不一定只能用於「暫時規則」。

如果專案中的某個模組，本身就需要一套與一般規則不同的要求，也可以使用。

例如：

project/
├─ AGENTS.md
└─ services/
   ├─ AGENTS.md
   └─ payments/
      └─ AGENTS.override.md

Payment Service 可以設定：

# AGENTS.override.md

## Payment Service Rules

- Never log cardholder data.
- Do not modify authentication logic without tests.
- Always run payment integration tests.
- Database migrations must be backward compatible.

這代表進到 Payment Service 工作時，Agent 會使用更適合該模組的特殊規則。

因此要特別注意：

AGENTS.override.md 不一定等於「個人檔案」或「不應 Commit」。

是否加入 Git，應該依團隊需求決定。

如果它代表正式的 Payment Service 規範，就可能應該進入版本控制；如果只是個人暫時 Debug 使用，才比較適合做成本地檔案。

十一、Codex 還有 Global AGENTS.md

除了 Repository 本身，Codex 還支援全域規則。

預設可以放在：

~/.codex/AGENTS.md

它比較像：

個人的 Codex 預設工作規範。

例如：

# ~/.codex/AGENTS.md

## Personal preferences

- Prefer minimal changes.
- Do not add dependencies unless necessary.
- Run appropriate tests after changes.
- Preserve existing project conventions.

如此一來，每個 Repository 都可以繼承這些基本偏好。

十二、Global 也可以 Override

如果：

~/.codex/
├─ AGENTS.md
└─ AGENTS.override.md

兩者同時存在，Codex 會優先選擇：

AGENTS.override.md

OpenAI 官方也特別提到，Global Override 可以拿來做：

Temporary Global Override

也就是暫時改變所有 Codex 工作環境的預設規則，而不需要刪除原本的 AGENTS.md。

移除 override 後，就可以重新恢復原本設定。

十三、完整載入順序怎麼看？

假設環境如下：

~/.codex/
└─ AGENTS.md

project/
├─ AGENTS.md
└─ src/
   ├─ AGENTS.md
   └─ payment/
      └─ AGENTS.override.md

如果目前工作目錄是：

project/src/payment/

可以把 instruction chain 理解成：

Global
~/.codex/AGENTS.md
        ↓
Repository
project/AGENTS.md
        ↓
Module
project/src/AGENTS.md
        ↓
Submodule
project/src/payment/AGENTS.override.md
        ↓
Current Task

也就是：

Global → Repository → Module → Submodule → Current Task

越往下，規則越具體。

十四、實際專案建議怎麼規劃？

如果是一個正常的軟體專案，可以考慮：

my-project/
│
├─ AGENTS.md
│
├─ frontend/
│  └─ AGENTS.md
│
├─ backend/
│  └─ AGENTS.md
│
└─ database/
   └─ AGENTS.md

Root AGENTS.md

適合放：

• 專案目的
• 技術架構
• 共通 Coding Style
• Build
• Test
• Git 規範
• 安全規範
• Definition of Done

frontend/AGENTS.md

適合放：

• Frontend Framework
• Component 規範
• CSS 規範
• UI/UX 原則
• Frontend Test

backend/AGENTS.md

適合放：

• API 規範
• Backend Framework
• Database 操作
• Logging
• Exception Handling
• Backend Test

如此就能讓 AI Agent 取得「剛剛好」的上下文，而不是把數百條規則全部塞進一個檔案。

十五、AGENTS.md 與 AGENTS.override.md 怎麼選？

可以用一個很簡單的判斷方式。

如果這條規則是：

正常情況下長期都需要遵守

放進：

AGENTS.md

如果這條規則代表：

目前這一層需要使用不同於原本 AGENTS.md 的規則

則考慮：

AGENTS.override.md

因此最容易記住的方式就是：

AGENTS.md
＝ 常態規則
AGENTS.override.md
＝ 同層覆寫規則

十六、還有一件事要注意

AGENTS.md 已逐漸成為不同 AI Coding Agent 之間使用的開放格式，但不同工具實際支援的規則載入方式仍可能不同。

尤其：

AGENTS.override.md

自動偵測與優先權行為，不能直接假設所有 Coding Agent 都與 OpenAI Codex 完全一致。

如果同一個專案同時使用：

• Codex
• Cursor
• Gemini CLI
• OpenCode
• Claude Code
• GitHub Copilot

最好還是確認每個工具自己的 Instruction 機制。

本文所介紹的 AGENTS.override.md 載入規則，主要以 OpenAI Codex 官方文件目前的行為為依據。

結語：未來 AI Coding 的重點不只是 Prompt

當 AI 只能補幾行程式碼時，我們最關心的是：

Prompt 要怎麼寫？

但當 AI Coding Agent 可以開始：

• 理解 Repository
• 修改多個檔案
• 執行 Shell
• 執行 Test
• 修正錯誤
• Refactoring
• 完成完整開發任務

真正重要的問題會逐漸變成：

AI 可以做什麼？

AI 應該怎麼做？

AI 有哪些事情不能做？

完成工作的標準又是什麼？

AGENTS.md 就是在回答這些問題。

而 AGENTS.override.md 則讓我們可以在不同目錄、不同模組與特殊情境下，切換成更適合的 Agent 工作規則。

最後用四句話記住：

AGENTS.md＝常態規則

AGENTS.override.md＝同層覆寫

Nested AGENTS.md＝Layering

AGENTS.override.md＝Replacement

如果開始使用 Agentic Coding，除了研究模型能力與 Prompt 技巧之外，如何設計一套清楚、可維護的 Agent Instructions，也會逐漸成為 AI 軟體開發流程中非常重要的一環。

參考資料

OpenAI｜Custom instructions with AGENTS.md

https://developers.openai.com/codex/guides/agents-md/

OpenAI Codex GitHub

https://github.com/openai/codex

AGENTS.md

https://agents.md/