在VS Code中使用自定义指令

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

你可以配置自定义指令，自动应用到所有聊天请求或仅针对特定文件。或者，你也可以手动将自定义指令附加到特定的聊天提示上。

指令文件的类型

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

始终在线指令

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

• 一首单曲.github/copilot-instructions.md文件

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

• 一个或多个AGENTS.md文件

  • 如果你在工作空间里同时作多个 AI 代理，这很有用
  • 自动应用于工作区内的所有聊天请求或特定子文件夹（实验性）
  • 存储在工作区根目录或子文件夹（实验性）

• 组织层级指令

  • 在 GitHub 组织内的多个工作区和仓库之间共享指令
  • 在GitHub组织层面定义

• CLAUDE.md文件

  • 为了兼容 Claude 代码及其他基于 Claude 的工具
  • 存储在工作区根中，.克劳德文件夹，或用户主目录

基于文件的指令

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

• 一个或多个.instructions.md文件
  • 通过使用滚动模式，基于文件类型或位置有条件地应用指令
  • 存储在工作区或用户配置文件中

为了在说明中引用具体上下文，比如文件或网址，可以使用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.mdMarkdown 文件，基于代理正在处理的文件或任务动态应用。

代理根据指定的文件模式决定要应用哪些指令文件应用指令文件头中的属性，或指令描述与当前任务的语义匹配。

用途.instructions.md文件涵盖：

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

指令文件位置

你可以为特定工作区或用户层面定义指令，并应用到所有工作区。

为了兼容 Claude Code 及其他基于 Claude 的工具，VS Code 还检测.claude/rulesworkspace 文件夹和~/.claude/rules用户文件夹。

你可以通过以下方式配置工作区指令文件的额外文件位置，

指令文件格式

指令文件是带有.instructions.md延伸。可选的 YAML 前置头负责控制指令的应用时间：

正文包含Markdown格式的指令。要引用代理工具，可以使用#tool：<工具名>语法（例如，#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.instructions文件位置

     • 在VS代码中打开
     • 在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 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编码代理，并且需要一套被所有AI识别的指令
• 你需要针对单仓库特定部分的子文件夹级指令

启用或禁用支持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 搜索CLAUDE.md这些地点的文件：

启用或禁用支持CLAUDE.md文件，配置

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

VS Code可以分析你的工作空间，生成与你的编码实践和项目结构相匹配的始终在线定制指令。这些指令随后会自动应用到工作区内的所有聊天请求。

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

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

使用该/init斩击命令

用自定义指令快速启动工作区的方法是输入/init在聊天输入框里用slash指令。

该/init命令以贡献提示词文件的形式实现，因此你可以通过修改底层提示来自定义其行为。

使用命令生成指令

要用以下命令生成自定义工作区指令：

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

2. 查看生成的说明文件并进行必要的修改。

跨团队共享自定义指令

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

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

为了实现组织层级自定义指令的发现，设置

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

跨设备同步用户指令文件

VS Code 可以通过设置同步功能，将用户指令文件同步到多个设备。

要同步用户指令文件，请启用提示和指令文件的设置同步：

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

2. 运行设置同步：从命令面板配置（Windows，Linux Ctrl+Shift+P））。

3. 从设置列表中选择“提示和指令”进行同步。

在设置中指定自定义指令

对于代码审查或提交信息生成等特殊场景，你可以使用 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在边缘情况下做出更明智的决策。例如：“使用日期-fns（日期-fns）代替moment.js—— moment.js 已被弃用并增加捆绑包大小。”

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

• 关注那些不显而易见的规则。跳过标准模板或格式化器已经强制执行的惯例。

• 对于任务或语言特定的指令，使用多个指令*.instructions.md每个主题的文件，并通过使用应用财产。

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

• 在提示文件和自定义代理中重复使用并引用指令文件，保持清晰且聚焦，避免重复指令。

• 指令之间的空白被忽略，因此你可以将指令格式化为单段、分行，或用空行分隔以保证可读性。

常见问题解答

为什么我的说明文件没有被应用？

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

• 确认说明文件在正确的位置。A.github/copilot-instructions.md文件必须在.github文件夹放在你工作区的根节点。A*.instructions.md文件必须位于指定文件夹中的某个

  chat.instructions文件位置

  • 在VS代码中打开
  • 在VS Code Insiders中开放
  设置（默认：.github/instructions）或者在你的用户资料中。

• 对于*.instructions.md文件，检查一下应用球状图案与你正在处理的文件相符。如果没有应用属性被指定，指令文件不会自动应用。请在聊天回复中查看参考文献部分，查看使用了哪些指令文件。

• 检查相关设置是否已启用：

  chat.include应用指令

  • 在VS代码中打开
  • 在VS Code Insiders中开放
  对于基于模式的指令，
  chat.includeReferencedInstructions

  • 在VS代码中打开
  • 在VS Code Insiders中开放
  通过Markdown链接参考的说明，
  chat.useAgentsMdFile

  • 在VS代码中打开
  • 在VS Code Insiders中开放
  对于AGENTS.md文件。

如需高级诊断，请在聊天调试视图中查看语言模型请求，或调试应用匹配逻辑.

我怎么知道自定义指令文件的来源？

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

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

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

使用聊天自定义诊断视图查看所有加载的指令文件和错误。在聊天视图中右键点击，选择诊断。了解更多关于在VS Code中排查AI的问题。

相关资源

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