Instruções do GitHub Copilot por pasta: como usar .instructions.md e applyTo

Ilustração de pastas de projeto com arquivo .instructions.md e regra applyTo do GitHub Copilot
Resposta rápida

Crie arquivos NAME.instructions.md dentro de .github/instructions, com um frontmatter YAML cuja chave applyTo recebe um ou mais globs (ex.: "app/models/**/*.rb"). Esses arquivos só entram quando o pedido envolve arquivos que batem com o padrão, e vencem o .github/copilot-instructions.md em caso de conflito. Funcionam no Chat do VS Code e do Visual Studio, no cloud agent e no code review do GitHub.com, mas não no Chat do GitHub.com. Para validar, abra um chat novo no VS Code e confira se o arquivo aparece na lista References da resposta.

O GitHub Copilot trabalha com três níveis de instruções personalizadas: as do repositório inteiro (repository-wide), as por caminho (path-specific) e as de agente (agent instructions), segundo a documentação oficial de custom instructions. Este tutorial cobre os dois primeiros. O primeiro é o .github/copilot-instructions.md, o segundo são os arquivos .github/instructions/NAME.instructions.md com a chave applyTo.

A lógica é a mesma das skills do Claude para código: o contexto entra sob demanda, conforme o escopo. Uma regra de migration Ruby que aparece quando você está mexendo num componente React não ajuda em nada. Ela só ocupa espaço no prompt e vira ruído.

Qual a diferença entre copilot-instructions.md e .instructions.md?

O copilot-instructions.md vale para todo pedido feito no repositório. Os arquivos .instructions.md entram conforme o escopo: pelo padrão do applyTo e, no VS Code, também pela description, que funciona como uma segunda porta de entrada (o passo 3 do tutorial explica como).

No VS Code, o .github/copilot-instructions.md da raiz do workspace é detectado automaticamente e aplicado a todos os pedidos de chat daquele workspace, conforme a documentação do VS Code sobre custom instructions. Você não precisa configurar nada para ele funcionar.

Já o arquivo por caminho é mais seletivo. Pense nele como um .editorconfig com escopo: a regra existe no repositório, mas pesa quando a tarefa tem a ver com a parte do projeto que ela cobre.

E se as duas instruções disserem coisas diferentes? A documentação do GitHub define a ordem de precedência assim:

  • instruções por caminho vencem as do repositório inteiro
  • instruções do repositório inteiro vencem as da organização e as pessoais

Na prática, a divisão fica assim:

  • No arquivo global: o que vale para qualquer parte do projeto, como idioma das mensagens de commit, stack principal, padrão de testes e convenções de nomenclatura.
  • Nos arquivos por caminho: regras de um módulo, de uma linguagem ou de um time, como convenções dos models, padrão dos componentes de front e regras de migrations.

Se tudo for parar no arquivo global, cada pedido carrega regras que não têm nada a ver com a tarefa. É justamente isso que as instruções do Copilot por pasta resolvem.

Onde as instruções por caminho funcionam no Copilot

Elas não valem em todos os recursos. A tabela abaixo resume o que a documentação do GitHub informa.

RecursoLê arquivos .instructions.md?
Copilot Chat no VS CodeSim
Copilot Chat no Visual StudioSim
Copilot cloud agentSim
Copilot code review no GitHub.comSim (suporte anunciado em 2025-09-03)
Copilot Chat no GitHub.comNão (usa só o copilot-instructions.md)
Copilot code review no VS Code e no Visual StudioNão
Copilot CLISó quando o applyTo bate com um arquivo em que o CLI está trabalhando

O suporte do code review foi anunciado no changelog de 2025-09-03. Para o Copilot CLI, a regra está na documentação de instruções do CLI.

Esse quadro muda com o tempo. Antes de montar um fluxo inteiro em cima dele, confira a página Custom instructions support, que lista recurso por recurso quais tipos de instrução cada um suporta.

O que você precisa antes de criar o arquivo

A lista é curta:

  • Um repositório em que você use o GitHub Copilot. Se ainda não tem acesso, estudantes podem conseguir o Copilot grátis pelo GitHub Education.
  • Permissão para criar a pasta .github/instructions na raiz do repositório.
  • No VS Code, saber que a pasta lida vem da configuração chat.instructionsFilesLocations.

Essa última merece atenção. O padrão dela é .github/instructions, e o VS Code procura ali de forma recursiva, segundo a documentação do VS Code. Se alguém do time mudou essa configuração, o arquivo precisa ficar na pasta que ela aponta.

Como criar instruções por pasta com applyTo, passo a passo

Os blocos abaixo são exemplos didáticos montados a partir da sintaxe oficial. Adapte os globs e o texto das regras ao seu projeto.

  1. Crie a pasta .github/instructions. A documentação do GitHub sobre instruções do repositório avisa que, se ela não existir, você mesmo cria. Os arquivos podem ficar direto nela ou em subpastas, então dá pra organizar por time, linguagem ou módulo:
    .github/
      copilot-instructions.md
      instructions/
        backend/
          models.instructions.md
        frontend/
          typescript.instructions.md
  2. Crie o arquivo NAME.instructions.md com o frontmatter. O arquivo começa com um bloco YAML com a chave applyTo, que recebe padrões glob. Que glob? É o padrão de caminho com curingas: ** casa com qualquer nível de pasta e *.rb casa com qualquer arquivo Ruby. Um exemplo para os models Ruby:
    ---
    applyTo: "app/models/**/*.rb"
    ---
    
    Nos models, mantenha validações no topo da classe.
    Prefira scopes nomeados a consultas soltas nos controllers.

    Para cobrir mais de um padrão, separe os globs por vírgula dentro da mesma string. Um exemplo para TypeScript e TSX:

    ---
    applyTo: "**/*.ts,**/*.tsx"
    ---
    
    Use tipos explícitos nas props dos componentes.
    Evite any; quando o tipo for desconhecido, use unknown.

    Erro comum deste passo: salvar o arquivo fora da pasta configurada ou esquecer a extensão .instructions.md (um models.md comum, por exemplo). Aí o VS Code não descobre o arquivo e a regra nunca entra no chat.

  3. No VS Code, preencha name e description. Segundo a referência de custom instructions do VS Code, o frontmatter aceita esses campos, além do applyTo:
    ---
    name: "Models Ruby"
    description: "Convenções para models ActiveRecord dentro de app/models"
    applyTo: "app/models/**/*.rb"
    ---

    Se liga nesse detalhe: no VS Code, o agente decide quais arquivos aplicar de dois jeitos independentes. Um é o glob do applyTo. O outro é a correspondência semântica entre a description e a tarefa atual (em sessões Local).

    A description não restringe o applyTo, ela abre uma segunda porta de entrada. É o mesmo mecanismo das skills, carregadas pela description.

    Erro comum deste passo: escrever uma description vaga, tipo "boas práticas de código". Ela combina com quase qualquer tarefa e o arquivo acaba carregado onde não deveria. Seja específico sobre o módulo e o assunto.

  4. No GitHub.com, restrinja quem lê com excludeAgent. A chave excludeAgent impede que o Copilot cloud agent ou o Copilot code review usem o arquivo. Os valores aceitos são "code-review" e "cloud-agent". Sem a chave, os dois usam o arquivo. O exemplo oficial abaixo cria um arquivo lido só pelo cloud agent:
    ---
    applyTo: "**"
    excludeAgent: "code-review"
    ---

    Isso é útil quando uma instrução serve para gerar código, mas atrapalharia a revisão de um PR (ou o contrário).

    Erro comum deste passo: copiar o valor "coding-agent" de material antigo. Ele aparece no changelog de 2025-11-12, que lançou o excludeAgent. Depois disso, o coding agent passou a se chamar cloud agent, e a documentação atual usa "cloud-agent".

  5. **No Copilot CLI, não use referências @caminho dentro de *.instructions.md.** Segundo a documentação do CLI, essas referências são expandidas em copilot-instructions.md, AGENTS.md e CLAUDE.md, mas não em arquivos *.instructions.md. Se a regra precisa apontar para outro arquivo, descreva o conteúdo direto no texto da instrução.

Como conferir se a instrução foi aplicada

A checagem mais confiável é no VS Code: abra um chat novo e veja se o arquivo aparece na lista References da resposta.

  1. Abra um chat novo com um arquivo que bate com o applyTo no contexto. Para o exemplo dos models, deixe um arquivo de app/models/ no contexto e faça um pedido sobre ele. Na resposta, procure o seu .instructions.md na lista References. A documentação do VS Code usa essa mesma checagem para o copilot-instructions.md.

    Quem faz o anexo automático é a configuração chat.includeApplyingInstructions, descrita na referência de configurações de IA do VS Code. Em pedidos de chat Local, ela anexa o arquivo quando o glob bate com algum arquivo no contexto do chat ou com um arquivo que o agente cria ou modifica.

  2. Se o arquivo não aparecer, veja se ele foi descoberto. Abra a Paleta de Comandos, rode Chat: Open Customizations e escolha Instructions. Se o arquivo não estiver na lista, volte ao passo 2 e confira a pasta e a extensão.

    O VS Code também tem uma tela de diagnóstico das customizações do chat, que mostra se o arquivo foi encontrado e se tem erros. Para investigar uma interação específica, existe a Chat Debug view.

    Se nem o chat responde naquele projeto, confira se o Copilot não ficou desativado no VS Code para aquele workspace.

  3. Não valide pelo Chat do GitHub.com. Quando o Chat web usa as instruções do repositório, ele lista como referência só o .github/copilot-instructions.md, porque não suporta instruções por caminho.

Erro comum deste passo: testar no Chat do GitHub.com, não ver o .instructions.md nas referências e concluir que o arquivo está quebrado. Ele pode estar certinho, só que aquele recurso não lê esse tipo de arquivo.

Próximo passo: escolha uma pasta e escreva a primeira regra

Escolha um módulo do seu projeto que tenha convenções próprias, como os models, uma pasta de componentes ou as migrations. Crie um único .instructions.md para ele, com um applyTo restrito àquela pasta e uma description que cite o módulo pelo nome.

Depois, abra um chat novo no VS Code com um arquivo desse módulo no contexto e confira a lista References. Se o arquivo aparecer e a resposta seguir a regra, aí sim vale replicar o padrão para outras pastas.

Perguntas frequentes

Posso ter mais de um arquivo .instructions.md para a mesma área do projeto?

Sim. O GitHub permite um ou mais arquivos NAME.instructions.md dentro de .github/instructions ou em subpastas dela, cada um com seu próprio applyTo e seu próprio conjunto de regras.

Fontes consultadas

Consulta em .

Veja mais exemplos práticos no canal Hora de Codar.

Escrito por | Matheus Battisti

Matheus Battisti
Fundador da Hora de Codar

Programador apaixonado pelo mundo das tecnologias, sempre buscando em aprender e se aprofundar em linguagens, frameworks e o que mais for necessário para executar um bom trabalho. Agora tem uma nova missão que é de passar seu conhecimento adiante para formar novos programadores e especializar mais os que já são.

Formações

Formação Vibe Coding

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

  • 474 aulas
  • 20 projetos
  • 39h 30min

Blog | Mais populares