O Peso Escondido da IA: Por Que Seu CLAUDE.md Está Engordando Seu Repositório
Quando a Documentação Vira um Acúmulo Sem Fim
Imagine o seguinte cenário: você inicia um novo projeto com um arquivo CLAUDE.md limpo. Algumas dicas úteis aqui, umas anotações de contexto ali, um aviso sobre aquele caso extremo esquisito no seu fluxo de autenticação. Meses depois, você abre o arquivo e ele se transformou num romance de instruções contraditórias, lembretes desatualizados e apêndices desesperados que ninguém mais entende.
Isso não acontece só com você. É um fenômeno universal.
Uma pesquisa analisou 247.694 instruções ao longo de suas vidas em 1.867 repositórios. O padrão que surgiu é perturbador: prompts de IA não crescem apenas — crescem sem limites, triplicando de tamanho ao longo da existência (+226%). Em média, esses arquivos ganham +4,9 instruções a cada commit. O arquivo nunca encolhe. Só expande.
Mas o mais fascinante: quanto mais velha uma instrução, menor a chance de ser apagada. Os dados mostram um log-hazard de -0,032 por commit, ou seja, instruções se tornam cada vez mais imortais com o tempo. Não é que ninguém queira fazer faxina — é que ninguém sabe se pode remover alguma coisa com segurança.
O Problema O(2^|D|)
Por que isso acontece? Os pesquisadores chamam de "lembrança catastrófica" — o inverso do famoso "esquecimento catastrófico" em machine learning. Mas você não precisa de um PhD para entender o motivo.
Pense no cálculo de custos: adicionar uma nova instrução é barato. Você vê um problema, escreve uma solução, segue em frente. O custo imediato é baixo e o benefício é claro.
Agora, remover uma instrução? Isso é outra história. Você precisa entender todos os lugares onde aquela instrução pode importar. Precisa raciocinar sobre interações com todas as outras. Precisa verificar que removê-la não vai quebrar algo sutil e importante. Os pesquisadores calcularam esse custo cognitivo como O(2^|D|) num prompt com |D| instruções — ou seja, cresce exponencialmente conforme o número de instruções existentes.
Então desenvolvedores fazem o que pessoas racionais fazem: param de tentar. Novas instruções são anexadas. As antigas permanecem. O arquivo cresce.
Comentários: O Herói Desconhecido
É aqui que a pesquisa fica realmente interessante. A solução não está em técnicas de prompting melhores ou modelos mais inteligentes. Está numa ferramenta que desenvolvedores usam desde o início da programação: comentários.
Os pesquisadores tiveram uma abordagem criativa — inverteram o IFEval, um benchmark padrão, criando "mundos verificáveis" onde os prompts ótimos são realmente conhecidos. Quando adicionaram comentários codificando raciocínios latentes aos prompts, o crescimento excessivo de instruções caiu de +211,3% para apenas +1,4%.
Isso é uma redução de 99,3%.
Mas o verdadeiro golpe? Esses comentários não só controlaram o crescimento — melhoraram o desempenho real de seguir instruções em até 23,1% em tarefas do mundo real. Comentários não são simplesmente sujeira organizacional. São estruturas de suporte que ajudam assistentes de IA a raciocinar sobre o contexto corretamente.
Por Que Isso Importa Agora
Estamos vivendo uma mudança fundamental no significado de "código". Os pesquisadores fazem uma pergunta provocativa: "Se inglês é o novo código, por que ainda não temos comentários?"
É um ponto justo. Por décadas, desenvolvedores entenderam que código sem comentários é dívida técnica. Comentários explicam o "porquê", não apenas o "quê". Capturam intenção, casos extremos e conhecimento institucional que não pode ser inferido da sintaxe sozinha.
Porém, na pressa de repassar cada vez mais tarefas para assistentes de codificação com IA, temos tratado instruções em linguagem natural como se fossem diferentes. Escrevemos imperativos — faça isso, não faça aquilo, lembre-se de verificar X — sem explicar nosso raciocínio.
O resultado é o que estamos vendo naqueles arquivos CLAUDE.md inflados: instruções que ninguém entende direito, que podem conflitar entre si, e que crescem sem nenhum mecanismo de racionalização.
O Caminho à Frente
Se você mantém um arquivo CLAUDE.md ou similar, aqui vai o que a pesquisa sugere:
Comente suas instruções, não apenas seu código. Explique por que uma regra existe. Documente casos extremos. Capture o raciocínio por trás das decisões.
Abrace a racionalização periódica. Não apenas anexe — reescreva. A pesquisa observa explicitamente que reescritas completas são uma das poucas coisas que param o crescimento.
Trate suas instruções de IA como documentação de onboarding. Você entregaria a um novo desenvolvedor um arquivo de 400 linhas de regras indiferenciadas? Seu assistente de IA merece a mesma clareza.
A trajetória que estamos não é sustentável. Todo novo projeto começa com boas intenções e termina num caos in manutenção. Mas a correção pode ser mais simples do que pensávamos: escreva para o humano (ou IA) que vai ler suas instruções em seis meses, não apenas para quem está respondendo sua pergunta hoje.
Comentários não são bagunça. São a arquitetura do entendimento.