🔀 Separe auditar de aplicar
A skill audit-ablacao é diagnóstico: ela lê, classifica e propõe, e nunca edita, move, apaga ou commita. Isso não é limitação, é desenho. Aplicar é um pedido separado, em outra sessão — por dois motivos. Primeiro: diagnóstico feito no mesmo fôlego da mão no teclado sai contaminado pela pressa de mexer; você começa a justificar o corte que já quer dar. Segundo: o relatório precisa continuar existindo intacto depois, para você conferir se o que foi aplicado é mesmo o que foi recomendado. Auditoria que já sai mexendo é auditoria em que você não confia.
🆕 Duas palavras antes de seguir
- Skill: uma pasta com um arquivo
SKILL.mdque ensina ao Claude Code um procedimento específico. Ela só é carregada quando a tarefa é aquela — diferente doCLAUDE.md, que é lido sempre. - Contexto: a janela de texto que o modelo está "vendo" naquela execução. Tudo que ocupa contexto — inclusive regra que não tem nada a ver com a tarefa — é espaço que sai do trabalho de verdade.
- Snapshot: uma cópia congelada do estado atual da sua config, à qual você consegue voltar com um comando. Um commit de git é o snapshot mais barato que existe.
⚠️ Nunca corte sem snapshot
Ablação só é método porque é reversível. Se você não consegue voltar em um comando ao estado anterior, você não está fazendo um experimento — está torcendo. E a primeira vez que um corte quebrar alguma coisa sem volta, você abandona o processo inteiro e nunca mais mexe na config.
Regra dura: nenhuma linha sai antes de o commit "antes" existir. Sem git, no mínimo um cp -r ~/.claude ~/.claude.bak-AAAA-MM-DD.
Colocar a config sob git é trabalho de trinta segundos e paga em toda a trilha 4, quando você for comparar as versões A, B e C. Faça isso na pasta da config global (~/.claude) ou na raiz do projeto, dependendo do escopo que você auditou.
📦 Copiar e rodar: config sob git
Objetivo: ter um ponto de retorno nomeado antes de qualquer corte.
# escopo global — a pasta de config do Claude Code cd ~/.claude git init -b main # so na primeira vez git add -A git commit -m "antes da ablacao" # escopo projeto — a config que anda com o repo # cd ~/projetos/<seu-projeto> # git add CLAUDE.md .claude/ # git commit -m "antes da ablacao"
Como verificar: rode git status. Se a saída disser nothing to commit, working tree clean, seu ponto de retorno existe. Teste a volta antes de precisar dela: git diff depois de um corte mostra exatamente o que saiu, e git checkout -- CLAUDE.md desfaz.
✓ Sessão de aplicação saudável
- ✓Sessão nova, com o relatório em
.mdaberto ao lado - ✓Commit "antes" já feito e
git statuslimpo - ✓Uma mudança por vez, com o trecho do relatório colado no pedido
- ✓O relatório permanece intocado — ele é a prova do que foi decidido
✗ Sinais de que vai dar errado
- ✗"Já que você está aqui, aplica tudo" na mesma sessão da auditoria
- ✗Config fora do git, "depois eu versiono"
- ✗Dez mudanças num commit só — se algo quebrar, você não sabe qual foi
- ✗Relatório sobrescrito pela própria sessão que aplicou os cortes
🎯 Ataque na ordem certa
A seção 10 do relatório entrega o Top 10 por impacto ÷ risco — as mudanças que devolvem mais contexto pelo menor risco de quebrar comportamento. Mas ela não é uma fila para você atacar de cima a baixo no mesmo dia. A ordem prática é por categoria de risco, em quatro ondas, e ela existe para construir confiança no processo antes de você chegar perto do que dá medo.
Onda 1 — Redundâncias e conflitos
Risco quase zero. Ganho imediato.
A mesma regra escrita em três lugares vira uma só; duas regras que se contradizem viram uma decisão. Você não está removendo comportamento — está removendo cópias. Ninguém perde nada, e a config encolhe visivelmente já no primeiro dia. Bônus: acaba o dia em que uma cópia muda e as outras não.
Onda 2 — Legado / obsoleta
Risco baixo, mas exige uma checagem.
Instruções datadas: conserto de fraqueza de um modelo que já saiu de cena, exceção com data de 2024, contorno de bug já corrigido. A checagem é simples — o motivo original ainda existe? Se você não consegue nomear o motivo, é forte indício de que ele morreu.
Onda 3 — Microgerenciamento → critério
Risco médio: você troca a forma, não remove a intenção.
O passo a passo rígido de doze etapas vira "tarefa + guardrails + critério de saída". A intenção sobrevive inteira; o que você devolve é a liberdade de o modelo achar um caminho melhor que o seu. Aqui já vale observar o comportamento por alguns dias antes de dar por boa.
Onda 4 — O que ficou em TEST
Risco desconhecido — por isso é a última.
TEST é a decisão que a skill toma quando fica em dúvida: pode ser peso morto, pode estar segurando algo. Essas não se aplicam por convicção, se aplicam por experimento — e o experimento é o plano A/B/C da trilha 4. Adiar essa onda não é covardia, é sequência.
💡 Por que começar pelo risco quase zero
A tentação é começar pelo maior corte — aquele bloco de 80 linhas que você sempre achou inútil. É o corte heroico, e ele é a armadilha clássica: uma coisa quebra, você não sabe qual das 80 linhas era necessária, reverte tudo e conclui que "a config estava certa do jeito que estava".
- •Ondas 1 e 2 te dão dias de evidência de que cortar não quebra — isso é o que compra sua confiança para as ondas 3 e 4
- •Mudanças pequenas e separadas por commit deixam o culpado óbvio quando algo muda de comportamento
- •Não estamos maximizando redução — o alvo é qualidade + autonomia + verificabilidade ÷ complexidade
| Onda | Categoria | Risco | Como confirmar que deu certo | Quando aplicar |
|---|---|---|---|---|
| 1 | Redundância / conflito | quase zero | a regra continua existindo — em um lugar só | primeira sessão |
| 2 | Legado / obsoleta | baixo | você não consegue nomear o motivo original | primeira sessão |
| 3 | Microgerenciamento → critério | médio | a saída continua passando no critério novo | depois de dias de uso real |
| 4 | TEST | desconhecido | só por experimento A/B/C | trilha 4 |
📦 Mova procedimento para skill
Este é o argumento central do módulo. Regra que vive no CLAUDE.md é lida em toda execução — inclusive nas ~90% de tarefas 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 é load-on-demand: carregar sob demanda, em vez de sempre. Mover procedimento do CLAUDE.md para uma skill é a forma mais barata de emagrecer a config sem perder nada — é exatamente o que o relatório chama de MOVE e de LOAD-ON-DEMAND.
O que olhar: o bloco roxo não sumiu — ele encolheu e o resto virou o bloco ciano, que aparece uma vez em vez de dez. Nenhuma instrução foi perdida; o que mudou foi quantas vezes você paga por ela. É por isso que MOVE costuma render mais que REMOVE nas primeiras ondas: você emagrece sem precisar decidir se alguma coisa é dispensável.
🧪 Copiar e rodar: criar a skill e recortar o bloco
Objetivo: tirar um procedimento do CLAUDE.md e colocá-lo numa skill que só carrega quando é chamada.
# 1. criar a pasta da skill (global; use .claude/skills/ para so o projeto) mkdir -p ~/.claude/skills/<nome-da-skill> # 2. escrever o SKILL.md — o frontmatter e o bloco YAML entre --- no topo, # que da nome e descricao a skill (e o que o Claude Code le pra saber que ela existe) cat > ~/.claude/skills/<nome-da-skill>/SKILL.md <<'EOF' --- name: <nome-da-skill> description: <quando usar, em uma frase, com as palavras que voce realmente usa> --- # <Nome da skill> <cole aqui o bloco procedimental que estava no CLAUDE.md, sem mudar nada> EOF # 3. remover o bloco do CLAUDE.md (agora ele vive na skill) # edite o arquivo e apague as linhas movidas — deixe UM ponteiro curto se precisar: # "Procedimento de <assunto>: /<nome-da-skill>" # 4. registrar o antes/depois wc -l ~/.claude/CLAUDE.md git -C ~/.claude add -A && git -C ~/.claude commit -m "move: <assunto> do CLAUDE.md para skill"
Como verificar: reinicie a sessão, chame /<nome-da-skill> e confirme que o procedimento responde igual ao que respondia antes. Depois rode uma tarefa que não é aquela e confirme que o comportamento também não mudou — é isso que prova que você moveu, e não perdeu.
Cuidado com o ponteiro: se o "ponteiro curto" no CLAUDE.md começar a crescer e reexplicar o procedimento, você recriou o problema. Uma linha, no máximo — ou nenhuma, se você pretende invocar direto (tópico 4).
✓ Fica no CLAUDE.md — verdade SEMPRE
- ✓Identidade — o que é este projeto, quem é o público, qual o domínio
- ✓Guardrails — o que nunca fazer, limites que valem em qualquer tarefa
- ✓Fontes de verdade — onde moram as chaves, os dados, o arquivo canônico
- ✓Segurança e compliance — o que não pode vazar, o que não pode ser publicado
- ✓Convenções internas que o modelo não tem como inferir sozinho
✗ Sai do CLAUDE.md — vira skill
- ✗Procedimento — "para fazer X, siga estes passos"
- ✗Formato — gabarito de saída, estrutura de documento, template
- ✗Receita — sequência de comandos de deploy, publicação, build
- ✗Integração — como falar com uma API/ferramenta específica
- ✗Roteamento — "quando eu pedir X, use a skill Y" (veja o tópico 4)
⌨️ Chame a skill direto
Uma skill normalmente é acionada por gatilho — o modelo compara a sua frase com o campo description do frontmatter e decide se aquela skill se aplica. Isso funciona, mas é uma loteria: se você escreveu "guia" e a descrição diz "landing page", a skill não dispara. Invocação explícita (/nome-da-skill) elimina a loteria por completo: você para de depender de a descrição casar com a sua frase.
💡 Invocação explícita mata a regra de roteamento
Quando várias skills competem pelo mesmo assunto, o reflexo é escrever no CLAUDE.md: "quando eu pedir um guia, use a skill X, não a Y". Essa linha é ela mesma mais uma linha zumbi — lida em toda execução, existindo só para desempatar um caso raro. Invocação explícita é o desempate, e é de graça: você digita /x e acabou a disputa.
- •Cada regra de roteamento removida é contexto devolvido em todas as execuções
- •Se você sabe o que quer, dizer o nome é sempre mais barato e mais preciso que descrever
- •Gatilho continua útil para quando você não sabe que a skill existe — mas não precisa ser reforçado por regra global
Onde a skill mora também importa. Skill em ~/.claude/skills/ vale para tudo que você faz; skill em .claude/skills/ dentro do projeto versiona junto com o código. Isso muda o regime de manutenção: o procedimento anda com o repo, entra no pull request, é revisável por outra pessoa, e — crucialmente — não vaza para os outros projetos. Uma receita de deploy específica do projeto A não tem por que ocupar contexto quando você está trabalhando no projeto B.
| Onde a instrução mora | Custo de contexto | Escopo | Revisável em PR |
|---|---|---|---|
~/.claude/CLAUDE.md | toda execução, em todo projeto | tudo | não |
CLAUDE.md do projeto | toda execução naquele projeto | o projeto | sim |
~/.claude/skills/ | só quando invocada/acionada | tudo | não |
.claude/skills/ do projeto | só quando invocada/acionada | o projeto | sim |
Conceitos-chave
Descrição casa com sua frase — ou não
/nome — sem loteria
Roteamento no CLAUDE.md é uma delas
Versiona no repo, não vaza
💊 Escolha o remédio certo
Quando o modelo tropeça, o reflexo é despejar mais uma regra no CLAUDE.md. No ciclo do Boris existem três remédios, e escolher o certo é o que impede a config de voltar a engordar: prompt melhor (a instrução estava obscura) · skill (falta procedimento repetível) · MCP (falta contexto ou acesso que ele não alcança). MCP é o protocolo pelo qual o Claude Code conversa com uma fonte externa — um banco, uma API, um sistema de arquivos remoto — que ele não teria como enxergar sozinho.
O que olhar: nenhum dos quatro caminhos termina em "escreva mais uma linha no CLAUDE.md". E repare no ramo ciano à esquerda: falha que aconteceu uma vez não é remédio nenhum — a regra de reintrodução manda esperar a mesma falha se repetir antes de devolver qualquer instrução. Metade das linhas zumbis de uma config nasceu de um tropeço único.
Tropeço → prompt melhor
Você pediu "melhora esse texto" e recebeu uma reescrita completa que perdeu o seu tom. O modelo não errou: "melhorar" não significa nada específico. O conserto é no pedido — "corrija gramática e corte redundância, preservando as escolhas de palavra" — não na config. Instrução obscura consertada com regra global vira uma regra global obscura.
Tropeço → skill
Toda vez que você publica um projeto, precisa lembrar o modelo da mesma sequência: guia em guia/, nunca na raiz; nome do repo = nome da pasta; Pages via Actions. É a terceira vez que você reexplica. Isso é procedimento repetível com contorno claro — vira skill, e você chama /publicar quando precisa.
Tropeço → MCP
Você pede uma análise dos pedidos do último trimestre e o modelo inventa números plausíveis. Nenhuma regra resolve isso, porque o problema não é comportamento — é que os dados estão num banco que ele não alcança. O remédio é dar acesso (um servidor MCP para o banco), não escrever "não invente dados" no CLAUDE.md.
🧹 Skill é fácil de auditar — e de aposentar
Uma skill tem fronteira, nome e escopo. Isso significa que ela é uma unidade que você consegue segurar na mão: dá para renomear a pasta, rodar uma semana sem ela e medir se alguma coisa piorou. É ablação em escala de uma unidade inteira.
Desativar "aquele parágrafo do meio do CLAUDE.md" é bem mais difícil: ele não tem nome, não tem fronteira clara, você não sabe quais tarefas dependiam dele, e nada acusa quando ele some. Por isso a mesma instrução, dentro de uma skill, é mais barata de manter — não só mais barata de rodar.
Checagem rápida (não bloqueia nada): pela terceira semana seguida, você reexplica ao modelo a mesma sequência de 8 passos para publicar um projeto. Qual é o remédio certo?
🛠️ Aplique suas 3 primeiras mudanças
O exercício deste módulo é curto e concreto: aplicar as 3 primeiras mudanças do Top 10 do seu relatório, numa sessão nova, com a config sob git — e pelo menos uma delas sendo um MOVE de bloco procedimental do CLAUDE.md para uma skill. Uma mudança por commit. Registre o antes e o depois em duas métricas: número de linhas e número de regras.
📏 Copiar e rodar: medir antes e depois
Objetivo: ter número, não impressão. "Ficou mais enxuto" não é registro.
# ANTES de aplicar qualquer coisa wc -l ~/.claude/CLAUDE.md grep -c '^[-*] ' ~/.claude/CLAUDE.md # aproximacao do numero de regras (bullets) git -C ~/.claude log --oneline -1 # confirma o commit "antes da ablacao" # ... aplique UMA mudanca, commite, repita ... # DEPOIS das 3 mudancas wc -l ~/.claude/CLAUDE.md grep -c '^[-*] ' ~/.claude/CLAUDE.md git -C ~/.claude diff --stat "antes da ablacao"..HEAD ls ~/.claude/skills/ # a skill nova esta la?
Como verificar: git diff --stat te dá a conta exata de linhas removidas e adicionadas — e num MOVE bem feito você vê linhas saindo do CLAUDE.md e entrando no SKILL.md, quase na mesma quantidade. Isso é o sinal de que você moveu, e não apagou por engano.
📋 Copiar e colar: o pedido de aplicação
Objetivo: pedir uma mudança específica, com o trecho do relatório colado — nunca "aplica o relatório".
Sessao de APLICACAO (a auditoria ja foi feita e esta salva em relatorio-ablacao.md — nao rode auditoria de novo, nao releia tudo). Aplique EXATAMENTE UMA mudanca, esta: <cole aqui o trecho do relatorio> Regras desta sessao: - Nao aplique nada alem do que esta no trecho acima. - Nao "aproveite pra melhorar" outras partes do arquivo. - Se for um MOVE: crie ~/.claude/skills/<nome>/SKILL.md com frontmatter (name, description) e mova o bloco INTEGRAL, sem reescrever o conteudo. - Remova do CLAUDE.md exatamente as linhas movidas. - No fim, mostre: (a) o diff, (b) wc -l do CLAUDE.md antes e depois, (c) uma frase dizendo o que EU devo testar pra confirmar que nada mudou. - Nao commite: eu commito depois de ler o diff.
Por que "não commite": o commit é o seu ponto de decisão. Ler o diff antes de commitar é o único momento em que você compara o que pediu com o que aconteceu — e é exatamente aí que aparece a reescrita silenciosa de um bloco que você mandou mover sem mudar.
✓ Critério de saída deste módulo
- ✓Commit (ou snapshot) "antes" e "depois" existem e são localizáveis
- ✓
CLAUDE.mdmenor — com o número, não com a impressão - ✓A skill nova responde à invocação direta
/<nome> - ✓O comportamento da tarefa correspondente não mudou
✗ Não conta como concluído se
- ✗As 3 mudanças foram para um commit só
- ✗O bloco movido foi "melhorado" no caminho — aí você mudou duas coisas de uma vez
- ✗A skill existe mas você nunca a invocou para conferir que responde
- ✗Você mediu "parece mais leve" em vez de
wc -l
📌 Resumo do Módulo
TEST. Começar pelo risco quase zero evita o corte heroico que faz você desistir.MOVE é a ferramenta principal — regra no CLAUDE.md é lida em toda execução; a mesma regra numa skill só custa contexto quando a tarefa é aquela./nome-da-skill desempata sem custar uma linha global. Skill de projeto versiona no repo e não vaza.CLAUDE.md"; e falha que aconteceu uma vez ainda não é remédio nenhum.CLAUDE.md — só o que é verdade sempre: identidade, guardrails, fontes de verdade, segurança. Todo o resto é skill.Próximo Módulo:
4.1 — O plano de ablação A/B/C: provar por teste, em tarefas reais, que a versão mínima não perdeu qualidade.