Ablação: reescreva seu CLAUDE.md para o Opus 5

O CLAUDE.md do nosso projeto tinha 498 linhas e cerca de 9.692 tokens. Somado ao arquivo de usuário, dá 10.482 tokens carregados em toda sessão, antes de qualquer skill, hook, busca ou primeira mensagem do dono. A contagem saiu de um tokenizador real; como não é o tokenizador do Claude, trate como ordem de grandeza, não como número exato.

A documentação oficial de memória do Claude Code pede, textualmente, "target under 200 lines per CLAUDE.md file", e explica o motivo: arquivo mais longo consome mais contexto e reduz a adesão às instruções. Estávamos em 2,5 vezes o teto. Ninguém escreveu 498 linhas de uma vez; elas se acumularam.

Dentro dessas 498 linhas existe uma escrita nossa que diz para economizar contexto no boot. O arquivo que prega economia é o maior gasto fixo do sistema. Isso não é piada interna: é o padrão de falha mais comum, porque a regra sobre contexto é a que menos alguém pensa em revisar.

Nada aqui é opinião. Toda afirmação vem marcada como medida por nós, declaração do fabricante ou não testada. O caso auditado é o nosso, com o arquivo real, e o número final aparece no bloco 8. Se você quiser conferir, os comandos estão na aula e o mapa no fim faz a auditoria na sua máquina.

Na conversa da Y Combinator Startup School em 27/07/2026, Boris Cherny, criador do Claude Code, afirma que apagaram mais de 80% do system prompt do produto no lançamento do Opus 5 (por volta de 03:13 do vídeo); que boa parte do que estava lá corrigia comportamentos que o modelo deveria saber e não sabia, e que agora o modelo simplesmente faz (04:20); e que existe um modo mínimo, usado internamente como ablação, em que o system prompt inteiro sai. Sobre esse modo ele diz que "the model is actually a little bit more intelligent without these prompts" (04:44). As três são declaração do fabricante: não temos acesso ao system prompt interno deles para auditar.

Ele mesmo relativiza em seguida (por volta de 05:11): quando o Claude Code é usado como produto, alguns desses prompts são desejáveis, porque fazem o produto se comportar do jeito que uma pessoa espera. A leitura correta é dupla. Prompt mínimo maximiza inteligência bruta; prompt de produto maximiza previsibilidade. Nem sempre você quer o primeiro.

Ainda como declaração do fabricante: que o modelo roda por períodos longos sem parar, dispensando andaime (01:27); que a combinação de alinhamento, classificador de injeção de prompt em todo o tráfego e classificador do modo automático deixou a injeção de prompt indemonstrável para eles (02:29 a 03:13); e o caso do runtime Bun reescrito de Zig para Rust, um prompt com condução humana, onze dias rodando, hoje em produção (17:09 a 18:09).

Procuramos e não existe lista oficial da Anthropic dizendo quais instruções ficaram desnecessárias. Lemos o anúncio do Opus 5 e ele fala de julgamento, verificação e trabalho longo, mas não menciona adesão a instruções, resistência a injeção de prompt nem "precisar de menos instrução". Portanto o que esta aula entrega não é a lista deles. É o método de você descobrir a sua, no seu repositório, com medição própria. É menos confortável e muito mais útil.

Cada geração de modelo é bastante diferente da anterior. O que você escreveu para um modelo três meses atrás pode simplesmente não se traduzir para o próximo, e é por isso que o harness do Claude Code muda tanto a cada lançamento, com prompt e ferramentas sendo apagados e reescritos (por volta de 03:37 a 04:20). Instrução escrita para remendar defeito é remendo: quando o furo fecha, o remendo continua colado, cobrando espaço.

A doc oficial de memória é direta nesse ponto: o conteúdo é tratado como contexto e não como configuração imposta, e é entregue como mensagem de usuário depois do system prompt. Consequência prática: instrução escrita ali não tem garantia de cumprimento. Para bloquear uma ação independentemente do que o modelo decidir, a saída indicada é hook, não texto.

A mesma doc avisa que, quando duas regras se contradizem, o modelo pode escolher uma arbitrariamente. Arquivo que cresceu por acúmulo quase sempre tem contradição escondida, porque a regra nova foi escrita sem ninguém reler a antiga. Revisar periodicamente para remover instrução desatualizada ou conflitante é recomendação oficial, não preferência nossa.

Se o modelo insiste em fazer algo que você proibiu por escrito, o reflexo é reescrever a regra em maiúsculas. A doc de boas práticas diz o contrário: nesse caso o arquivo provavelmente está longo demais e a regra está se perdendo no ruído. O remédio é encurtar o arquivo, não gritar mais alto.

A recomendação de apagar tudo a cada seis meses veio com uma condicional na frente, endereçada a quem usa o Claude Code, e não a quem constrói produto agêntico em cima da API (06:37 a 07:03). O método é o mesmo para os dois; a cadência e a rede de proteção não são. Quem usa apaga o arquivo e no pior caso perde uma tarde. Quem constrói produto apaga o system prompt e pode quebrar comportamento em produção para clientes reais, então ali a ablação vai atrás de eval e chave de funcionalidade.

É comum ouvir que o modo mínimo só existe como variável de ambiente obscura e não documentada. Fomos conferir no binário instalado nesta máquina: a string do modo simples aparece 19 vezes, e o próprio texto de ajuda declara que --bare seta essa variável e pula hooks, LSP, sincronia de plugin, auto memória e a descoberta automática de CLAUDE.md. Ou seja, existe porta oficial e documentada. Não testado aqui em runtime: a prova que temos é estática, do binário e do help, porque o token do CLI deste servidor estava expirado no dia da apuração.

A doc de boas práticas resume a ablação inteira em uma pergunta por linha do arquivo: "Would removing this cause Claude to make mistakes? If not, cut it." Se a resposta for não, corte. E ela nomeia o modo de falha oposto, o arquivo superespecificado, onde o modelo ignora metade porque a regra importante se perdeu no ruído.

Existe um consolo comum, o de que o prompt é descartável mas o eval é eterno. Na mesma conversa, perguntado sobre o que permanece estável entre modelos, ele responde que o eval sobrevive ao harness um pouco, mas não muito: talvez uma, duas ou três gerações de modelo, e depois satura e é jogado fora (09:25 a 10:12). Se nem o eval dura, a ideia de escrever o arquivo de instruções uma vez e nunca mais revisar não se sustenta. A ablação vira manutenção periódica, não faxina única.

O erro mais comum que ele diz ver é a pessoa dar instrução específica demais: faça isso, mas faça deste jeito, e deste, e deste, primeiro 1, depois 2, depois 3, depois 4 (14:50 a 15:11). Para modelos modernos esse não é o caminho. E ele aponta de onde vem o hábito: engenheiro com muitos anos de carreira tende a tentar fazer o modelo executar a tarefa exatamente do jeito que ele mesmo faria (23:58 a 24:24).

O formato que ele prescreve tem exatamente três partes: descreva a tarefa, descreva os guardrails, descreva o critério de saída. Depois disso, deixe o modelo trabalhar e volte depois. A doc de configuração de modelo diz o mesmo com outras palavras, ao orientar que se entregue o resultado desejado em vez do caminho, e que se dê problema ambíguo, do tipo investigação de causa raiz e decisão de arquitetura.

A mesma página é explícita ao dizer que os lembretes de verificação podem ser pulados, porque o modelo confere o próprio trabalho com menos incentivo e esses lembretes costumam ser desnecessários. É raro a documentação de um fabricante mandar você apagar um tipo específico de regra. Aproveite: no seu arquivo, procure todo "não esqueça de testar", "confira antes de dizer que acabou" e "rode o lint depois". Esses são os primeiros candidatos.

Muita gente divide o arquivo grande em vários pedaços com import por caminho e acha que resolveu. A doc avisa que isso ajuda a organizar mas não reduz contexto, porque os arquivos importados carregam no lançamento do mesmo jeito. O total pago continua idêntico, agora espalhado.

Comentário de bloco em HTML dentro do CLAUDE.md é removido antes de o conteúdo entrar no contexto. Isso resolve o dilema de perder a memória do porquê: a nota de manutenção, a data e a razão histórica de a regra existir viram comentário e param de custar token, sem sumir do arquivo para quem for ler amanhã.

Vale saber onde cada arquivo entra, porque tudo é concatenado e nada é sobrescrito: política gerenciada da máquina, depois o arquivo de usuário em ~/.claude/CLAUDE.md, depois o do projeto, depois o local do projeto. Arquivos em diretórios acima do diretório atual carregam inteiros no boot; os que estão em subdiretórios carregam sob demanda, quando o Claude lê algo lá dentro. Conteúdo repetido entre o de usuário e o de projeto é pago duas vezes, em toda sessão.

A memória automática grava notas do próprio Claude por projeto, com um índice, e vem ligada por padrão. Parte do que as pessoas ainda escrevem à mão ("lembra que o build é assim", "o teste precisa do Redis local") o produto já registra sozinho. Uma pegadinha vale o aviso: só o começo do índice carrega por sessão, então índice inchado perde memória em silêncio. No nosso servidor o índice estava em 54,4KB contra um limite de 24,4KB, com aviso explícito de que só parte foi carregada. Medido aqui.

Tirar o lembrete "rode o teste" é razoável, porque isso corrigia um defeito do modelo, e a própria doc do modelo novo diz que esses lembretes ficaram desnecessários. Tirar "só diga concluído com prova" não é, porque isso nunca foi correção de defeito: é contrato com o cliente. Os dois parecem a mesma família de regra e não são. Um é remendo técnico, o outro é padrão de aceitação, e padrão de aceitação continua sendo seu.

Se a instrução existe porque o modelo errava, é candidata a apagar. Se existe porque o mundo é assim, fica. Essa frase resolve a maioria dos casos duvidosos sem precisar de julgamento.

A maior fatia isolada não é instrução escrita para modelo velho, que deu 13,1%. É redundância pura, com 32,3%, duas vezes e meia maior. Isso muda a leitura do conselho: o modelo novo é o gatilho da faxina, não a causa da sujeira. A sujeira veio de acúmulo, e estaria lá mesmo que nenhum modelo tivesse sido lançado. Quem corta só o que é "para modelo antigo" deixa dois terços do problema intacto.

Um único bloco, o de scripts e tarefas agendadas, com 30 linhas, concentrava seis erros verificados um a um no sistema:

• Um timer documentado como se fosse nosso, com o nome de um recurso interno, sendo o timer padrão do Ubuntu. Conferido com o comando que mostra a unidade e com a consulta ao pacote que a instalou.
• Um timer documentado como rodando a cada 5 minutos, quando o real é a cada 30. Seis vezes mais lento do que o arquivo afirmava.
• Um terceiro timer listado como ativo estando desabilitado. Não roda desde sabe-se lá quando.
• Dois scripts listados como agendados que não estão no agendador. Um deles foi substituído por outro script, que o arquivo não menciona.
• Um agendamento apontando para um caminho de arquivo que não existe em disco. É uma falha silenciosa diária, e o arquivo ainda reforçava o caminho errado.
• De brinde, o agendador real tinha por volta de 26 entradas e o arquivo documentava 5, ignorando famílias inteiras de timers ativos.

Outro bloco listava as skills instaladas: quatro. O real eram 136, somando as duas pastas. O arquivo descrevia 2,9% da capacidade instalada, e isso é pior do que omitir: entregar ao modelo uma lista fechada e falsa desencoraja ativamente o uso das outras 132. Instrução velha não fica só inofensiva; ela passa a mentir.

Nada disso virou lixo. O contrato de verificação era duplicata exata do arquivo de usuário, e ficou só lá, deixando de ser pago duas vezes. A mecânica do watchdog e do hook virou comentário HTML, custo zero. As specs de carrossel já existiam como skill. O bloco de estilo e design virou rule com escopo. A tabela de agendamento virou dois comandos, que é uma fonte de verdade que não mente. E a lista de skills saiu, porque o produto lista sozinho.

O arquivo de projeto saiu de 498 para 108 linhas, uma queda de 78,3%. Em tokens, de 9.692 para 1.832, queda de 81,1%. O total carregado por sessão, somando o arquivo de usuário, caiu de 10.482 para 2.622, queda de 75%. E o arquivo passou a caber com folga dentro do teto oficial de 200 linhas. Medido aqui, com o mesmo tokenizador nas duas pontas.

A nossa poda deu 81,1%. A Anthropic afirma ter cortado mais de 80% do system prompt do Claude Code no mesmo período. Arquivos completamente diferentes, mesmo método, praticamente o mesmo número. Não é mágica: é a proporção típica entre o que você escreveu porque precisava e o que ficou porque ninguém revisou.