// 協議
AGENTS.md
定義 Codex 在這個程式碼庫中該有的行為。
給 Codex CLI 使用者
AGENTS.md 告訴 Codex 該怎麼工作。
但不會告訴它有什麼。
AGENTS.md 設定工作協議，MCP 讓 Codex 能夠取用工具。Maguyva 則是讓 Codex 取得可查詢程式碼庫地圖的 MCP 伺服器，讓第一次修改不再是對檔案結構的猜測。
Free 方案：3 個儲存庫, 最多 5 萬行索引儲存庫行數，免信用卡。
AGENTS.md 是協議，MCP 是通道，Maguyva 是地圖。分層的技術堆疊
四個概念，各司其職。
AGENTS.md 是工作協議，儘管用。
持久性的指示應該寫在 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 藉此取用工具與脈絡。（規格文件）
- Maguyva Codex 向程式碼庫提問時看到的內容。語意、AST、圖譜與文字搜尋，並回傳檔案路徑與行號。
AGENTS.md 告訴 Codex該怎麼工作。
Maguyva 給 Codex可以依據的東西。
三種工作流程
針對 Codex 打造，紮根於真實的呼叫圖，而不是 Codex 的 grep。
// workflow 01
重新命名共用類別前，先找出每一個依賴者
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 的記憶。
// workflow 02
找出真正的實作，而不是測試 mock
codex> normalizePhoneNumber 是怎麼處理 E.164 格式的？ semantic::query("正規化電話號碼 E.164") src/util/phone.ts:88 normalizePhoneNumber() ← 真正的實作 test/util/phone.spec.ts:14 jest.mock(...) ← mock [exit 0]
名字會騙人，mock 會掩蓋真正的程式碼。Maguyva 會把真正的實作排在測試 mock 之前。
// workflow 03
重構前先確認影響範圍
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 萬行索引儲存庫行數，免信用卡。
// step 01
在 maguyva.ai 索引一個程式碼庫
挑一個你熟悉的程式碼庫，這樣才能驗證答案是否正確。
// step 02
在你的 Codex 設定中，把 Maguyva 加為 MCP 伺服器
$ export MAGUYVA_API_KEY=mgv_xxxx $ codex mcp add maguyva --url https://maguyva.tools/mcp \ --bearer-token-env-var MAGUYVA_API_KEY # equivalent ~/.codex/config.toml [mcp_servers.maguyva] url = "https://maguyva.tools/mcp" bearer_token_env_var = "MAGUYVA_API_KEY"// step 03
問一個你已經知道答案的問題
不要一開始就丟出整間公司的規模。從一個程式碼庫、一個可驗證的問題開始。