🔍 Reconheça a especificação excessiva
Boris Cherny descreve a especificação excessiva — escrever a sequência exata de movimentos que o modelo deve fazer — como um dos erros mais comuns que ele vê. E o detalhe incômodo: é mais frequente em quem tem anos ou décadas de engenharia, não menos. Quanto mais experiente o autor da config, mais roteirizada ela tende a ser.
O motivo é histórico. Software se construía projetando o sistema inteiro de antemão, escrevendo uma suíte enorme
de testes unitários e tratando uma re-arquitetura como projeto de meses ou anos. Esse reflexo — decidir tudo antes,
no papel — virou o jeito de escrever CLAUDE.md. Com os modelos antigos funcionava:
eles precisavam da mão guiando cada passo. Hoje o roteiro faz o contrário do que você quer: ele impede o
modelo de achar um caminho melhor do que o que você imaginou.
🆕 Quatro palavras que vão aparecer o módulo inteiro
- Guardrail: um limite que não pode ser cruzado — “nunca commite sem rodar os testes”, “não toque em
node_modules/”. Diz o que é proibido, não como fazer. - Critério de saída: a frase que permite ao modelo saber que terminou. “Pronto quando o build passa e o arquivo existe” é critério; “pronto quando ficar bom” não é.
- Verificação: a forma concreta de o modelo conferir sozinho se o critério de saída foi atingido — um comando, um teste, uma comparação de arquivo, um screenshot.
- Autonomia: a permissão explícita para o modelo escolher a estratégia de execução, desde que respeite os guardrails e atinja o critério.
O que olhar: à esquerda existe uma rota só, e ela é a rota que você imaginou. Se houver um caminho melhor, o trilho o proíbe — e o modelo obedece. À direita nada foi roteirizado: as cercas são os guardrails (o que não pode), o portão é o critério de saída (quando acabou), e o miolo é livre. As três setas mostram o ganho concreto: o modelo pode escolher a rota mais curta para o problema real de hoje, que não é necessariamente a que você escreveu meses atrás.
✗ Cheiros de especificação excessiva
- ✗“Primeiro rode
git status, depoisgit diff, depois leia o arquivo, depois…” - ✗Numeração de 8 a 12 passos para uma tarefa que cabe em duas frases
- ✗“Use a ferramenta X, nunca a Y” sem dizer por quê (o porquê é que envelhece)
- ✗Exceções empilhadas: “exceto se…, mas se…, a não ser quando…”
- ✗Instrução que ensina o modelo a pensar (“analise cuidadosamente antes de responder”)
✓ O que sobrevive à auditoria
- ✓“O deploy acontece por push no git; o webhook cuida do resto.” — contexto que o modelo não infere
- ✓“Nunca imprima o valor de uma API key.” — guardrail de segurança
- ✓“As keys ficam em
~/projetos/wifi/.env.” — fonte de verdade, caminho concreto - ✓“Pronto quando
npm run buildsai com código 0.” — critério verificável - ✓“Escolha a estratégia de execução.” — autonomia declarada
Conceitos-chave
A sequência exata de movimentos
Projetar tudo antes, no papel
Bloqueia o caminho melhor
Mais comum em veteranos
🔄 Converta receita em critério
Existe uma conversão canônica, e ela cabe numa linha. Toda instrução na forma “faça A, depois B, depois C” vira: “Produza X. Respeite Y. O resultado deve atingir Z. Verifique usando W. Escolha a estratégia.” Cinco slots. X é o objetivo, Y são os guardrails, Z é o critério de saída, W é a verificação, e a última frase é a autonomia.
🎯 A frase-molde
Produza X. Respeite Y. O resultado deve atingir Z. Verifique usando W. Escolha a estratégia.
Se você não consegue preencher W, pare: você ainda não tem uma instrução, tem um desejo. A ausência de W é o defeito mais comum das configs que a auditoria encontra.
Um caso real: regra de publicação roteirizada
Abaixo, uma regra de publicação escrita do jeito que quase todo CLAUDE.md real
escreve — oito passos, ordem fixa, um comando por linha. Ela funciona, mas prende o modelo a uma sequência que já
não é a melhor (e que quebra no primeiro projeto que tem um passo a mais).
✗ ANTES — 8 passos, 14 linhas
## Publicação 1. Rode `git status` e verifique se há mudanças. 2. Rode `git diff` e leia tudo o que mudou. 3. Rode `git log -5` para ver o estilo das mensagens anteriores. 4. Rode `git config user.email` e confira se é o autor certo. 5. Se estiver errado, rode `git config user.email`. 6. Faça `git add` só dos arquivos que você editou (nunca `git add .`). 7. Escreva a mensagem de commit no padrão `tipo: descrição`. 8. Rode `git push` e depois confira no dashboard se o deploy subiu.
✓ DEPOIS — 4 linhas de critério
## Publicação Objetivo: publicar = commit + push no `origin`. O deploy é automático; não é sua responsabilidade. Guardrails: nunca `git add .`; o autor do commit acompanha a conta de destino do repo (default `inematds`). Critério de saída: o commit está em `origin` e a mensagem segue `tipo: descrição`. Verificação: `git log origin/main -1` mostra o seu commit com o autor esperado.
O que mudou de verdade: os passos 1–3 sumiram porque o modelo já sabe inspecionar um repositório — eram microgerenciamento puro. Os passos 4–5 viraram um guardrail (a regra, não o procedimento). Os passos 6–7 viraram guardrail e critério. E o passo 8 — “confira no dashboard” — virou uma verificação executável: um comando que dá a resposta sem depender de ninguém abrir um site.
💡 O teste do bisturi
Para cada passo numerado da instrução, pergunte: “isso é uma regra que vale sempre, ou é um movimento que o modelo escolheria sozinho?” Regra vira guardrail. Movimento vira nada — apaga. O que sobra costuma ser 20–30% do original, e é exatamente a parte que o modelo não conseguia adivinhar.
🧱 Use o template de 6 campos
A frase-molde do tópico anterior, esticada, vira um template de seis campos:
Objetivo · Contexto · Guardrails · Critérios de qualidade · Verificação · Autonomia.
Não é burocracia: cada campo existe porque a ausência dele produz um tipo específico de falha. Vale para prompts
avulsos, para blocos do CLAUDE.md e para o corpo de uma skill.
Objetivo — o resultado, não o caminho
Uma frase dizendo o que deve existir no final.
Erro típico: descrever a atividade (“revisar o código”) em vez do resultado (“um relatório com os bugs de correção encontrados no diff”).
Contexto — só o que ele não descobre sozinho
Caminhos, nomes de sistemas, fontes de verdade, convenções internas.
Erro típico: despejar o histórico do projeto. Contexto é endereço, não biografia. Se o modelo pode ler o arquivo, diga onde ele está em vez de resumi-lo.
Guardrails — o proibido, em forma negativa
Segurança, compliance, contratos de interface, o que nunca pode ser tocado.
Erro típico: disfarçar procedimento de guardrail. “Sempre rode o lint antes do build” não é um limite — é um passo. Limite é “não faça commit com o lint quebrado”.
Critérios de qualidade — o que significa “ficou bom”
De preferência contáveis: número máximo de linhas, formato de saída, cobertura, tom.
Erro típico: adjetivos sozinhos — “claro”, “profissional”, “bem escrito”. Adjetivo sem âncora não decide nada e o modelo preenche com o palpite dele.
Verificação — como ele confere sozinho
Um comando, um teste, uma comparação, uma checagem de arquivo. Com condição de parada.
Erro típico: o campo simplesmente não existe. É o campo mais ausente e o de maior impacto — o tópico 4 é inteiro sobre ele.
Autonomia — a permissão explícita
“Escolha a estratégia de execução.” Uma linha, e ela muda o comportamento.
Erro típico: achar que é redundante. Sem essa linha, uma config cheia de regras antigas ainda empurra o modelo para o modo “siga o roteiro”.
📋 Template pronto para colar
Copie, troque o que está entre < > e apague os campos que não se aplicam — menos o de Verificação, que nunca sai.
## <nome da tarefa> **Objetivo:** <o resultado que deve existir no final, em uma frase> **Contexto:** <caminhos, sistemas e convenções que o modelo não descobre sozinho> **Guardrails:** - <o que nunca pode acontecer> - <limite de segurança / compliance / interface> **Critérios de qualidade:** - <algo contável: tamanho, formato, cobertura> - <algo observável: tom, estrutura, nomes> **Verificação:** <comando, teste ou comparação que prova o critério>. Repita produzir → verificar até <condição de parada explícita>. **Autonomia:** escolha a estratégia de execução; não peça confirmação para decisões cobertas pelos guardrails acima.
💡 Dica: o template é uma régua, não um formulário
Você não precisa dos seis títulos literais na config. Precisa que os seis existam em algum lugar. Use o
template para auditar uma instrução: leia-a e marque quais dos seis campos ela cobre. Instrução
que só cobre “o caminho” e nenhum dos seis é candidata direta a REMOVE ou
SIMPLIFY na taxonomia do módulo 2.1.
🔬 Instale a verificação (a alavanca)
Perguntaram a Boris qual habilidade importa agora que “prompt engineering” perdeu força como cargo. A resposta: dar ao modelo uma tarefa que pareça um pouco difícil demais, e tornar possível que ele verifique o próprio trabalho ao longo do processo. Ele chamou a verificação de “a coisa mais importante que as pessoas não acertam”. Traduzindo para este curso: um prompt curto com um jeito real de conferir ganha de um prompt gigante sem nenhum.
O exemplo do Electron → Swift
Boris quis saber como seria o app desktop do Claude — feito em Electron — se virasse app nativo. Conectou um runner de macOS (uma máquina virtual Mac), criou um repositório vazio e deu uma única instrução: reescreva o app Electron em Swift, rode o original na VM, tire screenshots, compare pixel a pixel com a versão Swift e não pare até terminar. Na data da palestra a tarefa rodava havia mais de duas semanas, tendo criado de milhares a dezenas de milhares de agentes. O prompt não tinha técnica nenhuma. Tinha um ciclo de verificação completo.
O que olhar: a seta ciano de retorno. As três primeiras caixas quase todo mundo escreve; é a volta e a caixa em destaque que faltam. Sem condição de parada explícita, o ciclo não é ciclo — é uma linha reta que termina na primeira entrega. E repare que observar é a caixa que exige um recurso do mundo real (a VM, o comando, o arquivo). Verificação sem observação externa é só o modelo relendo a si mesmo.
Quatro verificações objetivas, em contextos diferentes
1. Teste que roda
“Pronto quando pytest tests/test_parser.py passa inteiro. Se falhar, corrija e rode de novo.” Observação externa: o resultado do teste. Parada: zero falhas.
2. Comando cujo exit code prova
“Rode npm run build; só considere concluído com código de saída 0.” Observação externa: o código de saída. Parada: 0. Não há espaço para interpretação.
3. Comparação de arquivo
“Gere o CSV e rode diff saida.csv esperado.csv; repita até o diff sair vazio.” Observação externa: o arquivo de referência. Parada: diff vazio.
4. Screenshot / comparação visual
“Abra a página, tire screenshot, compare com referencia.png; corrija até a diferença ficar abaixo de 2%.” Observação externa: a imagem renderizada. Parada: o limiar.
⚠️ Por que “revise antes de entregar” NÃO é verificação
É a linha mais comum em configs reais e ela não verifica nada. Faltam as duas peças que fazem o mecanismo funcionar:
- ✗Não tem observação externa. O modelo relê o próprio texto no mesmo contexto que o produziu — o raciocínio que gerou o erro continua ali, empurrando para o “está bom”.
- ✗Não tem condição de parada. “Revise” acontece uma vez e acabou. Não existe critério que diga se a revisão foi suficiente, então nunca há uma segunda volta.
Conserto: troque por “rode <comando>; enquanto ele reprovar, corrija e rode de novo”. Mesmo
tamanho de frase, mecanismo completamente diferente.
Os quatro momentos, em ordem
Produzir
Gerar a saída. É o único momento que toda config já tem.
Observar
Olhar algo fora do próprio texto: rodar um comando, abrir um arquivo, tirar um screenshot.
Comparar
Confrontar a saída com a referência e produzir um veredito — passou ou não passou.
Condição de parada
A frase que encerra o ciclo. “Não pare até terminar”, “até o diff sair vazio”, “até o exit code ser 0”.
🚀 Mire acima do teto
A recomendação de Boris é mirar mais alto do que parece confortável: dê ao modelo uma tarefa um pouco mais difícil do que você acha que ele aguenta. O motivo é simples — o teto muda a cada lançamento. A sua estimativa de “o que ele consegue” foi calibrada numa geração anterior e você não percebeu que ela ficou desatualizada, porque ninguém te avisa quando o teto sobe.
A consequência direta para a auditoria: reteste os seus fracassos antigos a cada versão nova. Aquela regra que você escreveu porque “ele sempre erra isso” pode estar protegendo contra uma falha que não existe mais. Ela continua custando contexto em toda execução, e o motivo dela desapareceu sem aviso. É exatamente o mecanismo do módulo 1.1: instrução é o conserto da fraqueza de um modelo específico.
🧬 Ciência empírica, não teórica
Trabalhar com um modelo se parece mais com conhecer uma criatura viva do que com configurar um sistema.
Cada geração se comporta de um jeito e tem uma personalidade ligeiramente diferente. Você passa um tempo aprendendo como ela funciona e depois ajusta o harness — o conjunto de prompts, ferramentas e regras ao redor do modelo — em cima do que observou. Note a ordem: observar primeiro, escrever a regra depois. O contrário disso é teoria, e teoria sobre modelo envelhece em semanas.
💡 A régua do colega de trabalho
O nível certo de instrução é o mesmo que você usaria orientando um colega competente: contexto, objetivo, os limites que ele não tem como adivinhar, e como saber que terminou. Você não escreveria para um colega “abra o editor, clique em arquivo, digite o nome”. Se a sua instrução não passaria no teste de ser lida em voz alta para uma pessoa sem soar ofensiva, ela é microgerenciamento.
✓ Postura empírica
- ✓Pede uma tarefa acima do que espera e observa onde trava
- ✓Guarda os fracassos antigos e reroda a cada modelo novo
- ✓Corrige a dificuldade específica observada — nada além dela
- ✓Escolhe o remédio certo: prompt melhor, skill ou MCP
✗ Postura teórica
- ✗Assume o teto da geração passada e nunca testa de novo
- ✗Escreve regras preventivas para falhas que nunca viu acontecer
- ✗Corrige “na área” — três parágrafos novos por um erro pontual
- ✗Procura o truque secreto em influenciador de rede social
🔁 Não existe truque secreto — existe um ciclo
Perguntaram a Boris o que separa o 1% dos melhores usuários de Claude Code. A resposta foi: pare de procurar um truque. O método é este, e ele é público:
1. tarefa difícil demais
2. meios de verificar o trabalho
3. observar onde ele trava
4. corrigir AQUILO → prompt melhor (instrução obscura)
→ skill (falta procedimento repetível)
→ MCP (falta contexto que ele não alcança)
5. repetir
O passo 4 é onde a maioria erra: diante de um tropeço, o reflexo é sempre “mais uma regra no
CLAUDE.md”. Três causas, três remédios diferentes — e só um deles é escrever texto.
✍️ Reescreva a sua pior instrução
Hora de aplicar. Abra a sua configuração — ~/.claude/CLAUDE.md, o
CLAUDE.md de um projeto ou o corpo de uma skill sua — e ache a instrução mais
“receita de bolo” que existe lá: a mais numerada, a mais longa, a que descreve movimentos. Você vai escrever
duas versões dela, e a segunda obrigatoriamente com verificação objetiva.
Versão 50% menor
Mesma estrutura, metade do texto. Corte o que o modelo já faz sozinho e funda passos que sempre andam juntos. Nenhuma regra real pode desaparecer nessa versão — é um corte de gordura, não de músculo.
Versão mínima, com o template de 6 campos
Reescrita do zero na forma Objetivo · Contexto · Guardrails · Critérios · Verificação · Autonomia. A verificação precisa ser um comando, um teste, uma comparação ou uma checagem de arquivo — algo que produza um resultado observável.
🧪 Prompt pronto para colar no Claude Code
Objetivo: fazer o próprio Claude Code produzir as duas versões lado a lado, sem deixá-lo aplicar nada no arquivo.
Leia <caminho do seu CLAUDE.md ou da sua skill> e localize o bloco "<titulo ou primeira linha do bloco mais roteirizado>". NÃO edite nenhum arquivo. Só produza texto na resposta. Devolva três blocos em markdown: 1. ORIGINAL — o trecho exatamente como está hoje, com a contagem de linhas. 2. VERSÃO 50% MENOR — o mesmo trecho com metade das linhas. Corte só o que você faria sozinho sem a instrução. Liste embaixo, em uma linha cada, o que foi cortado e por quê. 3. VERSÃO MÍNIMA — reescreva usando os campos Objetivo, Contexto, Guardrails, Critérios de qualidade, Verificação e Autonomia. A Verificação tem que ser um comando, um teste, uma comparação de arquivo ou uma checagem de existência — nada de "revise antes de entregar" — e tem que trazer uma condição de parada. No fim, responda em uma frase: um colega que não conhece este projeto conseguiria executar a Verificação da versão mínima sem me perguntar nada? Se a resposta for não, reescreva a Verificação.
Critério de saída deste exercício: as duas versões existem escritas ao lado da original, e a verificação da versão mínima é executável por um terceiro sem perguntar nada a você. Se ela depende de um contexto que só mora na sua cabeça, ela ainda não é verificação.
Como conferir isso na prática: mande a versão mínima para alguém (ou cole numa sessão nova, sem histórico) e peça só para executar a linha de Verificação. Se vier uma pergunta de volta, reescreva. Guarde as três versões — elas viram entrada direta do plano A/B/C da Trilha 4.
Checagem rápida (não bloqueia nada): sua instrução mínima termina com “antes de finalizar, revise o resultado com atenção e corrija o que estiver ruim”. Isso conta como verificação?
Conceitos-chave
50% menor e mínima
A original fica visível
Executável sem te perguntar
As três versões viram teste
📌 Resumo do Módulo
Próximo Módulo:
3.1 — Rodando a skill audit-ablacao: instalar, escolher o escopo e ler o relatório de 10 seções sabendo o que cada uma cobra de você.