在 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 中的特定语言指南
• 特定模块的框架特定模式
• 测试文件或文档的专用规则

指令文件位置

您可以为特定的工作区定义指令，也可以在用户级别定义指令，这些指令将应用于您的所有工作区。

您可以使用 配置工作区指令文件的其他文件位置。

为了与 Claude Code 和其他基于 Claude 的工具兼容，VS Code 还会检测工作区 .claude/rules 文件夹和用户 ~/.claude/rules 文件夹中的指令文件。

以下代码片段显示了如何配置指令文件位置，其中仅启用工作区级别指令，而禁用用户级别指令

"chat.instructionsFilesLocations": {
  ".github/instructions": true,
  ".claude/rules": true,
  "~/.copilot/instructions": false,
  "~/.claude/rules": false
}

指令文件格式

指令文件是带有 .instructions.md 扩展名的 Markdown 文件。可选的 YAML frontmatter 标头控制何时应用指令

正文包含以 Markdown 格式编写的指令。要引用代理工具，请使用 #tool:<tool-name> 语法（例如，#tool:githubRepo）。

---
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. 在聊天视图中，选择 配置聊天（齿轮图标）> 聊天指令，然后选择 新建指令文件。

   

   或者，使用来自命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 的 聊天：新建指令文件 命令。

2. 选择创建指令文件的位置。

   • 工作区：在工作区的 .github/instructions 文件夹中创建指令文件，以仅在工作区内使用它。使用 为您的工作区添加更多指令文件夹

     chat.instructionsFilesLocations

     • 在 VS Code 中打开
     • 在 VS Code Insiders 中打开
     设置来指定 VS Code 应该查找技能的自定义路径。

   • 用户配置文件：在 当前配置文件文件夹 中创建指令文件，以在所有工作区中使用它。

3. 输入指令文件的文件名。这是 UI 中使用的默认名称。

4. 使用 Markdown 格式编写自定义指令。

   • 在文件的顶部填写 YAML frontmatter，以配置指令的描述、名称以及何时应用它们。
   • 在文件的正文中添加指令。

要修改现有的指令文件，在聊天视图中，选择 配置聊天（齿轮图标）> 聊天指令，然后从列表中选择指令文件。或者，使用来自命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 的 聊天：配置指令 命令，并从快速选取器中选择指令文件。

使用 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 文件的支持，请配置

使用多个 AGENTS.md 文件（实验性）

在子文件夹中使用多个 AGENTS.md 文件非常有用，如果您希望将不同的指令应用于项目的不同部分。例如，您可以为前端代码创建一个 AGENTS.md 文件，为后端代码创建一个 AGENTS.md 文件。

使用实验性的

启用后，VS Code 会在工作区的所有子文件夹中递归搜索 AGENTS.md 文件，并将它们的相对路径添加到聊天上下文中。然后，代理可以根据正在编辑的文件决定使用哪些指令。

使用 CLAUDE.md 文件

VS Code 会自动检测 CLAUDE.md 文件，并将其作为始终开启的指令应用，类似于 AGENTS.md。如果您同时使用 Claude Code 或其他基于 Claude 的工具和 VS Code，并且希望所有工具都识别同一组指令，这将非常有用。

VS Code 在以下位置搜索 CLAUDE.md 文件

要启用或禁用对 CLAUDE.md 文件的支持，请配置以下设置：

为您的工作区生成自定义指令

VS Code 可以分析您的工作区并生成与您的编码实践和项目结构匹配的始终开启的自定义指令。这些指令将自动应用于工作区中的所有聊天请求。

当您生成指令时，VS Code 会执行以下步骤

1. 它会发现工作区中现有的 AI 约定，例如 copilot-instructions.md 或 AGENTS.md 文件。
2. 它会分析您的项目结构和编码模式。
3. 它会生成根据您的项目量身定制的全面工作区指令。

使用 /init 斜杠命令

为您的工作区准备自定义指令的最快方法是在聊天输入框中键入 /init 斜杠命令。

/init 命令被实现为一个贡献的 prompt 文件，因此您可以修改底层 prompt 来定制其行为。

使用命令生成指令

要使用命令为您的工作区生成自定义指令

1. 在“聊天”视图中，选择 配置聊天（齿轮图标）> 生成聊天指令。

2. 查看生成的指令文件并进行必要的编辑。

在团队之间共享自定义指令

要跨多个工作区和存储库在您的 GitHub 组织中共享自定义指令，可以在 GitHub 组织级别定义它们。

VS Code 会自动检测您的帐户有权访问的组织级别定义的自定义指令。这些指令将显示在 聊天指令 菜单中，与您的个人和工作区指令一起显示，并自动应用于所有聊天请求。

要启用组织级别自定义指令的发现，请设置

了解如何在 GitHub 文档中 为您的组织添加自定义指令。

在设备之间同步用户指令文件

VS Code 可以通过使用 设置同步 在多个设备之间同步您的用户指令文件。

要同步您的用户指令文件，请为 prompt 和指令文件启用设置同步

1. 确保您已启用 设置同步。

2. 从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行 设置同步：配置。

3. 从要同步的设置列表中选择 Prompt 和指令。

在设置中指定自定义指令

对于代码审查或提交消息生成等专业场景，您可以使用 VS Code 设置来定义自定义指令。对于常规编码指令，请使用 基于文件的指令 代替。

{
  "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" }
  ]
}

指令优先级

当存在多种类型的自定义指令时，它们都会提供给 AI。当发生冲突时，优先级较高的指令优先。

1. 个人指令（用户级别，优先级最高）
2. 存储库指令 (.github/copilot-instructions.md 或 AGENTS.md)
3. 组织指令（优先级最低）

编写有效指令的技巧

• 保持指令简短且自包含。每个指令应为单个简单语句。如果您需要提供多条信息，请使用多个指令。

• 包含规则背后的推理。当指令解释了约定存在的原因时，AI 在边缘情况下会做出更好的决策。例如：“使用 date-fns 代替 moment.js — moment.js 已弃用并会增加捆绑包大小。”

• 使用具体的代码示例展示首选和避免的模式。AI 对示例的响应比对抽象规则的响应更有效。

• 专注于非显而易见的规则。跳过标准 linter 或 formatter 已经执行的约定。

• 对于任务或语言特定的指令，请使用多个 *.instructions.md 文件来处理每个主题，并通过使用 applyTo 属性来选择性地应用它们。

• 将项目特定的指令存储在您的工作区中，以便与团队其他成员共享并在您的版本控制中包含它们。

• 在您的 prompt 文件 和 自定义代理 中重用和引用指令文件，以保持它们简洁和专注，并避免重复指令。

• 指令之间的空格会被忽略，因此您可以将指令格式化为单个段落、单独的行或用空行分隔以提高可读性。

常见问题

为什么我的指令文件没有被应用？

如果您的指令文件没有被应用，请检查以下内容

• 验证您的指令文件是否位于正确的位置。.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

  • Open in VS Code
  • Open in VS Code Insiders
  用于通过 Markdown 链接引用的指令，
  chat.useAgentsMdFile

  • Open in VS Code
  • Open in VS Code Insiders
  用于 AGENTS.md 文件。

对于高级诊断，检查“聊天调试”视图中的语言模型请求 或 调试 applyTo 匹配逻辑。

如何知道自定义指令文件来自哪里？

自定义指令文件可以来自不同的来源：内置的、用户在您的配置文件中定义的、工作区定义的指令在您的当前工作区中、组织级别的指令或扩展贡献的指令。

要识别自定义指令文件的来源

1. 从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 选择 聊天：配置指令。
2. 将鼠标悬停在列表中的指令文件上。源位置将显示在工具提示中。

使用聊天自定义诊断视图查看所有加载的指令文件和任何错误。右键单击“聊天”视图并选择 诊断。了解更多关于 在 VS Code 中解决 AI 问题 的信息。

相关资源

• 使用 Agent 技能
• 创建自定义代理
• 社区贡献的指令、prompt 和自定义代理