使用 GitHub Copilot 处理任务的最佳实践

了解如何让 Copilot 云端智能体（Copilot cloud agent）发挥出最佳效果。

说明：有关 Copilot 云端智能体的简介，请参阅关于 GitHub Copilot 云端智能体。

确保 issue 的范围界定清晰

为 GitHub Copilot 分配清晰、范围明确的任务时，它能给出更好的结果。理想的任务包括：

• 对需要解决的问题或所需工作的清晰描述。
• 关于好的解决方案应该是什么样子的完整验收标准（例如，是否应包含单元测试？）。
• 关于需要修改哪些文件的指引。

提示：Copilot 云端智能体能够搜索你的代码库，包括语义代码搜索，这有助于它根据含义而不仅仅是精确的文本匹配来找到相关代码。即使你没有在任务中指定确切的文件路径，智能体通常也能自行找到正确的代码。

如果你通过分配 issue 的方式把任务交给 Copilot，不妨把分配给 Copilot 的 issue 看作一个提示词。想一想这个 issue 的描述是否适合作为 AI 提示词，能否让 Copilot 做出所需的代码更改。

选择适合交给 Copilot 的任务类型

随着与 Copilot 协作的深入，你会逐渐了解它最适合处理哪些类型的任务。起初，你可能想先给 Copilot 分配一些较简单的任务，看看它作为云端智能体是如何工作的。例如，你可以先让 Copilot 修复 bug、修改用户界面功能、提高测试覆盖率、更新文档、改进无障碍性或处理技术债。

你可能会选择亲自处理、而不分配给 Copilot 的 issue 包括：

• 复杂且范围宽泛的任务

  • 范围宽泛、上下文丰富、需要跨仓库知识和测试的重构问题
  • 需要理解依赖和遗留代码的复杂 issue
  • 需要深厚领域知识的任务
  • 涉及大量业务逻辑的任务
  • 需要保持设计一致性的大规模代码库改动

• 敏感且关键的任务

  • 对生产环境至关重要的 issue
  • 涉及安全、个人身份信息、身份验证影响的任务
  • 事件响应

• 含义模糊的任务

  • 缺乏明确定义的任务：需求模糊的任务、开放式任务、需要在不确定性中摸索出解决方案的任务

• 学习型任务

  • 开发者希望通过学习加深理解的任务

在打开拉取请求（pull request）之前先研究、规划和迭代

与其让 Copilot 立即打开拉取请求，你可以先使用 Copilot 云端智能体研究仓库、制定实施计划，并在分支上进行迭代式的代码更改。这样你就可以在决定打开拉取请求之前审查差异并完善工作。

在以下情况下，这种工作流很有用：

• 你想在做出更改之前了解代码库的工作方式。
• 你想在编写任何代码之前与 Copilot 就方案达成一致。
• 你想在打开拉取请求供他人评审之前审查并迭代更改。

请参阅使用 Copilot 云端智能体研究、规划并迭代代码更改。

通过评论迭代拉取请求

在拉取请求上与 Copilot 协作，就像与人类开发者协作一样：拉取请求在合并之前通常还需要进一步完善。无论拉取请求是由 Copilot 创建还是由人创建，让它达到可合并状态的流程完全相同。

此外，你还可以：

• 在拉取请求的评论中提及 @copilot，说明你认为哪些地方不正确或可以改进，Copilot 就会直接向拉取请求的分支推送提交。
• 让 Copilot 解决拉取请求上的合并冲突。请参阅在 GitHub 上使用 Copilot 云端智能体。
• 自己在功能分支上工作，并将更改推送到拉取请求。

具有写入权限的用户在评论中提及 @copilot 后，Copilot 就会开始进行所需的更改，并在完成后更新拉取请求。由于 Copilot 会在评论提交后立即开始查看，如果你可能会在一个拉取请求上发表多条评论，最好点击 Start a review 将它们批量提交，而不是点击 Add single comment。这样你就可以一次性提交所有评论，让 Copilot 针对你的整个评审开展工作，而不是分别处理每条评论。

说明：Copilot 只会回复对仓库具有写入权限的用户所发表的评论。

在 Copilot 更改拉取请求的过程中，它会持续更新标题和正文，使其反映当前的更改。

向仓库添加自定义指令

通过向仓库添加自定义指令，你可以指导 Copilot 如何理解你的项目，以及如何构建、测试和验证它所做的更改。

如果 Copilot 能够在自己的开发环境中构建、测试和验证其更改，它就更有可能生成可以快速合并的优质拉取请求。

Copilot 云端智能体支持多种不同类型的自定义指令文件：

• /.github/copilot-instructions.md
• /.github/instructions/**/*.instructions.md
• **/AGENTS.md
• /CLAUDE.md
• /GEMINI.md

有关详细信息，请参阅为 GitHub Copilot 添加仓库自定义指令。

仓库级指令

要添加适用于仓库中分配给 Copilot 的所有任务的指令，请在仓库根目录中创建 .github/copilot-instructions.md 文件。该文件应包含有关项目的信息，例如如何构建和测试项目，以及你希望 Copilot 遵循的编码标准或约定。请注意，这些指令同样适用于 Copilot Chat 和 Copilot 代码评审。

你第一次让 Copilot 在某个仓库中创建拉取请求时，Copilot 会留下一条评论，其中附有自动生成自定义指令的链接。你也可以随时使用我们推荐的提示词，让 Copilot 为你生成自定义指令。请参阅为 GitHub Copilot 添加仓库自定义指令。

你也可以随时选择自己编写自定义指令。下面是一个行之有效的 copilot-instructions.md 文件示例：

这是一个基于 Go 的仓库，附带一个用于部分 API 端点的 Ruby 客户端。它主要负责接收 GitHub 的计量用量数据并记录这些用量。贡献代码时请遵循以下准则：

## 代码标准

### 每次提交前必做
- 提交任何更改前运行 `make fmt`，确保代码格式正确
- 这会对所有 Go 文件运行 gofmt，以保持风格一致

### 开发流程
- 构建：`make build`
- 测试：`make test`
- 完整 CI 检查：`make ci`（包括 build、fmt、lint、test）

## 仓库结构
- `cmd/`：主服务入口与可执行文件
- `internal/`：与其他 GitHub 服务交互相关的逻辑
- `lib/`：计费逻辑的核心 Go 包
- `admin/`：管理界面组件
- `config/`：配置文件与模板
- `docs/`：文档
- `proto/`：Protocol Buffers 定义。在此处更新后请运行 `make proto`。
- `ruby/`：Ruby 实现组件。更新此文件夹时，应按语义化版本规则递增此版本文件中的版本号：`ruby/lib/billing-platform/version.rb`
- `testing/`：测试辅助工具与测试夹具

## 关键准则
1. 遵循 Go 最佳实践与惯用模式
2. 保持现有的代码结构与组织方式
3. 在合适的地方使用依赖注入模式
4. 为新功能编写单元测试。尽可能使用表驱动的单元测试。
5. 为公共 API 和复杂逻辑编写文档。在合适时建议修改 `docs/` 文件夹

路径级指令

要添加仅适用于 Copilot 所处理的特定类型文件（例如单元测试或 React 组件）的指令，请在仓库中创建一个或多个 .github/instructions/**/*.instructions.md 文件。 在这些文件中写入有关这类文件的信息，例如如何构建和测试它们，以及你希望 Copilot 遵循的编码标准或约定。

利用指令文件 front matter 中的 glob 模式，你可以指定这些指令适用于哪些文件类型。例如，要为 Playwright 测试创建指令，你可以创建一个名为 .github/instructions/playwright-tests.instructions.md 的指令文件，内容如下：

---
applyTo: "**/tests/*.spec.ts"
---

## Playwright 测试要求

编写 Playwright 测试时，请遵循以下准则，以确保一致性和可维护性：

1. **使用稳定的定位器** - 优先使用 `getByRole()`、`getByText()` 和 `getByTestId()`，而不是 CSS 选择器或 XPath
1. **编写相互隔离的测试** - 每个测试都应独立，不依赖其他测试的状态
1. **遵循命名约定** - 使用描述性的测试名称，文件按 `*.spec.ts` 命名
1. **编写恰当的断言** - 使用 Playwright 的 `expect()` 搭配具体的匹配器，例如 `toHaveText()`、`toBeVisible()`
1. **利用自动等待** - 避免手动调用 `setTimeout()`，依靠 Playwright 内置的等待机制
1. **配置跨浏览器测试** - 在 Chromium、Firefox 和 WebKit 浏览器中进行测试
1. **使用页面对象模型** - 将选择器和操作组织到可复用的页面类中，以提升可维护性
1. **处理动态内容** - 正确等待元素加载完成，并处理加载状态
1. **准备合适的测试数据** - 使用 beforeEach/afterEach 钩子完成测试的准备与清理
1. **配置 CI/CD 集成** - 设置无头模式、失败时截图以及并行执行

组织级自定义指令

Copilot 云端智能体会在工作中利用你所在组织的自定义指令。Copilot 云端智能体会优先采用仓库级自定义指令。有关如何配置组织自定义指令的详细信息，请参阅为 GitHub Copilot 添加组织自定义指令。

使用模型上下文协议（MCP）

你可以使用 MCP 扩展 Copilot 云端智能体的能力。这让 Copilot 云端智能体能够使用本地和远程 MCP 服务器提供的工具。GitHub MCP 服务器和 Playwright MCP 服务器默认处于启用状态。有关详细信息，请参阅为仓库配置 MCP 服务器。

创建自定义智能体（custom agents）

自定义指令有助于在整个仓库范围内引导 Copilot 的总体行为，而自定义智能体则会创建完全专门化的智能体，具备聚焦的专业能力和量身定制的工具配置。这些智能体专为特定的、反复出现的工作流而设计，在这类工作流中，领域专业知识和一致的行为至关重要。自定义智能体以名为智能体配置文件的 Markdown 文件来定义。

以下是你可以创建的一些自定义智能体示例：

• 测试专家：配置了特定测试框架、专注于测试覆盖率、测试质量和测试最佳实践的智能体。它可以被限制为只能使用读取、搜索和编辑工具，以防止对生产代码做出意外更改，同时确保全面的测试覆盖。
• 文档专家：专门负责创建和维护项目文档的智能体，深入了解文档标准和风格指南，并能够分析代码，生成准确的 API 文档和用户指南。
• Python 专家：针对特定语言的智能体，了解 Python 约定以及 Django、Flask 等流行框架，并遵循 PEP 标准。它会具备有关 Python 工具链、虚拟环境以及 pytest 等测试框架的专门知识。

默认情况下，自定义智能体会继承仓库中已配置的所有 MCP 服务器工具，但你也可以将自定义智能体配置为只能访问特定工具。

凡是可以使用 Copilot 云端智能体的地方，你都可以使用自定义智能体，包括分配 issue 或通过提示词下达任务时。

有关创建和配置自定义智能体的详细信息，请参阅为 Copilot 云端智能体创建自定义智能体。

在 GitHub Copilot 的环境中预装依赖

在处理任务时，Copilot 可以使用由 GitHub Actions 提供支持的专属临时开发环境，在其中浏览你的代码、做出更改、执行自动化测试和 linter 等。

如果 Copilot 能够在自己的开发环境中构建、测试和验证其更改，它就更有可能生成可以快速合并的优质拉取请求。

为此，它需要你项目的依赖。Copilot 可以通过反复试错自行发现并安装这些依赖，但鉴于大语言模型（LLM）的非确定性，这一过程可能既缓慢又不可靠。

你可以配置 copilot-setup-steps.yml 文件，在智能体开始工作之前预装这些依赖，让它一上手就能迅速进入状态。有关详细信息，请参阅配置开发环境。