05 · Copilot 的上下文工程

Copilot 輸出差，很多時候不是“模型不行”，而是上下文工程（context engineering）沒做好。它看錯檔案、讀到過期規則、沒拿到 issue 背景、被衝突 instructions 干擾，結果就會像一個不瞭解專案的人在猜。

1. Copilot 的上下文來源

flowchart TD
  Request["一次 Copilot 請求"] --> Local["本地上下文"]
  Request --> Repo["儲存庫規則"]
  Request --> GitHub["GitHub 物件"]
  Request --> Custom["定製能力"]
  Request --> Tools["工具和外部系統"]
  Local --> Files["開啟檔案 / 選區 / diff / terminal"]
  Repo --> Instructions[".github/copilot-instructions.md / AGENTS.md"]
  GitHub --> Objects["issue / PR / branch / checks"]
  Custom --> Prompt["prompt files / Spaces / Memory"]
  Tools --> MCP["MCP servers / agent skills / custom agents"]
  Files --> Answer["Copilot 輸出"]
  Instructions --> Answer
  Objects --> Answer
  Prompt --> Answer
  MCP --> Answer

上下文工程不是堆資訊。目標是讓 Copilot 在合適的時刻看見合適的資訊，並且不要被無關資訊和衝突規則汙染。

2. 檔案上下文：先給它正確現場

IDE 裡的 Copilot 會受當前檔案、選區、開啟的相關檔案、工作區、diff、diagnostics 和 terminal output 影響。你要它修登入 bug，卻只開啟按鈕元件，它很可能圍繞 UI 猜，而不是去看 auth service、session storage 或 route guard。

實操規則：

• 問區域性程式碼：選中具體函式或開啟相鄰檔案。
• 問專案結構：先讓它列入口、路由、配置和測試位置。
• 讓 Agent 改程式碼：明確允許修改的目錄和禁止觸碰的目錄。
• 讓它解釋錯誤：貼完整報錯、命令、執行環境和最近 diff。
• 讓它審 PR：回到 PR diff、checks 和 review comments。

Copilot 不是讀心工具。上下文不明確時，先用 Ask 或 Plan，而不是直接讓 Agent 寫。

3. Custom instructions：穩定規則才寫進去

GitHub 官方響應定製頁列出幾類 instructions：

• Personal instructions：個人偏好。
• Repository-wide instructions：.github/copilot-instructions.md。
• Path-specific instructions：.github/instructions/**/*.instructions.md。
• Agent instructions：AGENTS.md、CLAUDE.md、GEMINI.md。
• Organization instructions：組織級規則。

官方說明的優先順序是：

1. Personal instructions。
2. Path-specific instructions。
3. Repository-wide instructions。
4. Agent instructions。
5. Organization instructions。

這意味著團隊不能隨便堆規則。優先順序不同、作用域不同，衝突會讓輸出變得不穩定。

適合寫進 instructions：

• 專案用途和目錄職責。
• 穩定技術堆疊和版本約束。
• 編碼風格、錯誤處理、測試要求。
• 安全紅線，例如不要記錄 token。
• 審查和構建命令。

不適合寫進去：

• 一次性任務。
• 過期遷移步驟。
• 金鑰、賬號、客戶資訊。
• 含餬口號。
• 和已有規則衝突的偏好。

4. Prompt files 和 Spaces：複用任務上下文

Prompt file 適合把某類重複任務寫成可複用請求，例如"按團隊規範寫測試""審查 API 相容性""生成 release note 草稿"。它比 instructions 更適合任務型內容，因為它不是每次都自動注入。

Spaces 更適合把相關資料組織成一個可複用上下文包，例如一個專案、一個功能域、一組設計文件或團隊知識。它的價值不是讓 Copilot 讀更多，而是讓多人在同一套上下文裡協作。

新手類比：把這幾樣想成"給 Copilot 配工作環境"——

• Custom instructions 像貼在工位牆上的便利貼：永遠在視線裡，每次工作都自動看到（團隊程式碼規範、命名約定）。
• Prompt files 像抽屜裡的固定流程清單：要做"週報""程式碼審查"這類重複活時取出來用，平時不打擾你（"按 PR 模板寫摘要"的標準 prompt）。
• Copilot Spaces 像專題資料夾：把"做好這件事需要的所有材料"裝進去（產品需求文件 + 設計稿 + 歷史決策 + 程式碼片段）然後打包給 Copilot。
• MCP 像給 Copilot 裝電話和鑰匙：讓它能聯絡外部系統（查 Jira issue、讀資料庫 schema、跑監控告警）。
• Memory 像 Copilot 的長期記憶筆記：它自己記下"這個儲存庫的命名規範是 camelCase""錯誤處理統一拋 BizError"，下次進同一個儲存庫直接用。

選擇規則：

5. MCP：外部上下文也是許可權

MCP server 可以把 Copilot 接到外部工具和資料來源。GitHub 官方把 MCP 放進 customization 和 context 擴充套件體系裡，VS Code Agent 工具文件也把 MCP tools 視為 agent 可呼叫工具的一類。

這會明顯提升能力，也會擴大風險：

• 資料庫、工單、雲平臺、日誌系統可能包含敏感資訊。
• 工具輸出會進入模型上下文。
• 有副作用的工具必須經過批准。
• 過多 MCP 會讓 agent 探索無關係統。

團隊策略應該是按任務開工具，而不是預設全開。

6. 一個可執行的上下文模板

任务：
修复登录后刷新页面丢失 session 的问题

上下文：
先看 src/auth、src/routes 和 tests/auth
参考 issue #123 的复现步骤

规则：
遵守 .github/copilot-instructions.md
只改 auth 和 tests/auth
不要修改支付、部署和数据库迁移

验收：
说明改动计划
展示 diff
运行 auth 相关测试

這個模板的關鍵不是格式，而是讓 Copilot 同時拿到任務、上下文、邊界和驗收標準。

7. 除錯壞上下文

當 Copilot 輸出明顯跑偏，按這個順序排查：

1. 它是否看到了正確檔案？
2. 是否缺少 issue、PR、報錯或終端輸出？
3. instructions 是否過期或衝突？
4. path-specific instructions 是否覆蓋了當前路徑？
5. MCP 是否開啟了無關工具？
6. 任務是否應該先 Plan，而不是直接 Agent？

不要用更長 prompt 掩蓋壞上下文。先把錯誤上下文拿掉，再補必要資訊。

本章自檢

你應該能回答：

• 當前 Copilot 請求會讀取哪些上下文？
• 哪些規則是自動注入，哪些是本次任務臨時提供？
• instructions 是否短、穩定、無衝突、無敏感資訊？
• MCP 工具是否按任務最小授權？

透過標準：你能控制 Copilot 看什麼、不看什麼、能做什麼，並把輸出回到 diff 和測試驗證。

官方來源

• About customizing GitHub Copilot responses：官方 custom instructions、prompt files、優先順序和寫法原則。
• GitHub Copilot features：官方 customization 能力清單，包含 Spaces、Memory、MCP、skills 和 custom agents。
• Tools in VS Code：VS Code 官方工具機制，說明 built-in、MCP、extension tools 和批准邊界。
• About Model Context Protocol：GitHub 官方 MCP 概念頁。

接下來去哪