在軟體團隊引入 GitHub Copilot 的過程中，技術領導者常面臨程式碼一致性難以維持的挑戰：若缺乏團隊層級的統一約束，Copilot 僅會根據公有模型訓練經驗與目前開啟檔案的零散上下文來生成建議。這會導致同一專案中出現截然不同的程式碼風格、違反分層架構約定，甚至在 Pull Request（PR）中引入非預期的外部依賴。
GitHub Copilot 的「儲存庫自訂指令（Repository Custom Instructions）」功能正是為了解決團隊協同難題而設計。研發團隊只需在 Git 儲存庫中維護版本受控的 Markdown 檔案——包含根目錄下的 .github/copilot-instructions.md 與指定路徑的 .github/instructions/**/*.instructions.md，就能將架構分層邊界、命名標準、型別規範、測試準則與安全要求，自動注入全體成員的 Copilot 互動與雲端程式碼審查中。
本文將完整解析 GitHub Copilot 儲存庫自訂指令的運作原理、設定步驟、路徑限定規則、PR 審查整合以及團隊工程實踐的最佳做法。
自訂指令的生效範圍與運作機制
在撰寫規則檔案之前，團隊必須先釐清 GitHub Copilot 在不同開發情境中如何載入自訂指令。
當使用者觸發高階推理與對話流程時，自訂指令會自動組裝進提示詞（Prompt）負載的前置上下文中：
- IDE 內的 Copilot Chat：支援 VS Code、Visual Studio、JetBrains 全系列 IDE（IntelliJ IDEA、PyCharm、WebStorm 等）、Xcode 及 Eclipse。
- GitHub.com 雲端介面：包含網頁端儲存庫對話、Copilot 雲端代理任務（Cloud Agent）以及自動化 PR 建立。
- Copilot Code Review（程式碼審查）：在 GitHub 提交 PR 時，Copilot 審查代理能依據自訂指令對程式碼差異（diff）進行自動化合規性檢驗。
- Copilot CLI：終端機命令列中的輔助互動。
行內自動完成（Ghost Text）的運作差異
需要特別釐清的是，自訂指令檔案主要影響 Copilot Chat、行內重構指令（如 /fix、/explain）、自律 Agent 與 PR 程式碼審查。對於開發者在編輯器中打字時出現的毫秒級行內灰色預測文字（Ghost Text），底層系統為求極低延遲，主要依賴游標鄰近程式碼與開啟的編輯標籤頁，無法即時消化長篇自訂指令。因此，自訂指令適合定位為設計、重構與審查的架構護欄；而對於分號、縮排等嚴格的語法格式，團隊仍需配合 ESLint、Prettier、Ruff 等靜態分析工具與 Git Hook 共同把關。
指令優先順序層級
當專案中存在多個層級的指令時，GitHub Copilot 會依照以下優先權進行合併與採用（由高至低）：
- 個人指令（Personal instructions）：開發者個人在 Copilot 設定中定義的偏好（優先權最高）。
- 路徑專屬指令（Path-specific instructions）：在
.github/instructions/**/*.instructions.md中以 glob 模式匹配當前檔案的規則。 - 儲存庫全域指令（Repository-wide instructions）：專案根目錄的
.github/copilot-instructions.md檔案。 - Agent 專屬指令：如
AGENTS.md、CLAUDE.md或GEMINI.md檔案。 - 組織層級指令（Organization instructions）：由企業管理者在 GitHub 組織層級統一設定的全公司規範（優先權最低）。
第一步：建立全域儲存庫指令（.github/copilot-instructions.md）
全域指令檔案適用於儲存庫內的所有互動，位置固定於儲存庫根目錄：
mkdir -p .github
touch .github/copilot-instructions.md
為了確保大型語言模型能精準執行規則，建議使用清晰的 Markdown 標題、條列式技術要求與肯定句型，避免冗長的背景描述。
團隊規則應涵蓋的核心區塊
- 專案概覽與架構邊界：說明專案核心業務、架構模式（如 Clean Architecture、模組化單體、六角架構）以及明確禁止的依賴方向（例如「Domain 層嚴禁引用資料庫驅動或前端 UI 模型」）。
- 語言版本與技術棧鎖定：指明精確的工具與執行環境版本（如 Node.js 22 LTS、TypeScript 5.5、Next.js 15 App Router）。
- 程式碼風格與模式約束：規定命名原則、非同步錯誤處理機制（如「一律採用 Result 模式，禁止拋出未經封裝的原生例外」）。
- 測試規範與覆蓋標準：指明測試框架（如 Vitest、Jest）、測試結構（AAA 模式）以及新商業邏輯的必要測試案例。
- 安全性與資料驗證：指定輸入檢查函式庫（如 Zod、Pydantic），強制使用參數化 SQL 查詢並嚴禁寫死機密憑證。
範例範本（TypeScript / Next.js 微服務）
# 儲存庫架構規範與程式碼約定
## 專案概況
本儲存庫為核心帳務服務（Core Billing Service），基於 Next.js 與 Node.js 構建，資料庫採用 PostgreSQL，支付端串接 Stripe。
## 架構分層與邊界約定
- 嚴格遵守分層架構：UI 組件層 (`/app`, `/components`) -> 應用服務層 (`/src/services`) -> 領域模型層 (`/src/domain`) -> 基礎設施倉儲層 (`/src/infrastructure`)。
- 領域模型層必須保持框架無關，嚴禁在 `/src/domain` 中引入 `next/*` 或資料庫連線驅動。
- 資料庫存取一律透過 `/src/infrastructure/repositories` 內的 Prisma 倉儲進行，業務邏輯中嚴禁直接撰寫原生 SQL。
## TypeScript 開發標準
- 全面啟用 TypeScript 5.x strict 模式；嚴禁使用 `any`，必須使用 `unknown` 搭配型別收窄或 Zod Schema 驗證。
- 物件與聯集型別定義優先使用 `type` 別名；僅在宣告具擴充需求的契約介面時使用 `interface`。
- 非同步操作必須以 `Result<T, E>` 型別或結構化錯誤類別處理，嚴禁產生未捕捉的 Promise rejection。
- 善用守衛陳述句（Guard Clauses）提早返回，避免深層巢狀 if/else 結構。
## 狀態管理與資料取得
- 用戶端資料取得一律採用 TanStack Query (`@tanstack/react-query`)，嚴禁在 `useEffect` 中直接觸發未快取的 API 呼叫。
- Server Actions 在呼叫領域服務前，必須使用 Zod 完成入參驗證。
## 測試規範
- 測試框架：Vitest 搭配 React Testing Library。
- 單元測試檔案必須與原始碼檔案同目錄存放（命名遵循 `*.spec.ts` 或 `*.spec.tsx`）。
- 測試案例必須符合 Arrange-Act-Assert（AAA）結構。
- 網路邊界一律透過 Mock Service Worker (MSW) 進行模擬，不得 Mock 語言內建基礎類別。
## 常見指令參考
- 執行測試：`pnpm test`
- 型別檢查：`pnpm typecheck`
- 程式碼檢驗：`pnpm lint`
第二步：配置路徑專屬指令（.github/instructions/）
在大型 Monorepo 或全端專案中，若將所有子領域的規範全部塞入單一檔案，容易消耗過多 Token 並降低 AI 的遵循精確度。例如，當後端工程師修改 Go 微服務時，前端 React 的 Tailwind 規則只會造成無謂的干擾。
透過路徑專屬指令，團隊可使用檔案匹配路徑（glob）精準提供特定目錄所需的約束。
目錄結構規劃
將各模組指令檔案統整存放在 .github/instructions/ 目錄中：
.github/
├── copilot-instructions.md
└── instructions/
├── frontend.instructions.md
├── backend.instructions.md
└── migrations.instructions.md
檔案命名與 Frontmatter 語法
路徑專屬檔案名稱必須以 .instructions.md 結尾，且開頭必須包含 YAML Frontmatter 區塊並宣告 applyTo：
---
applyTo: "apps/web/**/*.{ts,tsx}"
---
# 前端組件開發標準
- 組件必須為具名匯出的函式型組件（Named Functional Components）。
- 樣式統一採用 Tailwind CSS 工具類別，嚴禁行內 CSS 物件。
- 所有具互動行為的元素均須具備適當的 `aria-*` 無障礙屬性與鍵盤支援。
- 圖示庫統一從 `lucide-react` 匯入。
常見 Glob 比對模式
**/*.py：遞迴匹配專案中所有 Python 檔案。services/billing/**/*.go：限定僅適用於帳務微服務的 Go 程式碼。**/*.test.ts,**/*.spec.ts：以半形逗點分隔，同時比對兩種副檔名的測試檔案。
排除特定代理角色（excludeAgent）
若特定指令專為 Copilot 雲端代理建置而設，且不希望在自動 PR 程式碼審查時觸發，可在 Frontmatter 加上 excludeAgent：
---
applyTo: "**"
excludeAgent: "code-review"
---
# 雲端代理自主構建指引
- 執行整合測試前，必須先執行 `pnpm db:migrate`。
- 新增環境變數時，必須同步更新 `.env.example`。
第三步：啟用 GitHub PR 程式碼審查的自動化檢核
自訂指令不僅能輔助編輯器中的即時寫作，還能作為 Copilot 審查 PR 時的評估準則。
設定啟用步驟
- 開啟 GitHub 儲存庫頁面，點選 Settings（設定）。
- 在左側導覽列找到 Code, planning, and automation -> Copilot -> Code review。
- 開啟 Use custom instructions when reviewing pull requests（審查 pull request 時使用自訂指令）切換開關。
分支讀取機制（Head Branch）
進行 PR 審查時，GitHub Copilot 會讀取 來源分支（Head Branch） 上的 .github/copilot-instructions.md 與相關規則，而非目標分支（如 main）。
這項設計極具實務優勢：當架構團隊想要升級編程標準時，可以在功能分支中同步更新指令檔案與示範程式碼。Copilot 會直接依據功能分支上的新規則進行差異審查，讓團隊在合併至主幹分支前就能先行驗證規則成效。
第四步：驗證開發端工作區的指令載入狀態
為確認團隊成員的 IDE 已正確載入指令，可進行以下驗證：
- 確認 IDE 設定：
- VS Code：按下
Ctrl+,或Cmd+,開啟設定，搜尋instruction file，確認 Code Generation: Use Instruction Files 保持勾選（預設為開啟）。 - JetBrains IDE：在 Copilot Chat 面板點擊右上角齒輪圖示，進入 Customizations，即可檢視專案中目前生效的指令設定。
- VS Code：按下
- 檢查 Chat 回應的引用資訊（References）：
- 在 Copilot Chat 提出技術問題（例如：「請為此模組新增授權檢查函式」）。
- 展開回答頂端的 References（參考資料） 列表。
- 若設定成功，列表中會明確顯示
.github/copilot-instructions.md或相符的.instructions.md檔案連結，代表模型已將該規則納入提示上下文。
團隊工程實踐與常見地雷
| 推薦實踐 | 高風險錯誤 | 對團隊效率的影響 |
|---|---|---|
| 精準歸納核心架構邊界與硬性規範 | 將幾十頁的內部 Wiki 文件整份複製貼上 | 佔用模型上下文視窗；導致關鍵規範被遺漏 |
| 採用具體可行的指示（如「輸入參數一律以 Zod 驗證」） | 使用抽象空洞的口號（如「撰寫乾淨且具備擴充性的程式碼」） | 模型缺乏判斷準則，依舊產出平庸程式碼 |
依模組路徑以 .instructions.md 進行關注點分離 | 將前後端不同語言的規則雜糅於單一全域檔案 | 跨技術棧規則互相干擾或產生語義矛盾 |
| 指令提示搭配確定性 CI 工具（Linter/Test）共同把關 | 誤以為 Copilot 自訂指令可取代 CI 檢查管道 | 模型具機率特性，極端情況仍可能漏網 |
| 納入 Git 版本控管並透過 PR 流程審查更新 | 個別成員僅在本地暫存個人隨意設定 | 團隊標準脫節，缺乏集中維護機制 |
搭配 Prompt 範本檔案（.github/prompts/*.prompt.md）
儲存庫自訂指令用於維持「專案常態性約束」，而對於經常重複的特定標準流程（如新增 API 端點、資料庫遷移檔案、生成單元測試案例），團隊可進一步引入公開預覽中的 Copilot Prompt 檔案。
將常用的流程規格放置於 .github/prompts/ 內，團隊成員即可在 Chat 中快速呼叫結構化任務，而底層的 .github/copilot-instructions.md 則會確保生成結果始終遵循統一的架構約定。
團隊導入檢查清單
- 在儲存庫根目錄建立
.github/copilot-instructions.md，定義分層邊界、技術版本與不可妥協的編程規範。 - 針對特定目錄或多語言 Monorepo，在
.github/instructions/下建立具備applyTo的模組化規則。 - 於 GitHub 儲存庫設定中開啟 PR Code Review 的自訂指令支援。
- 於 IDE 中透過 Copilot Chat 的 References 列表驗證檔案是否成功載入。
- 隨專案演進與套件版本更新，在日常 PR 中持續迭代與修訂指令內容。
參考資料
- Adding repository custom instructions for GitHub Copilot - GitHub Docs
- Adding repository custom instructions for GitHub Copilot in your IDE - GitHub Docs
- Support for different types of custom instructions - GitHub Docs
- About customizing GitHub Copilot responses - GitHub Docs
- 5 tips for writing better custom instructions for Copilot - The GitHub Blog