儲存庫自定義指令
說明 Copilot repository instructions、path-specific instructions、AGENTS.md 和 references 驗證方式。
儲存庫自定義指令（repository custom instructions）是給 Copilot 的專案長期上下文。GitHub 官方文件說明，它用來告訴 Copilot 如何理解專案，以及如何構建（build）、測試（test）、驗證（validate）它的改動。
它不應該寫一次性任務，也不應該塞敏感資訊。它應該像專案規範一樣維護。
閱讀目標：讀完本章，你應該能建立 repository-wide、path-specific 和 agent instructions，並知道如何驗證 Copilot 是否使用了它們。
1. 三類儲存庫指令
GitHub 官方文件列出三類 repository custom instructions：
- Repository-wide instructions：適用於儲存庫上下文中的所有請求，檔案是
.github/copilot-instructions.md。 - Path-specific instructions：只適用於匹配路徑的檔案，檔案放在
.github/instructions/下，檔名以.instructions.md結尾。 - Agent instructions：給 AI agents 使用，常見檔名是
AGENTS.md、CLAUDE.md或GEMINI.md。
flowchart TD
Request["Copilot request"] --> Repo[".github/copilot-instructions.md"]
Request --> Path[".github/instructions/*.instructions.md"]
Request --> Agent["AGENTS.md / CLAUDE.md / GEMINI.md"]
Path --> Match{"路徑匹配?"}
Match -->|是| Combine["和儲存庫級規則一起使用"]
Match -->|否| RepoOnly["只用儲存庫級規則"]
Agent --> Nearest["nearest AGENTS.md takes precedence"]
Combine --> Response["Copilot response"]
RepoOnly --> Response
Nearest --> Response
style Repo fill:#dbeafe,stroke:#2563eb,stroke-width:2px
style Path fill:#fef3c7,stroke:#d97706,stroke-width:2px
style Response fill:#dcfce7,stroke:#16a34a,stroke-width:2px2. 檔案結構
推薦結構：
.github/
copilot-instructions.md
instructions/
frontend.instructions.md
backend.instructions.md
tests.instructions.md
AGENTS.mdPath-specific instructions 需要 frontmatter，使用 applyTo 指定 glob：
---
applyTo: "src/**/*.ts"
---
Use the existing error type.
Do not throw raw strings.3. 寫什麼
適合寫：
- 專案用途和核心架構。
- 目錄職責。
- build、test、lint、typecheck 命令。
- 程式碼風格、命名、錯誤處理。
- 安全紅線和不可改路徑。
- PR 和 review 標準。
不適合寫：
- 金鑰、token、賬號。
- 臨時 bug 處理方案。
- 已經過期的遷移說明。
- 個人偏好。
- 空泛口號。
4. 如何驗證生效
官方文件說明，custom instructions 會自動加入相關 Copilot 請求。它們通常不直接顯示在 Chat view 或 inline chat 裡，但可以從 response references 裡驗證。
檢查方式：
- 發起一個和儲存庫有關的 Chat 請求。
- 展開 response 頂部或 References 列表。
- 檢視是否出現
.github/copilot-instructions.md或相關 instruction 檔案。 - 如果沒有出現，檢查 feature 開關、檔案路徑和工具支援矩陣。
5. 支援邊界
不同 Copilot 功能支援的 instruction 型別不同。GitHub 官方支援矩陣會變化，寫教程時不能把某個 IDE 或功能支援狀態永久寫死。
穩定做法：
- 文件內標註
verifiedAt。 - 需要功能支援時連結官方 support matrix。
- 對團隊只寫“我們當前啟用的入口”。
深讀：為什麼 path-specific instructions 能降低上下文汙染
大型儲存庫裡，前端、後端、測試、基礎設施的規則不同。如果全部寫進一個儲存庫級檔案，Copilot 每次都要讀大量無關規則，還可能把後端規則套到前端。
Path-specific instructions 讓規則按檔案匹配載入，資訊更少、更準，也更容易維護。
本章自檢
完成本章後，用這 4 個問題檢查：
- 儲存庫級和路徑級規則是否職責清楚？
applyTo是否準確匹配目標檔案？- 是否能在 References 裡看到對應 instruction 檔案？
- 檔案裡是否沒有敏感資訊和臨時任務？
透過標準：新成員不需要口頭同步，就能讓 Copilot 遵守專案核心規則。
官方來源
- Adding repository custom instructions for GitHub Copilot —— 官方儲存庫指令頁。
- About customizing GitHub Copilot responses —— 官方定製概念頁。
- Support for different types of custom instructions —— 官方支援矩陣。