在 VS Code 中使用自定義指令

自定義指令使您能夠定義通用的準則和規則，從而自動影響 AI 生成程式碼和處理其他開發任務的方式。與其在每次聊天提示中手動包含上下文，不如將自定義指令指定在 Markdown 檔案中，以確保 AI 回覆的一致性，並符合您的編碼實踐和專案要求。

您可以配置自定義指令，使其自動應用於所有聊天請求，或僅應用於特定檔案。或者，您可以手動將自定義指令附加到特定的聊天提示。

指令檔案的型別

VS Code 支援多種型別的基於 Markdown 的指令檔案。如果您在專案中擁有多種型別的指令檔案，VS Code 會將它們合併並新增到聊天上下文中，但不能保證特定的順序。

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

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

• 一個或多個.instructions.md 檔案

  • 使用 glob 模式，根據檔案型別或位置有條件地應用指令
  • 儲存在工作區或使用者配置檔案中

• 一個或多個AGENTS.md 檔案

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

指令之間的空格將被忽略，因此指令可以寫成單個段落、每行一個、或用空行分隔以提高可讀性。

要引用指令中的特定上下文，例如檔案或 URL，您可以使用 Markdown 連結。

自定義指令示例

以下示例演示瞭如何使用自定義指令。有關更多社群貢獻的示例，請參閱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` 檔案

1. 啟用 github.copilot.chat.codeGeneration.useInstructionFiles 設定。

2. 在工作區根目錄建立 `.github/copilot-instructions.md` 檔案。如果需要，請先建立 `.github` 目錄。

3. 使用自然語言和 Markdown 格式描述您的指令。

使用 `.instructions.md` 檔案

與使用一個適用於所有聊天請求的指令檔案不同，您可以建立多個 `.instructions.md` 檔案，以應用於特定的檔案型別或任務。例如，您可以為不同的程式語言、框架或專案型別建立指令檔案。

透過在指令檔案頭中使用 `applyTo` frontmatter 屬性，您可以指定一個 glob 模式來定義指令應自動應用於哪些檔案。在建立或修改檔案時使用指令檔案，通常不適用於讀取操作。

或者，您也可以透過在“聊天”檢視中使用“**新增上下文**” > “**指令**”選項，手動將指令檔案附加到特定的聊天提示。

• 工作區指令檔案：僅在工作區內可用，並存儲在工作區的 `.github/instructions` 資料夾中。
• 使用者指令檔案：可在多個工作區中使用，並存儲在當前的VS Code 配置檔案中。

指令檔案格式

指令檔案是 Markdown 檔案，使用 `.instructions.md` 副檔名，並具有以下結構

頭部（可選）

頭部格式為 YAML frontmatter，包含以下欄位

正文

指令檔案正文包含自定義指令，這些指令在應用指令時會發送給 LLM。提供您希望 AI 遵循的具體準則、規則或任何其他相關資訊。

要在正文文字中引用代理工具，請使用 #tool:<tool-name> 語法。例如，要引用 githubRepo 工具，請使用 #tool:githubRepo。

示例

---
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).

建立指令檔案

建立指令檔案時，選擇是將其儲存在工作區還是使用者配置檔案中。工作區指令檔案僅適用於該工作區，而使用者指令檔案可在多個工作區中使用。

要建立指令檔案

1. 在“聊天”檢視中，選擇“**配置聊天**”（齒輪圖示） > “**聊天指令**”，然後選擇“**新建指令檔案**”。

   

   或者，使用命令面板（⇧⌘P（Windows、Linux Ctrl+Shift+P））中的“**Chat: New Instructions File**”命令。

2. 選擇建立指令檔案的位置。

   • 工作區：在工作區的 `.github/instructions` 資料夾中建立指令檔案，僅在該工作區內使用。使用 chat.instructionsFilesLocations 設定為您工作區新增更多指令資料夾。

   • 使用者配置檔案：在當前配置檔案資料夾中建立指令檔案，以便在所有工作區中使用。

3. 為您的指令檔案輸入一個檔名。這是 UI 中使用的預設名稱。

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

   • 在檔案頂部填寫 YAML frontmatter，以配置指令的描述、名稱以及何時應用。
   • 在檔案正文中新增指令。

要修改現有的指令檔案，請在“聊天”檢視中選擇“**配置聊天**”（齒輪圖示） > “**聊天指令**”，然後從列表中選擇一個指令檔案。或者，使用命令面板（⇧⌘P（Windows、Linux Ctrl+Shift+P））中的“**Chat: Configure Instructions**”命令，然後從快速選擇中選擇指令檔案。

使用 `AGENTS.md` 檔案

如果您在工作區中使用多個 AI 代理，您可以在工作區根目錄的 `AGENTS.md` Markdown 檔案中為所有代理定義自定義指令。VS Code 會自動將此檔案中的指令應用於此工作區內的所有聊天請求。

要啟用或停用對 `AGENTS.md` 檔案的支援，請配置 chat.useAgentsMdFile 設定。

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

如果您想將不同的指令應用於專案的不同部分，使用子資料夾中的多個 `AGENTS.md` 檔案非常有用。例如，您可以有一個用於前端程式碼的 `AGENTS.md` 檔案，另一個用於後端程式碼。

使用實驗性的 chat.useNestedAgentsMdFiles 設定來啟用或停用對工作區中巢狀 `AGENTS.md` 檔案的支援。

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

在設定中指定自定義指令

您可以透過使用 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` 檔案，其中包含符合您的編碼實踐和專案結構的自定義指令。

為您的工作區生成指令檔案

1. 在“聊天”檢視中，選擇“**配置聊天**”（齒輪圖示） > “**生成聊天指令**”。

2. 審閱生成的指令檔案並進行任何必要的編輯。

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

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

要同步您的使用者指令檔案，請啟用提示和指令檔案的設定同步

1. 確保您已啟用設定同步。

2. 從命令面板（⇧⌘P（Windows、Linux Ctrl+Shift+P））執行“**Settings Sync: Configure**”。

3. 從要同步的設定列表中選擇“**提示和指令**”。

定義自定義指令的技巧

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

• 對於特定於任務或語言的指令，請為每個主題使用多個 `*.instructions.md` 檔案，並透過 `applyTo` 屬性選擇性地應用它們。

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

• 在您的提示檔案和自定義代理中重用和引用指令檔案，以保持它們的簡潔和專注，並避免指令重複。

相關資源

• 自定義 AI 回覆概覽
• 建立可重用的提示檔案
• 建立自定義代理
• 開始在 VS Code 中使用聊天
• 在聊天中配置工具
• 社群貢獻的指令、提示和自定義代理