使用 GitHub Copilot 完成任务的最佳实践

注意

要了解 Copilot 云代理的简介，请参阅关于 GitHub Copilot 云代理。

确保你的 issue 范围明确

当分配明确且范围清晰的任务时，GitHub Copilot 能提供更好的结果。理想的任务应包括

对需要解决的问题或所需工作的清晰描述。
完整的验收标准，说明良好解决方案的样子（例如，是否需要单元测试？）。
关于需要更改哪些文件的指示。

提示

Copilot 云代理具备搜索代码库的能力，包括语义代码搜索，这使其能够根据意义而非仅仅是文本匹配来找到相关代码。即使在任务中未指定确切的文件路径，代理通常也能自行发现正确的代码。

如果通过指派 issue 将任务交给 Copilot，最好把分配给 Copilot 的 issue 当作提示来思考。考虑该 issue 描述是否能够作为 AI 提示，并让 Copilot 能够进行所需的代码更改。

为 Copilot 选择合适的任务类型

在使用 Copilot 的过程中，你会逐渐了解它最适合处理的任务类型。起初，你可能想先给 Copilot 较简单的任务，以观察其作为云代理的表现。例如，你可以让 Copilot 修复 bug、修改用户界面功能、提升测试覆盖率、更新文档、改善可访问性，或处理技术债务。

以下问题你可能会选择自行处理，而不是指派给 Copilot：

复杂且范围宽泛的任务
- 范围宽广、上下文丰富的重构问题，需要跨仓库的知识和测试
- 需要理解依赖关系和旧代码的复杂问题
- 需要深入领域知识的任务
- 涉及大量业务逻辑的任务
- 对代码库的大规模更改，需保持设计一致性
敏感且关键的任务
- 生产环境关键问题
- 涉及安全、个人身份信息、认证后果的任务
- 事件响应
模糊不清的任务
- 缺乏明确定义的任务：需求模糊、开放式的任务，需要在不确定性中寻找解决方案的任务
学习任务
- 开发者希望通过完成任务来获得更深入理解的任务

在打开 Pull Request 之前进行研究、规划和迭代

与其立即让 Copilot 打开 Pull Request，不如先使用 Copilot 云代理对仓库进行调研、制定实现计划，并在分支上进行迭代式代码修改。这样可以在决定打开 Pull Request 之前先审阅差异并完善工作。

当你希望时，此工作流非常有用：

在进行更改之前了解代码库的工作方式。
在编写任何代码之前，与 Copilot 商定方案。
在打开审查用的 Pull Request 之前审阅并迭代更改。

参见使用 Copilot 云代理研究、规划并迭代代码更改。

使用评论对 Pull Request 进行迭代

在 Pull Request 上与 Copilot 合作就像与人类开发者合作一样：在合并之前，Pull Request 通常需要进一步的工作。将 Pull Request 变为可合并状态的过程，无论是 Copilot 创建的还是人类创建的，都完全相同。

此外，你可以

在 Pull Request 的评论中提及 @copilot，说明你认为哪些地方不正确或可以改进，Copilot 将直接向该 Pull Request 的分支推送提交。
让 Copilot 解决 Pull Request 中的合并冲突。参见如何让 GitHub Copilot 对现有 Pull Request 进行更改。
自行在特性分支上工作并将更改推送到 Pull Request。

当具有写入权限的用户在评论中提及 @copilot 后，Copilot 将开始进行所需的更改，并在完成后更新 Pull Request。由于 Copilot 会在评论提交后立即开始查看评论，如果你可能对同一 Pull Request 进行多次评论，最好点击 开始审查 将它们批量处理，而不是点击 添加单条评论。随后一次性提交所有评论，就会触发 Copilot 对整个审查进行处理，而不是逐条评论单独处理。

注意

Copilot 只会响应拥有仓库写权限的人的评论。

当 Copilot 对 Pull Request 进行更改时，它会保持标题和正文的最新状态，以反映当前的更改。

向仓库添加自定义指令

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

如果 Copilot 能够在其自身的开发环境中构建、测试并验证更改，它更有可能生成可快速合并的高质量 Pull Request。

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 在某个仓库创建 Pull Request 时，Copilot 会留下带有自动生成自定义指令链接的评论。你也可以随时使用我们推荐的提示让 Copilot 为你生成自定义指令。参见为 GitHub Copilot 添加仓库自定义指令。

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

This is a Go based repository with a Ruby client for certain API endpoints. It is primarily responsible for ingesting metered usage for GitHub and recording that usage. Please follow these guidelines when contributing:

## Code Standards

### Required Before Each Commit
- Run `make fmt` before committing any changes to ensure proper code formatting
- This will run gofmt on all Go files to maintain consistent style

### Development Flow
- Build: `make build`
- Test: `make test`
- Full CI check: `make ci` (includes build, fmt, lint, test)

## Repository Structure
- `cmd/`: Main service entry points and executables
- `internal/`: Logic related to interactions with other GitHub services
- `lib/`: Core Go packages for billing logic
- `admin/`: Admin interface components
- `config/`: Configuration files and templates
- `docs/`: Documentation
- `proto/`: Protocol buffer definitions. Run `make proto` after making updates here.
- `ruby/`: Ruby implementation components. Updates to this folder should include incrementing this version file using semantic versioning: `ruby/lib/billing-platform/version.rb`
- `testing/`: Test helpers and fixtures

## Key Guidelines
1. Follow Go best practices and idiomatic patterns
2. Maintain existing code structure and organization
3. Use dependency injection patterns where appropriate
4. Write unit tests for new functionality. Use table-driven unit tests when possible.
5. Document public APIs and complex logic. Suggest changes to the `docs/` folder when appropriate

路径特定指令

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

在指令文件的 Front Matter 中使用 glob 模式，你可以指定其适用的文件类型。例如，若要为 Playwright 测试创建指令，可创建名为 .github/instructions/playwright-tests.instructions.md 的指令文件，内容如下

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

## Playwright test requirements

When writing Playwright tests, please follow these guidelines to ensure consistency and maintainability:

1. **Use stable locators** - Prefer `getByRole()`, `getByText()`, and `getByTestId()` over CSS selectors or XPath
1. **Write isolated tests** - Each test should be independent and not rely on other tests' state
1. **Follow naming conventions** - Use descriptive test names and `*.spec.ts` file naming
1. **Implement proper assertions** - Use Playwright's `expect()` with specific matchers like `toHaveText()`, `toBeVisible()`
1. **Leverage auto-wait** - Avoid manual `setTimeout()` and rely on Playwright's built-in waiting mechanisms
1. **Configure cross-browser testing** - Test across Chromium, Firefox, and WebKit browsers
1. **Use Page Object Model** - Organize selectors and actions into reusable page classes for maintainability
1. **Handle dynamic content** - Properly wait for elements to load and handle loading states
1. **Set up proper test data** - Use beforeEach/afterEach hooks for test setup and cleanup
1. **Configure CI/CD integration** - Set up headless mode, screenshots on failure, and parallel execution

测试专家：一个配置了特定测试框架、专注于测试覆盖率、测试质量和测试最佳实践的代理。它可能仅限于读取、搜索和编辑工具，以防止对生产代码的非预期更改，同时确保全面的测试覆盖。
文档专家：专门负责创建和维护项目文档的代理，深入了解文档标准、风格指南，并能够分析代码生成准确的 API 文档和用户指南。
Python 专家：专注于 Python 的代理，了解 Python 约定、流行框架如 Django 或 Flask，并遵循 PEP 标准。它具备对 Python 工具、虚拟环境以及 pytest 等测试框架的专门知识。

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

在使用 Copilot 云代理的任何场景下均可使用自定义代理，包括指派 issue 或使用任务提示时。

参见为 Copilot 云代理创建自定义代理。

在 GitHub Copilot 环境中预先安装依赖

在处理任务时，Copilot 能访问其自身的短暂开发环境，该环境由 GitHub Actions 提供支持，Copilot 可以在其中探索代码、进行更改、执行自动化测试、代码检查等操作。

如果 Copilot 能够在其自身的开发环境中构建、测试并验证更改，它更有可能生成可快速合并的高质量 Pull Request。

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

你可以配置一个 copilot-setup-steps.yml 文件，在代理开始工作之前预先安装这些依赖，从而让其快速投入工作。欲了解更多信息，请参见为 GitHub Copilot 云代理定制开发环境。

谁可以使用此功能？

本文内容