Módulo 2.1 — A taxonomia: o que cada linha é

🏷️ Classifique cada linha em uma das 10 categorias

Antes de decidir se uma instrução fica ou sai, você precisa dizer o que ela é. Sem isso, a auditoria vira gosto pessoal. A taxonomia tem 10 caixas — e cada linha da sua config cai em uma delas. Se você não consegue escolher a caixa, isso já é o diagnóstico: a instrução está fazendo duas coisas ao mesmo tempo e precisa ser partida.

🆕 Cinco palavras antes de seguir

Config: o conjunto de arquivos que instrui o agente — CLAUDE.md (global e de projeto), skills, hooks e settings.json.
Skill: um pacote de instruções que só é carregado quando aquela tarefa aparece (ou quando você chama por /nome) — diferente do CLAUDE.md, que é lido em 100% das execuções.
Hook: um comando que o programa executa automaticamente antes ou depois de uma ação do agente. Não é texto que o modelo lê — é código que o harness roda.
Guardrail: um limite duro. Diz o que não pode acontecer, nunca. "Não commite na branch principal" é guardrail.
Instrução: aqui, a menor unidade auditável — normalmente um bullet, uma frase ou um parágrafo curto com uma regra só.

Categoria	O que ela é	Exemplo real de instrução
CONTEXTO	Fato do seu mundo que o modelo não tem como adivinhar.	"O portal é o projeto em `~/projetos/portal`, domínio `inema.club`, Next.js na Vercel."
GUARDRAIL	Limite duro. O que nunca pode acontecer.	"Nunca commitar direto na `main`: sempre criar branch antes."
CRITÉRIO DE QUALIDADE	Define como é um resultado bom, sem dizer o caminho.	"A página tem que funcionar sem internet: nada de CDN externo."
VERIFICAÇÃO	Dá ao modelo um jeito objetivo de conferir o próprio trabalho.	"Antes de dizer 'pronto', rode `npm run build` e cole a saída."
INTEGRAÇÃO/FERRAMENTA	Onde mora uma credencial, um serviço, um binário.	"As API keys estão em `~/projetos/wifi/.env`; carregue em runtime, nunca imprima o valor."
PROCEDIMENTO REPETÍVEL	Sequência que se repete de verdade e tem valor — candidata a virar skill.	"Publicar no portal = editar o catálogo, commitar nos 3 repos, push."
MICROGERENCIAMENTO	Dirige como o modelo pensa/executa, em vez de dizer o resultado.	"Primeiro leia o arquivo, depois liste as funções, depois escolha uma, depois..."
REDUNDÂNCIA	A mesma regra já dita em outro arquivo (ou duas vezes no mesmo).	"Sem emoji na saída" — presente no `CLAUDE.md` global, no do projeto e em duas skills.
LEGADO/OBSOLETA	Conserta a fraqueza de um modelo que não roda mais aqui.	"Não tente editar mais de um arquivo por vez, você se confunde."
AMBÍGUA/NÃO COMPROVADA	Ninguém sabe o que ela segura nem o que quebra sem ela.	"Seja cuidadoso e pense bem antes de responder."

💡 As seis de cima e as quatro de baixo

As seis primeiras categorias descrevem instruções que podem estar pagando o próprio custo. As quatro últimas (microgerenciamento, redundância, legado, ambígua) são diagnósticos: dar esse rótulo a uma linha já significa que ela não vai sair da auditoria do jeito que entrou.

Cuidado com a inversão fácil: rotular algo como CONTEXTO não é passe livre. Contexto que só serve a 2% das suas tarefas e mora no CLAUDE.md global continua sendo custo em 100% das execuções.

🎚️ Decida entre as 6 saídas

Categoria é diagnóstico; decisão é o que você faz com ele. São seis saídas possíveis, e nenhuma linha pode ficar sem uma. Uma auditoria em que 90% das linhas saem como KEEP não é uma config saudável — é uma auditoria que não aconteceu.

O que olhar: a pilha da esquerda entra inteira no funil — nenhuma linha pula a triagem. Repare que a única caixa com brilho é TEST: ela é o destino padrão quando você não tem evidência, e não uma terceira via para adiar decisão. Note também que dez categorias desembocam em seis saídas — o mapeamento não é um-para-um, e é a pergunta 3 (tópico 3) que costuma decidir para qual lado a linha vai.

KEEP — fica como está

Escolha quando: você sabe dizer o que quebra sem ela, e já viu isso quebrar.

Típico de CONTEXTO, GUARDRAIL e INTEGRAÇÃO. KEEP exige justificativa; se a sua justificativa é "melhor não mexer", a decisão certa é TEST.

SIMPLIFY — a intenção fica, o volume some

Escolha quando: a regra é válida, mas está escrita em três parágrafos com quatro exemplos.

É a saída mais comum de PROCEDIMENTO REPETÍVEL inchado e de MICROGERENCIAMENTO leve. O teste: dá para dizer isso em uma frase que um colega entenderia?

MOVE — a regra é boa, o lugar é errado

Escolha quando: a instrução só vale para um tipo de tarefa, mas mora no arquivo lido em toda execução.

Do CLAUDE.md global para o do projeto; do CLAUDE.md para uma skill. Custo zero quando a tarefa não aparece.

MERGE — várias linhas, uma intenção

Escolha quando: a mesma ideia aparece em pedaços espalhados, às vezes com pequenas contradições.

Saída natural de REDUNDÂNCIA. Ao fundir, escolha explicitamente qual versão vence — senão você só juntou a contradição num lugar só.

TEST — remova numa rodada e observe

Escolha quando: você acha que ela ajuda, mas não consegue citar uma falha real que ela evitou.

É a saída honesta para AMBÍGUA/NÃO COMPROVADA e para boa parte do LEGADO. Ela não apaga nada agora: ela agenda uma medição (o plano A/B/C da Trilha 4).

REMOVE — sai, com trecho citado e risco escrito

Escolha quando: a linha é duplicata exata, conserta um modelo que você não usa mais, ou dirige um raciocínio que o modelo já faz.

Toda remoção vem acompanhada de três coisas: o trecho, o risco e como testar. Remoção sem essas três é chute com aparência de método.

💡 A regra de ouro deste módulo

Sem evidência suficiente, prefira TEST a KEEP. Nenhuma config fica inchada porque alguém decidiu deliberadamente inchá-la. Ela incha porque, linha a linha, manter parecia mais barato do que verificar. TEST é o antídoto: ele não custa nada hoje e transforma "eu acho" em dado na semana que vem.

❓ Faça as 7 perguntas por instrução

A categoria e a decisão não caem do céu: elas saem de sete perguntas feitas na mesma ordem, para toda instrução. Fazer sempre as sete é o que impede a auditoria de virar impressão. E uma delas — a terceira — costuma resolver o caso sozinha.

#	Pergunta	Para onde a resposta aponta
1	O que ela tenta evitar ou garantir?	Se você não consegue responder: `AMBÍGUA` → `TEST`.
2	O modelo atual ainda precisa dela?	Escrita para um modelo antigo: `LEGADO` → `TEST` ou `REMOVE`.
3	Ela diz O QUE deve acontecer, ou tenta dirigir COMO o modelo pensa/executa?	"Como" → `MICROGERENCIAMENTO` → `SIMPLIFY`. A mais discriminante.
4	Está duplicada em outro arquivo?	`REDUNDÂNCIA` → `MERGE` ou `REMOVE`.
5	Limita autonomia sem necessidade?	Fecha caminhos melhores sem motivo → `SIMPLIFY` ou `REMOVE`.
6	Existe forma mais curta de preservar a intenção?	Quase sempre sim → `SIMPLIFY`.
7	O que quebra se ela sumir?	Resposta concreta → `KEEP`. Silêncio ou "sei lá" → `TEST`.

Por que a 3 é a mais discriminante. Instruções que descrevem o resultado envelhecem bem: "o build tem que passar" continua verdadeiro em qualquer modelo. Instruções que descrevem o processo interno envelhecem mal, porque foram calibradas para uma fraqueza específica de uma geração específica. Quando um modelo melhor chega, a instrução de "como" não vira neutra — ela vira uma algema, impedindo o caminho melhor que o modelo agora conseguiria achar sozinho. Aqui, autonomia é exatamente isso: o espaço que você deixa para o modelo escolher a estratégia depois de você ter definido o alvo.

✓ Diz O QUE (envelhece bem)

✓"O resultado tem que rodar offline — nenhuma requisição a host externo."
✓"Antes de dizer que terminou, rode os testes e cole a saída."
✓"Nunca faça push com o autor errado; confira git config user.email antes."
✓"Publicar = commit + push. O deploy é automático e não é sua responsabilidade."

✗ Dirige COMO (envelhece mal)

✗"Primeiro leia o arquivo, depois liste as funções, depois escolha uma, depois edite."
✗"Pense passo a passo e explique seu raciocínio antes de agir."
✗"Não use mais de duas ferramentas por resposta."
✗"Sempre releia o que escreveu duas vezes antes de continuar."

🧾 As 7 perguntas aplicadas a uma linha real

TRECHO   "Antes de editar qualquer arquivo, leia-o inteiro,
          liste as funções encontradas, escolha a função alvo,
          só então aplique a edição."

1 evita/garante?   edição às cegas em arquivo que o agente não leu
2 ainda precisa?   não — o modelo atual já lê antes de editar
3 O QUE ou COMO?   COMO  ← decide o caso
4 duplicada?       sim, versão curta já existe na skill de refactor
5 limita autonomia? sim: proíbe edição direta mesmo quando é óbvia
6 forma mais curta? "não edite arquivo que você não leu nesta sessão"
7 o que quebra?    nada observado nos últimos meses

CATEGORIA  MICROGERENCIAMENTO
DECISÃO    SIMPLIFY (usar a forma da pergunta 6)

🛡️ Proteja o que o modelo não infere

Existe uma classe de instrução que você nunca corta por reflexo, por mais que o corte pareça atraente na contagem de linhas: aquilo que o modelo não tem como descobrir sozinho. Ele pode raciocinar; ele não pode adivinhar que o seu domínio é inema.club, que a fonte de verdade dos preços é uma planilha específica, ou que sua empresa proíbe enviar dado de cliente para fora.

✓ Contexto que só você sabe — protegido

✓Identidade do projeto: o que ele é, para quem, qual o nome certo.
✓Caminhos de arquivos: onde mora o quê no seu disco e no repo.
✓Fontes de verdade: qual arquivo manda quando dois discordam.
✓Branding: paleta, tom de voz, o que nunca aparece na marca.
✓Segurança e compliance: o que não pode sair, o que precisa de aprovação.
✓Contratos de interface: formato de payload, nomes de campos, versões.
✓Integrações: qual serviço, qual credencial, qual limite de uso.
✓Convenções internas: "aqui a gente chama isso de X", padrão de commit.

✗ Raciocínio genérico — o modelo já faz

✗"Escreva código legível e bem nomeado."
✗"Trate erros e casos de borda."
✗"Divida problemas grandes em partes menores."
✗"Explique o que uma função faz antes de reescrevê-la."
✗"Considere as alternativas antes de escolher uma."
✗"Use boas práticas de segurança em geral."
✗"Verifique se a resposta faz sentido."
✗Uma skill inteira ensinando "como debugar um problema".

🧭 O teste do colega novo

Imagine um profissional competente que entrou na sua equipe hoje. Ele sabe programar, sabe escrever, sabe pesquisar — mas não conhece a sua casa. Toda instrução que você precisaria dar a ele porque ele não teria como saber é contexto protegido. Toda instrução que ofenderia a inteligência dele é candidata a corte.

A pergunta 3 e este teste se apoiam: "leia o arquivo antes de editar" ofende o colega novo; "o CSS do curso vem de assets/curso.css, não repita inline" é exatamente o tipo de coisa que ele agradeceria por saber no primeiro dia.

⚠️ O erro caro da ablação mal feita

A falha mais cara não é manter uma linha inútil — é cortar contexto insubstituível e só descobrir três semanas depois, quando o agente publicou no repositório errado, com o autor errado, seguindo uma convenção que ninguém mais documentava. Linha inútil custa contexto; contexto perdido custa retrabalho e confiança. Por isso a ordem do curso é diagnóstico → proposta → teste, nunca corte por impulso.

⚖️ Otimize a função certa

Aqui está a parte que quase todo mundo erra quando descobre ablação: o objetivo não é reduzir ao máximo. Config de zero linha não é o alvo. O alvo é uma razão — e ela tem três coisas em cima e uma embaixo.

O que olhar: é uma fração, não uma meta de redução. As duas caixas vermelhas embaixo são os dois jeitos de errar — e elas erram em direções opostas. Repare que verificabilidade está no numerador: adicionar uma instrução de verificação aumenta o resultado mesmo custando linhas, porque o ganho em cima é maior que o custo embaixo. Ablação não é só subtração.

Qualidade — o resultado serve?

O trabalho entregue atende ao que você precisava, sem você ter que consertar depois. Mede-se em correções humanas por tarefa, não em sensação.

Autonomia — quanto ele resolve sem você?

Espaço para escolher a estratégia depois de o alvo estar definido. Instrução de "como" derruba autonomia; critério de saída preserva.

Verificabilidade — ele consegue conferir o próprio trabalho?

Existe um comando, um teste, uma comparação que diz objetivamente "passou" ou "não passou". É o termo que mais gente esquece de auditar — e o único que costuma estar faltando em vez de sobrando.

Complexidade — o denominador

Linhas lidas em toda execução, regras que competem entre si, exceções acumuladas, arquivos que ninguém entende inteiro. Cada linha do CLAUDE.md global é cobrada em 100% das tarefas, inclusive nas que nada têm a ver com ela.

💡 Duas auditorias que reprovam

"Cortei 90% e o agente ficou perdido": o numerador caiu junto. Você cortou contexto insubstituível ou a única verificação que existia. Reprovado — mesmo com a maior redução da turma.
"Não mexi em nada, tudo parecia importante": o denominador continua inflado e você não tem um único dado. Reprovado também — só que sem barulho, que é como o sedimento sobrevive.
Aprovado: menos linhas, mesma qualidade medida em tarefas reais, mais autonomia e pelo menos uma verificação objetiva onde antes não havia nenhuma.

🎯 Cace os sinais na sua config

Teoria acabou. Agora você aplica a taxonomia na sua própria config. Antes, a lista de caça — os 13 padrões que aparecem em quase toda configuração acumulada. Passe por ela com o arquivo aberto: cada item que você reconhecer já é um candidato com categoria quase decidida.

Checklist de caça

☐ Passo a passo desnecessário — sequência que o modelo já monta sozinho

☐ Regras duplicadas entre CLAUDE.md e skills

☐ Skills grandes demais — não cabem numa leitura

☐ Skills ensinando raciocínio genérico em vez de procedimento seu

☐ Instruções que compensam modelos antigos

☐ Excesso de exemplos — cinco onde um bastava

☐ Formatação rígida sem motivo — forma imposta sem razão

☐ Exceções acumuladas — "exceto quando... salvo se... a não ser que"

☐ Contradições e regras que competem pelo mesmo gatilho

☐ Contexto global que só serve a poucas tarefas — candidato a MOVE

☐ Regras que deveriam ser critérios de saída — critério de saída = condição objetiva que diz quando a tarefa está pronta; assunto do módulo 2.2

☐ VERIFICAÇÕES AUSENTES — o único item que se resolve somando, não cortando

☐ Regras substituíveis por teste objetivo — três parágrafos pedindo cuidado que um comando resolveria

🧪 Exercício: 15 linhas classificadas

Objetivo: extrair 15 instruções reais da sua config e dar categoria + decisão para cada uma. Copie e rode no terminal.

# 1) Extraia as instruções numeradas/bulletadas do CLAUDE.md global
grep -n "^-\|^[0-9]\." ~/.claude/CLAUDE.md | head -40

# 2) Faça o mesmo no CLAUDE.md do projeto que você mais usa
grep -n "^-\|^[0-9]\." ./CLAUDE.md | head -40

# 3) Tamanho de cada skill (skill grande demais é sinal do checklist)
wc -l ~/.claude/skills/*/SKILL.md | sort -rn | head -15

# 4) Caça rápida a redundância: uma palavra-chave sua em toda a config
grep -rn "commit\|deploy\|emoji" ~/.claude/CLAUDE.md ~/.claude/skills/ | head -20

Agora preencha esta tabela com 15 linhas. Uma instrução por linha, sem agrupar.

Trecho	Categoria	Decisão	Pergunta que decidiu	O que quebra se sumir
"Sem emoji na saída"	REDUNDÂNCIA	MERGE	4 — duplicada	nada: fica na versão fundida
"Primeiro leia, depois liste, depois…"	MICROGERENCIAMENTO	SIMPLIFY	3 — dirige o COMO	nada observado
"API keys em `~/projetos/wifi/.env`"	INTEGRAÇÃO	KEEP	7 — quebra na hora	o agente pede a key ao usuário
"Seja cuidadoso e pense bem"	AMBÍGUA	TEST	1 — sem intenção clara	desconhecido — por isso testar
…	…	…	…	…

Critério de saída: 15 linhas preenchidas, todas com categoria e decisão, e pelo menos uma em TEST.

Por que a exigência do TEST: se as 15 saíram como KEEP, o mais provável não é que sua config seja perfeita — é que você classificou pelo conforto. Volte às perguntas 1 e 7: se não dá para dizer o que a linha evita nem o que quebra sem ela, ela não é KEEP.

Checagem rápida (não bloqueia nada): você acha uma linha que diz "sempre releia o arquivo duas vezes antes de editar". Você não lembra de nenhuma falha que ela tenha evitado. Qual o par categoria/decisão mais defensável?

Conceitos-chave

Uma caixa por linha

Não escolhe? Está fazendo duas coisas

Pergunta 3 decide

O QUE envelhece bem, COMO envelhece mal

TEST > KEEP

Sem evidência, agende a medição

Verificação soma

O único item que se resolve adicionando

📌 Resumo do Módulo

✓

10 categorias — seis descrevem instruções úteis; quatro (microgerenciamento, redundância, legado, ambígua) já são diagnóstico.

✓

6 decisões — KEEP · SIMPLIFY · MOVE · MERGE · TEST · REMOVE. Nenhuma linha fica sem uma.

✓

Sem evidência, TEST — KEEP por conforto é exatamente como o sedimento se acumula.

✓

Pergunta 3 é a mais discriminante — diz O QUE deve acontecer, ou dirige COMO o modelo pensa?

✓

Contexto insubstituível é protegido — identidade, caminhos, fontes de verdade, branding, segurança, contratos, integrações, convenções.

✓

A função é uma razão — qualidade + autonomia + verificabilidade ÷ complexidade. Reduzir ao máximo não é o alvo.

Próximo Módulo:

2.2 — De microgerenciamento a critério e verificação: como reescrever "faça A, depois B, depois C" como objetivo, guardrails, critério de saída e um jeito real de conferir.

← Voltar para Trilha Próximo Módulo →