Práticas recomendadas de uso do GitHub Copilot para trabalhar em tarefas

Certificar-se de que seus issues têm um escopo bem definido

O GitHub Copilot apresenta melhores resultados quando recebe tarefas claras e com escopo bem definido. Uma tarefa ideal inclui:

• Uma descrição clara do problema a ser resolvido ou do trabalho necessário.
• Critérios de aceitação completos sobre como é uma boa solução (por exemplo, deve haver testes de unidade?).
• Instruções sobre quais arquivos precisam ser alterados.

Se você passar uma tarefa para o Copilot atribuindo um issue a ele, será útil pensar no issue atribuído ao Copilot como um prompt. Considere se a descrição do issue provavelmente funcionará como um prompt de IA e permitirá que o Copilot faça as alterações de código necessárias.

Escolher o tipo certo de tarefas a serem atribuídas ao Copilot

Conforme trabalhar com o Copilot, você terá uma noção dos tipos de tarefas em que ele é mais adequado trabalhar. Talvez você queira começar dando ao Copilot tarefas mais simples, para ver como ele funciona como agente de codificação. Por exemplo, você pode começar solicitando que o Copilot corrija bugs, altere recursos da interface do usuário, aprimore a cobertura de testes, atualize a documentação, melhore a acessibilidade ou resolva a dívida técnica.

Os issues em que você pode optar por trabalhar por conta própria, em vez de atribuir ao Copilot, incluem:

• Tarefas complexas com escopo amplo

  • Problemas de refatoração com escopo amplo e contexto complexo, que exigem conhecimento e testes entre repositórios
  • Issues complexos que exigem a compreensão de dependências e código herdado
  • Tarefas que exigem conhecimento profundo do domínio
  • Tarefas que envolvem lógica de negócios substancial
  • Alterações grandes em uma base de código que exigem consistência de design

• Tarefas confidenciais e críticas

  • Issues críticos para a produção
  • Tarefas que envolvem segurança, informações de identificação pessoal, repercussões para a autenticação
  • Resposta a incidente

• Tarefas ambíguas

  • Tarefas sem definição clara: tarefas com requisitos ambíguos, tarefas com várias soluções, tarefas que exigem trabalhar com incertezas para encontrar uma solução

• Tarefas de aprendizagem

  • Tarefas em que o desenvolvedor quer aprender, a fim de obter uma compreensão mais profunda

Usar comentários para iterar em uma pull request

Trabalhar com o Copilot em uma pull request é como trabalhar com um desenvolvedor humano: é comum que a pull request precise de mais trabalho antes de ser mesclada. O processo para levar a pull request a um estado mesclável é exatamente o mesmo empregado quando a pull request é criada pelo Copilot e quando é criada por um humano.

Você também pode mencionar @copilot nos comentários da pull request — explicando o que acha que está incorreto ou pode ser melhorado — e deixar o Copilot fazer as alterações necessárias. Como alternativa, você poderá trabalhar no branch de recurso por conta própria e efetuar push das alterações para a pull request.

Depois que um usuário com acesso de gravação mencionar @copilot em um comentário, o Copilot começará a fazer as alterações necessárias e atualizará a pull request quando terminar. Como o Copilot começa a examinar os comentários assim que eles são enviados, se você for fazer vários comentários em uma pull request, será melhor enviá-los em lote clicando em Start a review, em vez de em Add single comment. Você pode enviar todos os seus comentários de uma só vez, acionando o Copilot para trabalhar em toda a sua revisão, em vez de trabalhar em comentários individuais separadamente.

Como o Copilot faz alterações na pull request, ele manterá o título e o corpo atualizados para que eles reflitam as alterações atuais.

Adicionar instruções personalizadas ao repositório

Adicionando instruções personalizadas ao repositório, você pode orientar o Copilot sobre como entender seu projeto e como compilar, testar e validar suas alterações.

Se o Copilot for capaz de compilar, testar e validar suas alterações no próprio ambiente de desenvolvimento, será mais provável que ele produza boas pull requests que poderão ser mescladas rapidamente.

O Agente de codificação do Copilot dá suporte a vários tipos diferentes de arquivos de instruções personalizadas:

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

Para saber mais, confira Como adicionar instruções personalizadas de repositório no GitHub Copilot.

Instruções para todo o repositório

Para adicionar instruções que se apliquem a todas as tarefas atribuídas ao Copilot em seu repositório, crie um arquivo .github/copilot-instructions.md na raiz do repositório. Esse arquivo deve conter informações sobre seu projeto, como o modo de compilá-lo e testá-lo e os padrões de codificação ou convenções que você deseja que o Copilot siga. Observe que as instruções também se aplicarão ao Copilot Chat e ao Revisão de código do Copilot.

Na primeira vez que você pedir que o Copilot crie uma pull request em um determinado repositório, o Copilot deixará um comentário com um link para gerar automaticamente instruções personalizadas. Também é possível solicitar que o Copilot gere instruções personalizadas para você a qualquer momento usando nosso prompt recomendado. Confira Como adicionar instruções personalizadas de repositório no GitHub Copilot.

Você também pode optar por escrever suas próprias instruções personalizadas a qualquer momento. Aqui está um exemplo de um arquivo copilot-instructions.md eficaz:

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

Instruções específicas de caminho

Para adicionar instruções que se aplicam a tipos específicos de arquivos em que o Copilot vai trabalhar, como testes de unidade ou componentes do React, crie um ou mais arquivos .github/instructions/**/*.instructions.md em seu repositório. Nesses arquivos, inclua informações sobre os tipos de arquivo, como o modo de compilá-los e testá-los e outros padrões de codificação ou convenções que você deseja que o Copilot siga.

Usando o padrão glob na parte inicial do arquivo de instruções, você pode especificar os tipos de arquivo aos quais eles devem ser aplicados. Por exemplo, para criar instruções para testes de Playwright, você pode criar um arquivo de instruções chamado .github/instructions/playwright-tests.instructions.md com o seguinte conteúdo:

---
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

Usar o MCP (Model Context Protocol)

Você pode estender os recursos do Agente de codificação do Copilot usando o MCP. Isso permite que o Agente de codificação do Copilot use ferramentas fornecidas por servidores MCP locais e remotos. O servidor MCP do GitHub e o servidor MCP Playwright estão habilitados por padrão. Para saber mais, confira Como estender o agente de codificação do GitHub Copilot com o MCP (Model Context Protocol).

Pré-instalar dependências no ambiente do GitHub Copilot

Ao trabalhar em uma tarefa, o Copilot tem acesso ao próprio ambiente de desenvolvimento efêmero, da plataforma GitHub Actions, onde pode explorar seu código, fazer alterações, executar testes automatizados e linters e muito mais.

Se o Copilot for capaz de compilar, testar e validar suas alterações no próprio ambiente de desenvolvimento, será mais provável que ele produza boas pull requests que poderão ser mescladas rapidamente.

Para fazer isso, ele precisará das dependências do projeto. O Copilot pode descobrir e instalar essas dependências por meio de um processo de tentativa e erro, mas isso pode ser lento e não confiável, dada a natureza não determinística dos LLMs (modelos de linguagem grande).

Você pode configurar um arquivo copilot-setup-steps.yml para pré-instalar essas dependências antes que o agente comece a trabalhar para que ele possa trabalhar com eficácia rapidamente. Para saber mais, confira Como personalizar o ambiente de desenvolvimento para o agente de codificação do GitHub Copilot.