在 VS Code 中使用自定义指令

自定义指令使您能够定义通用的准则和规则，这些规则会自动影响 AI 如何生成代码及处理其他开发任务。无需在每个聊天提示词中手动包含上下文，只需在 Markdown 文件中指定自定义指令，即可确保 AI 的响应与您的编码实践和项目要求保持一致。

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

指令文件类型

VS Code 支持两类自定义指令。如果您的项目中存在多个指令文件，VS Code 会将它们合并并添加到聊天上下文中，不保证特定的组合顺序。

常驻指令（Always-on instructions）

常驻指令会自动包含在每个聊天请求中。适用于全项目的编码标准、架构决策以及适用于所有代码的约定。

• 单个 .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 中针对特定语言的指南
• 针对特定模块的框架模式
• 测试文件或文档的专门规则

指令文件位置

您可以为特定工作区定义指令，也可以在用户级别定义指令（应用于所有工作区）。下表列出了基于作用域的默认指令文件位置。您可以使用 chat.instructionsFilesLocations ... 设置来配置工作区指令文件的其他存放位置。

VS Code 会递归搜索这些文件夹，让您可以按团队、语言或模块组织指令文件。

.github/instructions/
  frontend/
    react.instructions.md
    accessibility.instructions.md
  backend/
    api-design.instructions.md
  testing/
    unit-tests.instructions.md

以下示例展示了如何配置指令文件位置，使其仅允许工作区级指令

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

指令文件格式

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

主体部分包含 Markdown 格式的指令。要引用代理工具，请使用 #tool:<tool-name> 语法（例如 #tool:web/fetch）。

---
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. 在聊天视图中，选择“配置聊天”（齿轮图标）以打开聊天自定义编辑器，然后选择“指令”选项卡。

2. 从下拉菜单中选择“新建指令 (工作区)”或“新建指令 (用户)”，具体取决于您希望存储该指令文件的位置。

   

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

3. 选择位置并为您的指令文件输入文件名。这是 UI 中使用的默认名称。

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

   • 在文件顶部填写 YAML frontmatter，以配置指令的描述、名称和应用时机。
   • 在文件主体中添加指令。

您可以在聊天自定义编辑器中打开现有指令文件并进行修改。

使用 AI 生成指令文件

您可以使用 AI 生成目标明确的指令文件。在聊天中输入 /create-instruction 并描述您想要执行的约定或指南（例如，“在这个项目中始终使用 tab 和单引号”）。代理会提出澄清问题，并生成一个包含相应 applyTo 模式和内容的 .instructions.md 文件。

您还可以从持续进行的对话中提取指令。例如，如果您在聊天中纠正了代理的 import 风格，可以要求“从中提取指令”，将该纠正保存为项目约定。

---
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 文件支持，请配置 chat.useAgentsMdFile ... 设置。

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

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

使用实验性设置 chat.useNestedAgentsMdFiles ... 来启用或禁用工作区中嵌套 AGENTS.md 文件的支持。

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

使用 CLAUDE.md 文件

VS Code 会自动检测 CLAUDE.md 文件并将其作为常驻指令应用，类似于 AGENTS.md。如果您在 VS Code 之外使用 Claude Code 或其他基于 Claude 的工具，并希望它们识别同一套指令，此功能非常有用。

VS Code 在这些位置搜索 CLAUDE.md 文件

要启用或禁用 CLAUDE.md 文件支持，请配置 chat.useClaudeMdFile ... 设置。

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

VS Code 可以分析您的工作区并生成与您的编码实践和项目结构相匹配的常驻自定义指令。这些指令随后会自动应用于工作区内的所有聊天请求。

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

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

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

• 在聊天输入框中输入 /init 并按 Enter 键。

• 输入 /create-instructions，后跟您想要生成的指令描述。

• 在聊天自定义编辑器中，从下拉菜单中选择“生成指令”。

跨团队共享自定义指令

要在 GitHub 组织内的多个工作区和仓库间共享自定义指令，您可以在 GitHub 组织层面定义它们。

VS Code 会自动检测在您的账户有权访问的组织层面定义的自定义指令。这些指令会显示在“聊天指令”菜单中，与您的个人和工作区指令并列，并自动应用于所有聊天请求。

要启用组织级自定义指令的发现功能，将 github.copilot.chat.organizationInstructions.enabled ... 设置为 true。

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

跨设备同步用户指令文件

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

要同步用户指令文件，请启用“设置同步”，并在命令面板中运行“设置同步：配置”（⇧⌘P (Windows, Linux Ctrl+Shift+P)）。从设置列表中选择“提示词和指令”进行同步。

在设置中指定自定义指令

对于代码审查、提交消息和拉取请求描述，您仍然可以使用 VS Code 设置来定义自定义指令。这些设置接受一个对象数组，每个对象包含 text 属性（内联指令）或 file 属性（指向 Markdown 文件的路径）。

指令优先级

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

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

编写有效指令的技巧

• 保持指令简短且自包含。每条指令都应是单个、简单的陈述。如果需要提供多条信息，请使用多条指令。

• 包含规则背后的理由。当指令解释了为什么要存在某个约定，AI 在处理边缘情况时会做出更好的决定。例如：“使用 date-fns 而不是 moment.js，因为 moment.js 已被弃用且会增加包体积。”

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

• 专注于非显而易见的规则。跳过标准 Linter 或格式化工具已经强制执行的约定。

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

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

• 在您的 提示词文件 和 自定义代理 中复用和引用指令文件，以保持它们简洁、重点突出，并避免指令重复。

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

常见问题

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

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

• 验证您的指令文件位置是否正确。.github/copilot-instructions.md 文件必须位于工作区根目录的 .github 文件夹中。*.instructions.md 文件必须位于 chat.instructionsFilesLocations ... 设置指定的文件夹之一（或其子目录，默认：.github/instructions），或在您的用户配置文件中。

• 对于 *.instructions.md 文件，检查 applyTo glob 模式是否匹配您正在处理的文件。如果未指定 applyTo 属性，该指令文件不会自动应用。检查聊天响应中的“引用”部分，查看使用了哪些指令文件。

• 检查相关设置是否已启用：用于模式匹配指令的 chat.includeApplyingInstructions ... ，用于通过 Markdown 链接引用的指令的 chat.includeReferencedInstructions ... ，以及用于 AGENTS.md 文件的 chat.useAgentsMdFile ... 。

如需高级诊断，请 在聊天调试视图中检查语言模型请求 或 调试 applyTo 匹配逻辑。

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

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

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

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

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

相关资源

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