在 VS Code 中使用自訂指令

自訂指令可讓您定義通用準則與規則，自動影響 AI 產生程式碼及處理其他開發任務的方式。與其在每次聊天提示中手動加入內容，不如在 Markdown 檔案中指定自訂指令，以確保 AI 的回應與您的編碼實務和專案需求保持一致。

您可以設定自訂指令以自動套用於所有聊天請求，或僅套用於特定檔案。或者，您也可以手動將自訂指令附加到特定的聊天提示。

指令檔案類型

VS Code 支援兩種類別的自訂指令。如果您的專案中有過個指令檔案，VS Code 會將它們合併並新增至聊天內容中，但不保證特定的順序。

常駐指令 (Always-on instructions)

常駐指令會自動包含在每個聊天請求中。請將其用於適用於所有程式碼的專案級編碼標準、架構決策與慣例。

• 單一 .github/copilot-instructions.md 檔案

  • 自動套用於工作區中的所有聊天請求
  • 儲存於工作區內

• 一個或多個 AGENTS.md 檔案

  • 如果您在工作區中使用多個 AI 代理程式，這將非常有用
  • 自動套用於工作區中的所有聊天請求，或特定子資料夾（實驗性功能）
  • 儲存於工作區根目錄或子資料夾中（實驗性功能）

• 組織級指令

  • 跨 GitHub 組織內的多個工作區與儲存庫共用指令
  • 於 GitHub 組織層級定義

• CLAUDE.md 檔案

  • 為了與 Claude Code 及其他基於 Claude 的工具相容
  • 儲存於工作區根目錄、.claude 資料夾或使用者家目錄

基於檔案的指令

當代理程式處理的檔案符合指定模式，或描述符合目前任務時，會套用基於檔案的指令。對於語言特定的慣例、框架模式或僅適用於程式碼庫特定部分的規則，請使用基於檔案的指令。

• 一個或多個 .instructions.md 檔案
  • 透過使用 Glob 模式，根據檔案類型或位置有條件地套用指令
  • 儲存於工作區或使用者設定檔中

若要在指令中參照特定內容（如檔案或 URL），可以使用 Markdown 連結。

使用 .github/copilot-instructions.md 檔案

VS Code 會自動偵測工作區根目錄中的 .github/copilot-instructions.md Markdown 檔案，並將此檔案中的指令套用於該工作區內的所有聊天請求。

將 copilot-instructions.md 用於：

• 適用於整個專案的編碼風格與命名慣例
• 技術堆疊宣告與偏好的函式庫
• 應遵循或避免的架構模式
• 安全性需求與錯誤處理方式
• 文件標準

請遵循以下步驟在您的工作區中建立 .github/copilot-instructions.md 檔案

1. 在工作區根目錄中建立 .github/copilot-instructions.md 檔案。若有需要，請先建立 .github 目錄。

2. 以 Markdown 格式描述您的指令。為了達到最佳效果，請保持簡潔並聚焦於核心內容。

---
applyTo: "**"
---
# Project general coding standards

## Naming Conventions
- Use PascalCase for component names, interfaces, and type aliases
- Use camelCase for variables, functions, and methods
- Prefix private class members with underscore (_)
- Use ALL_CAPS for constants

## Error Handling
- Use try/catch blocks for async operations
- Implement proper error boundaries in React components
- Always log errors with contextual information

使用 .instructions.md 檔案

您可以利用 *.instructions.md Markdown 檔案建立基於檔案的指令，這些指令會根據代理程式正在處理的檔案或任務進行動態套用。

代理程式會根據指令檔案標頭 applyTo 屬性中指定的檔案模式，或是指令描述與目前任務的語意匹配程度，來決定要套用哪些指令檔案。

將 .instructions.md 用於：

• 前端與後端程式碼的不同慣例
• Monorepo 中的語言特定準則
• 特定模組的框架特定模式
• 測試檔案或文件的專業規則

指令檔案位置

您可以針對特定工作區或在使用者層級定義指令（後者會套用於您所有的工作區）。下表列出了根據範圍劃分的預設指令檔案位置。您可以使用 chat.instructionsFilesLocations 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定，為工作區指令檔案配置額外的檔案位置。

VS Code 會遞迴搜尋這些資料夾，讓您可以按團隊、語言或模組來組織指令檔案。

.github/instructions/
  frontend/
    react.instructions.md
    accessibility.instructions.md
  backend/
    api-design.instructions.md
  testing/
    unit-tests.instructions.md

下列範例示範如何配置指令檔案位置，以僅允許工作區層級的指令

"chat.instructionsFilesLocations": {
  ".github/instructions": true,
  ".claude/rules": true,
  "~/.copilot/instructions": false,
  "~/.claude/rules": false
}

指令檔案格式

指令檔案為副檔名為 .instructions.md 的 Markdown 檔案。選用的 YAML Frontmatter 標頭可控制套用指令的時機。

主體包含 Markdown 格式的指令。若要參照代理程式工具，請使用 #tool:<tool-name> 語法（例如：#tool:web/fetch）。

---
name: 'Python Standards'
description: 'Coding conventions for Python files'
applyTo: '**/*.py'
---
# Python coding standards
- Follow the PEP 8 style guide.
- Use type hints for all function signatures.
- Write docstrings for public functions.
- Use 4 spaces for indentation.

建立指令檔案

建立指令檔案時，請選擇要將其儲存在您的工作區還是使用者設定檔中。工作區指令檔案僅適用於該工作區，而使用者指令檔案則適用於多個工作區。

若要建立指令檔案：

1. 在聊天檢視中，選擇設定聊天（齒輪圖示）開啟代理程式自訂編輯器，然後選擇指令頁籤。

2. 從下拉式選單中選擇新指令（工作區）或新指令（使用者），具體取決於您希望將指令檔案儲存於何處。

   

   或者，從命令面板使用聊天：新指令檔案命令 (⇧⌘P (Windows, Linux Ctrl+Shift+P))。

3. 選擇位置並輸入指令檔案的檔案名稱。這是在 UI 中使用的預設名稱。

4. 使用 Markdown 格式編寫自訂指令。

   • 在檔案頂端填寫 YAML Frontmatter，以配置指令的描述、名稱及套用時機。
   • 在檔案主體中加入指令。

您可以透過在代理程式自訂編輯器中開啟現有的指令檔案來進行修改。

使用 AI 產生指令檔案

您可以使用 AI 產生目標明確的指令檔案。在聊天中輸入 /create-instruction 並描述您想要強制執行的慣例或準則（例如：「在此專案中請一律使用 Tab 和單引號」）。代理程式會提出釐清問題並產生一個含有適當 applyTo 模式與內容的 .instructions.md 檔案。

您也可以從進行中的對話中擷取指令。例如，如果您在聊天過程中修正了代理程式的匯入風格，可以詢問「從這裡擷取一項指令」以將該修正捕捉為專案慣例。

---
applyTo: "**/*.ts,**/*.tsx"
---
# Project coding standards for TypeScript and React

Apply the [general coding guidelines](./general-coding.instructions.md) to all code.

## TypeScript Guidelines
- Use TypeScript for all new code
- Follow functional programming principles where possible
- Use interfaces for data structures and type definitions
- Prefer immutable data (const, readonly)
- Use optional chaining (?.) and nullish coalescing (??) operators

## React Guidelines
- Use functional components with hooks
- Follow the React hooks rules (no conditional hooks)
- Use React.FC type for components with children
- Keep components small and focused
- Use CSS modules for component styling

---
applyTo: "docs/**/*.md"
---
# Project documentation writing guidelines

## General Guidelines
- Write clear and concise documentation.
- Use consistent terminology and style.
- Include code examples where applicable.

## Grammar
* Use present tense verbs (is, open) instead of past tense (was, opened).
* Write factual statements and direct commands. Avoid hypotheticals like "could" or "would".
* Use active voice where the subject performs the action.
* Write in second person (you) to speak directly to readers.

## Markdown Guidelines
- Use headings to organize content.
- Use bullet points for lists.
- Include links to related resources.
- Use code blocks for code snippets.

欲知更多社群貢獻的範例，請參閱 Awesome Copilot 儲存庫。

使用 AGENTS.md 檔案

VS Code 會自動偵測工作區根目錄中的 AGENTS.md Markdown 檔案，並將此檔案中的指令套用於該工作區內的所有聊天請求。如果您在工作區中使用多個 AI 代理程式，並希望它們都能識別同一組指令，或者您希望在子資料夾層級進行針對特定部分的指令設定，這將非常有用。

使用 AGENTS.md 當您：

• 使用多個 AI 程式碼代理程式，且希望它們都能識別同一組指令
• 希望在子資料夾層級使用僅套用於 Monorepo 特定部分的指令

若要啟用或停用 AGENTS.md 檔案的支援，請配置 chat.useAgentsMdFile 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定。

使用多個 AGENTS.md 檔案（實驗性功能）

如果您希望對專案的不同部分套用不同的指令，在子資料夾中使用多個 AGENTS.md 檔案非常有用。例如，您可以為前端程式碼準備一個 AGENTS.md 檔案，並為後端程式碼準備另一個。

使用實驗性的 chat.useNestedAgentsMdFiles 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定來啟用或停用巢狀 AGENTS.md 檔案的支援。

啟用後，VS Code 會遞迴搜尋工作區的所有子資料夾以尋找 AGENTS.md 檔案，並將其相對路徑新增至聊天內容中。代理程式隨後可根據正在編輯的檔案，決定使用哪些指令。

使用 CLAUDE.md 檔案

VS Code 會自動偵測 CLAUDE.md 檔案並將其作為常駐指令套用，類似於 AGENTS.md。如果您在 VS Code 之外同時使用 Claude Code 或其他基於 Claude 的工具，且希望它們都能識別同一組指令，這將非常有用。

VS Code 會在下列位置搜尋 CLAUDE.md 檔案：

若要啟用或停用 CLAUDE.md 檔案的支援，請配置 chat.useClaudeMdFile 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定。

為您的工作區產生自訂指令

VS Code 可以分析您的工作區並產生符合您編碼實務與專案結構的常駐自訂指令。這些指令隨後會自動套用於工作區中的所有聊天請求。

當您產生指令時，VS Code 會執行下列步驟：

1. 它會探索工作區中現有的 AI 慣例，例如 copilot-instructions.md 或 AGENTS.md 檔案。
2. 它會分析您的專案結構與編碼模式。
3. 它會產生為您的專案量身打造的綜合工作區指令。

若要為您的工作區產生自訂指令：

• 在聊天輸入框中輸入 /init 並按 Enter。

• 輸入 /create-instructions，接著輸入您想要產生的指令描述。

• 在代理程式自訂編輯器中，從下拉式選單選擇產生指令。

跨團隊共用自訂指令

若要跨 GitHub 組織內的多個工作區與儲存庫共用自訂指令，您可以在 GitHub 組織層級定義它們。

VS Code 會自動偵測您帳號有權存取的組織級自訂指令。這些指令會顯示在聊天指令選單中（與您的個人和工作區指令並列），並自動套用於所有聊天請求。

若要啟用組織級自訂指令的探索功能，請將 github.copilot.chat.organizationInstructions.enabled 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設為 true。

在 GitHub 文件中了解如何 為您的組織新增自訂指令。

跨裝置同步使用者指令檔案

VS Code 可以透過 設定同步 (Settings Sync) 在多個裝置間同步您的使用者指令檔案。

若要同步您的使用者指令檔案，請啟用設定同步，並從命令面板執行設定同步：設定 (⇧⌘P (Windows, Linux Ctrl+Shift+P))。從要同步的設定清單中選擇提示與指令。

在設定中指定自訂指令

對於程式碼審查、提交訊息與 Pull Request 描述，您仍可以使用 VS Code 設定來定義自訂指令。這些設定接受物件陣列，其中包含 text 屬性（內嵌指令）或 file 屬性（Markdown 檔案路徑）。

指令優先順序

當存在多種類型的自訂指令時，它們都會提供給 AI。發生衝突時，優先順序較高的指令會優先執行：

1. 個人指令（使用者層級，最高優先權）
2. 儲存庫指令 (.github/copilot-instructions.md 或 AGENTS.md)
3. 組織指令（最低優先權）

撰寫有效指令的訣竅

• 保持您的指令簡短且獨立。每個指令都應是單一、簡單的陳述。如果您需要提供多項資訊，請使用多個指令。

• 包含規則背後的理由。當指令解釋了慣例存在的原因時，AI 能在處理邊緣情況時做出更好的決策。例如：「請使用 date-fns 而非 moment.js，因為 moment.js 已被棄用且會增加套件大小。」

• 透過具體的程式碼範例展示偏好與避免的模式。相較於抽象規則，AI 對範例的反應更有效。

• 聚焦於非明顯的規則。跳過標準 Lint 工具或格式化工具已經強制執行的慣例。

• 對於任務或語言特定的指令，請針對每個主題使用多個 *.instructions.md 檔案，並透過 applyTo 屬性進行選擇性套用。

• 將專案特定的指令儲存在您的工作區中，以便與其他團隊成員共用並納入版本控制。

• 在您的提示檔案與自訂代理程式中重複使用並參照指令檔案，以保持其簡潔聚焦，並避免指令重複。

• 指令之間的空白會被忽略，因此您可以將指令格式化為單一段落、分別位於不同行，或為了易讀性而以空白行隔開。

常見問題

為什麼我的指令檔案沒有被套用？

如果您的指令檔案未被套用，請檢查下列事項：

• 驗證您的指令檔案是否在正確位置。.github/copilot-instructions.md 檔案必須位於工作區根目錄的 .github 資料夾中。*.instructions.md 檔案必須位於 chat.instructionsFilesLocations 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定（預設為 .github/instructions）所指定的資料夾（或其子目錄）中，或者位於您的使用者設定檔中。

• 對於 *.instructions.md 檔案，請檢查 applyTo Glob 模式是否與您正在處理的檔案相符。若未指定 applyTo 屬性，指令檔案將不會自動套用。請檢查聊天回應中的參考區段，以查看實際使用了哪些指令檔案。

• 檢查相關設定是否已啟用： chat.includeApplyingInstructions 在 VS Code 中開啟 在 VS Code Insiders 中開啟 （針對基於模式的指令）、 chat.includeReferencedInstructions 在 VS Code 中開啟 在 VS Code Insiders 中開啟 （針對透過 Markdown 連結參照的指令）、 chat.useAgentsMdFile 在 VS Code 中開啟 在 VS Code Insiders 中開啟 （針對 AGENTS.md 檔案）。

若需進階診斷，請查看聊天除錯檢視中的語言模型請求或對 applyTo 匹配邏輯進行除錯。

我該如何知道自訂指令檔案的來源？

自訂指令檔案可能來自不同來源：內建、您個人設定檔中定義、目前工作區中定義的工作區指令、組織層級指令，或是由延伸模組提供的指令。

若要識別自訂指令檔案的來源：

1. 從命令面板選擇聊天：設定指令 (⇧⌘P (Windows, Linux Ctrl+Shift+P))。
2. 將滑鼠懸停在清單中的指令檔案上。來源位置會顯示在工具提示中。

使用聊天自訂診斷檢視來查看所有已載入的指令檔案與任何錯誤。在聊天檢視中按右鍵並選擇診斷。進一步了解如何在 VS Code 中對 AI 進行疑難排解。

相關資源

• 使用代理程式技能 (Agent Skills)
• 建立自訂代理
• 社群貢獻的指令、提示詞與自訂代理程式