在 VS Code 中使用自定义指令

自定义指令使您能够定义通用的指南和规则，这些指南和规则会自动影响 AI 生成代码和处理其他开发任务的方式。与其在每次聊天提示中手动包含上下文，不如在 Markdown 文件中指定自定义指令，以确保 AI 响应的一致性，并符合您的编码实践和项目要求。

您可以配置自定义指令，使其自动应用于所有聊天请求或仅应用于特定文件。或者，您可以手动将自定义指令附加到特定的聊天提示。

指令文件的类型

VS Code 支持两种类型的自定义指令。如果你的项目中有多个指令文件，VS Code 会将其合并并添加到聊天上下文中，不保证特定的顺序。

常开说明

始终开启的指令会自动包含在每个聊天请求中。使用它们来定义项目范围内的编码标准、架构决策和适用于所有代码的约定。

• 一个.github/copilot-instructions.md文件

  • 自动应用于工作区中的所有聊天请求
  • 存储在工作区中

• 一个或多个AGENTS.md文件

  • 如果您在工作区中与多个AI代理一起工作，这将非常有用。
  • 自动应用于工作区中的所有聊天请求或特定子文件夹（实验性）
  • 存储在工作区的根目录或子文件夹中（实验性）

• 组织层面的指示

  • 在 GitHub 组织内的多个工作区和仓库之间共享说明
  • 在 GitHub 组织级别定义

• 克劳德.md文件

  • 为了与Claude Code和其他基于Claude的工具兼容
  • 存储在工作区根目录，.claude文件夹，或用户主目录

基于文件的指令

基于文件的指令在代理处理的文件符合指定模式或描述符匹配当前任务时应用。使用基于文件的指令来处理特定语言规范、框架模式或仅适用于代码库某些部分的规则。

• 一个或多个.inSTRUCTIONS.md文件
  • 使用 glob 模式根据文件类型或位置有条件地应用指令
  • 存储在工作区或用户配置文件中

要引用您的说明中的特定上下文，例如文件或URL，您可以使用Markdown链接。

使用一个.github/copilot-instructions.md文件

VS Code自动检测一个.github/copilot-instructions.md在你的工作区根目录下创建一个Markdown文件，并将此文件中的说明应用于此工作区内的所有聊天请求。

使用Copilot指示.md对于：

• 适用于整个项目的编码风格和命名约定
• 技术栈声明和首选库
• 遵循或避免的架构模式
• 安全要求和错误处理方法
• 文档标准

请按照以下步骤创建.github/copilot-instructions.md在你的工作区中的文件：

1. 创建一个.github/copilot-instructions.md在你的工作区根目录下创建一个文件。如果需要，创建一个.github目录优先。

2. 用Markdown格式描述你的指示。保持简洁和集中，以获得最佳效果。

---
应用到："**"
---
# 项目通用编码标准

## 命名约定
- 组件名称、接口和类型别名使用PascalCase
- 变量、函数和方法使用camelCase
- 私有类成员前缀为下划线（_）
- 常量使用ALL_CAPS

## 错误处理
- 对异步操作使用try/catch块
- 在React组件中实现正确的错误边界
- 始终记录带有上下文信息的错误

使用.inSTRUCTIONS.md文件

您可以创建基于文件的说明*.instructions.md根据代理正在处理的文件或任务动态应用的Markdown文件。

代理根据在 中指定的文件模式来确定要应用的指令文件申请指令文件头部的属性或指令描述与当前任务的语义匹配。

使用.inSTRUCTIONS.md文件为：

• 前端和后端代码的不同约定
• 单存储库中的语言特定指南
• 框架特定模式的特定模块
• 测试文件或文档的特殊规则

说明文件位置

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

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

您可以使用 为工作区说明文件配置额外的文件位置

说明文件格式

说明文件是带有 的Markdown文件.inSTRUCTIONS.md扩展。 可选的 YAML 前置标记头部控制何时应用这些说明：

正文包含以Markdown格式编写的说明。要引用代理工具，请使用#工具：<工具名称>语法（例如，#工具:github仓库)。

---
名称: 'Python 标准'
描述: 'Python 文件的编码规范'
应用到: '**/*.py'
---
# Python 编码标准
- 遵循 PEP 8 样式指南。
- 为所有函数签名使用类型提示。
- 为公共函数编写文档字符串。
- 使用 4 个空格进行缩进。

创建说明文件

当您创建说明文件时，请选择将其存储在工作区还是用户配置文件中。工作区说明文件仅适用于该工作区，而用户说明文件在多个工作区中都可用。

要创建一个说明文件：

1. 在聊天视图中，选择配置聊天（齿轮图标）>聊天说明，然后选择新的说明文件。

   

   或者，使用 聊天：新指令文件 命令从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

2. 选择创建说明文件的位置。

   • 工作区：在.github/说明将你的工作区文件夹只用于该工作区。为你的工作区添加更多的指令文件夹

     聊天.指示文件位置

     • 在 VS Code 中打开
     • 在 VS Code Insiders 中打开
     设置。

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

3. 输入您的说明文件的文件名。这是在用户界面中使用的默认名称。

4. 使用Markdown格式编写自定义说明。

   • 在文件顶部填写 YAML 前置标记，以配置说明的描述、名称和适用时间。
   • 在文件主体中添加说明。

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

---
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 指南
- 使用带有 hooks 的函数组件
- 遵循 React hooks 规则（无条件 hooks）
- 为带有子元素的组件使用 React.FC 类型
- 保持组件小巧且专注
- 为组件样式使用 CSS 模块

---
应用到："docs/**/*.md"
---
# 项目文档编写指南

## 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 指南
- 使用标题来组织内容。
- 使用项目符号列表来列出项目。
- 包含相关资源的链接。
- 使用代码块来包含代码片段。

更多社区贡献的例子，请参见Awesome Copilot 仓库。

使用一个AGENTS.md文件

VS Code自动检测一个AGENTS.md在你的工作区根目录中创建一个Markdown文件，并将此文件中的说明应用于工作区内的所有聊天请求。如果你在工作区中使用多个AI代理，并希望有一套被所有代理认可的说明，或者你希望对单体仓库中的特定子文件夹应用说明，这将非常有用。

使用AGENTS.md时间：

• 您与多个AI编码器合作，并希望有一套被它们全部认可的指令
• 你希望对单库中特定部分的子文件夹级别进行说明

启用或禁用对AGENTS.md文件，配置

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

使用多个AGENTS.md子文件夹中的文件在您希望对项目的不同部分应用不同说明时很有用。例如，您可以有一个AGENTS.md前端代码的文件和后端代码的文件。

使用实验

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

使用一个克劳德.md文件

VS Code自动检测一个克劳德.md文件并将其作为始终启用的指令应用，类似于AGENTS.md这在你使用Claude Code或基于VS Code的其他Claude工具时，想要一组指令被它们全部识别时很有用。

VS Code 搜索克劳德.md这些位置的文件：

启用或禁用对克劳德.md文件，配置

为您的工作区生成自定义说明

VS Code 可以分析你的工作区，并生成始终开启的自定义指令，这些指令会匹配你的编码习惯和项目结构。然后，这些指令会自动应用于工作区中的所有聊天请求。

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

1. 它在您的工作区中发现现有的AI约定，例如Copilot指示.md或AGENTS.md文件。
2. 它分析你的项目结构和编码模式。
3. 它生成针对您的项目量身定制的全面工作区说明。

使用/初始化斜线命令

将您的工作区用自定义指令初始化的最快方法是输入/初始化在聊天输入框中输入斜线命令。

该/初始化 命令作为一个贡献的 提示文件 实施，因此你可以通过修改底层提示来自定义其行为。

使用命令生成说明

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

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

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

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

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

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

为了使组织级别自定义指令的发现成为可能，请设置

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

在设备之间同步用户说明文件

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

要同步您的用户说明文件，请启用设置同步以用于提示和说明文件：

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

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

3. 选择提示和说明从设置列表中同步。

在设置中指定自定义指令

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

{
  "github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
    { "text": "始终包括更改列表。”" }
  ],
  "github.copilot.chat.reviewSelection.instructions": [
    { "文件": "guidance/backend-review-guidelines.md" },
    { "文件": "guidance/frontend-review-guidelines.md" }
  ]
}

指令优先级

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

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

撰写有效说明的技巧

• 请将您的指示保持简短且自成一体。每个指示应为一个单一、简单的语句。如果您需要提供多个信息，请使用多个指示。

• 包括规则背后的原因。当说明为什么有一种惯例存在时，人工智能在边缘案例中做出更好的决定。例如：“使用日期-fns而不是时刻.js— moment.js 已被弃用并增加捆绑包大小。

• 展示首选和避免的模式，并提供具体的代码示例。人工智能对示例的响应比对抽象规则更有效。

• 关注不明显的规则。跳过标准 linters 或格式化程序已经实施的约定。

• 对于任务或语言特定的说明，使用多个*.instructions.md每个主题的文件并根据需要使用申请财产。

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

• 在你的提示文件和自定义代理中重用和引用说明指令文件，以保持它们的清洁和专注，并避免重复说明。

• 指令之间的空白会被忽略，因此你可以将指令格式化为单个段落，分行或用空白行分隔以便于阅读。

常见问题

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

如果您的说明文件未被应用，请检查以下内容：

• 验证你的指令文件是否位于正确的位置。.github/copilot-instructions.md文件必须在.github在你的工作区根目录下创建一个文件夹。一个*.instructions.md文件必须位于指定文件夹之一中

  聊天.指示文件位置

  • 在 VS Code 中打开
  • 在 VS Code Insiders 中打开
  设置（默认：.github/说明) 或在您的用户配置文件中。

• 对于*.instructions.md文件，检查申请 glob 模式匹配你正在处理的文件。如果没有任何申请 如果指定了属性，则不会自动应用说明文件。请在聊天响应的参考部分查看使用了哪些说明文件。

• 检查相关设置已启用：

  聊天.包含应用说明

  • 在 VS Code 中打开
  • 在 VS Code Insiders 中打开
  对于基于模式的指令，
  聊天.包含引用的指令

  • 在 VS Code 中打开
  • 在 VS Code Insiders 中打开
  对于通过Markdown链接引用的说明
  chat.useAgentsMdFile

  • 在 VS Code 中打开
  • 在 VS Code Insiders 中打开
  为AGENTS.md文件。

对于高级诊断，请在聊天调试视图中检查语言模型请求或调试申请 匹配逻辑.

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

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

要确定自定义指令文件的来源：

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

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

相关资源

• 使用代理技能
• 创建自定义代理
• 社区贡献的说明、提示和自定义代理