Por que arquivos AGENTS.md inchados estão prejudicando a performance do seu código

O perigo do excesso de instruções para agentes

Se você utiliza agentes de codificação em seus projetos, provavelmente já criou ou editou um arquivo AGENTS.md ou CLAUDE.md. A ideia parece simples: centralizar as diretrizes de estilo, comportamento e uso de ferramentas para que a IA entregue um resultado alinhado ao que você espera. No entanto, uma pesquisa recente do Instituto Federal de Minas Gerais mostra que a eficácia desses arquivos está caindo por excesso de zelo.

O estudo, que analisou 100 projetos open-source populares, identificou o que os pesquisadores chamam de "odores de configuração" (configuration smells). Em 91 desses arquivos, foram encontrados problemas que afetam diretamente o custo de processamento e a qualidade do código gerado.

Os três "odores" mais comuns no seu prompt

A pesquisa aponta três gargalos principais que drenam a eficiência do seu fluxo de desenvolvimento:

• Lint Leakage (62% dos casos): Você está gastando tokens para pedir à IA que siga regras que já são verificadas automaticamente por linters e ferramentas de análise estática. Se o seu pipeline já valida o código, não há necessidade de repetir isso na instrução do agente.
• Context Bloat (42% dos casos): O acúmulo de instruções desnecessárias. A Anthropic recomenda que esses arquivos não excedam 200 linhas. Arquivos maiores consomem o contexto da janela de execução, aumentando o custo e reduzindo a coerência do modelo.
• Skill Leakage (35% dos casos): Incluir instruções para ferramentas ou práticas raramente usadas no arquivo principal. O ideal é modularizar: crie um arquivo SKILLS.md separado e carregue apenas quando necessário.

Menos é mais: o impacto na entrega

Outros problemas, como referências cegas a documentos externos, instruções conflitantes e "fossilização" de configurações obsoletas de inicialização, também foram detectados. O resultado prático dessa "poluição" é um aumento desnecessário de custos e, ironicamente, uma queda na qualidade. Estudos anteriores da ETH Zurich indicaram que instruções excessivas podem até impactar negativamente o desempenho do código gerado.

Para quem trabalha com agentes de IA para acelerar o desenvolvimento, a lição é clara: o prompt deve ser minimalista. Se a instrução não for estritamente necessária para a tarefa atual, ela está apenas ocupando espaço que poderia ser usado para o modelo pensar melhor sobre o problema de negócio.

Como aplicar na rotina

A recomendação dos pesquisadores é clara: desenvolvedores precisam de ferramentas melhores para auditar seus arquivos de configuração. Enquanto isso não é automatizado, adote a política de revisão constante:

• Remova regras que seu linter já cobre.
• Quebre arquivos grandes em módulos específicos de habilidades.
• Revise se as instruções de inicialização do projeto ainda fazem sentido após meses de desenvolvimento.

Manter a operação enxuta não é apenas uma questão de boas práticas de código, mas de inteligência financeira e operacional. Pra times que ainda gerenciam projetos, tarefas e orçamentos de forma fragmentada, plataformas como o Orqueza ajudam a centralizar a visão da operação em um só lugar, permitindo que você foque no que realmente importa: entregar software de qualidade com menos ruído.

Fonte: theregister.com