copilot-instructions.md 怎麼寫：用途、範例、按路徑生效的 instructions 文件與 AGENTS.md 的區別

本文根據 GitHub 官方文檔《Adding repository custom instructions for GitHub Copilot》和《About GitHub Copilot code review》整理，資料核對於 2026-10-11。

適用於誰

• 想讓 Copilot 記住「這個項目怎麼構建、怎麼測試、有哪些約定」的人；
• 搜「copilot-instructions.md 範例」「copilot-instructions.md 用途」「copilot-instructions.md vs agents.md」的人；
• 同時用 Copilot、Cursor、Claude Code，不想維護三份規則的人。

結論先說

1. .github/copilot-instructions.md 是倉庫級的 Copilot 指令：一份 Markdown，儲存後自動附加到這個倉庫裏的 Copilot 請求上。
2. 想讓規則只對某些文件生效，用 .github/instructions/ 下的 名稱.instructions.md，在 frontmatter 裏用 applyTo 寫 glob。
3. AGENTS.md 是跨工具通用的智能體指令，Copilot 也讀；離被處理文件最近的那一份優先。倉庫根目錄下單獨一份 CLAUDE.md 或 GEMINI.md 也可以被當作智能體指令。
4. 官方一句話分工：copilot-instructions.md 是「Copilot，在這個倉庫裏始終記住這些」；路徑指令是「在這些路徑下始終記住這些」；AGENTS.md 是「任何智能體都記住這些」；skills 是「需要時才做這件事」。
5. 多種指令會同時提供給 Copilot，優先級是：個人指令 > 倉庫指令 > 組織指令。盡量別寫互相矛盾的內容。

三類文件對照

寫法一：倉庫級 copilot-instructions.md

1. 在倉庫根目錄建 .github/copilot-instructions.md（沒有 .github 目錄就新建）；
2. 用自然語言、Markdown 格式寫指令。指令之間的空白會被忽略，所以寫成一段、每條一行、或用空行隔開都可以。

一份可以直接改寫的中文範例：

markdown
# 項目說明
這是一個 Next.js 14 + TypeScript 的電商後台，數據庫用 Prisma + MySQL。

## 構建與驗證
- 安裝依賴：pnpm install（不要用 npm）
- 類型檢查：pnpm typecheck；單元測試：pnpm test
- 提交前必須保證以上兩條都通過

## 目錄
- src/app：頁面與路由；src/lib：業務邏輯；prisma/：數據模型
- 不要修改 src/generated/ 下的生成文件

## 約定
- 金額一律用「分」為單位的整數，不用浮點數
- 新接口先寫 zod 校驗，再寫處理邏輯
- 回答和代碼註釋使用簡體中文

官方的建議是讓 Copilot 自己生成初稿：在 github.com/copilot/agents 選中倉庫，貼上官方提供的「onboard 倉庫」提示詞，cloud agent 會通讀倉庫後提交一份 copilot-instructions.md。那段提示詞裏的兩條限制很值得照搬——不超過兩頁、不寫與具體任務相關的內容；目標是讓智能體少走彎路：少因為構建或 CI 失敗被打回、少花時間到處搜尋。在 VS Code 裏，登入後在聊天中輸入 /init 也能生成起步版本。

寫法二：按路徑生效的 instructions 文件

1. 建目錄 .github/instructions（可以再分子目錄）；
2. 新建文件，文件名必須以 .instructions.md 結尾；
3. 文件開頭寫 frontmatter，用 applyTo 指定 glob；多個模式用逗號分隔：

markdown
---
applyTo: "**/*.ts,**/*.tsx"
---
- 組件用具名導出
- 不使用 any；確實需要時寫明原因

常用 glob：**/.py 遞歸匹配所有目錄下的 py 文件；src/.py 只匹配 src 目錄這一層；src/**/*.py 遞歸匹配 src 下所有層級。

1. 可選：用 excludeAgent 讓某個功能不讀這份文件，取值 "code-review" 或 "cloud-agent"：

markdown
---
applyTo: "**"
excludeAgent: "code-review"
---

上面這份只給 cloud agent 用。不寫 excludeAgent 時，代碼審查和 cloud agent 都會用。官方註明：在 GitHub.com 上，路徑指令目前只有 cloud agent 和代碼審查支持。

當某個文件同時命中路徑指令和倉庫級指令時，兩份都會用上。

寫法三：AGENTS.md

可以在倉庫裏放一份或多份 AGENTS.md。Copilot 工作時，目錄樹裏離得最近的那份優先。適合放「換任何工具都成立」的內容：怎麼裝依賴、怎麼跑測試、目錄結構、提交規範。跨工具共用的詳細做法見《AGENTS.md 怎麼寫》；Claude Code 這邊的寫法見《CLAUDE.md 怎麼寫》。

一個實用的分法：通用約定寫進 AGENTS.md，只有 Copilot 才需要的（比如代碼審查的關注點）寫進 copilot-instructions.md，避免同一句話維護兩遍。

怎麼確認生效了

• 指令文件一儲存就可用，會自動加進你提交給 Copilot 的請求；
• 在 github.com/copilot 的聊天裏，把包含指令文件的倉庫作為附件加入對話；
• 展開回答頂部的 References（引用）列表，看裏面有沒有 .github/copilot-instructions.md——列出來了就說明這次用上了。

常見問題

Q：代碼審查沒按我的指令來？

代碼審查預設啟用自定義指令，但可以在倉庫 Settings → Copilot → Code review 裏被關掉，檢查「Use custom instructions when reviewing pull requests」開關。另外官方說明：審查 PR 時讀的是源分支（head）上的指令文件，所以可以在同一個 PR 裏改指令並立刻看到效果。

Q：寫多長合適？

官方給 cloud agent 的生成提示詞限制在兩頁以內。越長佔用上下文越多，也越容易自相矛盾。

Q：個人偏好（比如總是用中文回答）寫哪？

寫個人指令（personal instructions），它優先級最高，而且不會影響同事。

Q：回答質素變差，懷疑是指令衝突？

官方建議盡量避免衝突的指令；排查時可以臨時關閉倉庫指令對比效果。

參考資料

• Adding repository custom instructions for GitHub Copilot（GitHub 官方）：https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions
• Adding repository custom instructions in your IDE（GitHub 官方）：https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/customize-copilot/configure-custom-instructions/add-repository-instructions-in-your-ide
• About GitHub Copilot code review（GitHub 官方，含四類定製方式對照表）：https://docs.github.com/en/copilot/concepts/agents/code-review
• agentsmd/agents.md 倉庫：https://github.com/agentsmd/agents.md