# GEMINI.md 告诉 Gemini 你的规则。却不会让它了解你的代码。

Canonical source: https://maguyva.ai/zh-hans/for-gemini

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).

GEMINI.md 设定工作上下文。MCP 让 Gemini 能够调用工具。Maguyva 是那台 MCP 服务器，为 Gemini 提供一张可查询的代码仓库地图，让第一次编辑不再是对文件结构的猜测。

> GEMINI.md 是上下文，MCP 是通道，Maguyva 是地图。

## 分层的技术栈

四个概念，各司其职。

### GEMINI.md

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

### MCP

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

### Maguyva

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

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

智能体不需要付坐席费。[查看定价](https://maguyva.ai/zh-hans/pricing)

## GEMINI.md 是一份工作上下文，好好用它。

持久化的指令应该放进 `GEMINI.md`。它正适合承载：

- Gemini 应该运行的构建、测试和 lint 命令。
- 限定在某个目录范围内的“永远做 X / 永远别做 Y”护栏。
- 命名规范和重构偏好。
- 指向权威决策日志和架构说明的指引。

保持简洁，划定范围，提交它。

但 `GEMINI.md` 从来就不是为了充当你代码仓库中每一个符号、文件和调用点的可查询索引而设计的。

## 光靠 GEMINI.md 就力不从心的地方

四种失效模式，每张卡片一种。

### // 上下文不是索引

告诉 Gemini *该怎么工作*，不等于告诉它*代码库里有什么*。在陌生的包上做第一次编辑，还是得靠猜文件路径和函数名。GEMINI.md 没法列出每一个符号，你也不会希望它这么干。

### // 文档会偏离代码

一段描述你队列拓扑结构的 GEMINI.md 内容，在有人引入新的消费者之前都是对的。此后代码才是唯一的真相来源，文档则自信满满地过时了。Gemini 读到的是错的那一份。

### // 重命名是个图谱问题

“什么引用了这个类？”这个问题，markdown 文件是回答不了的。Gemini 要么在整个 monorepo 里 grep 一把碰运气，要么让你把调用点粘贴进对话。

### // 上下文窗口不是免费的

上下文窗口大，不等于可查询索引。把 GEMINI.md 塞到 Gemini “知道得够多”为止，依然是在用推理预算去换取静态上下文的体积。

## 三层是如何配合的

Gemini 用户其实早就这么想问题了，这个页面只是把它说明白。

- **GEMINI.md**: 上下文 (Gemini 如何表现)
- **MCP**: 传输通道 (如何获取信息)
- **Maguyva**: 代码库事实 (它看到了什么)

- **GEMINI.md**: Gemini 在这个代码仓库里如何表现。
- **MCP**: Gemini 如何获取工具和上下文。[（规范）](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: 当 Gemini 向代码库提问时看到的东西。语义、AST、图谱和文本搜索的结果，都带着文件路径和行号返回。

> GEMINI.md 告诉 Gemini *该怎么工作*。
> Maguyva 给 Gemini 提供*可以据以工作的东西*。

## 三种工作流

Gemini 专属场景，基于真实的调用图谱，而不是 Gemini 的 grep。

### 01. 重命名共享类之前，先找出所有依赖方

```text
gemini> 重命名 PaymentClient → BillingClient

graph::callers(PaymentClient)            跨 7 个包，共 12 处引用
graph::importers(src/payments/client.ts)  9 个引用方
graph::extends(PaymentClient)             2 个子类（RetryClient、MockClient）

→ Gemini 提出一份包含 21 处编辑的迁移方案，文件清单直接内联展示。
[exit 0]
```

Gemini 在开始编辑*之前*，先向 Maguyva 询问依赖方。返回的迁移清单基于真实图谱，而不是 Gemini 的记忆。

### 02. 找到真正的实现，而不是测试桩

```text
gemini> 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
gemini> 谁调用了 QueueDispatcher.publish？

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

跨包的调用点直接内联展示出来。改动依据的是真实的引用方，而不是 Gemini 的 grep。

## 在 Gemini CLI 中配置

三个步骤。Free 层级：3 个代码仓库, 最多 5 万行索引代码，无需信用卡。

### 01. 在 maguyva.ai 索引一个代码仓库

选一个你熟悉的，方便你验证答案。

### 02. 在你的 Gemini CLI 设置中把 Maguyva 添加为 MCP 服务器

`~/.gemini/settings.json`

```json
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. 问一个你已经知道答案的问题

别一上来就把整个公司丢进去。先从一个代码仓库和一个可验证的问题开始。

## 索引一个你已经熟悉的代码仓库。

通过 MCP 连接 Gemini，问一个你能自行验证答案的问题。