# AGENTS.md 告诉 Codex 该怎么工作。但不会告诉它那里有什么。

Canonical source: https://maguyva.ai/zh-hans/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 是那台 MCP 服务器，为 Codex 提供一张可查询的代码仓库地图，让第一次编辑不再是对文件结构的猜测。

> AGENTS.md 是约定，MCP 是通道，Maguyva 是地图。

## 分层的技术栈

四个概念，各司其职。

### AGENTS.md

Codex 在这个代码仓库里该如何表现。

### MCP

Codex 如何获取外部工具和上下文。

### Maguyva

返回有依据的仓库事实的 MCP 服务器。

### 按工作区计费，而非按坐席

智能体不需要付坐席费。[查看定价](https://maguyva.ai/zh-hans/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("normalize phone 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)
  3 处在 src/billing/*    1 处在 src/audit/*    1 处在 src/notifications/*
[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，问一个你能自行验证答案的问题。