# Mapa de reescrita do CLAUDE.md · auditoria e ablação Documento autossuficiente. Cole este arquivo inteiro no Claude Code, dentro do repositório que você quer auditar. As instruções abaixo são imperativas e escritas para o Claude executar. ## Contrato desta tarefa Você é o auditor do CLAUDE.md do dono deste repositório. Seu produto final é um relatório de classificação e uma proposta de arquivo enxuto, não uma edição. A regra dura que governa tudo: você não escreve nada no CLAUDE.md, não apaga linha e não move conteúdo antes de uma aprovação explícita do dono. Se ele não disser sim por escrito, você entrega o relatório e para. Ablação é o nome do método. Você apaga o conjunto inteiro de instruções, usa o sistema de verdade e traz de volta linha por linha só o que provar que faz falta. É o mesmo procedimento que a Anthropic descreve para o próprio system prompt do Claude Code. Antes de qualquer coisa, execute o Passo 0 e reporte o resultado: ```bash claude --version ``` Compare com o piso de versão do modelo que o dono quer usar. Na doc oficial de model-config, Opus 5 pede Claude Code 2.1.219 ou mais novo, e Fable 5 pede 2.1.170 ou mais novo. Se o CLI não alcança o modelo novo, avise o dono e recomende `claude update` antes de continuar. Apagar instrução escrita para um modelo antigo enquanto você ainda roda o modelo antigo é o pior dos dois mundos: perde a muleta e não ganha a capacidade. --- ## Requisito 1 · Backup datado, antes de qualquer coisa Execute isto primeiro, sem perguntar, porque não é destrutivo: ```bash cp CLAUDE.md "CLAUDE.md.bak.$(date +%Y%m%d-%H%M%S)" git add -A && git commit -m "checkpoint: antes da ablacao do CLAUDE.md" || true wc -l CLAUDE.md ``` Se o repositório não tiver git, o `cp` sozinho basta, e você deve dizer isso ao dono em uma linha. Registre a contagem de linhas como o valor "antes". Confirme que o arquivo de backup existe em disco antes de prosseguir. Nunca siga para o requisito 2 sem o backup confirmado. Se existir também um CLAUDE.md de usuário em `~/.claude/CLAUDE.md`, faça backup dele igual e conte as linhas separadamente. Os dois carregam juntos em toda sessão, e conteúdo repetido entre eles é cobrado duas vezes. --- ## Requisito 2 · Ler e classificar cada bloco, entregando tabela Leia o arquivo inteiro. Fatie em blocos lógicos, por heading quando houver, por assunto quando não houver. Classifique cada linha, sem sobra, em uma das quatro categorias: | Rótulo | Categoria | O que fazer | |---|---|---| | **a** | Atemporal: preferência, identidade, processo de negócio, segurança, credencial, caminho | Fica | | **b** | Correção de comportamento de modelo antigo | Candidata a remoção, testar | | **c** | Redundante ou realocável: repetida, virou skill, mecânica de hook, narrativa histórica | Cortar ou mover | | **d** | Desatualizada ou factualmente errada | Cortar já, sem teste | Formato de saída obrigatório, uma tabela markdown com estas colunas: ``` | Linhas | Qtd | Cat | Bloco | Por que | ``` **Assert de cobertura.** A soma dos intervalos tem que dar exatamente o total de linhas do arquivo, sem buraco e sem sobreposição. Confira isso e declare o resultado em uma linha: "cobertura N de N, sem buraco e sem sobreposição". Se não fechar, corrija a tabela antes de continuar. Feche com a contagem por categoria, em linhas e em percentual, mais o total cortável, que é a soma de b, c e d. **Instrução de rigor que evita o erro mais comum.** Para classificar algo como (d), verifique o fato de fora, não presuma. Se o arquivo afirma que um timer roda a cada 5 minutos, rode `systemctl cat`. Se afirma que um script está agendado, rode `crontab -l`. Se lista skills instaladas, conte os diretórios. Se cita um caminho, confira com `ls`. Cada item (d) sai com a prova ao lado, na coluna "Por que". Sem prova, o item volta para (c). Comandos úteis de verificação, adapte ao ambiente: ```bash systemctl list-timers --all systemctl cat .timer crontab -l ls ~/.claude/skills/ .claude/skills/ 2>/dev/null | wc -l ``` Expectativa realista, para você não achar que errou: em arquivo maduro, a fatia dominante costuma ser (c), redundância, não (b). Regra dita quatro vezes, procedimento que já virou skill, mecânica de hook escrita em prosa e narrativa histórica de por que a regra nasceu somam mais do que instrução para modelo velho. O modelo novo é o gatilho da faxina, não a causa da sujeira. --- ## Requisito 3 · Rodar a ablação Duas partes, nesta ordem. **Parte 1, a versão enxuta.** Proponha o arquivo novo contendo só o que ficou em (a), mais o que de (c) sobreviver reescrito em forma curta. Teto explícito: 200 linhas, que é o limite recomendado na doc oficial de memory. Se não couber, corte mais, não aumente o teto. **Parte 2, o teste sem as regras candidatas.** Ensine o dono a rodar sem nada, com os comandos reais: ```bash claude --bare # modo mínimo: sem CLAUDE.md, sem hooks, sem auto memory. Seta CLAUDE_CODE_SIMPLE=1 claude --safe-mode # sem nenhuma customização: skills, plugins, MCP, comandos, agentes, output styles CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 claude # mantém o resto, desliga só a memória ``` Deixe explícita a nota que derruba a barreira psicológica: não é preciso deletar arquivo nenhum para o primeiro teste. As flags desligam o carregamento sem tocar no disco. Depois vem o passo que quase todo mundo pula, e sem ele o resto não vale nada: use de verdade. Uma semana normal de trabalho, no próprio repositório, com as próprias tarefas. Não tente adivinhar de qual instrução vai sentir falta, porque a previsão erra. Crie o arquivo de anotação fora do CLAUDE.md, para ele não voltar a inflar o contexto: ``` # tropecos.md 2026-07-29 commitou sem rodar teste 2026-07-30 usou npm em vez de pnpm 2026-07-31 commitou sem rodar teste (2a vez, sessao diferente) ``` Uma linha por ocorrência, com data. Enquanto não estiver escrito, a memória infla o problema: erro que irritou uma vez parece sistêmico e não é. --- ## Requisito 4 · Critério de devolução Aplique como teste binário, para não virar julgamento subjetivo. **Não devolve a regra** quando: aconteceu uma vez só; o prompt do dono estava ambíguo; o contexto já estava cheio, e nesse caso a causa é outra e o certo é `/clear`; ele corrigiu no chat e o modelo acertou o resto da sessão; incomodou mas não estragou nada. **Devolve a regra** quando: o mesmo tropeço apareceu duas ou mais vezes em sessões diferentes, e nas duas o prompt estava razoável. Deixe esta frase visível para o dono: duas vezes na mesma sessão não conta, isso é contexto poluído. E lembre o custo: a instrução devolvida vai ser lida em toda sessão futura, para sempre. Cada linha que volta é um imposto permanente. ### Onde devolver a regra que passou no critério Antes de escrever a linha de volta no CLAUDE.md, faça três perguntas nesta ordem. Só o que sobrar das três volta para o arquivo. 1. **Precisa acontecer sempre, sem exceção?** Então não é texto, é **hook**. Instrução em CLAUDE.md é advisory; hook é determinístico e dirigido a evento. "Rode lint antes de commitar" é hook. 2. **É procedimento de vários passos, ou só vale às vezes?** Então é **skill**. O corpo da skill só carrega quando ela é usada, então material longo de referência custa quase nada até ser necessário. 3. **Só vale em parte do repositório?** Então é **rule com `paths:`** em `.claude/rules/`. Só entra no contexto quando o Claude toca um arquivo que casa com o glob. Sobrou fato curto que vale em toda sessão? Aí sim, CLAUDE.md. Escreva concreto e verificável: "use indentação de 2 espaços" funciona, "formate o código direito" não. Duas armadilhas que você deve apontar ao dono: - **Import `@path` não reduz contexto.** Quebrar o arquivo em imports organiza, mas os arquivos importados carregam no lançamento do mesmo jeito. O total pago continua o mesmo. - **Comentário HTML de bloco custa zero.** Comentário no formato `` é removido antes do conteúdo entrar no contexto. Nota histórica, data e o motivo de a regra existir devem virar comentário em vez de sumir. E escreva no formato da geração nova, com três partes em vez de uma escada de passos: | Jeito antigo, superespecificado | Jeito novo | |---|---| | "Leia o arquivo. Depois liste as funções. Depois escreva o teste. Depois rode. Depois corrija." | "Cubra `auth.ts` com teste. Não mexa em código de produção. Pronto quando `npm test` passar limpo." | Descreva a tarefa, descreva os guardrails, descreva o critério de saída. Deixe o modelo escolher o caminho. --- ## Requisito 5 · O que NUNCA apagar (lista fechada) Você não pode propor corte de nada que caia nas seis categorias abaixo, mesmo que pareça redundante. O critério que une todas: o modelo não tem como descobrir isso sozinho, por mais inteligente que fique. Inteligência não substitui informação que só existe dentro da operação do dono. 1. **Segurança e limites de dano.** Quem pode mandar instrução, o que exige aprovação humana, o que nunca sai do servidor, o que é irreversível, política anti-jailbreak. 2. **Credencial e caminho.** Onde vive o cofre, como se lê um segredo, IP, porta, nome de banco, caminho de script. É informação, não comportamento. 3. **Preferência declarada do dono.** Tom de voz, marca, fonte, paleta, o que ele odeia ver. É gosto, e gosto não se infere. 4. **Processo de negócio.** Fluxos, papéis, quem faz o quê, quando um lead muda de estágio. O modelo pode executar melhor, não pode inventar qual é. 5. **Contrato de qualidade e definição de pronto.** Níveis de evidência, o que precisa de prova antes de ser declarado concluído, o que exige revisão humana. Aqui mora a distinção mais fina desta auditoria: tirar o lembrete "rode o teste" é razoável, porque isso corrigia defeito do modelo. Tirar "só diga concluído com prova" não é, porque isso é contrato com o cliente. 6. **Fato local não inferível.** Nome de serviço interno, particularidade do ambiente, pegadinha conhecida, decisão arquitetural com razão histórica. **Regra de bolso, para aplicar em caso de dúvida:** se a instrução existe porque o modelo errava, é candidata a apagar. Se existe porque o mundo é assim, fica. --- ## Requisito 6 · Como medir antes e depois Quatro medidas, todas baratas. Entregue como tabela de antes, depois e delta, e diga explicitamente quais números foram medidos e quais foram estimados. - **Linhas.** `wc -l CLAUDE.md` contra o valor "antes" do requisito 1. Meta: abaixo de 200. - **Tokens.** Rode `/context` dentro da sessão. Ele mostra o bloco de arquivos de memória e o custo de cada parte. Se você usar um tokenizador externo para estimar, diga que é aproximação. - **Tropeços por semana.** A contagem do `tropecos.md`. Se caiu ou ficou igual com metade do arquivo, o corte foi lucro puro. - **Adesão.** Escolha as 3 regras que mais importam para o dono e confira se o modelo obedece mais com o arquivo menor. É o teste que prova na própria máquina o que a doc oficial afirma: arquivo inchado faz o Claude ignorar a instrução que importa. Existe um diagnóstico invertido que vale ouro e que você deve reportar se encontrar: se o dono tem uma regra escrita contra um comportamento e o modelo insiste em fazer, o arquivo provavelmente está longo demais e a regra está se perdendo no ruído. O reflexo de reescrever a regra em maiúsculas é o errado. O certo é encurtar o arquivo. --- ## Requisito 7 · Relatório e pedido de aprovação Este é o portão. Instrução literal para você: > Não escreva no CLAUDE.md. Entregue o relatório e pare. Só aplique depois de um sim explícito. O relatório final tem cinco partes, nesta ordem: 1. A tabela de classificação completa, com o assert de cobertura declarado. 2. O que seria cortado e por quê, agrupado por categoria, com a prova ao lado de cada item (d). 3. O que seria movido e para onde, com o conteúdo já escrito e pronto para colar: o hook, o `SKILL.md`, a rule com `paths:` ou o comentário HTML. 4. A versão enxuta proposta do CLAUDE.md, inteira, dentro de um bloco de código, para o dono ler antes de existir. 5. A tabela de antes e depois do requisito 6. Termine com uma pergunta única e fechada, oferecendo três saídas: - **Aplicar tudo:** cortes, movimentações e o arquivo novo. - **Aplicar só a categoria (d):** os erros factuais comprovados, que são cortes de risco zero. - **Não aplicar nada:** ficar só com o relatório. E diga como desfazer, citando o nome exato do arquivo de backup criado no requisito 1: ```bash cp CLAUDE.md.bak. CLAUDE.md ``` Enquanto o dono não escolher, o CLAUDE.md dele continua intocado. Essa é a única forma de esta auditoria ser segura. --- ## Cadência A recomendação da fonte é rodar a cada seis meses. Na prática o gatilho melhor não é o calendário, é o lançamento de modelo: saiu modelo novo, rode a ablação. E rode também quando aparecer o sintoma descrito no requisito 6, a regra que existe e não é obedecida. --- ## Fontes Documentação oficial do Claude Code: - https://code.claude.com/docs/en/memory - https://code.claude.com/docs/en/best-practices - https://code.claude.com/docs/en/skills - https://code.claude.com/docs/en/hooks - https://code.claude.com/docs/en/model-config - https://code.claude.com/docs/en/cli-reference Anúncio do modelo: - https://www.anthropic.com/news/claude-opus-5 Fonte primária do método da ablação, Boris Cherny no Y Combinator Startup School, 27/07/2026: - https://www.youtube.com/watch?v=qyPCVqFUyDo - https://www.ycrootaccess.com/p/boris-cherny-building-claude-code Nota de honestidade: não existe lista oficial da Anthropic dizendo quais instruções ficaram desnecessárias no Opus 5. O que este mapa entrega não é essa lista, é o método de você descobrir a sua, no seu repositório, com medição própria.