Por que o GitHub Copilot ignora as convenções do meu projeto nas sugestões

Você escreve código seguindo um guia de estilo e convenção de nomenclatura rigorosos, mas o GitHub Copilot sugere código que não corresponde. Isso acontece porque o Copilot gera sugestões com base em padrões de milhões de repositórios públicos, não nas regras específicas do seu projeto. A ferramenta não lê automaticamente sua configuração de linter, configurações do editor ou padrões da equipe. Este artigo explica por que o Copilot ignora suas convenções e como configurá-lo para se alinhar ao seu projeto.

Por que o Copilot não segue as convenções do seu projeto

O GitHub Copilot usa um modelo de linguagem grande treinado em código público de repositórios do GitHub. O modelo aprende padrões estatísticos — por exemplo, como a maioria dos projetos Python nomeia variáveis ou como projetos JavaScript estruturam funções. Quando você digita código, o Copilot prevê os próximos tokens com base nesses dados de treinamento globais, não nos seus arquivos de configuração locais.

O Copilot não lê nativamente regras do ESLint, configurações do Prettier ou guias de estilo Ruby. Ele não analisa seu arquivo .editorconfig durante a geração de sugestões. A ferramenta trata cada sugestão como uma previsão estatística baseada no contexto de código ao redor, mas a janela de contexto é limitada ao arquivo atual e alguns arquivos adjacentes. Se as convenções do seu projeto não estiverem refletidas no contexto imediato do código, o Copilot usa padrões gerais.

A limitação da janela de contexto

O Copilot vê cerca de 2000 caracteres de contexto do seu arquivo aberto e de quaisquer arquivos que você abriu recentemente. Se o seu projeto usa uma mistura de camelCase e snake_case, o Copilot pode não detectar o padrão correto até que você tenha digitado exemplos consistentes suficientes. O modelo não verifica toda a sua base de código para inferir um estilo global.

Sem integração nativa com linter

O Copilot não chama seu linter ou formatador antes de exibir uma sugestão. Ele gera as conclusões primeiro, e seu editor pode aplicar a formatação após a sugestão ser aceita. Isso significa que o Copilot pode sugerir código que viola suas regras do ESLint ou formatação do Prettier, mesmo que seu editor corrija depois.

Passos para configurar o Copilot a seguir as convenções do seu projeto

Você pode melhorar a adesão do Copilot às suas convenções fornecendo instruções explícitas e arquivos de configuração estruturados. Siga estes passos em ordem para melhores resultados.

Passo 1: Crie um arquivo copilot-instructions.md

1. Abra a pasta raiz do seu projeto
   Navegue até a raiz do seu repositório no sistema de arquivos ou terminal.
2. Crie um diretório .github se ele não existir
   Execute mkdir .github a partir da raiz do projeto.
3. Crie o arquivo copilot-instructions.md
   Dentro da pasta .github, crie um arquivo chamado copilot-instructions.md.
4. Escreva suas convenções em português claro
   Use marcadores ou listas numeradas. Por exemplo:

# Convenções de Codificação para Este Projeto

- Use camelCase para nomes de variáveis, nunca snake_case
- Use 2 espaços para indentação, nunca tabs
- Termine todas as instruções com ponto e vírgula
- Use aspas simples para strings em JavaScript
- Prefira const em vez de let e nunca use var
- Use async/await em vez de cadeias .then()

O Copilot lê este arquivo automaticamente ao gerar sugestões. Coloque o arquivo na raiz do seu repositório. As instruções se aplicam a todos os arquivos do repositório.

Passo 2: Configure as configurações do editor para reforçar as convenções

1. Abra as configurações do seu editor
   No VS Code, vá em Arquivo > Preferências > Configurações. Pesquise por github.copilot.
2. Ative as configurações em nível de projeto
   Defina github.copilot.enableProjectSettings como true. Isso instrui o Copilot a priorizar instruções do arquivo .github/copilot-instructions.md em vez dos padrões globais.
3. Defina uma configuração específica do editor
   No VS Code, crie um arquivo .vscode/settings.json na raiz do seu projeto. Adicione entradas para formatação e linting:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.validate": ["javascript", "typescript"],
  "github.copilot.enable": {
    "": true
  }
}

Isso não altera as sugestões do Copilot diretamente, mas garante que, após você aceitar uma sugestão, o editor a reformate para corresponder às suas regras de linter. Com o tempo, o Copilot aprende com seu código aceito e reformatado.

Passo 3: Forneça contexto consistente no seu código

1. Escreva algumas linhas de código manualmente antes de aceitar sugestões do Copilot
   Digite de 5 a 10 linhas que sigam suas convenções exatas. O Copilot usa isso como padrão para sugestões subsequentes no mesmo arquivo.
2. Use nomes de funções e variáveis significativos
   O Copilot usa os nomes que você define para inferir estilos de nomenclatura. Se você digitar userProfile, o Copilot sugerirá userSettings (camelCase) em vez de user_settings.
3. Evite misturar estilos no mesmo arquivo
   Se você alternar entre camelCase e snake_case, o Copilot pode escolher qualquer padrão. Mantenha um estilo por arquivo.

Passo 4: Use um arquivo .editorconfig para formatação básica

1. Crie um arquivo .editorconfig na raiz do seu projeto
   Este arquivo é lido por muitos editores e algumas versões do Copilot. Adicione regras para indentação e charset:

root = true

[]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[py]
indent_size = 4

O Copilot respeita algumas regras do EditorConfig durante a geração de sugestões, especialmente indentação. Esta é uma forma leve de impor espaçamento sem criar um arquivo copilot-instructions.md.

Se o Copilot ainda ignorar suas convenções

Copilot sugere caso de nomenclatura errado apesar das instruções

O arquivo copilot-instructions.md é lido pelo Copilot, mas não substitui o modelo completamente. Se suas instruções forem vagas, o Copilot pode ainda usar padrões dos dados de treinamento. Reescreva suas instruções como comandos curtos e imperativos. Por exemplo, escreva Use camelCase para todos os nomes de variáveis em vez de Variáveis devem estar em camelCase.

Copilot sugere tabs quando seu projeto usa espaços

Esta é a incompatibilidade de formatação mais comum. Adicione uma regra explícita ao seu copilot-instructions.md: Use 2 espaços para indentação, nunca tabs. Também defina indent_style = space no seu .editorconfig. Se o problema persistir, digite manualmente dois espaços no início de uma linha e pressione Enter. O Copilot corresponderá à indentação da linha acima.

Copilot usa async/await quando seu projeto usa Promises

O Copilot usa padrões modernos de JavaScript por padrão. Adicione uma regra às suas instruções: Use .then() e .catch() para operações assíncronas, não async/await. Em seguida, digite algumas linhas de código baseado em promise antes de aceitar sugestões. O Copilot mudará para o padrão que você fornecer no contexto.

Copilot Pro vs Copilot Enterprise: diferenças no suporte a convenções

Item	Copilot Pro	Copilot Enterprise
Instruções em nível de projeto	Suporta .github/copilot-instructions.md	Suporta .github/copilot-instructions.md mais políticas organizacionais
Integração com linter	Nenhuma	Nenhuma
Suporte a EditorConfig	Parcial (apenas indentação)	Parcial (apenas indentação)
Bases de conhecimento personalizadas	Não disponível	Disponível via bases de conhecimento do GitHub Copilot Enterprise
Regras impostas por administrador	Não disponível	Administradores podem definir diretrizes de codificação para toda a organização

Usuários Enterprise podem impor convenções em todos os repositórios de uma organização. Usuários Pro devem confiar em instruções por repositório e configuração manual.

Agora você sabe por que o Copilot ignora as convenções do seu projeto e como corrigir isso. Comece criando um arquivo .github/copilot-instructions.md com regras explícitas para nomenclatura, indentação e sintaxe. Combine isso com um arquivo .editorconfig e digitação manual consistente em cada arquivo. Para equipes, considere atualizar para o Copilot Enterprise para impor políticas em toda a organização. A chave é tratar o Copilot como um mecanismo de sugestão que precisa de orientação clara e repetida, em vez de assumir que ele inferirá suas regras apenas a partir da base de código.