Como configurar instruções personalizadas de repositório no GitHub Copilot para padronizar código e arquitetura em equipes de engenharia

Quando equipes de engenharia de software adotam o GitHub Copilot em larga escala, frequentemente encontram um desafio inicial: a falta de consistência no código sugerido. Sem diretrizes compartilhadas no nível do projeto, o modelo de IA responde com base apenas no seu treinamento geral e nos arquivos abertos recentemente no editor. Como consequência, em um mesmo repositório, um desenvolvedor recebe sintaxes obsoletas de JavaScript em um projeto TypeScript, outro quebra o isolamento de camadas arquiteturais e um terceiro inclui bibliotecas não homologadas em um Pull Request (PR).

O GitHub Copilot resolve essa divergência por meio das instruções personalizadas de repositório (Repository Custom Instructions). Ao manter arquivos Markdown versionados no Git — principalmente .github/copilot-instructions.md na raiz e arquivos modulares em .github/instructions/**/*.instructions.md —, o time injeta fronteiras arquiteturais, convenções de código, diretrizes de testes e requisitos de segurança diretamente em todas as interações do Copilot e nas revisões automatizadas de código.

Este guia aborda o funcionamento das instruções personalizadas, suas regras de precedência, como configurar diretrizes globais e por escopo de caminho, como habilitar a verificação em revisões de PR no GitHub.com e as práticas recomendadas para manter o contexto dos modelos enxuto e eficaz.

Onde as instruções personalizadas se aplicam (e onde não se aplicam)

Antes de criar regras, é fundamental compreender em quais superfícies o GitHub Copilot consome esses arquivos de instrução.

As instruções são anexadas automaticamente ao início do prompt enviado aos LLMs em fluxos de trabalho de alto nível e raciocínio:

• Copilot Chat nas IDEs: VS Code, Visual Studio, suíte JetBrains (IntelliJ IDEA, PyCharm, WebStorm etc.), Xcode e Eclipse.
• Superfícies no GitHub.com: Chat web no repositório, tarefas do agente autônomo na nuvem (Cloud Agent) e criação assistida de PRs.
• Copilot Code Review: Revisão automatizada de pull requests no GitHub.com, avaliando as alterações contra as regras do repositório.
• Copilot CLI: Linha de comando no terminal para geração de scripts e comandos.

A diferença em relação ao autocompletar em linha (Ghost Text)

As instruções personalizadas não controlam de maneira estrita o autocompletar em linha (o texto fantasma cinza que surge durante a digitação). O mecanismo de sugestão em linha prioriza latência de milissegundos e utiliza prioritariamente o código no entorno do cursor e as abas abertas no editor. As instruções de repositório foram desenhadas primariamente para o Chat, comandos de refatoração (/fix, /explain), agentes autônomos e revisões de PR. Para garantir padrões estritos de formatação (espaçamento, ponto e vírgula, aspas), combine o Copilot com linters e formatadores determinísticos, como ESLint, Biome ou Prettier.

Hierarquia de precedência de instruções

Quando múltiplas camadas de regras estão presentes, o GitHub Copilot combina as instruções na seguinte ordem de prioridade (da maior para a menor):

1. Instruções pessoais (Personal instructions): Preferências individuais configuradas pelo desenvolvedor no perfil do Copilot.
2. Instruções específicas por caminho (Path-specific instructions): Arquivos .github/instructions/**/*.instructions.md que coincidem via padrão glob com o arquivo em edição.
3. Instruções globais de repositório (Repository-wide instructions): O arquivo central .github/copilot-instructions.md.
4. Instruções de agente: Arquivos como AGENTS.md, CLAUDE.md ou GEMINI.md.
5. Instruções da organização (Organization instructions): Regras corporativas aplicadas por administradores em toda a organização no GitHub.

Passo 1: Criar instruções globais do repositório (.github/copilot-instructions.md)

O arquivo base de configuração fica situado na raiz do repositório Git:

mkdir -p .github
touch .github/copilot-instructions.md

Para garantir máxima aderência pelo modelo, estruture o documento com títulos Markdown objetivos, listas com marcadores e instruções formuladas de maneira afirmativa.

Seções essenciais recomendadas

1. Visão geral e fronteiras arquiteturais: Descrição sucinta do serviço, padrão arquitetural adotado (Clean Architecture, Monólito Modular, Arquitetura Hexagonal) e regras de separação (ex.: "A camada de domínio nunca deve importar dependências de banco de dados ou componentes de interface").
2. Versões de linguagem e ferramentas principais: Fixação de versões exatas do ecossistema (ex.: Node.js 22 LTS, TypeScript 5.5, Next.js 15 App Router).
3. Padrões de codificação e tratamento de erros: Convenções de nomenclatura e tratamento de falhas (ex.: "Utilize tipos Result em vez de lançar exceções não tratadas").
4. Diretrizes de testes: Framework de testes (Vitest, Jest), padrão estrutural (Arrange-Act-Assert - AAA) e cobertura obrigatória para regras de negócio.
5. Segurança e validação de entrada: Bibliotecas de validação obrigatórias (Zod, Pydantic), consultas parametrizadas ao banco e proibição de credenciais hardcoded.

Exemplo de produção (Serviço TypeScript e Next.js)

# Arquitetura do Repositório e Padrões de Código

## Visão Geral do Projeto
Este repositório contém o Core Billing Service, desenvolvido com Next.js e Node.js, conectado ao PostgreSQL e ao Stripe para liquidação de pagamentos.

## Fronteiras Arquiteturais
- Separação rigorosa de camadas: Componentes UI (`/app`, `/components`) -> Serviços de Aplicação (`/src/services`) -> Modelos de Domínio (`/src/domain`) -> Repositórios de Dados (`/src/infrastructure`).
- A camada de domínio deve permanecer agnóstica a frameworks. Nunca importe `next/*` ou clientes de banco de dados em `/src/domain`.
- Todo acesso ao banco deve ser realizado através dos repositórios Prisma em `/src/infrastructure/repositories`. SQL direto fora de arquivos de migração é proibido.

## Padrões de TypeScript
- TypeScript 5.x em modo strict. O uso de `any` é proibido; utilize `unknown` com narrowing ou esquemas Zod explícitos.
- Prefira aliases `type` para declaração de objetos e uniões; utilize `interface` apenas para contratos extensíveis.
- Erros assíncronos devem ser tratados com tipos `Result<T, E>` ou classes de erro estruturadas; não permita Promise rejections não tratadas.
- Aplique cláusulas de guarda (guard clauses) e retornos antecipados para evitar encadeamentos profundos de if/else.

## Gerenciamento de Estado e Requisições
- Requisições no client-side devem utilizar TanStack Query (`@tanstack/react-query`). Não utilize hooks `useEffect` sem cache para chamadas a APIs.
- Server Actions devem validar os dados de entrada usando Zod antes de acionar os serviços de domínio.

## Padrões de Testes
- Ferramenta de testes: Vitest com React Testing Library.
- Testes unitários devem ficar no mesmo diretório do arquivo correspondente (`*.spec.ts` ou `*.spec.tsx`).
- Estrutura Arrange-Act-Assert (AAA) obrigatória em cada suíte.
- Isole dependências de rede com Mock Service Worker (MSW); não crie mocks de utilitários nativos da linguagem.

## Comandos de Referência
- Execução de testes: `pnpm test`
- Verificação de tipos: `pnpm typecheck`
- Validação de lint: `pnpm lint`

Passo 2: Configurar instruções específicas por caminho (.github/instructions/)

Em monorepositórios ou aplicações full-stack, concentrar todas as regras em um único arquivo sobrecarrega a janela de contexto e dispersa a atenção do modelo. Um engenheiro alterando um serviço em Go, por exemplo, não deve receber regras de estilização Tailwind do frontend React.

Instruções por caminho resolvem isso associando arquivos específicos a padrões glob.

Estrutura de diretórios

Mantenha arquivos modulares dentro de .github/instructions/:

.github/
  ├── copilot-instructions.md
  └── instructions/
      ├── frontend.instructions.md
      ├── backend.instructions.md
      └── migrations.instructions.md

Sintaxe e Frontmatter

Cada arquivo deve terminar com .instructions.md e iniciar com um bloco YAML Frontmatter declarando a chave applyTo:

---
applyTo: "apps/web/**/*.{ts,tsx}"
---

# Padrões para Componentes Frontend

- Componentes devem ser funções com exportações nomeadas (Named Exports).
- Utilize classes utilitárias do Tailwind CSS; evite objetos CSS inline.
- Elementos interativos devem conter atributos de acessibilidade `aria-*` e suporte a navegação por teclado.
- Ícones devem ser importados exclusivamente da biblioteca `lucide-react`.

Padrões Glob comuns

• **/*.py: Aplica a todos os arquivos Python em qualquer subdiretório.
• services/billing/**/*.go: Aplica exclusivamente ao código Go do serviço de faturamento.
• **/*.test.ts,**/*.spec.ts: Associa ambos os formatos de arquivos de teste separando-os por vírgula.

Exclusão de agentes (excludeAgent)

Caso determinadas diretrizes sejam voltadas exclusivamente para a execução do agente em nuvem e não devam influenciar revisões de código, adicione excludeAgent:

---
applyTo: "**"
excludeAgent: "code-review"
---

# Guia para Agente Autônomo de Build
- Execute `pnpm db:migrate` antes de rodar os testes de integração.
- Ao adicionar novas configurações, atualize o arquivo `.env.example`.

Passo 3: Habilitar a verificação em revisões de Pull Request

As instruções personalizadas também servem como critérios automáticos durante o processo de code review realizado pelo Copilot.

Como ativar a revisão automatizada

1. No GitHub.com, acerte a página do repositório.
2. Acesse a aba Settings (Configurações).
3. Na barra lateral esquerda, vá até Code, planning, and automation -> Copilot -> Code review.
4. Ative a opção Use custom instructions when reviewing pull requests.

Mecanismo de leitura do Branch de origem (Head Branch)

Ao revisar um PR, o GitHub Copilot lê os arquivos de instrução a partir do branch de origem (head branch) do PR, e não do branch de destino (main).

Essa dinâmica proporciona uma vantagem essencial: quando a equipe de arquitetura decide atualizar as convenções de código, pode criar um PR que contenha tanto a nova instrução quanto a implementação adaptada a ela. O Copilot aplicará de imediato as novas regras na revisão daquele PR, permitindo testar a eficácia das diretrizes antes do merge final.

Passo 4: Validar o carregamento das instruções no ambiente de desenvolvimento

Para assegurar que o ambiente dos desenvolvedores está carregando os arquivos de instrução corretamente:

1. Configuração na IDE:
   • No VS Code, abra as Configurações (Ctrl+, ou Cmd+,), pesquise por instruction file e confira se Code Generation: Use Instruction Files está marcado (ativo por padrão).
   • Nas IDEs da JetBrains, abra o painel do Copilot Chat, clique no ícone de engrenagem e selecione Customizations para inspecionar os arquivos ativos do projeto.
2. Conferência da seção References no Chat:
   • Envie uma pergunta no Copilot Chat (ex.: "Crie um serviço de validação de clientes").
   • Expanda o bloco References no topo da resposta gerada.
   • Caso as regras estejam ativas, o arquivo .github/copilot-instructions.md (e eventuais arquivos .instructions.md pertinentes) aparecerá listado como link, confirmando a consulta às diretrizes da equipe.

Boas práticas e armadilhas a evitar

Uso combinado com Prompt Files (.github/prompts/*.prompt.md)

Enquanto as instruções de repositório delimitam restrições globais imutáveis, muitas rotinas de desenvolvimento são tarefas repetitivas, como a criação de novos endpoints, migrações de banco ou baterias de testes unitários.

Nesses cenários, combine as instruções de repositório com arquivos de prompt do Copilot armazenados em .github/prompts/*.prompt.md. Eles oferecem modelos pré-estruturados chamados pelo Copilot Chat, enquanto as regras de .github/copilot-instructions.md garantem que o resultado final siga a arquitetura da equipe.

Checklist de implantação

1. Criar .github/copilot-instructions.md na raiz do projeto com arquitetura, versões de dependências e regras inegociáveis.
2. Estruturar regras modulares em .github/instructions/ com o atributo applyTo para diretórios específicos.
3. Habilitar o uso de instruções personalizadas no Copilot Code Review nas configurações do repositório no GitHub.
4. Validar o carregamento dos arquivos inspecionando a seção References nas respostas do Copilot Chat.
5. Manter as instruções atualizadas por meio de PRs regulares conforme o projeto evolui.

Referências

• Adding repository custom instructions for GitHub Copilot - GitHub Docs
• Adding repository custom instructions for GitHub Copilot in your IDE - GitHub Docs
• Support for different types of custom instructions - GitHub Docs
• About customizing GitHub Copilot responses - GitHub Docs
• 5 tips for writing better custom instructions for Copilot - The GitHub Blog