Arquivos de configuração de agentes têm meia-vida: audite-os

A configuração envelhece

Arquivos como CLAUDE.md, AGENTS.md, skills, hooks e memórias de agentes de programação têm uma espécie de meia-vida: modelos e ferramentas evoluem, os repositórios mudam e instruções escritas para versões antigas podem perder valor. Ao tentar corrigir cada erro adicionando uma nova regra, o arquivo cresce, o agente passa a receber mais contexto e a qualidade pode cair. A recomendação central é tratar esses arquivos como guias curtos de decisão, não como bases completas de conhecimento.

Estudos citados reforçam o problema. Uma análise de 100 repositórios populares encontrou vazamento relacionado a lint em 62% deles, excesso de contexto em 42% e vazamento de skills em 35%; os arquivos frequentemente ultrapassavam a orientação de 200 linhas, chegando em alguns casos a centenas ou milhares. O texto também cita a Anthropic, que teria removido mais de 80% do prompt de sistema do Claude Code para seus modelos Claude 5 sem perda mensurável em avaliações internas de programação. O resultado não deve ser tratado como meta geral: as avaliações não são públicas e dizem respeito a modelos e ambientes específicos. A conclusão é que o valor de uma instrução pode expirar; regras indispensáveis deveriam ser transformadas em testes, hooks ou permissões, em vez de permanecerem apenas como prosa sujeita a ser ignorada.

Skills e arquivos de contexto

O autor continua vendo valor nas Agent Skills, que podem especializar um agente generalista e funcionar em diferentes agentes e ambientes de programação. Mas a qualidade varia: descrições vagas, gatilhos pouco claros, etapas incompletas e exemplos insuficientes reduzem sua utilidade. Skills instaladas durante experimentos também se acumulam, embora apenas uma fração seja usada, aumentando custo, ruído e possíveis conflitos. Instalar uma skill útil e mantê-la indefinidamente são decisões diferentes.

Pesquisas citadas relativizam a personalização. Uma skill derivada do histórico de um desenvolvedor teve desempenho semelhante ao de uma skill emprestada de outra pessoa, enquanto uma skill genérica construída com dados de vários desenvolvedores foi mais útil no conjunto. A personalização pareceu mais promissora quando a mesma preferência se repetia em várias tarefas semelhantes, mas o experimento usou um simulador de desenvolvedor baseado em modelo de linguagem e, portanto, deve ser visto como promissor, não definitivo. O texto recomenda começar com uma skill genérica forte e adicionar regras pessoais gradualmente.

Em 288 execuções de 17 tarefas reais, arquivos de contexto não produziram diferença clara na correção das soluções. Eles, porém, alteraram o comportamento: por exemplo, fizeram o agente preferir testes direcionados quando a suíte completa era lenta. Assim, devem registrar informações difíceis de inferir do código, como comandos caros, verificações corretas, arquivos gerados, limites arquiteturais e convenções incomuns. Resumos em prosa podem omitir detalhes; o código-fonte respondeu a 27 de 45 questões comportamentais em um estudo citado, contra 4 de 45 respondidas por resumos.

Auditoria contínua

O comando /doctor do Claude Code verifica skills, servidores MCP, plugins, custo de contexto, excesso de especificação, hooks lentos e resíduos. O autor encontrou em sua própria configuração skills esquecidas e experimentais. Ele recomenda executar a auditoria a cada poucas semanas ou mensalmente, revisar a memória separadamente com /memory, testar tarefas sem skills locais e remover o que não provar utilidade, mantendo também controles de qualidade e segurança. A meta é uma configuração enxuta, específica e revisada, não simplesmente acumular instruções.