AIDive

Pack de vídeo

Apague seu CLAUDE.md, medido: tabelas de ablação, checklist e fontes

11 min de leitura

TL;DR

  • Num repositório real com um CLAUDE.md de 177 linhas, 3 skills e 1 hook, apagar tudo quebrou exatamente uma regra, em uma única situação: a regra de i18n num arquivo novo em folha. Todas as outras convenções se mantiveram porque o código ao redor já as ensinava.
  • O arquivo custou de 4 a 14% dos tokens lidos nas tarefas em que o resultado foi idêntico, cerca de um dólar a cada dez. Os 32% de economia que se cita são dominados pela única tarefa em que o arquivo fez o modelo trabalhar mais.
  • Skills e hook não custam nada mensurável: skills carregam só quando invocados e nenhum foi invocado, o hook injeta uma única frase.
  • A visão geral de arquitetura de 82 linhas não rendeu nada na pergunta de arquitetura: seis respostas, todas corretas, com ou sem o arquivo.
  • «Apagar», nas palavras da própria Anthropic, significa ablacionar e passar para a divulgação progressiva, não eliminar. Mantenha as regras que o código não consegue ensinar, mova o resto para arquivos de regras e skills, e transforme as inegociáveis em hooks.
  • Duas repetições por configuração são um piso, não um veredito: diferenças por tarefa abaixo de 15% estão dentro do ruído entre execuções.

O que as medições dizem

A palestra que todo mundo comenta diz duas coisas, e a segunda se perde. Boris Cherny confirma no palco que o Claude Code apagou 80% do seu prompt de sistema, e descreve o método: apagar o prompt de sistema inteiro e depois trazê-lo de volta linha por linha para medir o impacto de cada uma s2. A passagem do «every 6 months» fica entre 00:06:58 e 00:07:05, e a formulação é «really do recommend», não «strongly recommend» s1. Duas frases muito atribuídas a ele não estão na palestra: «context, goals and a definition of done» (a mais próxima de real, aos 15:22, é «describe the task, the guardrails, the exit criteria») e «64 agents». Ele diz «eleven days» e, quando perguntam quantos agentes, «I'm not sure» s2. O número 64 vem do post sobre a reescrita do Bun: «64 Claudes running for 11 days», cerca de $165,000 no preço da API, 9 billion de tokens de entrada sem cache, 690 million de tokens de saída e 72 billion de leituras de tokens de entrada em cache s14.

O que torna tudo isso mensurável é o carregamento. CLAUDE.md e arquivos de regras são injetados a cada turno; skills só carregam quando invocados. A documentação de memória também traz a orientação de tamanho que todo mundo parafraseia: «target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.» s4. A versão escrita do conselho da Anthropic trata o CLAUDE.md como repositório central como um mito e aponta para a divulgação progressiva e a memória automática s3.

O único estudo controlado antes do nosso é o artigo da ETH sobre AGENTS.md: 138 issues em 12 repositórios, e «providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average». Arquivos escritos por desenvolvedores superam os gerados por LLM em 7% na média, e instruções que nomeiam ferramentas específicas ajudam s5.

Dois dados sobre o que esses arquivos contêm e como são lidos. Em 28,721 repositórios e 165,063 arquivos, o arquivo de instruções mediano tem 50 itens de conteúdo, dos quais 12 são diretivas de verdade; o autor resume que só 27% do arquivo faz o que você pensa s8. Num experimento controlado com duas instruções em conflito real, mover uma única regra do topo do arquivo para o fim muda em cerca de 90 pontos a frequência com que o modelo a obedece, de quase nunca a quase sempre s9. O mesmo editor traça a linha que o nosso experimento segue: ablação não é apagar, e hooks são aplicação forçada de regra, não expiram com uma troca de modelo s7.

Dois dados informais bateram com o nosso resultado. Um CLAUDE.md de 1,000 linhas comparado a uma versão enxuta de ~20 linhas nas mesmas issues do GitHub com o mesmo modelo: a arquitetura se manteve, as regras da casa quebraram s6. Um comentarista que moveu tudo para divulgação progressiva relata o contexto carregado automaticamente caindo de ~35k para ~4.5k tokens por sessão, sem nenhum conhecimento apagado s11. Para pontuar ablações de skills existe uma ferramenta: o --ablate do caliper cobre skills e servidores MCP e seu compare reporta taxa de sucesso, tokens e tempo real; a troca do CLAUDE.md continua manual s16.

Medições

Protocolo: um repositório privado Expo / React Native (1,021 arquivos rastreados), CLAUDE.md de 177 linhas, 7,243 caracteres, cerca de 1,800 tokens, 3 skills, 4 comandos slash, 1 hook PreToolUse. Modelo fixado em claude-opus-5 em todas as execuções, Claude Code 2.1.278, claude -p em modo headless, --max-turns 40, diretório de configuração do usuário vazio, sem MCP, clone limpo restaurado antes de cada execução. Cinco tarefas do dia a dia (componente novo, editar um componente, refatorar helpers compartilhados, persistir um campo do store, explicar um caminho de dados), ablação de uma peça por vez. 44 execuções, $38.97 no preço da API, 92 minutos de tempo de agente. Pontuação: as regras da casa do repo nas linhas adicionadas, tsc --noEmit, eslint, respostas avaliadas à mão.

Qualidade, o que quebrou:

config execuções de edição violações das regras da casa novos erros do tsc erros do eslint
A completo 8 0 0 0
B sem CLAUDE.md 8 1 (título novo escrito direto no código, sem .content.ts) 0 0
C sem skills 4 0 0 0
D sem hook 4 0 0 0
E nada 8 2 (título escrito direto no código duas vezes, sem .content.ts) 0 0

Custo por execução, média sobre as execuções da config (tokens = leituras de cache, o contexto relido a cada turno):

config execuções $ / execução turnos / execução tokens lidos / execução
A completo 10 0.95 25.6 829k
B sem CLAUDE.md 10 0.74 21.9 568k
C sem skills 5 0.96 28.2 819k
D sem hook 5 0.96 27.8 851k
E nada 10 0.85 25.7 655k

Por tarefa, de A para B (média de 2 execuções cada):

tarefa A $ B $ custo tokens lidos
T1 componente novo 1.72 0.96 -44% -61%
T2 editar componente 1.49 1.26 -15% -15%
T3 refactor 0.64 0.63 -1% -5%
T4 store 0.57 0.53 -6% -4%
T5 pergunta 0.34 0.31 -9% -14%
as 10 execuções 9.51 7.40 -22% -32%

Lendo as tabelas. Sem o CLAUDE.md, 3 de 4 execuções do componente novo escreveram o título como string simples; com ele, 4 de 4 criaram o .content.ts com EN e FR. Na tarefa de edição, todas as configs, até a E, colocaram a string nova num .content.ts: os arquivos vizinhos carregavam a convenção. Todo o resto se manteve nas 44 execuções: 0 imports relativos, type e não interface em seis edições do arquivo de tipos, design tokens em todo diff, 0 cores hexadecimais, nenhum arquivo barrel. Uma instrução que ninguém conseguiu seguir: o arquivo manda importar theme de @design-tokens, um alias que não existe no tsconfig.json; nenhuma execução, em nenhuma config, o usou, 1,800 tokens lidos à toa em toda sessão. A economia de T1 é a execução mais barata fazendo menos trabalho. A variância entre execuções é maior que a maioria dos efeitos de config: T1 com a config completa custou $2.11 e depois $1.33. Um controle com o grafo de código de 333 MB presente caiu nos números da config completa ($1.59 vs $1.72 em T1, $0.38 vs $0.34 em T5): o bloco do grafo e o hook não mudaram nada mensurável.

Faça isto na segunda-feira

  • Conte seu CLAUDE.md: linhas, caracteres e quantas linhas são diretivas de verdade (Always, Never, Use, Prefer). O resto é contexto que o modelo relê a cada turno.
  • Escolha uma convenção por seção e confira se um arquivo vizinho já a mostra. Se três arquivos da pasta seguem a regra, a linha é candidata a ser apagada.
  • Encontre a regra que o código não consegue ensinar num arquivo novo em folha (i18n, telemetria, cabeçalhos de licença, uma etapa de registro obrigatória). Mantenha-a, escreva em uma linha e coloque perto do topo.
  • Teste cada caminho de import e cada comando que seu arquivo cita. Um alias morto ou um script renomeado é uma instrução que ninguém consegue seguir.
  • Mova visões gerais de arquitetura longas e passo a passos de setup para um arquivo de regras ou um skill carregado sob demanda, e depois compare o contexto carregado automaticamente antes e depois.
  • Transforme suas duas ou três regras inegociáveis em um hook ou uma regra de lint. A aplicação forçada não depende de o modelo ler um parágrafo.
  • Rode suas duas tarefas mais comuns duas vezes com o arquivo e duas vezes sem, num modelo fixado, e leia os tokens e o diff. Duas repetições dizem onde olhar, não o que concluir.

Para ir além

  • A palestra em si, pelo método e não pela frase solta: apagar e depois trazer de volta linha por linha s2.
  • O conjunto completo de resultados do artigo, incluindo a constatação de que arquivos escritos por desenvolvedores superam os gerados em 7% e que nomear ferramentas ajuda s5.
  • A posição da regra como variável: a oscilação de ~90 pontos e como o modelo resolve em silêncio instruções em conflito s9.
  • A anatomia de um arquivo de instruções em 30k repositórios: 50 itens, 12 diretivas, e o que são os outros 38 s8.
  • O guia da HumanLayer para escrever um bom CLAUDE.md e a thread que o contesta s10.
  • A thread «MUST use agent, ignorado 80% das vezes»: um argumento a favor dos hooks onde a prosa falha s12.
  • A thread «Claude Code now ignores everything», útil para separar deriva do modelo de conflito de instruções s13.
  • caliper, para pontuar ablações de skills e MCP com taxa de sucesso, tokens e tempo real s16.

Fontes

FAQ

Devo apagar meu CLAUDE.md?

Não às cegas. No nosso repo, a única perda foi uma regra em arquivos novos; tudo que o código já demonstrava se manteve sem o arquivo. Ablacione uma seção por vez e mantenha o que muda o resultado.

Por que o arquivo economizou 32% de tokens se custou só de 4 a 14%?

Porque o agregado é dominado pela tarefa do componente novo, em que o arquivo fez o modelo escrever um segundo arquivo em dois idiomas. A execução mais barata fez menos. Nas tarefas com resultado idêntico, a economia foi de 4 a 14%.

Skills e hooks custam tokens a cada turno?

Skills só carregam quando invocados, então um skill não invocado não custa nada; o hook injeta uma única frase. Apagar os dois não mudou nenhum número nas nossas execuções. Arquivos de regras e CLAUDE.md são os que são relidos a cada turno.

Duas execuções por configuração bastam?

Não. Duas repetições localizam o efeito, não o dimensionam. Nossa config completa custou $2.11 e depois $1.33 na mesma tarefa, então diferenças por tarefa abaixo de 15% estão dentro do ruído.