在 VS Code 中使用自定义指令

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

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

指令文件类型

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

始终生效（Always-on）指令

始终生效指令会自动包含在每个聊天请求中。请将它们用于适用于所有代码的项目级编码标准、架构决策和规范。

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

2. 根据您希望存储文件的位置，从下拉菜单中选择“新建指令（工作区）”（New Instructions (Workspace)）或“新建指令（用户）”（New Instructions (User)）。

   

   或者，使用命令面板（⇧⌘P）中的“Chat: New Instructions File”命令。

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

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

   • 填写文件顶部的 YAML frontmatter，以配置指令的描述、名称及生效条件。
   • 在文件正文中添加指令。

您可以通过在代理自定义编辑器中打开现有指令文件来修改它们。

使用 AI 生成指令文件

您可以使用 AI 生成有针对性的指令文件。在聊天中输入 /create-instruction 并描述您想要实施的惯例或准则（例如“在此项目中始终使用 Tab 键和单引号”）。代理会提出澄清问题，并生成一个带有适当 applyTo 模式和内容的 .instructions.md 文件。

您还可以从正在进行的对话中提取指令。例如，如果您在聊天期间纠正了代理的导入风格，可以要求“extract an instruction from this”，将该纠正保存为项目规范。

---
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，后跟您想要生成的指令描述。

• 在代理自定义编辑器中，从下拉菜单中选择“生成指令”（Generate Instructions）。

在团队间共享自定义指令

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

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

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

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

跨设备同步用户指令文件

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

要同步您的用户指令文件，请启用“设置同步”，并从命令面板（⇧⌘P）运行“Settings Sync: Configure”。从要同步的设置列表中选择“提示和指令”（Prompts and Instructions）。

在设置中指定自定义指令

对于代码审查、提交消息和拉取请求描述，您仍然可以使用 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 属性，该指令文件不会自动应用。查看聊天响应中的“引用”（References）部分，确认使用了哪些指令文件。

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

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

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

自定义指令文件可能来自不同来源：内置、您个人资料中定义的用户指令、当前工作区定义的工作区指令、组织级指令，或扩展插件提供的指令。

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

1. 从命令面板（⇧⌘P）中选择“Chat: Configure Instructions”。
2. 将鼠标悬停在列表中的指令文件上。来源位置会显示在工具提示中。

使用聊天自定义诊断视图查看所有已加载的指令文件及任何错误。在聊天视图中右键单击并选择“诊断”（Diagnostics）。详细了解如何在 VS Code 中对 AI 进行故障排查。

相关资源

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