# AGENTS.md 告訴 Codex 該怎麼工作。但不會告訴它有什麼。

Canonical source: https://maguyva.ai/zh-hant/for-codex

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

AGENTS.md 設定工作協議，MCP 讓 Codex 能夠取用工具。Maguyva 則是讓 Codex 取得可查詢儲存庫地圖的 MCP 伺服器，讓第一次修改不再是對檔案結構的猜測。

> AGENTS.md 是協議，MCP 是通道，Maguyva 是地圖。

## 分層的技術堆疊

四個概念，各司其職。

### AGENTS.md

定義 Codex 在這個儲存庫中該有的行為。

### MCP

Codex 藉此取用外部工具與脈絡。

### Maguyva

回傳有程式碼依據的儲存庫事實的 MCP 伺服器。

### 以工作區計費，而非席位

代理不需要付席位費。[查看定價](https://maguyva.ai/zh-hant/pricing)

## AGENTS.md 是工作協議，儘管用。

持久性的指示應該寫在 [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md) 裡，這裡適合放：

- Codex 應該執行的建置、測試與 lint 指令。
- 限定在特定目錄範圍內的「一定要做 X／絕對不要做 Y」規範。
- 命名慣例與重構偏好。
- 指向正式決策紀錄與架構說明的連結。

保持精簡、限定範圍、記得提交。

但 `AGENTS.md` 從來就不是設計來當作你儲存庫裡每一個符號、檔案與呼叫點的可查詢索引。

## 規模擴大後，只靠靜態 AGENTS.md 的限制

四種失效模式，一張卡片一種。

### // 協議不是索引

告訴 Codex*該怎麼工作*，不等於告訴它*有什麼存在*。在不熟悉的套件上做第一次修改，就是在猜檔案路徑與函式名稱。AGENTS.md 沒辦法列出每一個符號，你也不會希望它這麼做。

### // 文件會偏離程式碼

一段描述你佇列拓撲的 AGENTS.md 內容，在有人加入新的消費者之前都是對的。程式碼現在才是真相來源，而文件卻自信滿滿地過時了。Codex 讀到的是錯的那份。

### // 重新命名是圖譜問題

「什麼東西參照了這個類別？」是一份 markdown 檔案回答不了的問題。Codex 只能在整個 monorepo 裡靠 grep 碰運氣，或是要你把呼叫點貼進聊天視窗。

### // 脈絡視窗不是免費的

把 AGENTS.md 塞到讓 Codex「覺得知道得夠多」，會吃掉本該用於推理的 token。超過幾 KB 之後，你就是在用答案品質換取靜態脈絡容量。

## 這三層如何協同運作

Codex 使用者早就習慣這種思考方式，這個頁面只是把它說清楚。

- **AGENTS.md**: 協議 (Codex 的行為方式)
- **MCP**: 通道 (它取用資源的方式)
- **Maguyva**: 程式碼庫事實 (它看到的內容)

- **AGENTS.md**: 定義 Codex 在這個儲存庫中的行為方式。
- **MCP**: Codex 藉此取用工具與脈絡。[（規格文件）](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: Codex 向程式碼庫提問時看到的內容。語意、AST、圖譜與文字搜尋，並回傳檔案路徑與行號。

> AGENTS.md 告訴 Codex*該怎麼工作*。
> Maguyva 給 Codex*可以依據的東西*。

## 三種工作流程

針對 Codex 打造，紮根於真實的呼叫圖，而不是 Codex 的 grep。

### 01. 重新命名共用類別前，先找出每一個依賴者

```text
codex> 重新命名 PaymentClient → BillingClient

graph::callers(PaymentClient)            橫跨 7 個套件，共 12 筆參照
graph::importers(src/payments/client.ts)  9 個匯入者
graph::extends(PaymentClient)             2 個子類別（RetryClient、MockClient）

→ Codex 會提出一份 21 處修改的遷移方案，並直接列出檔案清單。
[exit 0]
```

Codex 在動手修改*之前*，會先向 Maguyva 詢問依賴者。回傳的遷移清單紮根於真實的圖譜，而不是 Codex 的記憶。

### 02. 找出真正的實作，而不是測試替身

```text
codex> normalizePhoneNumber 是怎麼處理 E.164 格式的？

semantic::query("正規化電話號碼 E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← 真正的實作
  test/util/phone.spec.ts:14  jest.mock(...)      ← 測試替身
[exit 0]
```

名字會騙人，mock 會掩蓋真正的程式碼。Maguyva 會把真正的實作排在測試 mock 之前。

### 03. 重構前先確認影響範圍

```text
codex> 誰呼叫了 QueueDispatcher.publish？

graph::callers(QueueDispatcher.publish)
  src/billing/* 中有 3 筆    src/audit/* 中有 1 筆    src/notifications/* 中有 1 筆
[exit 0]
```

跨套件的呼叫點會直接顯示在結果中。這份差異紮根於真實的匯入者，而不是 Codex 的 grep。

## 在 Codex CLI 中設定

三個步驟。Free 方案：3 個儲存庫, 最多索引 5 萬行儲存庫程式碼，免信用卡。

### 01. 在 maguyva.ai 索引一個儲存庫

挑一個你熟悉的儲存庫，這樣才能驗證答案是否正確。

### 02. 在你的 Codex 設定中，把 Maguyva 加為 MCP 伺服器

`~/.codex/config.toml`

```text
export MAGUYVA_API_KEY=mgv_xxxx
codex mcp add maguyva --url https://maguyva.tools/mcp --bearer-token-env-var MAGUYVA_API_KEY
```

```toml
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"
```

### 03. 問一個你已經知道答案的問題

不要一開始就丟出整間公司的規模。從一個儲存庫、一個可驗證的問題開始。

## 索引一個你已經熟悉的儲存庫。

透過 MCP 連接 Codex，問一個你能自行驗證答案的問題。