Os arquivos de instruções destinados a agentes de programação com inteligência artificial precisam de revisão contínua, não de expansão sem fim. Cada vez que o modelo comete um erro, uma nova regra é adicionada; cada vez que uma ferramenta muda, uma solução alternativa é acrescentada, enquanto as orientações de modelos anteriores permanecem mesmo depois do surgimento de modelos mais novos. O resultado pode ser um arquivo que combina um guia de configuração para desenvolvedores, um guia de estilo, um registro de solução de problemas e um conjunto de técnicas antigas de formulação de prompts.
Segundo o artigo, esse acúmulo pode tornar o agente de programação menos eficaz. Os modelos modernos são cada vez mais capazes de explorar repositórios, reconhecer frameworks comuns, seguir os padrões existentes e lidar com erros habituais. No entanto, eles não conhecem as decisões específicas da equipe, as restrições ocultas ou as experiências operacionais acumuladas internamente. Portanto, o objetivo não é tornar o arquivo de instruções o mais curto possível, mas manter o menor conjunto de informações de alto sinal que realmente altera o resultado.
Trate o contexto como um recurso limitado
O arquivo de instruções é adicionado ao contexto disponível para o modelo em cada solicitação à qual se aplica, e suas linhas disputam a atenção do modelo com a tarefa do desenvolvedor, o código relevante, as saídas das ferramentas, o histórico da conversa e outras instruções. Uma janela de contexto maior não significa que cada token adicional seja gratuito.
A pergunta prática não é: o que pode ser dito ao modelo sobre o repositório? Mas sim: o que o modelo precisa saber e não consegue descobrir, inferir ou recuperar de forma confiável? O artigo recomenda concentrar-se em informações específicas, relevantes e difíceis de inferir.
O que deve permanecer no arquivo?
As informações de maior valor incluem fatos não óbvios sobre o sistema, como os limites de propriedade entre componentes do repositório, o fato de uma pasta antiga ainda ser usada em produção ou o fato de determinados arquivos serem gerados e não poderem ser modificados manualmente. É útil esclarecer que determinada interface possui o contrato HTTP público ou que as regras de domínio pertencem a uma camada específica, em vez de deixar o modelo inferir esses limites a partir dos nomes das pastas.
Também deve ser documentado o caminho confiável mais curto para compilação e validação, limitando-se aos comandos que foram testados. Entre os exemplos apresentados no artigo estão executar dotnet restore App.slnx antes da primeira compilação, depois usar dotnet build App.slnx --no-restore, executar testes específicos ao alterar interfaces de programação ou usar a ferramenta de validação de arquivos gerados após modificar contratos. Os requisitos especiais devem ser esclarecidos, como a necessidade de Docker para testes de integração e o fato de eles não deverem ser executados em paralelo, pois um comando incorreto repetido com confiança é pior do que a ausência de um comando.
Também é útil registrar escolhas locais que o código não consegue determinar de forma consistente: o framework de testes adotado, a preferência por Minimal APIs em vez de controladores, o padrão Result<T> para tratar erros de domínio esperados ou o uso de TimeProvider em vez de chamar diretamente o relógio do sistema. Essas não são regras gerais de programação, mas decisões específicas da base de código e, por isso, são adequadas para o arquivo de instruções.
Quanto às restrições rígidas, palavras como «sempre», «nunca» e «deve» devem ser reservadas para regras realmente absolutas, como preservar um contrato JSON público, não colocar dados de clientes nos logs, manter as migrações do banco de dados compatíveis com a versão anterior ou impedir a alteração de arquivos do ambiente de produção sem uma tarefa explícita de implantação. Também é possível apontar para fontes de verdade em vez de copiar seu conteúdo, como arquivos de diretrizes de design de interfaces, arquivos de definição das versões do ambiente de execução, documentação de implantação e decisões de arquitetura.
O que pode ser removido ou transferido?
O artigo recomenda remover conselhos gerais como escrever código limpo, seguir as melhores práticas, usar nomes significativos e tratar erros adequadamente. Essas frases não resolvem uma decisão prática, enquanto uma regra local específica é mais útil; por exemplo, associar erros de validação à resposta 400, recursos inexistentes à resposta 404 e conflitos de concorrência à resposta 409 usando as ferramentas ProblemDetails existentes.
Em geral, os arquivos não precisam de um inventário completo das pastas, pois o modelo consegue ler rapidamente a estrutura do repositório. Também não é necessário repetir regras de formatação impostas pelas ferramentas; basta mencionar o comando de validação adequado, como dotnet format --verify-no-changes. Deve-se evitar copiar integralmente README, guias de arquitetura e instruções de contribuição, para não aumentar o custo de manutenção nem criar contradições entre os documentos.
O artigo também alerta contra «mitos antigos de prompts», como pedir ao modelo que respire fundo, que aja como um engenheiro sênior ou que leia todos os arquivos antes de fazer qualquer alteração. Essas frases não acrescentam conhecimento sobre o projeto e podem levar a uma exploração desnecessária. É melhor descrever o resultado, as restrições e a validação necessária: fazer a menor alteração que corrija a causa raiz, preservar o comportamento público e executar os testes direcionados.
As soluções temporárias devem ser removidas depois que o problema que as motivou for corrigido. Caso contrário, o agente continuará evitando um caminho que já não está quebrado. As instruções também devem ser escritas para uma classe de modelos, e não para uma versão específica; instruções divididas em caminhos particulares para cada modelo tornam-se frágeis à medida que os modelos e seus comportamentos mudam.
Escolha o escopo das instruções e revise-as
Nem toda orientação é adequada para o arquivo geral do repositório. O GitHub Copilot oferece instruções gerais em .github/copilot-instructions.md, arquivos específicos por caminho em .github/instructions/ e instruções para agentes, como AGENTS.md. O arquivo geral de instruções é usado junto com o arquivo específico do caminho correspondente quando ambos existem.
A estrutura do sistema, os comandos compartilhados e as restrições gerais devem ser colocados no escopo geral; regras de frameworks, padrões de testes e arquivos gerados específicos de determinada parte devem ser transferidos para um arquivo específico por caminho. Já as explicações detalhadas, o histórico das decisões e os procedimentos raros devem permanecer preferencialmente em documentos vinculados. Assim, uma regra referente a testes de componentes React não consome a atenção do modelo durante uma tarefa de migração de banco de dados.
O artigo propõe revisar cada orientação de acordo com quatro resultados: manter se ela for correta, relevante e difícil de inferir; remover se o modelo já a conhecer, se uma ferramenta a impuser ou se ela tiver se tornado ambígua ou obsoleta; transferir se for útil, mas pertencer a outro caminho ou documento; e verificar se mencionar um comando, uma solução temporária ou uma versão que pode ter mudado.
Os momentos para revisão incluem a adoção de um modelo mais capaz, a mudança do sistema de compilação, a reorganização do repositório ou a observação de que os agentes ignoram as instruções ou as aplicam de forma incorreta. Em seguida, o arquivo menor deve ser testado em uma tarefa específica, as falhas reais devem ser monitoradas, a menor instrução capaz de impedir sua repetição deve ser adicionada e o teste deve ser repetido em outra tarefa.
Parte da manutenção do projeto
O artigo recomenda revisar as alterações nos arquivos de instruções em pull requests comuns, perguntar aos revisores se a regra é reutilizável ou se trata apenas de uma única tarefa e designar um responsável pelos comandos operacionais e pelos requisitos do ambiente. As soluções temporárias também devem ser removidas na mesma pull request que trata a causa do problema, e os comandos devem ser verificados novamente após atualizações dos pacotes do SDK, dos frameworks, das ferramentas de teste ou do processo de compilação.
A qualidade do arquivo não deve ser medida pelo número de linhas. Um arquivo de 30 linhas contendo instruções erradas pode ser pior do que um arquivo de 100 linhas que descreve os limites de um repositório com vários projetos e informações que o modelo não pode deduzir. O melhor critério é permitir que o arquivo possibilite a um modelo capaz começar a trabalhar rapidamente, fornecendo-lhe aquilo que somente a equipe sabe: o que é o sistema, os limites importantes, as escolhas locais, como construir e validar, o que não pode ser quebrado e onde encontrar os detalhes mais aprofundados.