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

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

Black Week do Nexus
A formação de IA mais completa do Brasil
- 7 formações · 112 cursos · 26 mil alunos
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.
| Recurso | Lê arquivos .instructions.md? |
|---|---|
| Copilot Chat no VS Code | Sim |
| Copilot Chat no Visual Studio | Sim |
| Copilot cloud agent | Sim |
| Copilot code review no GitHub.com | Sim (suporte anunciado em 2025-09-03) |
| Copilot Chat no GitHub.com | Não (usa só o copilot-instructions.md) |
| Copilot code review no VS Code e no Visual Studio | Não |
| Copilot CLI | Só 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.

VPS Hostinger para seu sistema
10% OFF extraVPS com SSD NVMe e backups semanais. O cupom MATHEUSHORADECODAR é aplicado automaticamente pelo link.
Ver planos com 10% OFF →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/instructionsna 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.
- 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 - Crie o arquivo
NAME.instructions.mdcom o frontmatter. O arquivo começa com um bloco YAML com a chaveapplyTo, que recebe padrões glob. Que glob? É o padrão de caminho com curingas:**casa com qualquer nível de pasta e*.rbcasa 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(ummodels.mdcomum, por exemplo). Aí o VS Code não descobre o arquivo e a regra nunca entra no chat. - No VS Code, preencha
nameedescription. Segundo a referência de custom instructions do VS Code, o frontmatter aceita esses campos, além doapplyTo:--- 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 adescriptione a tarefa atual (em sessões Local).A
descriptionnão restringe oapplyTo, 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.
- No GitHub.com, restrinja quem lê com
excludeAgent. A chaveexcludeAgentimpede 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 oexcludeAgent. Depois disso, o coding agent passou a se chamar cloud agent, e a documentação atual usa"cloud-agent". - **No Copilot CLI, não use referências
@caminhodentro de*.instructions.md.** Segundo a documentação do CLI, essas referências são expandidas emcopilot-instructions.md,AGENTS.mdeCLAUDE.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.

Crie sistemas com IA para vender
Prompts, modelos e checklists para criar e publicar seu sistema com IA e preparar a oferta para o primeiro cliente.
Quero o e-book gratuito Receba o livro e os bônus no seu e-mail.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.
- Abra um chat novo com um arquivo que bate com o
applyTono contexto. Para o exemplo dos models, deixe um arquivo deapp/models/no contexto e faça um pedido sobre ele. Na resposta, procure o seu.instructions.mdna lista References. A documentação do VS Code usa essa mesma checagem para ocopilot-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. - Se o arquivo não aparecer, veja se ele foi descoberto. Abra a Paleta de Comandos, rode
Chat: Open Customizationse 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.
- 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 .
- GitHub Docs: Custom instructions for GitHub Copilot
- GitHub Docs: Adding repository custom instructions for GitHub Copilot
- changelog de 2025-11-12
- changelog de 2025-09-03
- GitHub Docs: Custom instructions support
- GitHub Docs: Adding custom instructions for GitHub Copilot CLI
- VS Code Docs: Use custom instructions in VS Code
- VS Code Docs: Custom instructions reference
Formações
Formação Vibe Coding
Do Prompt ao Produto: Crie Software Real com IA
- 474 aulas
- 20 projetos
- 39h 30min
Blog | Mais populares

Copilot code review agora resolve os próprios comentários: como testar isso em um PR?
Copilot code review agora resolve os próprios comentários na rerevisão do PR. Veja o passo a passo para testar isso em um pull request real.
GitHub Copilot Fusion chega à disponibilidade geral e passa a escolher e orquestrar os modelos de cada tarefa
GitHub Copilot Fusion chega à disponibilidade geral: você escolhe o nível de esforço e o Copilot decide quais modelos usar em cada tarefa.
Requisições premium do GitHub Copilot: o que mudou com os AI Credits e quanto cada plano libera
Como funcionam as requisições premium do GitHub Copilot com os AI Credits e quantos créditos cada plano libera por mês.
