# GEMINI.md 告訴 Gemini 你的規則。但不會告訴它你的程式碼。

Canonical source: https://maguyva.ai/zh-hant/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 則是讓 Gemini 取得可查詢儲存庫地圖的 MCP 伺服器，讓第一次修改不再是對檔案結構的猜測。

> GEMINI.md 是脈絡，MCP 是通道，Maguyva 是地圖。

## 分層的技術堆疊

四個概念，各司其職。

### GEMINI.md

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

### MCP

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

### Maguyva

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

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

代理不需要付席位費。[查看定價](https://maguyva.ai/zh-hant/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("正規化電話號碼 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)
  src/billing/* 中有 3 筆    src/audit/* 中有 1 筆    src/notifications/* 中有 1 筆
[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，問一個你能自行驗證答案的問題。