Agent.md pode melhorar a qualidade do código produzido por LLMs

Da geração de código à revisão

O autor relata que sua primeira tentativa de usar modelos de linguagem para acelerar a programação, em meados de 2025, produziu código que nem sequer compilava em um projeto de implementação de mDNS em Rust. Ao revisitar a abordagem em janeiro de 2026, obteve resultados tecnicamente mais impressionantes: o modelo criou uma classe complexa de heap binário indexado e identificou um bug obscuro na biblioteca polling, relacionado à implementação Windows IOCP. Ainda assim, a qualidade do código era, segundo ele, muito baixa: faltavam comentários e estrutura, e o resultado se parecia com código espaguete. O ganho de velocidade acabava sendo consumido pela limpeza necessária para alcançar um padrão de produção.

Em março de 2026, o autor passou a usar IDEs com recursos de agentes, como Antigravity e o plug-in Claude Code para VS Code. Isso permitiu iterar sobre o código já produzido. Ele descreve a experiência como revisar o trabalho de um estudante iniciante de ciência da computação, sugerindo repetidamente mudanças como eliminar números mágicos, inserir comentários curtos e usar nomes de funções menores. A qualidade melhorou de forma significativa e ficou próxima do que ele produziria manualmente, mas o processo exigia repetir as mesmas orientações em cada nova sessão.

O papel do agent.md

A solução proposta é usar um arquivo chamado agent.md. No início de uma sessão, o ambiente de programação carrega esse arquivo e o injeta no prompt, transformando-o em um local persistente para registrar preferências de estilo e regras de implementação. O autor sugere colocar o arquivo na raiz do projeto; alternativamente, gemini.md ou claude.md podem ser ligados simbolicamente a ele para ativar as instruções em qualquer diretório.

Entre as regras de sua versão estão escrever comentários, mensagens de commit e respostas com o mínimo de palavras; evitar elogios e superlativos; substituir valores recorrentes ou significativos por constantes ou enumerações; reduzir a indentação com retornos antecipados; manter nomes de funções com menos de 30 caracteres; separar blocos lógicos com linhas vazias; e adicionar comentários breves que expliquem o que um bloco faz e por quê. O arquivo também orienta a preservar a visibilidade privada de membros, exigir aprovação explícita antes de ampliá-la, encapsular mecanismos de baixo nível em abstrações próprias, respeitar limites entre camadas e evitar alterações em trechos não relacionados à tarefa.

Há ainda regras específicas para mensagens de commit, incluindo limite de tamanho, uso do modo imperativo e explicação do contexto e do motivo. Quando a tarefa envolve corrigir um bug, a orientação é escrever primeiro um teste, observar sua falha, implementar a correção e verificar sua aprovação.

Limites e manutenção das instruções

O autor afirma que o arquivo melhorou consideravelmente o código gerado, mas não é uma solução definitiva. Os modelos continuam alucinando e não podem ser considerados confiáveis; ele ainda precisa ler o código, verificar resultados e iterar bastante. A principal mudança é que sua atenção passou a se concentrar mais em arquitetura e design do que em estilo.

Ele também alerta para a “diluição de contexto”, fenômeno associado ao trabalho Lost in the Middle: à medida que o contexto cresce, o modelo tenderia a dar menos atenção às instruções no meio, favorecendo as do início e do fim. Para reduzir o efeito, recomenda iniciar uma sessão nova para cada funcionalidade e pedir explicitamente ao ambiente que recarregue o agent.md quando a qualidade cair. O próprio agente também pode ser instruído a atualizar o arquivo com novas regras.