Adding repository custom instructions for GitHub Copilot in your IDE

This version of this article is for using repository custom instructions and prompt files in Visual Studio. Click the tabs above for instructions on using custom instructions in other environments.

介绍

通过存储库自定义说明，可以为 Copilot 提供特定于存储库的指导和首选项。 有关详细信息，请参阅“关于自定义GitHub Copilot 响应”。

仓库自定义指令的先决条件

• 必须有自定义指令文件（请参阅以下指令）。

• The Enable custom instructions... option must be enabled in your settings. This is enabled by default. See Enabling or disabling repository custom instructions later in this article.

Creating custom instructions

Visual Studio supports two types of custom instructions. For details of which GitHub Copilot features support these types of instructions, see 关于自定义GitHub Copilot 响应.

• Repository-wide custom instructions, which apply to all requests made in the context of a repository.

  These are specified in a copilot-instructions.md file in the .github directory of the repository. See Creating repository-wide custom instructions.

• Path-specific custom instructions, which apply to requests made in the context of files that match a specified path.

  These are specified in one or more NAME.instructions.md files within or below the .github/instructions directory in the repository. See Creating path-specific custom instructions.

  If the path you specify matches a file that Copilot is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used.

Creating repository-wide custom instructions

1. In the root of your repository, create a file named .github/copilot-instructions.md.

   Create the .github directory if it does not already exist.

2. Add natural language instructions to the file, in Markdown format.

   Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility.

Creating path-specific custom instructions

1. 如果尚无 .github/instructions 目录，则创建该目录。

2. （可选）创建用于组织指令文件的子目录 .github/instructions 。

3. 创建一个或多个 NAME.instructions.md 文件，其中 NAME 指示指令的用途。 文件名必须以 .instructions.md 结尾。

4. 在文件开头，创建包含 applyTo 关键字的前辅文块。 使用 glob 语法指定指令应用于的文件或目录。

   例如：

   ---
   applyTo: "app/models/**/*.rb"
   ---
   

   可以通过用逗号分隔多个模式来指定这些模式。 例如，若要将指令应用于仓库中的所有 TypeScript 文件，可以使用以下前辅文块：

   ---
   applyTo: "**/*.ts,**/*.tsx"
   ---
   

   Glob 示例：

   • * - 会匹配当前目录中的所有文件。
   • ** 或 **/* - 均会匹配所有目录中的所有文件。
   • *.py - 将匹配当前目录中的所有 .py 文件。
   • **/*.py - 将以递归方式匹配所有目录中的所有 .py 文件。
   • src/*.py - 将匹配 .py 目录中所有 src 文件。 例如，src/foo.py和src/bar.py但_不_src/foo/bar.py。
   • src/**/*.py - 将以递归方式匹配目录中的所有 .py 文件 src 。 例如 、 src/foo.py``src/foo/bar.py和 src/foo/bar/baz.py。

   •           `**/subdir/**/*.py` - 将递归匹配任意深度下任意 `subdir` 目录中的所有 `.py` 文件。 例如，`subdir/foo.py`、`subdir/nested/bar.py`、`parent/subdir/baz.py` 和 `deep/parent/subdir/nested/qux.py`，但不匹配_不_`foo.py`包含 `subdir` 目录的路径。
     

5. 或者，为了防止文件被 Copilot cloud agent 或 Copilot code review 使用，将 excludeAgent 关键字添加到 frontmatter 区块中。 使用 "code-review" 或 "cloud-agent"。

   例如，以下文件将仅由 Copilot cloud agent 读取。

   ---
   applyTo: "**"
   excludeAgent: "code-review"
   ---
   

   如果在 front matterblock 中不包括关键字 excludeAgent，则 Copilot code review 和 Copilot cloud agent 都将使用您的说明。

6. 使用 Markdown 格式以自然语言添加自定义指令。 系统会忽略说明信息间的空格，因此可将信息编写为一个段落，每个段落位于一行上，或用空白行分隔，以保持其可读性。

正在使用的自定义说明

文件（s）中的说明可在保存文件后立即使用 Copilot 。 指令会自动添加到您提交给Copilot的请求中。

自定义说明在“聊天”视图或内联聊天中不可见，但可以通过查看“聊天”视图中的回复引用列表来验证 Copilot 是否正在使用这些说明。 如果将自定义说明添加到发送到模型的提示中，引用信息中会列出文件 .github/copilot-instructions.md。 可以单击引用信息来打开该文件。

启用或禁用存储库自定义说明

可以选择是否要让 Copilot 使用基于仓库的自定义指令。

为 Copilot Chat 启用或禁用自定义指令

默认情况下，Copilot Chat 已启用自定义指令，但你可以随时禁用或重新启用它们。 这适用于你自己的 Copilot Chat 使用，不会影响其他用户。

1. In the Visual Studio menu bar, under Tools, click Options.

   

2. In the "Options" dialog, type custom instructions in the search box, then click Copilot.

3. Select or clear the checkbox for Enable custom instructions to be loaded from .github/copilot-instructions.md files and added to requests.

   

启用或禁用 Copilot code review 的自定义指令

默认情况下，Copilot code review 已启用自定义说明，但你可以在 GitHub.com 上的仓库设置中将其禁用或重新启用。 这适用于 Copilot 在此仓库中执行所有代码审查时对自定义指令的使用。

1. 在 GitHub 上，导航到存储库的主页面。

2. 在仓库名称下，单击 “Settings”****。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。

   

3. 在边栏中的“代码、规划和自动化”下， 单击 Copilot，然后单击 代码评审。

4. 打开或关闭“Use custom instructions when reviewing pull requests”选项。

Using prompt files

Prompt files let you build and share reusable prompt instructions with additional context. A prompt file is a Markdown file, stored in your workspace, that mimics the existing format of writing prompts in Copilot Chat (for example, Rewrite #file:x.ts). You can have multiple prompt files in your workspace, each of which defines a prompt for a different purpose.

Creating prompt files

1. Add a prompt file, including the .prompt.md file name extension inside the .github/prompts folder in the root of the repository. The name can contain alphanumeric characters and spaces and should describe the purpose of the prompt information the file will contain.

2. Write the prompt instructions, using Markdown formatting.

   You can reference other files in the workspace by using Markdown links—for example, [index](../../web/index.ts)—or by using the #file:'../../web/index.ts' syntax. Paths are relative to the prompt file. Referencing other files allows you to provide additional context, such as API specifications or product documentation.

For more information about prompt files, see Use prompt files in Visual Studio in the Visual Studio documentation.

Further reading

• 支持不同类型的自定义说明
• 定制化库—a curated collection of examples
• 使用自定义指令来激发Copilot代码评审的强大功能