Codex 的 AGENTS.md 檔案是什麼？怎麼用？讓 Codex 永久記住專案規則

目前使用 AI 已經從原本的單純提示詞，進化到了 AI Agent。如果你本身有在使用 Codex，但你不想每次開新聊天視窗，都要從頭告訴 Codex 整個流程，那麼這個時候，就要懂得建立 AGENTS.md 這個檔案。如果你常常用 Codex，你應該很快會遇到一件事：每次開新聊天，都要重新交代規則。AGENTS.md 就是讓 Codex 記住專案規則的工具。

根據 OpenAI 官方文件，AGENTS.md 是給 Codex 的 durable project guidance，也就是「會跟著專案存在的長期指引」。Codex 在開始工作前會讀取 AGENTS.md 這個檔案，讓每次任務都能帶著一致的專案規範進場。

簡單的說，AGENTS.md 就像這個專案寫給 Codex 的「工作守則」。不是每次聊天臨時提醒，而是把重要規則寫成檔案，讓 Codex 進來工作時先看。

AGENTS.md 是什麼？

AGENTS.md 是一個 Markdown 檔案，用來放 Codex 在某個專案或個人環境中應該遵守的固定工作規則。

你可以把它想成：

• 給人看的是 README：告訴人這個專案怎麼用。
• 給 Codex 看的是 AGENTS.md：告訴 Codex 這個專案怎麼工作。

它通常適合放：

• 專案固定規則
• 測試與建置指令
• 寫作風格
• 審查要求
• 資料夾邊界
• 不可碰的檔案
• 每次任務前要先讀的文件
• 輸出格式要求

重點是：它不是一次性聊天 prompt，而是會在未來工作中繼續生效的專案規則。

為什麼 Codex 需要 AGENTS.md？

Codex 很擅長讀檔、改檔、跑指令和整理專案資訊。但它不會天生知道你的習慣。

如果你不寫清楚，它可能會合理推測：

• 這個專案可以直接改檔。
• 測試指令是 npm test。
• 草稿可以直接寫成發布版。
• 來源可以之後再補。
• 每次任務都可以從頭探索資料夾。

這些推測不一定錯，但如果和你的工作流不同，就會造成困擾。

AGENTS.md 適合放哪些內容？

AGENTS.md 適合放的內容，可以分成下面幾類。

1. 專案邊界

這種規則很重要。尤其 Codex 是會讀檔、改檔、跑指令的工具，不是只會聊天的文字框。專案邊界越清楚，越不容易發生「我只是叫你整理文章，你怎麼跑去動別的資料夾」這種事。

2. 固定工作流程

這種規則可以讓 Codex 每次寫文章時都先照流程走，不用你每次從頭提醒。

3. 測試與驗證方式

如果是寫程式的專案，就可以加上測試跟驗證方式。

4. 寫作與語氣規則

如果是寫作工作流，可以加上你平時慣用的寫作與語氣規則。因為文章風格是長期輸出需要。

5. 需要優先讀取的文件

這一條可以讓 Codex 不用每次都需要亂翻資料夾。如果你能在 AGENTS.md 直接告訴它怎麼讀取檔案，這樣以後開新聊天視窗時，就能快速接軌，不用單獨靠記憶。

AGENTS.md 放在哪裡？

官方文件提到，Codex 會從多個位置讀取指引，包含全域 和 專案。

簡單整理如下：

範圍	位置	適合用途
Global	~/.codex/AGENTS.md	你個人所有專案都要遵守的偏好
專案	專案根目錄的 AGENTS.md	這個專案的固定規則
巢狀資料夾	子資料夾裡的 AGENTS.md 或 AGENTS.override.md	某個子模組或資料夾的特殊規則

簡單的說，就是如下這樣的路徑：

~/.codex/AGENTS.md
my-project/
  AGENTS.md
  app/
    AGENTS.md
  scripts/
    AGENTS.override.md

Codex 官方文件有提到，Codex 會在開始時建立指令鏈。Global 層級會先讀；Project 層級會從專案根目錄往目前工作目錄一路往下讀。越靠近目前工作目錄的檔案會靠後加入，因此可以覆蓋前面的較廣泛規則。

白話說：

• 全域規則：像你的個人工作習慣。
• 專案規則：像這個專案的公司規章。
• 子資料夾規則：像某個部門的特殊作業流程。

如果規則衝突，越靠近你目前工作位置的規則通常越具體、越優先考慮。

AGENTS.override.md 是什麼？

除了 AGENTS.md，官方文件也提到 AGENTS.override.md。

簡單的說：

• AGENTS.md：一般長期規則。
• AGENTS.override.md：同層優先讀取的覆蓋規則。

什麼時候適合用 AGENTS.override.md？

• 暫時要覆蓋全域規則。
• 某個子資料夾有完全不同的操作要求。
• 某個服務或模組需要特殊測試指令。

但一般新手不需要一開始就用 AGENTS.override.md。先從專案根目錄的一份 AGENTS.md 開始就好。

怎麼建立 AGENTS.md？

最簡單的方法，就是在專案根目錄建立一個 AGENTS.md。

例如你有一個專案：

my-project/
  README.md
  src/
  package.json

你可以新增：

my-project/
  AGENTS.md
  README.md
  src/
  package.json

內容可以先很簡單，不用一開始就寫得很長。

AGENTS.md 最好的寫法是邊用邊補。Codex 哪裡常誤會，你就把那條規則加進去。這比一開始寫出一份二十頁規範更實際。

AGENTS.md、Prompt、Skill、自動化差在哪？

Codex 裡面有很多容易搞混的東西。下面用白話表格拆開。

名稱	用途	適合情境
Prompt	這一次任務的指令	臨時要求、單次任務
AGENTS.md	專案或個人的長期規則	每次進這個專案都要遵守
Codex Skill	可重複使用的任務工作流程	寫文章、校稿、code review、報告整理等 SOP
自動化	定時或重複執行任務	每天、每週固定跑工作
MCP / Plugin	連接外部工具或打包能力	需要外部系統、工具整合或分發能力

最簡單的區分方式：

• 只想這次有效：寫 prompt。
• 想整個專案都遵守：寫 AGENTS.md。
• 想讓 Codex 學會一套固定任務流程：寫 Skill。
• 想每天固定時間跑：用自動化。
• 想連外部工具：用 MCP 或 Plugin。

總結

AGENTS.md 是 Codex 的專案長期規則檔。它可以讓 Codex 在每次進入專案時，先理解你的固定要求，例如資料夾邊界、測試指令、寫作風格、來源要求、不能碰的檔案與輸出格式。

如果 prompt 是「這次請這樣做」，那 AGENTS.md 就是「在這個專案裡，每次都要這樣做」。

它最適合放那些你不想每次重複交代、但又真的會影響結果品質的規則。尤其是 Codex 會讀檔、改檔、跑指令，規則寫清楚，Codex 執行起來才會事倍功半。

新手建議先從一份簡單的專案根目錄 AGENTS.md 開始，寫清楚工作邊界、必讀文件、輸出格式與驗證方式。等你發現 Codex 常犯哪些錯，再逐步補規則。

簡單的說，AGENTS.md 不是給人看的，而是給 Codex 看的工作規則。寫得好，未來每次讓 Codex 工作，都能少一點重複溝通，多一點穩定輸出。