// 協議
copilot-instructions.md
定義 Copilot 在這個程式碼庫中該有的行為。
面向 GitHub Copilot CLI 使用者
Copilot 每次工作階段都從一無所知開始。
自訂指示告訴 Copilot 該如何行事，卻沒有告訴它你的儲存庫裡有什麼。Maguyva 會為程式碼庫建立索引，並透過 MCP 提供回來，讓 GitHub Copilot CLI 編輯時就像已經讀過程式碼一樣。
Free 方案：3 個儲存庫, 最多索引 5 萬行儲存庫程式碼，免信用卡。
用指示來約束行為，用 Maguyva 來取得目前程式碼庫的真實情況。分層的技術堆疊
四個概念，各司其職。
自訂指示是一份工作約定，請善用它。
# .github/copilot-instructions.md
- 優先遵循現有的模組邊界。
- 在提出合併之前執行儲存庫的測試指令。
- 不要臆造檔案路徑。建立新套件前先確認。持久性指示應該放在 .github/copilot-instructions.md中。這是存放以下內容的合適位置：
- Copilot 應執行的建置、測試與 lint 指令。
- 僅適用於此儲存庫的「一律做 X／絕不做 Y」規則。
- 命名慣例與審查偏好。
- 指向決策日誌的指標——而不是每個符號的堆砌。
那份檔案從來都不是儲存庫可查詢的索引。它告訴 Copilot 該如何工作，但不會告訴它裡面有什麼。
自訂指示在規模擴大後失效的地方
Copilot 無法僅憑一個 markdown 檔案解決的四種失效模式。
// 指示不是索引
Telling Copilot how to behave does not tell it which class owns parseConfig, or which package actually implements the public API. 在陌生程式碼樹上的第一次編輯，只是對檔案結構的一種猜測。
// 文件會過時，程式碼不會
描述上一季驗證流程的指示區塊，會在有人拆分工作階段儲存區的那天徹底出錯。 Copilot will prefer the file you committed over the code that shipped.
// 相依關係不在 markdown 裡
“是什麼匯入了這個？” is a graph question. 指示無法列出每一個呼叫者，而你其實也不會想要那樣。
// 上下文視窗是有預算的
把更多儲存庫內容塞進指示，等於用推理 token 換取一份過時的快照。超過幾 KB 之後，你付出的代價就是一份更差的地圖。
作為附加層的 Maguyva
Copilot 已經在用指示和工具進行思考。
copilot-instructions.md
約定
Copilot 如何表現
MCP
通道
如何存取
Maguyva
程式碼庫事實
它能看到什麼
- 可查詢的儲存庫地圖 作為遠端 streamable-HTTP 伺服器透過 MCP 提供。
- 11 個面向客戶的工具 涵蓋語意、結構（AST）、圖形與文字搜尋，外加符號、依賴方與檔案擷取。
- 帶有檔案路徑與行號的排序結果 涵蓋 284+ 種語言與以文字為基礎的技術。
- 一份設定 同一個工作區在 Copilot、Claude Code、Cursor、Codex 以及任何其他相容 MCP 的用戶端中給出相同的回答。
自訂指示告訴 Copilot 該如何表現。
Maguyva 給 Copilot 提供一份可查詢的程式碼地圖。
三種工作流程
在接受差異之前先向地圖提問。
// workflow 01
找到真正的實作，而不是測試樁
copilot> normalizePhoneNumber 如何處理 E.164？ semantic::query("normalize phone E.164") src/util/phone.ts:88 normalizePhoneNumber() ← 真實實作 test/util/phone.spec.ts:14 jest.mock(...) ← 樁程式 → Copilot 開啟的是真實實作，而不是 mock。 [exit 0]
名稱會騙人。Mock 會掩蓋真實程式碼。Maguyva 會把真實實作排在測試 mock 之上。
// workflow 02
重構前檢查影響範圍
copilot> 什麼呼叫了 QueueDispatcher.publish？ graph::callers(QueueDispatcher.publish) src/billing/* 中有 3 處 src/audit/* 中有 1 處 src/notifications/* 中有 1 處 → diff 以真實的匯入者為依據。 [exit 0]
跨套件呼叫點會直接內嵌顯示。diff 以真實的匯入者為依據，而不是 Copilot 的 grep 結果。
// workflow 03
重新命名共用類別，先找出每一個依賴方
copilot> rename PaymentClient → BillingClient graph::callers(PaymentClient) 7 個套件中共 12 處參照 graph::importers(src/payments/client.ts) 9 個匯入者 graph::extends(PaymentClient) 2 個子類別（RetryClient、MockClient） → Copilot 提出的遷移方案已內含檔案清單。 [exit 0]
Copilot 會在開始編輯之前先向 Maguyva 詢問依賴方。遷移清單回傳時以真實的相依圖為依據，而不是 Copilot 的記憶。
在 GitHub Copilot CLI 中設定
三個步驟。Free 方案：3 個儲存庫, 最多索引 5 萬行儲存庫程式碼，免信用卡。
// step 01
在 maguyva.ai 上為一個儲存庫建立索引
選擇一個你已經熟悉的儲存庫，這樣你就能評估答案的準確性。免費註冊、連接 GitHub，然後等待索引完成。
// step 02
在 Copilot 中將 Maguyva 新增為遠端 MCP 伺服器
copilot mcp add --transport http --header "Authorization: Bearer mgv_xxxx" maguyva https://maguyva.tools/mcp~/.copilot/mcp-config.json{ "mcpServers": { "maguyva": { "type": "http", "url": "https://maguyva.tools/mcp", "headers": { "Authorization": "Bearer mgv_xxxx" } } } }// step 03
提出一個你已經知道答案的問題
不要一開始就問整間公司範圍的問題。先提出一個你已經知道答案的問題，然後開啟被引用的檔案。