---
title: "04 · 為什麼 AGENTS.md 能改變 Codex 行為"
description: "面向新手解釋 AGENTS.md 為什麼能讓 Codex 更穩定：它是專案和 Agent 的協作介面。"
canonical: "https://xiangyugongzuoliu.com/openai-codex-agents-md-guide"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

`AGENTS.md` 能改變 Codex 行為，是因為它把“每次都要重複交代的話”變成了任務開始前就會進入上下文的專案規則。

> [!TIP]
> 下個月仍然有效的規則寫進 `AGENTS.md`；只對這次任務有效的細節寫進 prompt。

<Cards>
  <Card title="AGENTS.md" href="https://developers.openai.com/codex/guides/agents-md">
    官方說明如何發現、合併和使用 `AGENTS.md`。
  </Card>
  <Card title="Rules" href="/zh-Hant/docs/codex/official/02-config-security/05-project-rules">
    專案規則頁講全域性、專案、巢狀和排障。
  </Card>
  <Card title="Context engineering" href="/zh-Hant/docs/codex/understanding/context-engineering">
    `AGENTS.md` 是長期上下文，不是一次性任務說明。
  </Card>
</Cards>

## 它本質上是介面

```mermaid
flowchart LR
    Repo["專案事實"] --> Agents["AGENTS.md"]
    Team["團隊約束"] --> Agents
    Agents --> Codex["Codex 行為"]
    Codex --> Work["讀檔案 / 改程式碼 / 跑驗證"]
```

README 主要解釋專案給人看。`AGENTS.md` 主要約束 Agent 怎麼幹活。兩者互補，不互相替代。

沒有專案規則時，Codex 只能猜包管理器、目錄職責、測試命令和禁止事項。有了 `AGENTS.md`，它能先知道專案真實約定，再開始做事。

## 發現順序

Codex 啟動時會構建 instruction chain。官方規則可以理解成三層：

1. Global scope：Codex home 下的 `AGENTS.override.md` 或 `AGENTS.md`。
2. Project scope：從專案根一路到當前目錄，逐層讀取 `AGENTS.override.md`、`AGENTS.md` 或配置裡的 fallback 檔名。
3. Merge order：越靠近當前工作目錄的規則越晚進入上下文，因此更能覆蓋上層規則。

這意味著：

- 全域性檔案適合個人穩定習慣。
- 根目錄檔案適合全倉共同規則。
- 子目錄檔案適合模組規則。
- override 檔案適合臨時強覆蓋，但不能濫用。

## 什麼該寫進去

適合寫：

- 專案用途。
- 技術堆疊。
- 包管理器。
- 目錄職責。
- 啟動、測試、構建、lint 命令。
- 禁止事項。
- 受保護路徑。
- 驗收要求。

不適合寫：

- 本次任務細節。
- 臨時想法。
- 長篇背景。
- 金鑰、賬號、私有 token。
- 沒穩定下來的個人偏好。
- 與現有規則衝突的模板。

如果你第二次對 Codex 糾正同一個問題，這就是寫進規則的訊號。

## 三層內容

第一層是事實：專案用什麼技術堆疊、哪個包管理器、哪些目錄做什麼、哪些命令能驗證。

第二層是約束：哪些檔案不要碰，哪些操作不能預設做，哪些高風險邏輯必須先確認。

第三層是驗收：改完要跑什麼檢查，無法驗證時要怎麼說明，最終交付應該包含哪些證據。

只有事實，沒有約束，就是說明書。只有約束，沒有事實，就是口號。沒有驗收，就無法判斷完成。

## 新手第一次怎麼寫

不要追求完整。先寫六塊：

- 專案概況：一句話說明專案做什麼。
- 目錄職責：列關鍵目錄，不要逐檔案註釋。
- 開發命令：只列啟動、測試、構建、lint。
- 編碼規則：寫具體可執行的約定。
- 禁止事項：寫不能碰的路徑、命令和依賴。
- 驗收要求：寫不同改動型別怎麼檢查。

寫法要具體。“程式碼要優雅”沒有用，因為 Codex 無法驗證。“修改 API handler 後執行某個測試命令”有用，因為它能執行。

## 怎麼維護

`AGENTS.md` 不是一次寫完的文件。它應該隨著專案和團隊實踐迭代。

每次 Codex 犯錯後，先判斷是任務沒寫清，還是專案規則缺失。只有會反覆出現的問題，才沉澱到 `AGENTS.md`。

團隊專案裡，`AGENTS.md` 應該像程式碼一樣走 review。它改變的是所有 Agent 進入專案後的行為，不能隨手改。

如果檔案越來越長，先刪除低價值說明，再把區域性規則拆到更靠近對應目錄的位置。

## 新手常見坑

- 把 README 複製進去：人類介紹太長，Agent 規則不夠清楚。
- 寫一堆抽象要求：無法驗證，無法穩定執行。
- 把任務模板塞進去：每次任務不同，應該寫 prompt。
- 把金鑰、賬號、私有 URL 寫進去。
- 規則互相沖突：根目錄說用 pnpm，子目錄又讓用 npm。
- 沒有驗收要求：Codex 只會說“完成了”。

## 怎麼驗收

讓 Codex 只讀總結當前載入到的規則。它應該能複述專案用途、命令、禁止事項和驗收要求。

給一個小任務，看它是否先讀相關檔案、是否只改允許範圍、是否按規則跑驗證。

檢查最終回覆是否包含改動檔案、驗證結果、未驗證項和剩餘風險。

如果這些沒有發生，優先改 `AGENTS.md` 的具體性，而不是繼續堆更多提示詞。

## 官方資料

- [AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
- [Rules](https://developers.openai.com/codex/rules)
- [Project instructions discovery](https://developers.openai.com/codex/config-advanced#project-instructions-discovery)
