Instruções do projeto e memória no Copilot CLI
VPS Agêntica
30% off na sua VPS Agêntica nos 2 primeiros meses
A StayCloud aplica o desconto sozinha no plano mensal, sem fidelidade. Suba uma VPS em São Paulo, instale o SetupVibe Desktop e desenvolva com agentes num ambiente que fica ligado o tempo todo.
Link de parceiro da Promovaweb.
Black Friday até 30/11
30%off
nos 2 primeiros meses do plano mensal da VPS
- Backup diário grátis para sempre
- Servidores em São Paulo no datacenter da Ascenty
- Datacenter Tier III manutenção sem parada
- Acesso root com disco SSD NVMe
- Réplica do backup em Ashburn, nos EUA
As instruções personalizadas são arquivos Markdown que o GitHub Copilot CLI acrescenta a cada mensagem sua, com as convenções do projeto, os comandos de build e o jeito de rodar os testes. A memória do Copilot completa esses arquivos com fatos que o agente deduz enquanto trabalha e guarda para as próximas sessões.
Sumário da página
Explicar o projeto uma vez só
Você manda o Copilot corrigir um teste e ele roda npm test, quando o projeto usa pnpm e um script próprio de testes. Na tarefa seguinte, o mesmo engano acontece. As instruções personalizadas resolvem esse vaivém: você escreve num arquivo como o projeto compila, como roda os testes e quais convenções segue. O Copilot CLI acrescenta esse texto a cada mensagem. A informação não aparece na tela, mas está disponível para o modelo em toda resposta.
A documentação do GitHub resume o ganho assim: em vez de repetir os mesmos detalhes em cada prompt, você deixa as instruções num arquivo e o Copilot responde com base nelas. O arquivo mais comum é o .github/copilot-instructions.md, na raiz do repositório, escrito em Markdown com instruções em linguagem natural. Os espaços entre as instruções são ignorados, então você distribui o texto em parágrafos ou linhas, do jeito mais legível.
O CLI lê vários arquivos de instrução
O Copilot CLI procura instruções em vários lugares. Os arquivos do repositório e de agentes são buscados na raiz do repositório, na pasta atual, nas pastas intermediárias entre as duas e nas pastas do caminho de cada arquivo que o agente está editando. Os arquivos do usuário ficam na pasta ~/.copilot e valem para todos os seus repositórios.
~/.copilot/Instruções do usuário, válidas em todos os repositórios.copilot-instructions.mdPreferências pessoais em um arquivo só.instructions/*.instructions.mdInstruções pessoais divididas por assunto.repositório/Instruções que vão para o Git com o projeto..github/copilot-instructions.mdConvenções do repositório inteiro..github/instructions/*.instructions.mdInstruções que valem só para os arquivos do applyTo.AGENTS.mdInstruções no formato aberto para agentes.CLAUDE.md e GEMINI.mdArquivos de outros agentes, lidos também pelo Copilot.
A lista inclui arquivos criados para outras ferramentas. O AGENTS.md segue o formato aberto mantido no repositório agentsmd/agents.md. O CLI também lê o CLAUDE.md, inclusive dentro de .claude/, junto com o GEMINI.md. Na prática, um repositório que já tem instruções para outro agente de código não precisa de um arquivo novo para o Copilot começar a respeitar as convenções. A variável COPILOT_CUSTOM_INSTRUCTIONS_DIRS acrescenta pastas extras com arquivos AGENTS.md e *.instructions.md, separadas por vírgula.
Os arquivos se somam, sem ordem de prioridade
Quando vários arquivos se aplicam, o Copilot CLI combina as instruções de todos. Ele remove as cópias idênticas de um mesmo texto, mas não define uma ordem de precedência entre os arquivos. A consequência prática é clara: duas instruções que se contradizem chegam juntas ao modelo. O resultado fica imprevisível. A própria documentação recomenda evitar instruções conflitantes entre o arquivo pessoal, o do repositório e os arquivos de agentes.
O comando /instructions mostra os arquivos encontrados para a sessão atual e permite ligar ou desligar cada um. Um arquivo desligado ali não entra na conversa. Esse controle resolve o caso de um CLAUDE.md antigo com instruções que não valem mais para o Copilot, enquanto você não define se apaga o arquivo.
Instruções por caminho valem só para alguns arquivos
Os arquivos *.instructions.md da pasta .github/instructions/ são modulares. Cada um pode declarar um valor applyTo com o padrão dos arquivos a que se aplica. Uma instrução sobre testes de componentes React, por exemplo, entra só quando o agente trabalha nos arquivos que casam com o padrão declarado. As outras tarefas ficam livres desse texto, o que poupa tokens da conversa.
Os arquivos .github/copilot-instructions.md, AGENTS.md e CLAUDE.md aceitam referências a outros arquivos com @ seguido de um caminho relativo. O CLI lê o arquivo citado na hora, inclusive as referências que ele fizer. Os arquivos referenciados precisam ficar dentro do repositório, ou dentro da pasta de instruções locais. Caminhos absolutos e caminhos iniciados por ~/ não são carregados. O GEMINI.md e os *.instructions.md não expandem referências.
Uma mudança nas instruções não chega a uma sessão em andamento. Para aplicar o texto novo, você sai e retoma a sessão com copilot --continue, ou abre uma conversa nova com /new. Se a variável COPILOT_HOME estiver definida, o CLI usa essa pasta no lugar de ~/.copilot para as instruções do usuário.
A memória guarda o que o agente aprende
A memória do Copilot constrói um entendimento persistente do repositório. Enquanto trabalha, o agente deduz convenções de código, padrões e preferências e guarda esses fatos como memórias, para não precisar descobrir tudo de novo na próxima sessão. O Copilot CLI armazena fatos do repositório e as suas preferências pessoais.
Nas sessões interativas, conforme as suas configurações de permissão, o Copilot solicita a sua aprovação antes de guardar uma memória nova. Essa pergunta é uma chance de conferir o que ele concluiu. Uma memória errada, aprovada sem leitura, continua orientando as respostas seguintes.
Instrução escrita orienta, permissão garante
As instruções e as memórias mudam o que o agente tenta fazer. Uma frase como “não rode migrações em produção” num arquivo de instruções orienta o modelo, mas não impede a chamada. Para garantir que um comando não rode, a ferramenta certa é a opção --deny-tool ou uma restrição nas permissões, explicadas no hub de permissões e sandbox. As duas camadas trabalham juntas. O arquivo explica o projeto. As permissões limitam o que pode acontecer nele.