# Claude 每次工作階段開始時都兩眼一抹黑。

Canonical source: https://maguyva.ai/zh-hant/for-claude-code

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

`CLAUDE.md` 告訴 Claude 該怎麼表現，但不會告訴 Claude 你的程式碼庫裡有什麼。Maguyva 會為程式碼庫建立索引，並透過 MCP 回傳，讓 Claude 修改起來，就像早已讀過這份程式碼一樣。

> 用 CLAUDE.md 定義行為，用 Maguyva 取得最新的程式碼庫事實。

## CLAUDE.md 是最佳實務，儘管用。

```text
> cat CLAUDE.md
# project conventions, commands, scoped rules
```

持久性的指示應該寫在 `CLAUDE.md` 裡，這裡適合放：

- 代理應該執行的建置、測試與 lint 指令。
- 程式碼風格規則與命名慣例。
- 限定在特定目錄範圍內的「一定要做 X／絕對不要做 Y」規範。
- 指向正式文件與決策紀錄的連結。

Anthropic 的[記憶功能文件](https://code.claude.com/docs/en/memory)對此有很好的說明。保持精簡、限定範圍、記得提交。

但 `CLAUDE.md` 從來就不是設計來當作你程式碼庫地圖用的。

## CLAUDE.md 力有未逮之處

四種光靠 markdown 解決不了的失效模式。

### // 這份檔案不等於程式碼庫

告訴 Claude*該怎麼表現*，不等於告訴它*有什麼存在*。在不熟悉的儲存庫上做第一次修改，就是在猜檔案路徑、函式名稱與呼叫點。CLAUDE.md 沒辦法列出每一個符號，你也不會希望它這麼做。

### // 文件會過時，程式碼不會

一段描述你身分驗證流程的 `CLAUDE.md` 內容，在有人重構身分驗證邏輯之前都是對的。程式碼現在才是真相來源，而文件卻自信滿滿地錯著。Claude 讀到的是錯的那份。

### // 依賴關係不在 markdown 裡

「改了這個函式會弄壞什麼？」是一個圖譜問題，文件檔案回答不了。Claude 只能靠 grep 碰運氣，或是要你把檔案貼進聊天視窗。

### // 脈絡視窗是有預算的

把 CLAUDE.md 塞到讓 Claude「覺得知道得夠多」，會吃掉本該用於推理的 token。超過幾 KB 之後，你就是在用答案品質換取脈絡容量。

## Maguyva 補上 CLAUDE.md 覆蓋不到的那一層

一個遠端 MCP 伺服器，能為 Claude Code 提供：

- **語意、AST、圖譜與文字搜尋**: 涵蓋你已索引的儲存庫，並回傳檔案路徑與行號。
- **依賴關係、型別與呼叫點查詢**: 這些是圖譜能回答、而文件檔案回答不了的問題。
- **感知分支的結果**: 讓 Claude 看到它實際正在編輯的那個程式碼版本。
- **以工作區計費**: 而非依席位計費。無論索引 1 個還是 50 個儲存庫，代理都不需要付席位費。

> CLAUDE.md 告訴 Claude*該怎麼表現*。
> Maguyva 給 Claude*一份可查詢的程式碼地圖*。

## 三種工作流程

編號呈現，大量程式碼區塊。都是你早就會問 Claude 的問題，只是這次紮根於真實的程式碼行。

### 01. 找出真正的實作，而不是測試替身

```text
你："我們付款用戶端的重試機制是怎麼運作的？"

沒有 Maguyva → Claude 對 retry 做 grep，找到 14 筆結果，挑一個（通常是測試 mock）。
有 Maguyva    → Maguyva 會回傳符號定義、呼叫點，以及依排序呈現的
                   真正實作 file:line。
```

### 02. 重構前先確認影響範圍

```text
你："誰呼叫了 normalizePhoneNumber？"

Maguyva 回傳：橫跨 4 個套件、共 7 個呼叫點，其中包含一個透過 gRPC stub
匯入它的 Python 服務。Claude 會直接附上遷移清單提出變更方案，
而不是等 CI 變紅之後才發現。
```

### 03. 接受 diff 之前，先驗證代理的說法

```text
Claude："我修改了 src/auth/session.ts:142，修好了權杖刷新的問題。"

問 Maguyva："給我看看 session.ts:130-160，還有任何匯入 session 的地方。"

Maguyva 回傳即時的檔案片段，加上 3 個匯入者。這份 diff 現在紮根於
真實的程式碼行，而不是 Claude 在第 11,000 個 token 時的記憶。
```

## 在 Claude Code 中設定

三個步驟。Free 方案：3 個儲存庫, 最多索引 5 萬行儲存庫程式碼，免信用卡。

### 01. 在 maguyva.ai 索引一個儲存庫

挑一個你熟悉的儲存庫，這樣你才能驗證答案是否正確。Free 方案涵蓋 3 個儲存庫, 最多索引 5 萬行儲存庫程式碼。

### 02. 在 Claude Code 中安裝 Maguyva 外掛

```text
/plugin marketplace add maguyva/agent-plugins
/plugin install maguyva@maguyva

# the plugin reads your key from the environment
export MAGUYVA_API_KEY=mgv_xxxx
```

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

從一個儲存庫、一個可驗證的問題開始，不要一次丟出整間公司的規模。如果答案跟你預期的一樣，就代表設定成功了。

完整說明收錄在[Maguyva 的文件](https://maguyva.ai/zh-hant/docs)中。

## 索引一個你已經熟悉的儲存庫。

測試一個你能自行驗證答案的問題。這就是完整的上手流程。