---
title: "儲存庫自定義指令"
description: "說明 Copilot repository instructions、path-specific instructions、AGENTS.md 和 references 驗證方式。"
verifiedAt: "2026-05-06"
---

儲存庫自定義指令（repository custom instructions）是給 Copilot 的專案長期上下文。GitHub 官方文件說明，它用來告訴 Copilot 如何理解專案，以及如何構建（build）、測試（test）、驗證（validate）它的改動。

它不應該寫一次性任務，也不應該塞敏感資訊。它應該像專案規範一樣維護。

> [!TIP]
> **閱讀目標**：讀完本章，你應該能建立 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`。

```mermaid
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:2px
```

## 2. 檔案結構

推薦結構：

```text
.github/
  copilot-instructions.md
  instructions/
    frontend.instructions.md
    backend.instructions.md
    tests.instructions.md
AGENTS.md
```

Path-specific instructions 需要 frontmatter，使用 `applyTo` 指定 glob：

```md
---
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 裡驗證。

檢查方式：

1. 發起一個和儲存庫有關的 Chat 請求。
2. 展開 response 頂部或 References 列表。
3. 檢視是否出現 `.github/copilot-instructions.md` 或相關 instruction 檔案。
4. 如果沒有出現，檢查 feature 開關、檔案路徑和工具支援矩陣。

## 5. 支援邊界

不同 Copilot 功能支援的 instruction 型別不同。GitHub 官方支援矩陣會變化，寫教程時不能把某個 IDE 或功能支援狀態永久寫死。

穩定做法：

- 文件內標註 `verifiedAt`。
- 需要功能支援時連結官方 support matrix。
- 對團隊只寫“我們當前啟用的入口”。

<details>
<summary>深讀：為什麼 path-specific instructions 能降低上下文汙染</summary>

大型儲存庫裡，前端、後端、測試、基礎設施的規則不同。如果全部寫進一個儲存庫級檔案，Copilot 每次都要讀大量無關規則，還可能把後端規則套到前端。

Path-specific instructions 讓規則按檔案匹配載入，資訊更少、更準，也更容易維護。
</details>

## 本章自檢

完成本章後，用這 4 個問題檢查：

1. 儲存庫級和路徑級規則是否職責清楚？
2. `applyTo` 是否準確匹配目標檔案？
3. 是否能在 References 裡看到對應 instruction 檔案？
4. 檔案裡是否沒有敏感資訊和臨時任務？

透過標準：新成員不需要口頭同步，就能讓 Copilot 遵守專案核心規則。

## 官方來源

- [Adding repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) —— 官方儲存庫指令頁。
- [About customizing GitHub Copilot responses](https://docs.github.com/en/copilot/concepts/prompting/response-customization) —— 官方定製概念頁。
- [Support for different types of custom instructions](https://docs.github.com/en/copilot/reference/custom-instructions-support) —— 官方支援矩陣。

## 接下來去哪

<Cards>
  <Card title="個人和組織指令" description="繼續分清個人偏好、儲存庫事實和組織原則。" href="/zh-Hant/docs/github-copilot/official/06-context-customization/personal-org-instructions" />
  <Card title="Prompt Files" description="把重複任務從 instructions 裡拆出來。" href="/zh-Hant/docs/github-copilot/official/06-context-customization/prompt-files" />
</Cards>
