跳至主要內容

給 Gemini CLI 使用者

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

GEMINI.md 設定工作脈絡，MCP 讓 Gemini 能夠取用工具。Maguyva 則是讓 Gemini 取得可查詢程式碼庫地圖的 MCP 伺服器，讓第一次修改不再是對檔案結構的猜測。

免費開始閱讀 Gemini 設定說明

Free 方案：3 個儲存庫, 最多 5 萬行索引儲存庫行數，免信用卡。

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

分層的技術堆疊

四個概念，各司其職。

// 脈絡

GEMINI.md

定義 Gemini 在這個程式碼庫中該有的行為。

// 傳輸

MCP

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

// 程式碼庫

Maguyva

回傳紮根程式碼庫事實的 MCP 伺服器。

// 誰付費

以工作區計費，而非席位

代理不需要付席位費。查看價格

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 藉此取用工具與脈絡。（規格文件）
  • Maguyva Gemini 向程式碼庫提問時看到的內容。語意、AST、圖譜與文字搜尋，並回傳檔案路徑與行號。

GEMINI.md 告訴 Gemini該怎麼工作。

Maguyva 給 Gemini可以依據的東西。

三種工作流程

針對 Gemini 打造，紮根於真實的呼叫圖，而不是 Gemini 的 grep。

// workflow 01

重新命名共用類別前，先找出每一個依賴者

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 的記憶。

// workflow 02

找出真正的實作，而不是測試 mock

gemini> 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

重構前先確認影響範圍

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 萬行索引儲存庫行數，免信用卡。

  1. // step 01

    在 maguyva.ai 索引一個程式碼庫

    挑一個你熟悉的程式碼庫，這樣才能驗證答案是否正確。

  2. // step 02

    在你的 Gemini CLI 設定中，把 Maguyva 加為 MCP 伺服器

    // ~/.gemini/settings.json
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer <your-key>"
      }
    }
  }
}

  3. // step 03

    問一個你已經知道答案的問題

    不要一開始就丟出整間公司的規模。從一個程式碼庫、一個可驗證的問題開始。

自助註冊，隨時開放。

索引一個你已經熟悉的程式碼庫。

透過 MCP 連接 Gemini，問一個你能自行驗證答案的問題。

索引您的第一個儲存庫查看相容性文件

Free 方案：3 個儲存庫, 最多 5 萬行索引儲存庫行數，免信用卡。