为 GitHub Copilot 编写自定义指令的五个核心技巧

#clippings
本文总阅读量次

前言

随着 AI 编程助手日益融入日常开发流程，我们正从简单的提示词互动，迈向一个更深层次的“上下文工程 (Context Engineering)”时代。从 Cursor 编辑器的 .cursorrule 文件，到 Claude Code 的 claude.md 再到 OpenAI 提出的 agents.md 概念，各大平台都在探索如何让开发者通过自定义指令文件，更精确地引导 AI 的行为。这种与 AI 深度协作，依赖直觉和上下文引导的“氛围编程 (Vibe Coding)”模式正逐渐成为新范式。这些不同名称的指令文件，其核心目标殊途同归：为 AI 提供高质量、结构化的项目背景信息。因此，掌握如何编写一份优秀的指令文件至关重要。

下面将分享一篇关于为 GitHub Copilot 编写自定义指令技巧的文章，而这些原则和方法同样具有普适性，可以轻松应用于 claude.md, agents.md 或 .cursorrule 等文件的编写中，帮助你全面提升与各类 AI 编码工具的协作效率。

copilot_5_tips.png

如果你曾读过我的文章或听过我的演讲，或许会记得我那句略带幽默的提醒：“对 Copilot，请直截了当，别惜字如金，含糊其辞。”

这句玩笑话背后，其实蕴藏着一个严肃的道理：Copilot 只有在获得足够清晰、准确的上下文信息时，才能发挥最佳效用。它就像一位新入职的团队成员，无法直接洞察你的意图（尽管有时它会让你产生这种错觉）。

Copilot 很可能能理解你在做什么以及你是如何实现的。但若能明确阐述要点，比如你正在构建什么、使用的技术栈、需要遵循的规则等，将有助于避免混淆和错误。

这就是自定义指令文件如此重要的原因。它们是你向 Copilot 提供背景信息，以及团队其他成员通过项目实践积累的项目沉淀和团队经验的机会。

Copilot 的核心是 copilot-instructions.md 文件，每次 Copilot 聊天或代理请求都会读取这个文件。

那么，这样的文件应该如何编写呢？

为了避免“无从下手”的困扰，这里有五项每份自定义指令文件都应包含的内容（外加一项额外技巧：Copilot 如何帮助你编写指令文件本身）。

开始之前

在深入细节之前，我想先分享一个重要建议：不要过度思考。编写自定义指令文件并没有一套固定的、预设的方式。生成式 AI 的本质是基于概率的（即它的输出具有不确定性），这意味着相同的请求实际上可能会产生不同的结果。你的目标是“提升成功率”，尽可能地引导 Copilot 找到你期望的答案。

下面的五个部分（以及额外技巧）并非强制性要求，而是建议。根据我的经验，在指令文件中包含这些部分，或者至少是这些部分所指出的关键信息，将大大提高 Copilot 建议的质量。

你应该将它们作为起点，并根据你的项目、模型以及与 Copilot 的使用经验进行试验和探索。

为 GitHub Copilot 提供项目概览

如果你不知道一个应用是做什么的，就很难为其编写代码！GitHub Copilot 也是如此，而项目概览指令文件在这里能提供极大的帮助。

你的自定义指令文件开头应该包含应用的“电梯演讲”式概括。这个应用是什么？目标受众是谁？主要功能有哪些？它不需要冗长，只需几句话来铺垫即可。

以下是一个指令文件中项目概览的示例：

# Contoso Companions

This is a website to support pet adoption agencies. Agencies are onboarded into the application, where they can manage their locations, available pets, and publicize events. Potential adoptors can search for pets available in their area, discover agencies, and submit adoption applications.

# Contoso Companions

这是一个支持宠物领养机构的网站。机构可以入驻到应用程序中，管理其地点、可领养的宠物以及宣传活动。潜在领养者可以搜索其所在区域可领养的宠物、发现机构并提交领养申请。

上面的示例清晰、直接、简洁。你无需写成长篇巨著，但从宏观层面为 Copilot 提供你试图实现的目标的上下文非常重要。当然，这个示例应用与我个人是否想收养宠物的心情无关，纯属巧合。

明确项目中使用的技术栈

在明确项目目标后，下一步应说明实现目标所采用的技术栈。这包括你正在使用的后端和前端技术、调用的任何 API 以及目标测试套件。毕竟，仅用于创建网站的框架数量就一直在增长。举个例子？你开始阅读这篇博文以来，可能已经有三个新的 JavaScript 框架发布了！

在创建自定义指令文件时，你无需事无巨细地撰写长篇大论来解释每一个细节。相反，可以考虑创建一个列表，突出显示你正在使用的技术，并可能添加一两句关于它们如何被使用的说明。这将帮助 Copilot 理解它正在其中创建代码的环境。以下是我自己工作中的一个简短示例供你参考：

## Tech stack in use

### Backend

- Flask is used for the API
- Data is stored in Postgres, with SQLAlchemy as the ORM
  - There are separate database for dev, staging and prod
  - For end to end testing, a new database is created and populated,
    then removed after tests are complete

### Frontend

- Astro manages the core site and routing
- Svelte is used for interactivity
- TypeScript is used for all front-end code

### Testing

- Unittest for Python
- Vitest for TypeScript
- Playwright for e2e tests

## 使用的技术栈

### 后端

- Flask 用于 API
- 数据存储在 Postgres 中，使用 SQLAlchemy 作为 ORM
  - 开发、预发布和生产环境有独立的数据库
  - 对于端到端测试，会创建一个新数据库并填充数据，然后在测试完成后移除

### 前端

- Astro 管理核心站点和路由
- Svelte 用于交互性
- TypeScript 用于所有前端代码

### 测试

- Python 使用 Unittest
- TypeScript 使用 Vitest
- 端到端测试使用 Playwright

阐明你的编码规范

在创建第一个拉取请求之前，你需要了解应该遵循的规范。其中一些是关于代码应该如何编写的。例如，JavaScript 或 TypeScript 是否使用分号？Python 是否使用类型提示？使用制表符还是空格？（唯一正确的答案是：分号、类型提示和空格。对此，我不会接受任何质疑！）

根据项目结构，你可以将这些指南整合到技术栈指令文件中。但我通常喜欢为指南设置一个单独的部分，因为其中许多指南适用于所有使用的语言。我发现这样做可读性更强，这对可维护性很重要，而且不同语言和框架之间的指导意见也常有交叉。

你还可以考虑使用 .instructions 文件 来为特定类型的文件提供指南，例如所有 .astro 或 .jsx 文件，或者可能匹配 /tests/test_*.py 模式的单元测试。

以下是我自己工作中的另一个示例：

## Project and code guidelines

- Always use type hints in any language which supports them
- JavaScript/TypeScript should use semicolons
- Unit tests are required, and are required to pass before PR
  - Unit tests should focus on core functionality
- End-to-end tests are required
  - End-to-end tests should focus on core functionality
  - End-to-end tests should validate accessibility
- Always follow good security practices
- Follow RESTful API design principles
- Use scripts to perform actions when available

## 项目和代码规范

- 任何支持类型提示的语言中，都应始终使用类型提示
- JavaScript/TypeScript 应使用分号
- 单元测试是必需的，并且在 PR 之前必须通过
  - 单元测试应侧重于核心功能
- 端到端测试是必需的
  - 端到端测试应侧重于核心功能
  - 端到端测试应验证可访问性
- 始终遵循良好的安全实践
- 遵循 RESTful API 设计原则
- 在可用时使用脚本执行操作

解释你的项目结构

项目结构的方式也和代码框架一样多种多样。例如，在一个 monorepo 结构中，你的前端代码可能在一个名为 frontend 的文件夹里。或者 front-end。或者 front_end。或者 client。或者 web……

想必你已经明白我的意思了。

虽然 Copilot 最终或许能自行弄清楚（一个简单的  ls  命令就能找到答案），但在自定义指令文件中列出你的项目结构，既能为 Copilot 省去一些工作，也让你有机会提供更多关于文件夹内容的上下文信息。

以下是一个示例：

## Project structure

- server/ : Flask backend code
  - models/ : SQLAlchemy ORM models
  - routes/ : API endpoints organized by resource
  - tests/ : Unit tests for the API
  - utils/ : Utility functions and helpers, including database calls
- client/ : Astro/Svelte frontend code
  - src/components/ : Reusable Svelte components
  - src/layouts/ : Astro layout templates
  - src/pages/ : Astro pages and routes
  - src/styles/ : CSS stylesheets
- scripts/ : Development, deployment and testing scripts
- docs/ : Project documentation to be kept in sync at all times

## 项目结构

- 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/ : 始终保持同步的项目文档

指引 GitHub Copilot 使用可用资源

几乎每个项目都有一系列可用的脚本或资源来辅助开发。这些可能包括简化设置或运行测试的脚本，或是用于生成代码或模板的代码生成工具或模板。特别是 VS Code 中 MCP (Model Context Protocol) 支持 和 Copilot 编码代理 的引入，为 Copilot 的代理提供了更多可用的工具。

Copilot 虽然可以自动发现可用资源，但通过自定义指令文件提供明确指引，能进一步提升其准确性和效率。

以下是一个示例：

## Resources

- scripts folder
  - start-app.sh : Installs all libraries and starts the app
  - setup-env.sh : Installs all libraries
  - test-project.sh : Installs all libraries, runs unit and e2e tests
- MCP servers
  - Playwright: Used for generating Playwright tests or interacting with site
  - GitHub: Used to interact with repository and backlog

## 资源

- scripts 文件夹
  - start-app.sh : 安装所有库并启动应用
  - setup-env.sh : 安装所有库
  - test-project.sh : 安装所有库，运行单元和端到端测试
- MCP 服务器
  - Playwright: 用于生成 Playwright 测试或与网页进行交互
  - GitHub: 用于与仓库和产品待办列表交互

额外技巧：让 GitHub Copilot 帮你创建自定义指令文件

创建自定义指令文件没有一种完美的方法，而且有总比没有好。话虽如此，我们都希望尽可能做到最好。希望上述指南能给你带来一些启发！

但仍然存在实际编写它们的问题。而这可能仍然会让你面临我们最初提到的“白板问题”。

幸运的是，Copilot 甚至能帮你指导 Copilot！

你可以在 IDE 中启动 Copilot 代理模式（或者在 GitHub 仓库中 将问题分配给 Copilot），要求它为你创建指令文件。你可以直接使用这个文件，也可以根据需要进行编辑。在我们的 Copilot 文档 中甚至有一个推荐的提示词，你可以用它来生成指令文件！一个精简版的完整推荐内容可能如下所示：

Your task is to "onboard" this repository to a coding agent by adding a .github/copilot-instructions.md file. It should contain information describing how the agent, seeing the repo for the first time, can work most efficiently.

You will do this task only one time per repository, and doing a good job can SIGNIFICANTLY improve the quality of the agent's work, so take your time, think carefully, and search thoroughly before writing the instructions.

## Goals

- Document existing project structure and tech stack.
- Ensure established practices are followed.
- Minimize bash command and build failures.

## Limitations

- Instructions must be no longer than 2 pages.
- Instructions should be broadly applicable to the entire project.

## Guidance

Ensure you include the following:

- A summary of what the app does.
- The tech stack in use
- Coding guidelines
- Project structure
- Existing tools and resources

## Steps to follow

- Perform a comprehensive inventory of the codebase. Search for and view:
  - README.md, CONTRIBUTING.md, and all other documentation files.
  - Search the codebase for indications of workarounds like 'HACK', 'TODO', etc.
- All scripts, particularly those pertaining to build and repo or environment setup.
- All project files.
- All configuration and linting files.
- Document any other steps or information that the agent can use to reduce time spent exploring or trying and failing to run bash commands.

## Validation

Use the newly created instructions file to implement a sample feature. Use the learnings from any failures or errors in building the new feature to further refine the instructions file.

你的任务是“引导”此仓库与编码代理协作，方法是添加一个 .github/copilot-instructions.md 文件。该文件应包含描述代理首次查看仓库时如何最有效地工作的信息。

你每个仓库只执行此任务一次，并且做好这项工作可以显著提高代理的工作质量，因此请花时间仔细思考，并彻底搜索后，再编写指令。

## 目标

- 记录现有项目结构和技术栈。
- 确保遵循既定实践。
- 最大程度减少 bash 命令和构建失败。

## 限制

- 指令长度不得超过 2 页。
- 指令应普遍适用于整个项目。

## 指导

请确保包含以下内容：

- 应用功能摘要。
- 使用的技术栈。
- 编码规范。
- 项目结构。
- 现有工具和资源。

## 遵循的步骤

- 对代码库进行全面盘点。搜索并查看：
  - README.md、CONTRIBUTING.md 和所有其他文档文件。
  - 搜索代码库中是否存在“HACK”、“TODO”等表示变通方案的注释。
- 所有脚本，特别是与构建、仓库或环境设置相关的脚本。
- 所有项目文件。
- 所有配置和 linting 文件。
- 记录代理可以用来减少探索时间或尝试运行 bash 命令失败的任何其他步骤或信息。

## 验证

使用新创建的指令文件实现一个示例功能。利用在构建新功能过程中遇到的任何失败或错误，进一步完善指令文件。

使用上述提示模板可以帮助你节省时间。但更重要的是，它还能帮助你理清你对任何给定项目的思路和目标。

关于指令文件的最后几句话

需要注意的是，提供指令并不意味着能生成完美的代码。但拥有一个好的自定义指令文件是提高 Copilot 代码建议质量的重要第一步。在我看来，对于任何使用 Copilot 的项目，copilot-instructions.md 文件都是一项必备要求。

再说一次——它不需要是完美的。从以下这些部分开始，将为你打下坚实的基础：

在此基础上，你可以开始探索 .instructions 文件 以获取更具体的 Copilot 指导。但一切都基于 copilot-instructions.md 这个自定义指令文件。

本站总访问量次