在 VS Code 中使用自定义指令
自定义指令允许您定义通用指南和规则，这些指南和规则会自动影响 AI 生成代码和处理其他开发任务的方式。您无需在每个聊天提示中手动包含上下文，而是在 Markdown 文件中指定自定义指令，以确保 AI 响应与您的编码实践和项目要求保持一致。
您可以将自定义指令配置为自动应用于所有聊天请求，或仅应用于特定文件。或者，您可以手动将自定义指令附加到特定的聊天提示。
自定义指令不会在您在编辑器中键入时进行代码补全时考虑。
指令文件类型
VS Code 支持多种基于 Markdown 的指令文件类型。如果您的项目中存在多种指令文件类型，VS Code 会将它们组合并添加到聊天上下文中，不保证特定顺序。
-
单个
.github/copilot-instructions.md文件- 自动应用于工作区中的所有聊天请求
- 存储在工作区内
-
一个或多个
.instructions.md文件- 为特定任务或文件创建
- 使用
applyTo前置数据来定义指令应应用于哪些文件 - 存储在工作区或用户配置文件中
-
单个
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文件
-
在工作区根目录创建
.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前置数据属性，您可以指定 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））并从快速选择中选择指令文件。
使用AGENTS.md文件
如果您在工作区中使用多个 AI 代理，则可以在工作区根目录中的AGENTS.md Markdown 文件中定义所有代理的自定义指令。VS Code 会自动将此文件中的指令应用于此工作区内的所有聊天请求。
要启用或禁用对AGENTS.md文件的支持，请配置chat.useAgentsMdFile设置。
使用多个AGENTS.md文件（实验性）
在子文件夹中使用多个AGENTS.md文件非常有用，如果您想对项目的不同部分应用不同的指令。例如，您可以为前端代码设置一个AGENTS.md文件，为后端代码设置另一个AGENTS.md文件。
使用实验性chat.useNestedAgentsMdFiles设置来启用或禁用对工作区中嵌套AGENTS.md文件的支持。
启用后，VS Code 会在工作区的所有子文件夹中递归搜索AGENTS.md文件，并将其相对路径添加到聊天上下文。然后，代理可以根据正在编辑的文件决定使用哪些指令。
对于特定文件夹的指令，您还可以使用多个具有不同applyTo模式的.instructions.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文件，其中包含与您的编码实践和项目结构匹配的自定义指令。
为您的工作区生成指令文件
-
在聊天视图中，选择配置聊天 > 生成指令。
-
审查生成的指令文件并进行任何必要的编辑。
跨设备同步用户指令文件
VS Code 可以使用设置同步在多个设备之间同步您的用户指令文件。
要同步您的用户指令文件，请为提示和指令文件启用设置同步
-
确保您已启用设置同步。
-
从命令面板运行设置同步：配置（⇧⌘P（Windows、Linux Ctrl+Shift+P））。
-
从要同步的设置列表中选择提示和指令。
定义自定义指令的提示
-
保持您的指令简短且自包含。每个指令都应该是一个简单明了的语句。如果您需要提供多条信息，请使用多条指令。
-
对于任务或语言特定的指令，每个主题使用多个
*.instructions.md文件，并使用applyTo属性选择性地应用它们。 -
将项目特定的指令存储在您的工作区中，以便与其他团队成员共享并将其包含在您的版本控制中。