摘要：本指南提供了编写有效的 GitHub Copilot 自定义指令的 5 个关键技巧，内容涵盖项目概述、技术栈、编码规范、结构和资源，旨在帮助开发者获得更优质的代码建议。
M
作者：Christopher Harrison
排版：Alan Wang
本指南提供了编写有效的 GitHub Copilot 自定义指令的 5 个关键技巧，内容涵盖项目概述、技术栈、编码规范、结构和资源，旨在帮助开发者获得更优质的代码建议。
如果你读过我的文章，或者听过我的演讲，你很可能已经听过我那个带点调侃的玩笑：“别对 Copilot 搞消极对抗那一套。”
不过，这个玩笑背后其实有个认真的观点：Copilot 在得到合适的上下文时才能发挥最佳效果。它就像一个新加入的队友，并不能读心（尽管有时看起来像能读心一样）。
Copilot 通常能大致推断出你在做什么以及怎么做，但如果你能把关键点说明清楚——比如你在构建什么、使用的技术栈有哪些、需要遵循什么规则等等——就能避免很多误解和错误。
这也是为什么指令文件如此重要。它能为 Copilot 提供你团队成员通过项目经验才掌握的背景信息和知识。
其中的核心就是 copilot-instructions.md文件。每一次 Copilot 的对话或 Agent 请求，都会读取它。
那么，这个文件应该怎么写呢？
为了帮你避免“面对空白文件无从下手”的困境，我整理了每个指令文件都应该包含的五个要点（还会额外附赠一个小技巧——让 Copilot 自己帮你写这个文件）。
在开始之前
在深入更多细节之前，我想先分享一个重要建议：别想太多。撰写说明文档并没有一套固定的 “标准流程”。生成式 AI 的本质是概率性的 —— 这意味着即便是相同的请求，实际输出的结果也可能不同。你的目标不是追求 “绝对正确”，而是 “优化概率”：尽可能引导 Copilot，让它更频繁地给出你期望的答案。
下面提到的 5 部分内容（以及附赠技巧）并非 “强制要求”，而是 “参考建议”。根据我的经验，只要你的指令文件中包含了这些内容，或者至少涵盖了这些内容所指向的关键信息，Copilot 给出的建议质量就会大幅提升。
你可以把这些内容当作 “起点”，再结合自身项目特点、使用的模型类型，以及与 Copilot 的互动经验，不断尝试和调整优化。
01 为 GitHub Copilot 提供项目概述
要是连一款应用是做什么的都不知道，根本没法为它写代码！GitHub Copilot 也是如此——而项目概述指令文件，恰好能在这一点上发挥关键作用。
你的指令文件开头，应当像“电梯演讲”一样概括应用。比如：这款应用是什么？目标用户是谁？核心功能有哪些？内容无需冗长，只需用几句话搭建好背景框架即可。
以下是指令文件中项目概述的示例：
Contoso Companions
本网站为宠物领养机构提供支持服务。机构可入驻平台，管理自身线下站点、待领养宠物信息，并发布相关活动；潜在领养者则能搜索所在地区的可领养宠物、了解各类领养机构，还可提交领养申请。
02 明确你在项目中使用的技术栈
在确定你要构建的内容之后，下一个关键点就是明确你是用什么来构建它的。这包括你使用的后端与前端技术、调用的 API，以及目标测试套件。毕竟，用来创建网站的框架数量本就不断增长。举个例子，或许在你读完这篇博文的时间里，已经有三个新的 JavaScript 框架发布了！
在编写指令文件时，你不需要化身 George RR Martin，写出成段成段的技术细节。相反，可以考虑列出你所使用的技术栈，并加上一两条关于它们用法的简要说明。这将帮助 Copilot 理解它要生成代码的环境。
以下是我工作中使用的一个快速示例，供参考：
## 使用的技术栈### 后端- 使用 Flask 作为 API - 数据存储在 Postgres 中，使用 SQLAlchemy 作为 ORM - 为开发、测试和生产环境分别配置了数据库 - 在端到端测试中，会新建并填充一个数据库，测试完成后再删除 ### 前端- 使用 Astro 管理核心站点与路由 - 使用 Svelte 实现交互功能 - 使用 TypeScript 编写所有前端代码 ### 测试- 使用 Unittest 进行 Python 测试 - 使用 Vitest 进行 TypeScript 测试 - 使用 Playwright 进行端到端测试03 明确你的编码规范
在创建第一个 Pull Request 之前，你需要清楚应该遵循哪些编码规范。其中一部分是关于代码应该如何编写的。比如说，我们在 JavaScript 或 TypeScript 中是否使用分号？Python 是否使用类型提示？使用 Tab 还是空格？（唯一正确答案是：使用分号、使用类型提示，以及——用空格。不接受反驳。）
根据你的项目结构，你可以把编码规范写进技术栈指令文件中。但我通常更倾向于单独设立一个规范部分，因为很多规范会适用于多个语言。我发现这样更便于阅读，而可读性对于可维护性至关重要，而且不同语言和框架之间往往存在共通的指导原则。
你也可以考虑为特定类型的文件使用单独的 .instructions 文件来定义规范，例如所有 .astro或.jsx文件，或者遵循/tests/test_*.py命名模式的单元测试文件。
专业提示
人们很容易陷入一种循环，不断尝试去寻找给 Copilot 编写提示词或构建指令文件的“完美方式”。但实际上，一个“不完美”的指令文件也远比完全没有文件的效果要好得多。指令文件也应该随着时间演进，就像文档一样。（当然，我们的文档都是随时保持更新的，对吧？）我强烈建议你多做尝试，找出最适合的方法，不要让“完美”成为“良好”的敌人。
这是我自己工作中的另一个示例：
## 项目与代码规范- 在任何支持类型提示的语言中，始终使用类型提示 - JavaScript/TypeScript 必须使用分号 - 必须编写单元测试，并且在提交 PR 前必须全部通过 - 单元测试应聚焦于核心功能 - 必须编写端到端测试 - 端到端测试应聚焦于核心功能 - 端到端测试应验证可访问性 - 始终遵循良好的安全实践 - 遵循 RESTful API 设计原则 - 在可行时使用脚本来执行操作.instructions
https://code.visualstudio.com/docs/copilot/copilot-customization#_use-instructionsmd-files/?wt.mc_id=3reg_webpage_reactor
04 解释你的项目结构
正如编写代码有无数种框架和方式一样，项目结构也有看似无限的组织方法。比如，在一个 monorepo 结构中，你的前端代码可能放在名为 frontend的文件夹里。或者叫front-end。或者front_end。或者client。甚至web……
你大概已经明白我要说什么了。
虽然 Copilot 大概率能自己推断出来，但一次简单的 ls 命令就能得出答案。不过，在自定义指令文件中列出项目结构，既能帮 Copilot 省点功夫，也给了你一个机会去提供更多关于文件夹内容的上下文信息。
以下是一个示例：
## 项目结构- server/ ：Flask 后端代码 - models/ ：SQLAlchemy ORM 模型 - routes/ ：按资源组织的 API 端点 - tests/ ：API 的单元测试 - utils/ ：工具函数与辅助方法，包括数据库调用 - client/ ：Astro/Svelte 前端代码 - src/components/ ：可复用的 Svelte 组件 - src/layouts/ ：Astro 布局模板 - src/pages/ ：Astro 页面与路由 - src/styles/ ：CSS 样式表 - scripts/ ：开发、部署与测试脚本 - docs/ ：项目文档（需始终保持同步）05 指引 GitHub Copilot 使用可用资源
几乎每个项目都有一套可用的脚本或资源来辅助开发。这些可能是用于简化环境搭建或运行测试的脚本，也可能是用于生成代码或模板的软件工厂。特别是随着 VS Code 中 MCP 支持以及 Copilot 编码 Agent 的引入，为 Copilot 的 Agent 提供了更多可用工具。
我们已经确认 Copilot 能够发现可用资源，但通过自定义指令文件提供一些指向正确方向的提示，可以提升其准确性和运行速度。
下面是一个示例：
## 资源- scripts 文件夹 - start-app.sh：安装所有依赖库并启动应用 - setup-env.sh：安装所有依赖库 - test-project.sh：安装所有依赖库，并运行单元测试和端到端测试 - MCP 服务器 - Playwright：用于生成 Playwright 测试或与网站交互 - GitHub：用于与代码仓库和待办事项（backlog）交互VS Code 中 MCP 支持
https://code.visualstudio.com/docs/copilot/chat/mcp-servers/?wt.mc_id=3reg_webpage_reactor
Copilot 编码 Agent
https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp/?wt.mc_id=3reg_webpage_reactor
额外提示
让 GitHub Copilot 帮你创建自定义指令文件
创建指令文件没有一种完美的方法，有总比没有好。但我们都希望尽量做得正确，或者尽量接近正确。希望上面的指南已经给了你一些灵感！
然而，实际去写文件仍然是一个问题，这可能会让你再次面对“面对空白文件无从下手”的困境。
幸运的是，Copilot 可以帮助你更好地帮助自己！
你可以在 IDE 中使用 Copilot Agent 模式，或者在 GitHub 仓库中为 Copilot 分配一个 Issue，请它帮你生成指令文件。生成的文件可以直接使用，也可以根据需要进行编辑。我们的 Copilot 官方文档中甚至提供了推荐的提示语，用于生成指令文件！精简版的推荐提示如下：
你的任务是通过添加 .github/copilot-instructions.md 文件，将此仓库“接入”编码 Agent。文件应包含信息，说明当智能体首次接触该仓库时，如何能够最高效地工作。每个仓库只需执行一次此任务，做好这项工作可以显著提升 Agent 的工作质量，因此请慢慢来，仔细思考，并在撰写指令前进行充分搜索。## 目标- 文档化现有项目结构和技术栈 - 确保遵循既定的开发规范 - 尽量减少 bash 命令和构建失败 ## 限制- 指令文件不得超过 2 页 - 指令应适用于整个项目 ## 指南请确保包含以下内容：- 应用功能概述 - 使用的技术栈 - 编码规范 - 项目结构 - 已有工具和资源 ## 步骤- 对代码库进行全面盘点，查找并查看： - README.md、CONTRIBUTING.md 及其他所有文档文件 - 搜索代码库中类似 HACK、TODO 等标记的解决方案 - 所有脚本，尤其是与构建、仓库或环境设置相关的脚本 - 所有项目文件 - 所有配置文件和 lint 文件 - 记录其他任何可以帮助智能体减少探索或尝试失败的 bash 命令时间的步骤或信息 ## 验证使用新创建的指令文件实现一个示例功能。利用在构建新功能过程中遇到的失败或错误经验，进一步完善指令文件。使用上述提示语可以帮助你节省时间，但更重要的是，它还能帮助你理清对任意项目的思路和目标。
为 Copilot 分配一个 Issue
https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/assign-copilot-to-an-issue/?wt.mc_id=3reg_webpage_reactor
Copilot 官方文档
https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions-a-single-githubcopilot-instructionsmd-file-1/?wt.mc_id=3reg_webpage_reactor
关于指令文件的最后说明
需要说明的是，提供指令并不能保证生成的代码完美无缺。但拥有一个良好的指令文件，是提升 Copilot 代码建议质量重要的第一步。如果你问我，对于任何使用 Copilot 的项目，拥有一个 copilot-instructions.md文件都是必备的。
再次强调——它不需要完美。以以下几个部分为起点，就能打下坚实的基础：
你正在构建内容的简要介绍
使用的框架和技术栈
编码规范及其他项目指南
项目结构及资源位置
可用于自动化和任务处理的资源
从这里出发，你可以进一步探索 .instructions 文件，来为 Copilot 提供更具体的指导。但这一切都始于 copilot-instructions.md。
.instructions 文件
阅读官方文档
https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions/?wt.mc_id=3reg_webpage_reactor
来源：opendotnet
