为 GitHub Copilot CLI 添加自定义指令

如果您为 GitHub Copilot 提供足够的上下文，它便可提供根据您的个人偏好、团队工作方式、所用工具或项目特定要求量身定制的响应。您无需反复将此上下文详细信息添加到提示中，而是可以创建自定义指令，Copilot 会自动为您添加此信息。附加信息不会显示，但 Copilot 可以使用这些信息来生成更高质量的响应。

自定义指令类型

GitHub Copilot CLI 支持以下类型的自定义指令。

仓库范围的自定义指令

这些指令适用于在仓库上下文中发出的所有请求。

这些指令在仓库根目录的 .github 目录下的 copilot-instructions.md 文件中指定。参见 创建仓库范围的自定义指令。

路径特定的自定义指令

这些指令适用于在匹配指定路径的文件上下文中发出的请求。

这些指令在仓库根目录的 .github/instructions 目录及其下的一个或多个 NAME.instructions.md 文件中指定，或在当前工作目录的 .github/instructions 目录及其下的文件中指定。参见 创建路径特定的自定义指令。

如果您在这些指令中指定的路径匹配 Copilot 正在处理的文件，并且同时存在仓库范围的自定义指令文件，则两者的指令都会被使用。应避免指令之间的潜在冲突，因为 Copilot 对冲突指令的选择是非确定性的。

代理指令

这些指令被各种 AI 代理使用。

您可以创建一个或多个 AGENTS.md 文件。这些文件可以放在仓库根目录、当前工作目录，或在环境变量 COPILOT_CUSTOM_INSTRUCTIONS_DIRS 中以逗号分隔的路径列表指定的任意目录中。

如果在根目录中找到 AGENTS.md 文件，其指令将被视为主要指令。如果在仓库根目录同时存在 AGENTS.md 文件和 .github/copilot-instructions.md 文件，则两者的指令都会被使用。

在其他 AGENTS.md 文件中找到的指令被视为附加指令。任何找到的主要指令通常会对 Copilot 的响应产生比附加指令更大的影响。

欲了解更多信息，请参阅 agentsmd/agents.md 仓库。

或者，您也可以使用 CLAUDE.md 和 GEMINI.md 文件。这些文件必须位于仓库根目录。

本地指令

这些指令适用于特定的本地环境。

您可以在自己的主目录中指定指令，方法是在 $HOME/.copilot/copilot-instructions.md 创建文件。

您也可以将环境变量 COPILOT_CUSTOM_INSTRUCTIONS_DIRS 设置为逗号分隔的目录列表。Copilot CLI 将在每个目录中查找 AGENTS.md 文件以及任何 .github/instructions/**/*.instructions.md 文件。

创建仓库范围的自定义指令

1. 在仓库的根目录中，创建一个名为 .github/copilot-instructions.md 的文件。

   如果 .github 目录尚不存在，请创建它。

2. 以 Markdown 格式向文件中添加自然语言指令。

   指令之间的空白将被忽略，因此指令可以写成单个段落，每条指令在新的一行，或者为了易读性用空行分隔。

   有关编写有效自定义指令的帮助，请参阅 关于自定义 GitHub Copilot 响应。

创建特定路径的自定义指令

1. 如果 .github/instructions 目录尚不存在，请创建它。

2. 可选地，创建 .github/instructions 的子目录来组织您的指令文件。

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

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

   例如

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

   您可以通过逗号分隔多个模式。例如，要将指令应用于仓库中的所有 TypeScript 文件，可以使用以下 frontmatter 块

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

   Glob 示例

   • * - 将匹配当前目录中的所有文件。
   • ** 或 **/* - 将匹配所有目录中的所有文件。
   • *.py - 将匹配当前目录中的所有 .py 文件。
   • **/*.py - 将递归匹配所有目录中的所有 .py 文件。
   • src/*.py - 将匹配 src 目录中的所有 .py 文件。例如，src/foo.py 和 src/bar.py，但**不**匹配 src/foo/bar.py。
   • src/**/*.py - 将递归匹配 src 目录中的所有 .py 文件。例如，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，但**不**匹配不包含 subdir 目录的路径中的 foo.py。

5. 可选地，为了防止文件被 Copilot 云代理或 Copilot 代码审查使用，请在 frontmatter 块中添加 excludeAgent 关键字。使用 "code-review" 或 "cloud-agent"。

   例如，以下文件将仅由 Copilot 云代理读取。

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

   如果 frontmatter 块中未包含 excludeAgent 关键字，Copilot 代码审查和 Copilot 云代理都将使用您的指令。

6. 使用 Markdown 格式添加您的自然语言自定义指令。指令之间的空白将被忽略，因此指令可以写成单个段落，每条指令在新的一行，或者为了易读性用空行分隔。

正在使用的自定义指令

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

如果您在 CLI 会话期间更改了自定义指令，则这些更改将在当前或将来的会话中下次提交提示时供 Copilot 使用。

延伸阅读

• 对不同类型自定义指令的支持
• 自定义指令——精选示例集
• 使用自定义指令解锁 Copilot 代码审查的强大功能