Usando instruções personalizadas para desbloquear o poder da revisão de código Copilot

Saiba como escrever instruções personalizadas eficazes que ajudam a GitHub Copilot fornecer revisões de código mais relevantes e acionáveis.

Neste artigo

Introdução

          GitHub Copilot A revisão de código pode ser personalizada usando arquivos de instrução para adaptar a experiência de revisão às necessidades e aos padrões de codificação da sua equipe. No entanto, escrever instruções personalizadas eficazes requer entender como Copilot processar essas instruções e quais abordagens funcionam melhor.

Neste tutorial, você aprenderá a escrever instruções personalizadas claras e eficazes que ajudam a Copilot fornecer revisões de código mais relevantes. Você descobrirá as práticas recomendadas para estruturar suas instruções, armadilhas comuns a serem evitadas e estratégias para organizar instruções em arquivos diferentes.

Este tutorial é sobre como usar instruções personalizadas para Copilot revisão de código. Para obter uma introdução mais geral ao uso de instruções personalizadas, consulte Configurar instruções personalizadas para GitHub Copilot.

O que você aprenderá

Ao final deste tutorial, você entenderá:

  • Como escrever instruções personalizadas concisas e eficazes para revisão de código.
  • A diferença entre instruções para todo o repositório e específicas para o caminho.
  • Padrões comuns que funcionam bem com Copilot revisão de código.
  • No momento, não há suporte para quais tipos de instruções.
  • Como estruturar e organizar suas instruções para obter melhores resultados.

Pré-requisitos

  • Acesso a Copilot revisão de código.
  • Um GitHub repositório em que você pode criar arquivos de instrução personalizados.
  • Familiaridade básica com a sintaxe markdown.

Noções básicas sobre como GitHub Copilot a revisão de código processa instruções

Antes de escrever instruções personalizadas, é útil entender como o Copilot revisão de código as utiliza. Ao revisar uma solicitação de pull, Copilot lê seus arquivos de instrução e os usa para orientar sua análise. No entanto, como qualquer sistema de IA, ele tem limitações:

  •         **Comportamento não determinístico**: Copilot pode não seguir todas as instruções perfeitamente todas as vezes.

  •         **Limites de contexto**: arquivos de instrução muito longos podem resultar em algumas instruções sendo ignoradas.

  •         **Questões de especificidade**: instruções claras e específicas funcionam melhor do que diretivas vagas.

Tenha esses fatores em mente ao escrever suas instruções: eles ajudarão você a definir expectativas realistas e escrever diretrizes mais eficazes.

Observação

* Copilot revisão de código lê apenas os primeiros 4.000 caracteres de qualquer arquivo de instrução personalizado. Qualquer instrução além desse limite não afetará as revisões geradas por Copilot revisão de código. Esse limite não se aplica a Bate-Papo Copilot ou agente de nuvem Copilot.

  • Ao revisar uma solicitação de pull, o Copilot usa as instruções personalizadas na ramificação base da solicitação de pull. Por exemplo, se sua solicitação de pull busca mesclar my-feature-branch em main, o Copilot usará as instruções personalizadas em main.

Como escrever instruções personalizadas eficazes

A chave para instruções personalizadas bem-sucedidas é ser clara, concisa e específica. Aqui estão os princípios fundamentais a seguir:

Manter as instruções curtas e focadas

Arquivos de instrução mais curtos são mais propensos a serem totalmente processados por Copilot. Comece com um conjunto mínimo de instruções e adicione de forma mais iterativa com base no que funciona.

          **Prática recomendada**: limite qualquer arquivo de instrução única a um máximo de cerca de 1.000 linhas. Além disso, a qualidade das respostas pode se deteriorar.

Usar estrutura e formatação claras

          Copilot se beneficia de instruções bem estruturadas com:

* Títulos distintos que separam tópicos diferentes. * Pontos de marcador para verificação e referência fáceis. * Diretivas imperativas e curtas em vez de longos parágrafos narrativos.

Por exemplo, em vez de escrever:

When you're reviewing code, it would be good if you could try to look for
situations where developers might have accidentally left in sensitive
information like passwords or API keys, and also check for security issues.

Gravação:

## Security Critical Issues

- Check for hardcoded secrets, API keys, or credentials
- Look for SQL injection and XSS vulnerabilities
- Verify proper input validation and sanitization

Fornecer exemplos concretos

Assim como quando você explica um conceito para um colega, os exemplos ajudam a Copilot entender o que você quer dizer. Inclua snippets de código mostrando padrões corretos e incorretos.

Por exemplo:

## Naming Conventions

Use descriptive, intention-revealing names.

```javascript
// Avoid
const d = new Date();
const x = users.filter(u => u.active);

// Prefer
const currentDate = new Date();
const activeUsers = users.filter(user => user.isActive);
```

Organizando instruções entre arquivos

          Copilot revisão de código dá suporte a dois tipos de arquivos de instrução:

1. ** copilot-instructions.md **: instruções em todo o repositório que se aplicam a todos os arquivos. 1. ** *.instructions.md **: instruções específicas do caminho que se aplicam a determinados arquivos ou diretórios.

Use instruções específicas do caminho para manter o Copilot focado e evitar que ele aplique regras específicas de idioma aos arquivos incorretos.

Quando utilizar instruções para todo o repositório

Use copilot-instructions.md para:

  • Padrões e diretrizes gerais da equipe

  • Requisitos de segurança universal

  • Questões transversais, como filosofia de tratamento de erros

  • Expectativas de documentação

            **Estrutura de exemplo para `copilot-instructions.md`**:
Markdown
# General Code Review Standards

## Code Quality Essentials

- Functions should be focused and appropriately sized
- Use clear, descriptive naming conventions
- Ensure proper error handling throughout

## Security Standards

- Never hardcode credentials or API keys
- Validate all user inputs
- Use parameterized queries to prevent SQL injection

## Documentation Expectations

- All public functions must include doc comments
- Complex algorithms should have explanatory comments
- README files must be kept up to date

Quando usar instruções de caminho específicas

Use *.instructions.md arquivos com a applyTo propriedade frontmatter para:

  • Padrões de codificação específicos do idioma

  • Padrões específicos do framework

  • Preocupações de segurança específicas à tecnologia

  • Regras diferentes para diferentes partes da base de código

            **Example: instruções específicas Python**

Crie um arquivo chamado python.instructions.md no .github/instructions diretório:

Text
---
applyTo: "**/*.py"
---

# Python Coding Conventions

## Naming Conventions

- Use snake_case for variables and functions
- Use PascalCase for class names
- Use UPPERCASE for constants

## Code Style

- Follow PEP 8 style guidelines
- Limit line length to 88 characters (Black formatter standard)
- Use type hints for function signatures

## Best Practices

- Use list comprehensions for simple transformations
- Prefer f-strings for string formatting
- Use context managers (with statements) for resource management

```python
# Avoid
file = open('data.txt')
content = file.read()
file.close()

# Prefer
with open('data.txt') as file:
    content = file.read()
```

          **Exemplo: instruções específicas do front-end**

Crie um arquivo chamado frontend.instructions.md no .github/instructions diretório:

Text
---
applyTo: "src/components/**/*.{tsx,jsx}"
---

# React Component Guidelines

## Component Structure

- Use functional components with hooks
- Keep components small and focused (under 200 lines)
- Extract reusable logic into custom hooks

## State Management

- Use useState for local component state
- Use useContext for shared state across components
- Avoid prop drilling beyond 2-3 levels

## Accessibility

- All interactive elements must be keyboard accessible
- Include appropriate ARIA labels
- Ensure color contrast meets WCAG AA standards

Separando conjuntos de instruções complexos

Para repositórios grandes com muitas preocupações, divida as instruções em vários arquivos focados:

.github/
  copilot-instructions.md          # General standards

.github/instructions/
  python.instructions.md           # Python-specific
  javascript.instructions.md       # JavaScript-specific
  security.instructions.md         # Security-specific
  api.instructions.md              # API-specific

Cada arquivo deve ter uma finalidade clara e específica e um frontmatter apropriado applyTo quando necessário.

Com base no que funciona bem com Copilot revisão de código, aqui está um modelo recomendado para estruturar suas instruções:

Text
---
applyTo: "**/*.{js,ts}"  # If this is a path-specific file
---

# [Title: Technology or Domain Name] Guidelines

## Purpose

Brief statement of what this file covers and when these instructions apply.

## Naming Conventions

- Rule 1
- Rule 2
- Rule 3

## Code Style

- Style rule 1
- Style rule 2

```javascript
// Example showing correct pattern
```

## Error Handling

- How to handle errors
- What patterns to use
- What to avoid

## Security Considerations

- Security rule 1
- Security rule 2

## Testing Guidelines

- Testing expectation 1
- Testing expectation 2

## Performance

- Performance consideration 1
- Performance consideration 2

Adapte essa estrutura às suas necessidades específicas, mas mantenha o seccionamento claro e o formato de lista com marcadores.

O que não incluir em instruções personalizadas

Entender o que Copilot revisão de código atualmente não dá suporte ajuda você a evitar perda de tempo em instruções que não funcionarão.

Tipos de instrução sem suporte

          Copilot revisão de código Atualmente, não há suporte para instruções que tentam:

          **Altere a experiência ou a formatação do usuário**:

  • Use bold text for critical issues

  • Change the format of review comments

  • Add emoji to comments

            **Modifique o comentário de visão geral da solicitação de pull**:

  • Include a summary of security issues in the PR overview

  • Add a testing checklist to the overview comment

            **Alterar GitHub Copilota função principal:**

  • Block a PR from merging unless all Copilot revisão de código comments are addressed

  • Generate a changelog entry for every PR

            **Siga links externos**:

  • Review this code according to the standards at https://example.com/standards

    Solução alternativa: copie o conteúdo relevante diretamente no arquivo de instrução

            **Melhorias de qualidade vagas**:

  • Be more accurate

  • Don't miss any issues

  • Be consistent in your feedback

Esses tipos de instruções adicionam ruído sem melhorar a eficácia de Copilot, pois já está otimizado para fornecer revisões precisas e consistentes.

Testando e iterando sobre suas instruções

A melhor abordagem para criar instruções personalizadas eficazes é começar pequeno e iterar com base nos resultados.

Comece com um conjunto de instruções mínimo

Comece com instruções específicas de 10 a 20 que abordam suas necessidades de revisão mais comuns e teste se elas estão influenciando Copilot revisão de código da maneira desejada.

Testar com solicitações de pull reais

Depois de criar suas instruções:

  1. Abra uma solicitação pull no repositório.
  2. Solicite uma revisão de Copilot.
  3. Observe quais instruções ele segue efetivamente.
  4. Anote quaisquer instruções que são frequentemente perdidas ou mal interpretadas.

Iterar com base nos resultados

Adicione novas instruções uma de cada vez ou em grupos pequenos:

  1. Identifique um padrão que Copilot poderia examinar melhor.
  2. Adicione uma instrução específica para esse padrão.
  3. Teste com uma nova solicitação de pull.
  4. Refinar a instrução com base nos resultados.

Essa abordagem iterativa ajuda você a entender o que funciona e mantém seus arquivos de instrução focados.

Exemplo: concluir instruções personalizadas para revisão de código

Aqui está um exemplo completo que incorpora todas as práticas recomendadas deste tutorial:

          **Arquivo: `.github/copilot-instructions.md`**
Markdown
# General Code Review Standards

## Purpose

These instructions guide Copilot revisão de código across all files in this repository.
Language-specific rules are in separate instruction files.

## Security Critical Issues

- Check for hardcoded secrets, API keys, or credentials
- Look for SQL injection and XSS vulnerabilities
- Verify proper input validation and sanitization
- Review authentication and authorization logic

## Performance Red Flags

- Identify N+1 database query problems
- Spot inefficient loops and algorithmic issues
- Check for memory leaks and resource cleanup
- Review caching opportunities for expensive operations

## Code Quality Essentials

- Functions should be focused and appropriately sized (under 50 lines)
- Use clear, descriptive naming conventions
- Ensure proper error handling throughout
- Remove dead code and unused imports

## Review Style

- Be specific and actionable in feedback
- Explain the "why" behind recommendations
- Acknowledge good patterns when you see them
- Ask clarifying questions when code intent is unclear

## Testing Standards

- New features require unit tests
- Tests should cover edge cases and error conditions
- Test names should clearly describe what they test

Always prioritize security vulnerabilities and performance issues that could impact users.

          **Arquivo: `.github/instructions/typescript.instructions.md`**
Text
---
applyTo: "**/*.{ts,tsx}"
---

# TypeScript Development Standards

## Type Safety

- Avoid using `any` type—use `unknown` or specific types instead
- Use strict null checks (no `null` or `undefined` without explicit handling)
- Define interfaces for all object shapes

```typescript
// Avoid
function processData(data: any) {
    return data.value;
}

// Prefer
interface DataShape {
    value: string;
}

function processData(data: DataShape): string {
    return data.value;
}
```

## Naming Conventions

- Use PascalCase for types, interfaces, and classes
- Use camelCase for variables, functions, and methods
- Use UPPER_CASE for constants

## Modern TypeScript Patterns

- Use optional chaining (`?.`) and nullish coalescing (`??`)
- Prefer `const` over `let`; never use `var`
- Use arrow functions for callbacks and short functions

## React-Specific (for .tsx files)

- Use functional components with TypeScript props interfaces
- Type all props and state explicitly
- Use proper event types (e.g., `React.ChangeEvent<HTMLInputElement>`)

Solução de problemas comuns

Se Copilot revisão de código não estiver seguindo suas instruções conforme o esperado, experimente estas soluções:

Problema: as instruções são ignoradas

          **Causas possíveis**:

  • O arquivo de instrução é muito longo (mais de 1.000 linhas).

  • As instruções são vagas ou ambíguas.

  • As instruções entram em conflito entre si.

            **Soluções**:

  • Reduza o arquivo removendo instruções menos importantes.

  • Reescreva instruções vagas para serem mais específicas e acionáveis.

  • Examine as instruções conflitantes e priorize as mais importantes.

Problema: regras específicas do idioma aplicadas a arquivos incorretos

          **Causas possíveis**:

* applyTo Frontmatter ausente ou incorreto.

  • Regras em um arquivo aplicável ao repositório inteiro ao invés de um arquivo específico do caminho.

            **Soluções**:

  • Adicione applyTo frontmatter aos arquivos de instruções para caminhos específicos.

  • Mover regras específicas de idioma de copilot-instructions.md para os arquivos apropriados *.instructions.md.

Problema: Comportamento inconsistente entre revisões

          **Causas possíveis**:

  • As instruções são numerosas demais.

  • As instruções não têm especificidade.

  • Variabilidade natural em respostas de IA.

            **Soluções**:

  • Concentre-se nas instruções de prioridade mais alta.

  • Adicione exemplos concretos para esclarecer a intenção.

  • Aceite que alguma variabilidade é normal para sistemas de IA.

Conclusion

Instruções personalizadas eficazes ajudam a Copilot revisão de código fornecer comentários mais relevantes e acionáveis adaptados aos padrões da sua equipe. Seguindo os princípios neste tutorial, mantendo instruções concisas, fornecendo estrutura clara, usando exemplos concretos e organizando vários arquivos, você pode melhorar significativamente sua experiência de revisão de código.

Lembre-se de que criar instruções efetivas é um processo iterativo. Comece com um pequeno conjunto de instruções focadas, teste-as com solicitações de pull reais e expanda gradualmente com base no que funciona bem para sua equipe.

Próximas Etapas