GitHub Copilot repository instructions 教學：通用與路徑規範怎麼設？

想讓 GitHub Copilot 依照專案慣例回覆，先決定規範適用範圍：整個儲存庫共用的規則，寫在根目錄的 .github/copilot-instructions.md；需要依檔案路徑區分的規則，則可另建 .github/instructions 下、檔名以 .instructions.md 結尾的指示檔，並以 applyTo 指定匹配範圍。這就是設定 GitHub Copilot repository instructions 時最重要的檔案選擇。

先選範圍：全儲存庫共用，還是依路徑拆分？

例如，你可以把專案整體的命名與驗證原則放在通用檔，再為特定目錄寫較具體的規範。這是撰寫指示的組織方式，不代表 Copilot 的每種功能都會使用這些檔案；實際支援範圍仍須按使用介面區分。

建立 .github/copilot-instructions.md：把規範寫成可執行的要求

1. 在儲存庫根目錄建立 .github/copilot-instructions.md。檔案位置可對照 GitHub 的儲存庫指示設定文件。
2. 先寫各處都適用的慣例；針對架構、命名、測試或驗證方式，說清楚你希望產出的內容遵守什麼，而不只寫「遵守專案規範」。
3. 若專案有指定的驗證指令，填入實際使用的指令；不要把其他專案的指令直接當成自己的規範。

撰寫時，可用「修改某類程式碼時，沿用同目錄既有的命名方式」這類明確要求，取代籠統的品質口號。指示是提供給 Copilot 的工作脈絡，不是程式碼審查或測試的替代品。

依路徑設定 .instructions.md 與 applyTo

若不同路徑需要不同規則，可在 .github/instructions 或其子目錄新增檔案，例如 .github/instructions/frontend.instructions.md；檔名須以 .instructions.md 結尾。要讓指示依檔案路徑匹配，可在檔案開頭的 YAML frontmatter 設定 applyTo glob。

以下僅示意三行 frontmatter 的寫法，實際路徑模式應依自己的儲存庫調整：

---
applyTo: "src/**/*.ts"
---

接著在下方寫該範圍的規範，並檢查所用模式是否符合預期檔案。

applyTo 不是每份 .instructions.md 的一律必填欄位。這裡使用它，是為了解決「依檔案路徑指定規則」這個需求；不要把這種寫法誤認為所有指示檔唯一的設定方式。VS Code 自訂指示文件可供對照相關設定。

通用與路徑規則同時符合時

當 Copilot 處理的檔案符合某一路徑專屬指示的匹配條件，且儲存庫也有通用指示檔時，GitHub 文件說明兩份指示都會使用。因此，通用檔適合寫共同要求；路徑檔則聚焦該範圍的特殊慣例，避免寫出彼此難以協調的要求。

在 VS Code Copilot Chat 檢查指示是否用於回覆

GitHub 的自訂指示支援表列出，VS Code 的 Copilot Chat 支援 .github/instructions/**/*.instructions.md 路徑專屬指示。設定後，可在相關檔案的工作情境中檢視 Chat 回覆，展開該次回覆的 References，確認預期的指示檔是否出現；這也是 VS Code 文件建議的檢查方式。

References 是檢查指示是否用於該次回覆的線索，不是產出符合規範的證明。仍應閱讀產出的程式碼，並依專案原有流程驗證。若沒有看到預期的檔案，先核對指示檔位置、檔名是否以 .instructions.md 結尾與 applyTo 路徑模式，再確認自己檢查的是哪個介面的回覆。

別把一個介面的支援範圍套到所有 Copilot 功能

除了 VS Code Copilot Chat 的路徑專屬指示，官方支援表也列出 GitHub.com 的 Copilot Chat 支援 .github/copilot-instructions.md 通用指示。這兩項資訊不能直接推論其他介面、行內程式碼補全或其他工作流程也以相同方式使用指示。若你的主要工作介面不同，應先依官方支援表確認，再決定如何分配專案規範。

實務上，先建立簡潔的通用規範；只有當某些檔案確實需要不同要求時，再新增依路徑匹配的指示檔。完成後在 VS Code Copilot Chat 展開該次回覆的 References，檢查預期的指示檔是否出現，並保留人工審查這一步。