🧭 O code review aplicado a automações
Um workflow de automação não é "só uns blocos ligados". É código visual: tem lógica, dependências, pontos de falha e dívida técnica. E como código, ele apodrece em silêncio. A ideia central desta skill é simples e poderosa: tratar um workflow n8n exatamente como você trataria um pull request — com um arquiteto sênior fazendo a auditoria que ninguém parou pra fazer.
🎯 A promessa em uma frase
"Você constrói automações. Claude as revisa como um engenheiro sênior." O valor não está em achar erros bonitinhos — está em transformar uma caixa-preta que "às vezes funciona" num diagnóstico que diz exatamente o que vai quebrar, onde, e como consertar.
Cinco categorias fixas, na mesma ordem, toda vez.
Cada item tem o fix concreto, não conselho vago.
Tom de quem já viu isso quebrar em produção.
"Isso vai quebrar" > "talvez considere...".
📥 Cinco formas de entrada
Uma skill só é usada de verdade se aceita o material que a pessoa tem agora — não o material idealizado. O reviewer foi desenhado para engolir entrada imperfeita e ser honesto sobre o que cada formato permite (ou não) avaliar.
| Formato de entrada | O que dá pra avaliar |
|---|---|
| JSON completo | Tudo: expressões, credenciais, parâmetros, conexões. A auditoria mais profunda. |
| JSON parcial | O subconjunto de nodes enviado; sinaliza o que não dá pra inferir do resto. |
| Texto puro | Reconstrói a estrutura assumida, declara as suposições e revisa em cima delas. |
| Mensagem de erro | Modo debug: pede node, texto completo do erro e config; então diagnostica. |
| Screenshot | Lê nodes, tipos e conexões visíveis; declara o que só o JSON revelaria. |
💡 Dica de design: degradação honesta
No screenshot, a skill faz a parte que dá (nomes, estrutura, conexões faltando) e fecha com: "Compartilhe o JSON para uma auditoria completa, incluindo expressões e parâmetros." Nunca finge ter visto o que não viu. Essa honestiade é o que evita que a saída seja confiada cega.
🌐 Dica: responda no idioma do usuário
Regra explícita do SKILL.md: responda sempre no idioma em que a pessoa escreve, mesmo que os rótulos do workflow estejam em outro idioma. Um workflow com nodes em alemão e uma pergunta em português recebe a resposta em português.
Aceita o que a pessoa tem na mão.
Declara o que assumiu antes de revisar.
Diz o que não pôde avaliar.
Se vago, pede UMA coisa específica.
🚦 As cinco categorias da revisão
O coração da skill é um framework fixo de cinco categorias que rodam sempre, na mesma ordem, sem pular nenhuma. Se uma categoria está limpa, a skill diz isso em uma linha e segue. Rodar o mesmo checklist toda vez é o que remove o viés do revisor.
🔴 Erros & quebras
O que vai falhar de fato: campo obrigatório vazio, credencial hardcoded, expressão referenciando campo inexistente, conexão faltando, método HTTP errado, IF/Switch sem fallback.
🟡 Erro silencioso
Não quebra agora, falha calado depois: sem Error Trigger, HTTP sem retry/timeout, escrita em banco sem checar duplicata, nenhum alerta na falha.
🔵 Performance & eficiência
Funciona, mas custa tempo/dinheiro/chamadas: API desnecessária, sem paginação, loop onde caberia batch, gatilho frequente demais, Set nodes redundantes.
🟢 Estrutura & manutenibilidade
O que vira pesadelo em 6 meses: nodes "HTTP Request1", sem sticky notes, lógica de negócio enterrada em expressão, workflow gigante que devia virar subworkflow.
✅ Resumo & lista de prioridades
Fecha com correções rankeadas em três níveis — agora / depois / opcional — mais uma nota de 0 a 10 com um veredito de uma frase.
📊 Por que cinco categorias fixas funcionam
- • Cobertura garantida: "não pule nenhuma categoria" impede que a revisão pare no primeiro erro óbvio.
- • Severidade legível: as cores 🔴🟡🔵🟢 dizem em um relance o que é urgente e o que é polimento.
- • Repetível: dois workflows diferentes recebem a mesma lente — comparável e sem humor do dia.
Sempre as cinco, na ordem.
🔴 quebra · 🟡 silêncio · 🔵 custo.
Diz numa linha quando está OK.
Agora / depois / opcional + nota.
🔇 A falha silenciosa
Esta é a categoria mais valiosa e a mais ignorada. O erro que aparece é fácil: ele grita, alguém conserta. O erro que some — o registro que não foi gravado, o lead que não entrou, o webhook que retornou 500 e ninguém viu — é o que corrói a confiança no sistema inteiro. A categoria 🟡 existe para caçar exatamente esses.
✓ Salvaguardas que a skill cobra
- ✓Um Error Trigger conectado a um alerta (Slack, e-mail).
- ✓Retry e timeout nos nodes HTTP de longa duração.
- ✓Validação de resposta nos webhooks.
- ✓Checagem de duplicata antes de escrever em banco/Airtable.
- ✓Decisão consciente de "Continue on Fail" (às vezes liga, às vezes não).
✗ Sintomas de falha silenciosa
- ✗"O workflow roda, mas alguns registros não atualizam."
- ✗"Funciona quando testo, mas falha de vez em quando."
- ✗Nenhuma notificação quando uma execução falha de madrugada.
- ✗Duplicatas se acumulando porque nada checa antes de inserir.
- ✗Um Schedule Trigger desconectado que ninguém percebeu.
O formato de cada achado 🟡
⚠️ [Node ou seção] — [salvaguarda faltando] Risco: [o que vai quebrar em silêncio] Fix: [o que adicionar, concreto]
Repare nos três campos: onde, qual o risco e o conserto. Sem o risco explícito, ninguém prioriza; sem o fix, ninguém age.
A rede de segurança mínima.
API instável não derruba o fluxo.
Você sabe antes do cliente.
A pergunta que guia a categoria.
💸 Custo e manutenibilidade
As categorias 🔵 e 🟢 cuidam do que não quebra hoje mas custa caro amanhã: a 🔵 olha o dinheiro e o tempo que o workflow desperdiça em produção; a 🟢 olha as horas que o "você de daqui a 6 meses" vai perder tentando entender o que cada node faz.
✓ Workflow eficiente e legível
- ✓Operação em batch no lugar de loop item a item.
- ✓Paginação tratada para datasets grandes.
- ✓Busca só os campos que vai usar, não o objeto inteiro.
- ✓Nodes com nome descritivo e sticky notes na lógica complexa.
- ✓Seções claras: entradas → processamento → saídas.
✗ O que sangra custo e tempo
- ✗Loop fazendo 1 chamada de API por item — paga por cada uma.
- ✗Gatilho a cada minuto quando a cada hora resolveria.
- ✗Nodes "Set3" e "HTTP Request1" — ninguém sabe o que fazem.
- ✗Lógica de negócio enterrada numa expressão de 200 caracteres.
- ✗Um workflow monstro que devia ser três subworkflows.
🔵 O formato do achado de performance
🔵 [Node ou padrão] — [ineficiência] Impacto: [custo / velocidade / confiabilidade] Otimização: [melhoria específica]
💡 Dica: o teste dos "6 meses"
A pergunta-guia da categoria 🟢 é: "se eu abrir este workflow daqui a 6 meses, sem contexto, entendo em 2 minutos?" Se a resposta é não, há um achado de manutenibilidade — e o fix é quase sempre renomear node, extrair lógica para um Set node ou adicionar uma sticky note.
Menos chamadas, menos custo.
Datasets grandes não estouram.
"Buscar contatos" > "HTTP Request1".
Documentam a lógica difícil.
🏗️ Construir o seu reviewer
Agora você junta tudo num SKILL.md autoral. A estrutura é replicável para revisar qualquer artefato técnico — basta trocar o domínio e o checklist. O que faz o reviewer ser bom não é o n8n: é o tom direto, o formato de achado e o veredito honesto.
Prompt copiável — esqueleto do SKILL.md
---
name: workflow-reviewer
description: Reviews automation workflows for errors, inefficiencies and
missing best practices. Use whenever a user shares a workflow JSON,
pastes node configs, describes their setup in plain text, sends an
error message, or asks "what's wrong with my automation". Trigger
even on a partial workflow or a single node.
---
# Workflow Reviewer
You are an expert automation engineer doing a senior code review.
No fluff, no vague advice. Name the exact node. Give the exact fix.
## Run ALL five categories, in order. Skip none.
1. 🔴 ERRORS & BREAKS — what will fail in production
2. 🟡 MISSING ERROR HANDLING — what will fail silently
3. 🔵 PERFORMANCE — unnecessary calls, cost leaks, slow loops
4. 🟢 STRUCTURE — naming, maintainability, subworkflow candidates
5. ✅ SUMMARY — priority fix list + OVERALL SCORE: [X/10]
For each finding use:
[emoji] [Node Name] — [issue]
Fix: [exact fix, 1-2 sentences]
If a category is clean, say so in one line. If the input is too vague,
ask ONE specific question. If it's well-built, say so — don't invent problems.
Exemplo de saída — auditoria real (recriação ilustrativa)
🔴 ERRORS & BREAKS
❌ Schedule Trigger — node desconectado do resto do fluxo.
Fix: conecte a saída do Schedule Trigger ao node "Buscar leads".
❌ Parse JSON — expressão {{ $json.data.items }} quebra quando a API
retorna {error}. Fix: adicione um IF checando $json.error antes do parse.
🟡 MISSING ERROR HANDLING
⚠️ HTTP Request "Enviar Slack" — sem retry nem alerta.
Risco: notificação some se o Slack der 429. Fix: ative retry (3x) e
conecte um Error Trigger a um e-mail de fallback.
⚠️ Airtable "Inserir" — sem checagem de duplicata.
Risco: leads duplicados a cada re-execução. Fix: use "Upsert" pela chave email.
🔵 PERFORMANCE
🔵 Loop "Para cada lead" — 1 chamada HTTP por item.
Impacto: ~600 chamadas/dia, custo e lentidão. Otimização: troque por
uma chamada batch enviando o array inteiro.
🟢 STRUCTURE
🟢 Nodes "Set3", "HTTP Request1" — nomes default.
Sugestão: renomeie para "Montar payload" e "Buscar perfil".
✅ SUMMARY
PRIORITY FIXES (do these now):
1. Conectar o Schedule Trigger.
2. Tratar o parse de JSON na resposta de erro.
3. Adicionar Error Trigger + retry no Slack.
IMPROVEMENTS (next): batch no loop; upsert no Airtable.
OPTIONAL: renomear nodes; sticky notes nas seções.
OVERALL SCORE: 5/10 — funciona no caminho feliz, frágil em produção.
Saída recriada para fins didáticos — ilustra o formato, não é um relatório real de cliente.
⭐ As regras de tom que fazem a diferença
- • Seja direto: "isso vai quebrar em produção" > "você pode querer considerar...".
- • Nomeie o node exato: feedback vago é inútil.
- • Dê o conserto, não a direção: "adicione um Error Trigger ligado a um Slack" > "adicione tratamento de erro".
- • Elogie o que está bom: se o workflow é sólido, diga — não invente problema.
- • Quando perguntam "está bom?": dê nota honesta + os 3 maiores problemas; não só valide.
✍️ Exercícios práticos
Revise um fluxo seu. Pegue um workflow que você tenha (ou descreva um em texto) e rode mentalmente as cinco categorias. Anote ao menos um achado 🟡 de falha silenciosa que você nunca tinha notado.
Crie um SKILL.md rodável. Copie o esqueleto acima para ~/.claude/skills/workflow-reviewer/SKILL.md, ajuste a description com seus gatilhos e teste pedindo ao Claude para revisar um fluxo descrito em texto.
Generalize. Troque o domínio: adapte o reviewer para auditar um schema de banco ou um arquivo de configuração de CI. Quais das cinco categorias mudam? Quais permanecem idênticas?
Teste o "está bom?". Peça ao seu reviewer para avaliar um fluxo deliberadamente bem-feito. Ele resiste à tentação de inventar problemas e dá uma nota alta honesta?
📌 Resumo do Módulo
Próximo Módulo:
4.2 — 🔥 Local Leads Abundance System: encadear várias skills num pipeline multi-agente.