在 VS Code 中使用自訂指令

自訂指令讓您能夠定義通用的準則和規則，這些準則和規則會自動影響 AI 如何產生程式碼和處理其他開發任務。您無需在每個聊天提示中手動包含上下文，只需在 Markdown 檔案中指定自訂指令，即可確保 AI 回應與您的編碼實踐和專案要求保持一致。

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

指令檔案類型

VS Code 支援兩種類型的自訂指令。如果您的專案中有多個指令檔案，VS Code 會將它們合併並添加到聊天上下文中，但不保證特定的順序。

永久開啟的指令

永久開啟的指令會自動包含在每個聊天請求中。將它們用於專案範圍的編碼標準、架構決策以及適用於所有程式碼的慣例。

• 單一 .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. 選取位置並輸入指令檔案的檔案名稱。這是使用者介面中使用的預設名稱。

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

   • 填寫檔案頂部的 YAML Frontmatter，以設定指令的描述、名稱以及何時應用。
   • 在檔案內文添加指令。

您可以透過在聊天自訂編輯器中開啟現有指令檔案來修改它們。

使用 AI 產生指令檔案

您可以使用 AI 產生有針對性的指令檔案。在聊天中鍵入 /create-instruction，然後描述您想要執行的慣例或準則 (例如，「在此專案中始終使用定位字元和單引號」)。代理會提出澄清問題，並產生一個帶有適當 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 代理，並希望所有代理都識別單一組指令，或者您想要應用於 monorepo 特定部分的子資料夾層級指令，這會很有用。

在下列情況下使用 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 可以透過使用 設定同步 在多個裝置之間同步您的使用者指令檔案。

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

在設定中指定自訂指令

對於程式碼審查、提交訊息和提取請求描述，您仍然可以使用 VS Code 設定來定義自訂指令。這些設定接受一個物件陣列，其中包含 text 屬性 (內嵌指令) 或 file 屬性 (Markdown 檔案的路徑)。

指令優先順序

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

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

編寫有效指令的技巧

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

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

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

• 專注於不明顯的規則。跳過標準 linter 或格式器已強制執行的慣例。

• 對於任務或特定語言的指令，每個主題使用多個 *.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 疑難排解。

相關資源

• 使用代理技能
• 建立自訂代理
• 社群貢獻的指令、提示和自訂代理