Ir para o conteúdo
Promovaweb

Instruções do projeto e memória no Copilot CLI

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

Aproveitar a Black Friday

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

  1. Explicar o projeto uma vez só
  2. O CLI lê vários arquivos de instrução
  3. Os arquivos se somam, sem ordem de prioridade
  4. Instruções por caminho valem só para alguns arquivos
  5. A memória guarda o que o agente aprende
  6. Instrução escrita orienta, permissão garante

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.
Os arquivos de instrução que o Copilot CLI encontra na sua pasta pessoal e no repositório. Todos os aplicáveis entram juntos na conversa.

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.