GitHub Copilot 的表现完全取决于你提供的上下文。如果没有恰当的引导，你会浪费大量时间纠正偏离目标的建议，或者反复解释项目的基本细节。

一份精心编写的 copilot-instructions.md 文件能为每次提示提供一致且针对项目的上下文。你将获得：

更好的初稿质量更少的修正次数在 Agent 模式下更快的工作效率

下面我们来探讨如何构建一份有效的指令文件。

一、不要"氛围"式地编写 copilot-instructions.md

我在 GitHub 和开发者社区中调研了人们如何编写 copilot-instructions.md 文件。大多数人要么让大语言模型 (LLM) 在没有恰当项目上下文的情况下生成，要么直接复制粘贴他人的通用指令。

结果大多是通用的 AI 垃圾内容。别这么做。

copilot-instructions.md 文件会成为每次 Copilot 请求的上下文窗口的一部分。由于它随每次提示一起提交，其内容直接影响所有建议的质量和相关性。研究表明，无关信息会大幅降低响应质量，甚至更糟，会让 AI 完全偏离方向。因此，避免那些只会浪费 Token 的通用句子，转而优先提供 Copilot 无法仅从代码中立即推断出的项目特定细节，例如架构模式、领域术语和非显而易见的约束。

但首先，让我们先完成设置。

二、设置你的 copilot-instructions.md

你有两个起步选择：自己填写下面的模板来编写，或者让 Copilot Agent 为你生成文件后再进行编辑。

基于上述原因，我推荐前者。

选项 1：自己编写文件（推荐）

在仓库根目录下，如果不存在则创建 .github 文件夹。

然后在该目录中创建一个名为 copilot-instructions.md 的空文件，并将以下内容复制粘贴进去：

## 摘要
<!-- 仓库的简要概述 -->

## 术语
<!-- 领域特定术语及其解释列表 -->

## 架构
<!-- 架构的简短概述 -->

## 任务规划与问题解决
<!-- 最重要的问题解决指南 -->
<!-- 例如："在编写任何代码之前先规划任务" -->

## 编码规范
<!-- 最重要的编码规范 -->

选项 2：使用 Copilot Agent 生成文件

或者，你也可以让 GitHub Copilot Agent 生成该文件（需要最新版 VSCode）。

这会提供一个可用的起点，但某些信息很可能会有偏差甚至错误，有些内容也会缺失。因此，创建文件后，请逐句检查，迭代改进现有内容，并添加你自己的内容。

接下来，让我们看看应该包含哪些内容。

三、指令文件（instructions）中应包含什么内容

我调研了 copilot-instructions.md 文件中最常用的章节，以识别有效实践。将这些作为灵感，但根据你的项目和 Copilot 使用方式进行定制。如果你只用 Copilot 为 React 仓库生成单元测试，你的指令文件会与那些用它为 Java 服务生成新功能的人大不相同。

摘要

简要概述你的仓库，例如：

本仓库包含一个宝可梦卡牌交易平台的网页应用源代码，支持在线卡牌交易。它管理交易处理和卡牌库存追踪。

术语

列出领域特定术语及其解释，例如：

- trade - 用户的交易请求（卡牌、品相、价格）。
- stock - 宝可梦卡牌的库存，用于追踪和上架。
- queue - 待处理交易列表，优先处理用户报价。

架构

描述架构，重点关注非显而易见的细节。当你解释架构决策背后的"为什么"而不仅是"是什么"时，这个章节最有效。同时，确保引用重要文件：

React 前端直接与 Supabase 交互，进行数据库操作、
用户认证和实时交易更新，同时集成 PokeAPI 获取宝可梦数据。
选择 Supabase 是因为其实时能力，选择 PokeAPI 是因为其宽松的速率限制。
- `supabaseClient.js` - Supabase 客户端与认证。
- `realTimeTradeSubscriptions.js` - 管理交易更新。
- `pokeApiIntegration.js` - 与 PokeAPI 交互。

任务规划与问题解决

大语言模型在常识和问题解决方面存在困难。为提高 Copilot 的任务准确性，请在此章节中包含分步指令。我发现告诉大语言模型先规划再编码能获得更好的结果。有些模型会用代码淹没问题直到能运行（Claude ）。指示 Copilot 复用现有代码会有帮助。

- 每次任务前，你必须先完成以下步骤：
1. 提供完整的变更计划。
2. 提供你将变更的行为列表。
3. 提供要添加的测试用例列表。
- 在添加任何代码之前，始终检查是否可以通过复用或重新配置现有代码来实现结果。

模型特定指令

如果你发现自己主要使用同一个 AI 模型，你可能会注意到一些反复出现的缺陷或烦人之处。使用此章节来引导大语言模型朝你期望的方向发展。例如，如果 AI 倾向于过于全面，可以使用类似这样的内容：

- 始终关注简洁和精确，而非全面性。
- 编写测试时，关注主路径和最重要的边界情况。
- 在添加新测试之前，始终确保不存在类似的测试。

语言特定指令

添加语言特定规则，或使用代码生成指令（code generation instructions） （撰写本文时仅在 VSCode 中可用）。

编码规范

指定代码检查工具 (linter) 无法捕获的编码风格。需要时包含示例。

还有什么？

这些只是最常见的实用示例。添加其他针对你项目的相关指令。

但首先，让我们确保你的指令遵循有效的写作风格。

四、如何编写 copilot-instructions.md

无论你最终决定在 copilot-instructions.md 文件中包含什么，我建议遵循以下写作技巧。它们能确保你的指令对 Copilot 来说清晰且可执行：

使用一致的祈使语气。

<!-- 不要 ❌ -->
修复 bug 时，先写失败的测试会有帮助。

<!-- 要 ✅ -->
修复 bug 时，始终先写一个失败的测试。

不要泛泛而谈。建议应该具体且可执行。

<!-- 不要 ❌ -->
编写可维护的代码。

<!-- 要 ✅ -->
始终遵循 DRY 原则，避免代码重复。

与其告诉 AI 不要做什么，不如告诉它该做什么。

<!-- 不要 ❌ -->
不要使用硬编码数字。

<!-- 要 ✅ -->
避免硬编码数字，使用共享常量替代。

不要添加代码检查工具已经能捕获的风格指南。少即是多。

<!-- 不要 ❌ -->
- 遵循 ESLint 规则 `default-case`。
- 始终在 `switch` 语句末尾添加 `default` 情况。

<!-- 要 ✅ -->
<!-- 让你的代码检查工具来捕获这些问题。 -->

不要在指令中链接外部资源。

<!-- 不要 ❌ -->
获取特定宝可梦数据的 API 端点定义在[这里](https://pokeapi.co/docs/v2#pokemon)。

<!-- 要 ✅ -->
要获取特定宝可梦的数据，向 `https://pokeapi.co/api/v2/pokemon/{id or name}/` 发送 `GET` 请求。

必要时包含示例，特别是描述模式时。

<!-- 不要 ❌ -->
布尔变量前缀使用恰当的动词。

<!-- 要 ✅ -->
布尔变量前缀使用恰当的动词，例如 `isLoading`、`hasPermissions`、`matchesFilter`。

五、额外技巧：增强 Agent 模式

GitHub Copilot 的 Agent 模式在你专注于其他任务时在后台运行任务。理想情况下，你给它一个指令，它就会自动完成代码、测试和检查。实际上，Copilot 经常修改代码后就停下来，需要提示才能运行代码检查工具或测试。添加前置指令可以自动化这个过程。

为此，在你的 copilot-instructions.md 的任务规划章节中添加：

如果你添加新代码或修改现有代码，始终通过运行以下*每一项*检查来验证一切仍然正常：
1. `npm run lint` 运行代码检查工具。
2. `npm run test:unit` 运行单元测试。
3. `npm run test:e2e` 运行端到端测试。

所有检查通过后才能完成任务。

Copilot 会添加变更、运行命令、评估输出，并迭代直到修复所有错误：

默认情况下，Copilot 需要你对每次工具使用进行批准，但在 VSCode 中，你可以在 settings.json 中添加 "chat.tools.autoApprove": true 来启用 自动批准，实现完全的 氛围编程 (Vibe-Coding)。

六、总结

一份量身定制的 copilot-instructions.md 能节省你的时间并提升 Copilot 的输出质量。专注于具体、可执行的指令来引导其建议。