在 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属性有选择地应用它们。 -
将项目特定的指令存储在您的工作区中，以便与其他团队成员共享并将它们包含在您的版本控制中。