🩺 Auditar de verdade

A skill lê seu CLAUDE.md (projeto e global), suas skills, seus hooks e o settings.json, classifica cada instrução e propõe uma versão mínima. Ela nunca edita, move, apaga, sobrescreve config nem commita.

Porque a fronteira é o que torna a auditoria confiável. Ferramenta que já sai mexendo você não deixa rodar no global — e aí nunca audita nada. Sabendo que é só leitura, dá para rodar sem medo, inclusive antes de ter git na config.

Diagnóstico ≠ tratamento. Aplicar é um pedido separado, de propósito. E não confunda com memory-audit: aquela cuida da memória guardada da sessão, esta cuida da configuração do agente.

São dois destinos possíveis: ~/.claude/skills/audit-ablacao/SKILL.md, que vale para todos os projetos, ou .claude/skills/audit-ablacao/SKILL.md dentro do repositório, que vale só ali. Em ambos os casos é um cp do SKILL.md e um reinício da sessão para o Claude Code carregar.

A escolha do destino já é uma decisão de arquitetura de config. Skill dentro do projeto versiona junto com o código, entra no PR, é revisável e não vaza para os outros projetos. Skill global fica disponível em qualquer sessão, mas custa um slot na lista de skills que todo projeto vê.

A raiz do repositório já contém o SKILL.md instalável — é o motivo de o guia ficar em guia/ e não na raiz. Se a skill não aparecer, quase sempre falta reiniciar a sessão.

Três escopos com gatilhos distintos. Global (~/.claude/): a cada ~6 meses ou em lançamento grande de modelo. Um projeto: quando o CLAUDE.md dele passa de ~150 linhas. Um conjunto de skills: quando 3 ou mais brigam pelo mesmo gatilho.

Escopo grande demais produz relatório que você não consegue aplicar; escopo pequeno demais esconde a redundância, que quase sempre está entre o global e o projeto. Auditar tudo de uma vez é a forma mais comum de não cortar nada.

Os gatilhos são sinais mensuráveis, não sensação: número de linhas, número de skills em conflito, lançamento de modelo. Sinal objetivo é o que impede a auditoria de virar tarefa que nunca chega.

Resumo executivo, métricas, problemas por arquivo, candidatas à remoção, redundâncias e conflitos, skills, CLAUDE.md mínimo proposto, skills propostas, plano de teste de ablação (versões A/B/C) e Top 10 mudanças por impacto ÷ risco.

Cada seção cobra uma coisa diferente de você. Métricas e problemas por arquivo são leitura; candidatas à remoção e conflitos exigem veredito seu; o CLAUDE.md mínimo é proposta, não sentença; o Top 10 é a única seção que vira plano de trabalho imediato.

Impacto ÷ risco ordena o Top 10 porque o objetivo não é reduzir o máximo, e sim maximizar qualidade + autonomia + verificabilidade ÷ complexidade. Corte de alto impacto e alto risco entra depois, com teste.

Cada skill recebe um de sete vereditos: KEEP, SIMPLIFY, MERGE, SPLIT, LOAD-ON-DEMAND, CONVERT-TO-CONTEXT ou DELETE-CANDIDATE. É um eixo separado do veredito por linha do CLAUDE.md.

Skill tem fronteira, nome e escopo — é fácil de auditar e de aposentar, ao contrário de "aquele parágrafo do meio do CLAUDE.md". Por isso a skill é a unidade certa de conserto: dá para desativar uma e medir o efeito.

MERGE resolve skills que brigam pelo mesmo gatilho; SPLIT resolve skill que faz coisas demais; CONVERT-TO-CONTEXT é para o que era informação disfarçada de procedimento; LOAD-ON-DEMAND tira o custo de contexto das execuções que não usam aquilo.

Rodar /audit-ablacao no escopo escolhido, pegar as três primeiras candidatas à remoção, abrir o arquivo citado, conferir o trecho no lugar e dar veredito próprio: concordo, discordo, ou mando para TEST.

É o hábito que separa auditoria de fé cega. Conferir o trecho no arquivo original pega os dois erros mais comuns do relatório: citação fora de contexto e linha que parece redundante mas guarda um detalhe que só existe ali.

Na dúvida, TEST — nunca REMOVE. E a auditoria preserva de propósito o que o modelo não consegue inferir: identidade do projeto, caminhos e fontes de verdade, branding, segurança, compliance, integrações e contratos de interface.

O relatório sai numa sessão; os cortes entram em outra. Antes de aplicar qualquer coisa, a config precisa estar sob controle de versão — commit limpo antes, commit do corte depois, para que reverter seja um comando e não uma arqueologia.

Aplicar na mesma sessão que auditou contamina o julgamento: o modelo já está com o relatório inteiro no contexto e tende a defender as próprias conclusões. Sessão nova lê a config como ela está, não como o relatório disse que estava.

Reversibilidade é pré-condição de coragem. Com git na config, um corte agressivo custa um git revert; sem git, custa lembrar o que estava escrito — e ninguém lembra.

Primeiro as redundâncias e os conflitos — a mesma regra em três lugares, duas regras que se contradizem. Depois o microgerenciamento e o legado datado. Por último o que ficou marcado como TEST, que só sai depois de medição.

Redundância e conflito são os cortes de maior impacto e menor risco: apagar a cópia não muda o comportamento, porque a regra continua existindo em um lugar. Começar por eles dá redução real sem arriscar nada — e limpa o terreno para julgar o resto.

Conflito é pior que redundância: com duas regras contraditórias, o modelo escolhe uma e você não sabe qual. Resolver conflito é decisão sua sobre qual regra vale, não corte automático.

Regra que vive no CLAUDE.md é lida em toda execução, inclusive nas 90% que não têm nada a ver com ela. A mesma regra dentro de uma skill só custa contexto quando a tarefa é aquela. Isso é exatamente o MOVE e o LOAD-ON-DEMAND do relatório.

É a forma mais barata de emagrecer a config sem perder nada — nenhuma instrução é descartada, ela só muda de lugar. Para quem tem medo de apagar, mover é o corte que dá para fazer no primeiro dia.

O critério de partição: o CLAUDE.md fica só com o que é verdade sempre — identidade, guardrails, fontes de verdade, segurança. Todo o resto (procedimento, formato, receita, integração) vira skill.

Invocar por /nome-da-skill em vez de torcer para a descrição casar com a sua frase. Quando várias skills competem pelo mesmo assunto, a invocação explícita é o desempate.

Isso mata uma categoria inteira de linha inchada: a regra de roteamento no CLAUDE.md ("quando o usuário pedir X, use a skill Y"). Se você chama direto, a regra de roteamento não precisa existir — e ela era lida em toda execução.

Gatilho por descrição é probabilístico; invocação explícita é determinística. Trocar um pelo outro reduz contexto e aumenta previsibilidade ao mesmo tempo — raro ganhar nas duas pontas.

Quando o modelo tropeça, há três remédios. Prompt melhor: a instrução estava obscura. Skill: falta um procedimento repetível. MCP: falta contexto que ele não alcança sozinho.

Escolher errado engorda o CLAUDE.md. O reflexo mais comum é despejar mais uma regra global para um problema que era falta de ferramenta ou falta de procedimento — e a regra fica lá para sempre, sendo relida em toda execução.

O diagnóstico vem da falha observada, não do palpite: se o modelo não sabia de algo, é contexto/MCP; se sabia mas fez fora de ordem, é procedimento/skill; se entendeu errado o pedido, é prompt.

O exercício de fechamento da trilha: tirar três itens do Top 10, aplicar numa sessão separada e registrar o antes/depois em dois números — linhas do CLAUDE.md e quantidade de regras — mais uma frase sobre o comportamento observado.

Sem registro, você não sabe se a config emagreceu ou se você só reorganizou. E o critério de sucesso não é a redução: é comportamento inalterado com menos linhas. Se algo quebrou, o corte errado é identificável porque foram só três.

Três de cada vez é lote pequeno de propósito — é o que mantém a causa identificável. Depois vem o uso em trabalho real por alguns dias, que é onde a Trilha 4 pega o assunto com o plano A/B/C.