在 VS Code 中使用自定義指令
自定義指令使您能夠定義通用的指南和規則，這些指南和規則會自動影響 AI 生成程式碼和處理其他開發任務的方式。您無需在每個聊天提示中手動包含上下文，而是在 Markdown 檔案中指定自定義指令，以確保 AI 響應的一致性，使其符合您的編碼實踐和專案要求。
您可以將自定義指令配置為自動應用於所有聊天請求，或僅應用於特定檔案。或者，您也可以手動將自定義指令附加到特定的聊天提示中。
當您在編輯器中輸入時，自定義指令不會被用於程式碼補全。
指令檔案型別
VS Code 支援多種基於 Markdown 的指令檔案型別：
-
單個
.github/copilot-instructions.md檔案- 自動應用於工作區中的所有聊天請求
- 儲存在工作區內
-
一個或多個
.instructions.md檔案- 為特定任務或檔案建立
- 使用
applyTofrontmatter 來定義指令應應用於哪些檔案 - 儲存在工作區或使用者配置檔案中
-
AGENTS.md檔案（實驗性功能）(chat.useAgentsMdFile)- 當您在工作區中與多個 AI 代理一起工作時非常有用
- 自動應用於工作區中的所有聊天請求
- 儲存在工作區的根目錄中
指令之間的空白會被忽略，因此指令可以寫成一個段落，也可以每條指令佔一行，或者用空行分隔以提高可讀性。
透過使用 Markdown 連結，在您的指令中引用特定的上下文，例如檔案或 URL。
自定義指令示例
以下示例演示瞭如何使用自定義指令。更多社群貢獻的示例，請參閱 Awesome Copilot 倉庫。
示例：通用編碼指南
---
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
示例：特定語言的編碼指南
請注意這些指令如何引用通用編碼指南檔案。您可以將指令分成多個檔案，以保持它們的組織性並專注於特定主題。
---
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.
使用 .github/copilot-instructions.md 檔案
在工作區根目錄下的單個 .github/copilot-instructions.md Markdown 檔案中定義您的自定義指令。VS Code 會將此檔案中的指令自動應用於該工作區內的所有聊天請求。
要使用 .github/copilot-instructions.md 檔案：
-
啟用 github.copilot.chat.codeGeneration.useInstructionFiles 設定。
-
在工作區的根目錄下建立一個
.github/copilot-instructions.md檔案。如果需要，請先建立一個.github目錄。 -
使用自然語言和 Markdown 格式描述您的指令。
Visual Studio 和 GitHub.com 中的 GitHub Copilot 也會檢測 .github/copilot-instructions.md 檔案。如果您有一個在 VS Code 和 Visual Studio 中都使用的工作區，您可以使用同一個檔案為兩個編輯器定義自定義指令。
使用 .instructions.md 檔案
您可以建立多個適用於特定檔案型別或任務的 .instructions.md 檔案，而不是使用一個適用於所有聊天請求的單一指令檔案。例如，您可以為不同的程式語言、框架或專案型別建立指令檔案。
透過在指令檔案頭中使用 applyTo frontmatter 屬性，您可以指定一個 glob 模式來定義指令應自動應用於哪些檔案。指令檔案通常在建立或修改檔案時使用，一般不適用於讀取操作。
或者，您可以透過聊天檢視中的 新增上下文 > 指令 選項，手動將指令檔案附加到特定的聊天提示中。
- 工作區指令檔案：僅在工作區內可用，並存儲在工作區的
.github/instructions資料夾中。 - 使用者指令檔案：可在多個工作區中使用，並存儲在當前的 VS Code 配置檔案中。
指令檔案格式
指令檔案使用 .instructions.md 副檔名，並具有以下結構：
-
頭部（可選）：YAML frontmatter
description：在聊天檢視中懸停時顯示的描述applyTo：用於自動應用的 glob 模式（使用**表示所有檔案）
-
正文：Markdown 格式的指令
示例
---
applyTo: "**/*.py"
---
# Project coding standards for Python
- Follow the PEP 8 style guide for Python.
- Always prioritize readability and clarity.
- Write clear and concise comments for each function.
- Ensure functions have descriptive names and include type hints.
- Maintain proper indentation (use 4 spaces for each level of indentation).
建立指令檔案
當您建立指令檔案時，請選擇是將其儲存在工作區還是使用者配置檔案中。工作區指令檔案僅適用於該工作區，而使用者指令檔案則可在多個工作區中使用。
要建立指令檔案：
-
在聊天檢視中，選擇 配置聊天 > 指令，然後選擇 新建指令檔案。
或者，從命令面板（⇧⌘P (Windows、Linux Ctrl+Shift+P)）使用 聊天: 新建指令檔案 命令。
-
選擇建立指令檔案的位置。
-
工作區：預設情況下，工作區指令檔案儲存在工作區的
.github/instructions資料夾中。您可以使用 chat.instructionsFilesLocations 設定為您的工作區新增更多的指令資料夾。
-
-
為您的指令檔案輸入一個名稱。
-
使用 Markdown 格式編寫自定義指令。
在頭部指定
applyTo元資料屬性，以配置指令應在何時自動應用。例如，您可以指定applyTo: "**/*.ts,**/*.tsx"，使指令僅應用於 TypeScript 檔案。要引用其他工作區檔案，請使用 Markdown 連結（
[index](../index.ts)）。
要修改現有的指令檔案，請在聊天檢視中選擇 配置聊天 > 指令，然後從列表中選擇一個指令檔案。或者，從命令面板（⇧⌘P (Windows、Linux Ctrl+Shift+P)）使用 聊天: 配置指令 命令，並從快速選擇列表中選擇指令檔案。
在設定中指定自定義指令
您可以透過使用 VS Code 的使用者或工作區設定，為特定場景配置自定義指令。
* codeGeneration 和 testGeneration 設定自 VS Code 1.102 起已棄用。我們建議您改用指令檔案（.github/copilot-instructions.md 或 *.instructions.md）。
您可以在設定值（text 屬性）中將自定義指令定義為文字，或引用工作區中的外部檔案（file 屬性）。
以下程式碼片段展示瞭如何在 settings.json 檔案中定義一組指令。
{
"github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
{ "text": "Always include a list of key changes." }
],
"github.copilot.chat.reviewSelection.instructions": [
{ "file": "guidance/backend-review-guidelines.md" },
{ "file": "guidance/frontend-review-guidelines.md" }
]
}
為您的工作區生成指令檔案
VS Code 可以分析您的工作區，並生成一個匹配的 .github/copilot-instructions.md 檔案，其中包含符合您編碼實踐和專案結構的自定義指令。
要為您的工作區生成指令檔案：
-
在聊天檢視中，選擇 配置聊天 > 生成指令。
-
審查生成的指令檔案並進行任何必要的編輯。
跨裝置同步使用者指令檔案
VS Code 可以使用設定同步功能在多臺裝置之間同步您的使用者指令檔案。
要同步您的使用者指令檔案，請為提示和指令檔案啟用設定同步：
-
確保您已啟用設定同步。
-
從命令面板（⇧⌘P (Windows、Linux Ctrl+Shift+P)）執行 設定同步: 配置。
-
從要同步的設定列表中選擇 提示和指令。
定義自定義指令的技巧
-
保持您的指令簡短且獨立。每條指令都應該是一個單一、簡單的陳述。如果需要提供多條資訊，請使用多條指令。
-
對於特定任務或語言的指令，請為每個主題使用多個
*.instructions.md檔案，並使用applyTo屬性有選擇地應用它們。 -
將專案特定的指令儲存在您的工作區中，以便與其他團隊成員共享並將它們包含在您的版本控制中。