// 约定
AGENTS.md
Codex 在这个代码仓库里该如何表现。
面向 Codex CLI 用户
AGENTS.md 告诉 Codex 该怎么工作。
但不会告诉它那里有什么。
AGENTS.md 设定了工作约定。MCP 让 Codex 能够调用工具。Maguyva 是那台 MCP 服务器，为 Codex 提供一张可查询的代码仓库地图，让第一次编辑不再是对文件结构的猜测。
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> rename 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
找到真正的实现，而不是测试桩
codex> normalizePhoneNumber 是怎么处理 E.164 格式的？ semantic::query("normalize phone E.164") src/util/phone.ts:88 normalizePhoneNumber() ← 真实实现 test/util/phone.spec.ts:14 jest.mock(...) ← 测试桩 [exit 0]
名字会骗人，mock 会遮住真实代码。Maguyva 会把真实实现排在测试 mock 之上。
// workflow 03
重构前先看清影响范围
codex> 谁调用了 QueueDispatcher.publish？ graph::callers(QueueDispatcher.publish) 3 处在 src/billing/* 1 处在 src/audit/* 1 处在 src/notifications/* [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
问一个你已经知道答案的问题
别一上来就把整个公司丢进去。先从一个代码仓库和一个可验证的问题开始。