🔄 O ciclo em uma frase
Plan (alinha o quê e o como) → Build (a IA constrói e valida) → Troubleshoot (você devolve o erro com contexto) → Optimize (você melhora em camadas). E, em volta de tudo: verifique de verdade e tenha um backup antes de cada mudança.
O ciclo não é uma linha reta com fim: depois de otimizar você costuma voltar a depurar (a mudança quebrou algo?) ou até a planejar (surgiu um requisito novo). Por isso ele é desenhado como um loop — e o backup é o que torna esse loop seguro.
Diagrama ilustrativo — o ciclo é um loop, não uma fila. O coordenador (a IA) lê o erro que você devolve e propõe a correção; otimizar costuma realimentar depurar.
🗺️ Fase 1 — Plan
O que é
A fase de alinhamento. No Plan Mode, a IA pesquisa os recursos certos, faz perguntas de esclarecimento (intervalo? colunas? o que conta como "urgente"?) e propõe um plano numerado para você aprovar. Você ainda não construiu nada — está definindo o quê e o como, na fase mais barata de mudar de ideia.
O que é?Perguntas de esclarecimento — as dúvidas que a IA levanta antes de construir (formato de saída, fonte de dados, casos de exceção). Respondê-las bem é metade do trabalho.
Por que aprender
Pular o plano é a causa nº 1 de retrabalho: a IA constrói uma coisa, você queria outra, e agora há nós para refazer. Alinhar no plano custa uma conversa; alinhar depois custa um rebuild.
🎯 Objetivo: obter um plano aprovável antes de qualquer build.
Entre em plan mode. Quero <descreva o resultado, ex.: "um workflow que monitora o Gmail por e-mails com 'urgente' no assunto e registra cada um numa planilha">. Antes de construir: 1. Pesquise os recursos/nós necessários. 2. Liste as perguntas de esclarecimento (colunas, ações extras, casos de exceção). 3. Apresente um plano numerado com a arquitetura e as credenciais que vou precisar. Não escreva nada até eu aprovar.
✅ Como verificar: a resposta traz perguntas + um plano + a lista de credenciais. Você responde, ajusta o plano e aprova — só então começa o build.
Conceitos-chave
Recursos certos.
Tirar dúvidas antes.
Numerado e aprovável.
Você dá o "ok".
🏗️ Fase 2 — Build
O que é
Com o plano aprovado, a IA constrói o workflow/projeto e valida sozinha o que consegue (corrige problemas de validação automaticamente). Em bypass permissions, ela executa sem pedir confirmação a cada passo. Lembre: a saída pode variar entre execuções — não compare tela a tela.
Por que aprender
Assistir ao build cedo tem dois ganhos: você aprende como o sistema funciona e consegue interromper rápido se a IA sair do trilho — economizando tempo e token. O bypass acelera, mas você deixa de ver cada passo; use com critério.
🎯 Objetivo: construir o que foi aprovado e validar antes de testar.
Aprovado. Construa exatamente o plano acima. Ao terminar: - Valide o que foi criado e corrija problemas de validação automaticamente. - Me diga claramente o que ainda preciso fazer à mão (credenciais, mapeamento, criar destinos). - Não considere "pronto" sem antes apontar o que falta para eu testar.
✅ Como verificar: o build aparece montado e validado; a IA lista o que é manual. Você não tenta testar antes de saber o que ainda falta configurar.
🎯 Dica prática
Se a sua versão tiver nomes e layout diferentes de um tutorial, tudo bem: a IA é não-determinística. Avalie pelo comportamento final, não pela aparência passo a passo.
Conceitos-chave
A IA auto-corrige.
Sem interromper.
Interrompa se errar.
Esperada, não defeito.
🙅 O que a IA NÃO faz
O que é
A fronteira do automático. Algumas etapas precisam de você: criar credenciais OAuth (logar com a sua conta), criar a planilha/pasta de destino, e mapear campos (dizer qual valor vai em qual coluna). E a regra de ouro: chave/segredo nunca no chat — só em arquivo de ambiente.
O que é?OAuth — o jeito seguro de autorizar um app a acessar a sua conta (Gmail, Sheets) sem entregar a senha. Mapear campos — ligar cada dado de entrada (remetente, assunto) à coluna/saída correta.
✓ A IA faz
- ✓Escolher e montar os nós/arquivos.
- ✓Validar e auto-corrigir o que dá.
- ✓Sugerir as colunas e o mapeamento.
- ✓Te dizer exatamente o que falta fazer à mão.
✗ Você faz (manual)
- ✗Criar as credenciais OAuth (logar nas contas).
- ✗Criar a planilha/pasta de destino.
- ✗Confirmar o mapeamento final dos valores.
- ✗Guardar a chave no .env — nunca colar no chat.
Por que aprender
Sem saber a fronteira, você fica esperando a IA fazer o que só você pode (autorizar a sua própria conta) — ou, pior, cola uma chave no chat por impaciência. Saber a divisão acelera o build e mantém os segredos seguros.
🎯 Objetivo: obter um checklist do que é manual antes de testar.
Antes de eu testar, me dê um checklist do que SÓ EU posso fazer: - Quais credenciais OAuth criar e em quais nós/serviços. - Que destinos preciso criar (planilha, pasta) e com quais colunas. - Qual o mapeamento de cada campo de entrada para a saída. Para chaves/segredos, me diga onde colocá-los no arquivo de ambiente — nunca me peça para colar uma chave aqui no chat.
✅ Como verificar: você recebe uma lista clara de ações manuais. Nenhuma instrução pede que você cole segredos no chat.
Conceitos-chave
Você autoriza.
Crie planilha/pasta.
Valor → coluna.
Nunca no chat.
🔧 Fase 3 — Troubleshoot
O que é
Quando algo quebra, o reflexo certo é devolver o erro com contexto: copie a mensagem inteira, diga em qual nó/passo aconteceu e o que você esperava, e peça diagnóstico + causa + correção. A IA lê os inputs/outputs de cada passo e conserta. Depois você reexecuta — uma correção por vez.
Diagrama ilustrativo — ler a entrada, o passo e a saída esperada localiza o erro. O que a IA precisa é a mensagem literal + onde ela ocorreu.
Por que aprender
"Deu erro" sem contexto vira chute. A mensagem exata + o local + o que você esperava transformam o problema num pedido acionável — e a IA costuma achar a causa real (um formato de modelo errado, uma expressão de tempo inválida, um campo lido em caixa diferente) e corrigir rápido.
🎯 Objetivo: devolver o erro de forma que a IA conserte de primeira.
Apareceu um erro. Aqui está o contexto completo: - Onde aconteceu: <nó/passo, ex.: "nó Google Sheets append"> - O que eu esperava: <ex.: "que a linha fosse adicionada na planilha"> - O que aconteceu: <descreva o sintoma> - Mensagem de erro (literal): """ <cole a mensagem de erro exatamente como apareceu> """ Diagnostique a causa, explique por que aconteceu e corrija. Não mude mais nada além do necessário para resolver isso.
✅ Como verificar: a IA explica a causa e aplica uma correção pontual. Você recarrega/reexecuta; se ainda falhar, repita o template com o novo erro.
Conceitos-chave
Cole exatamente.
Qual nó/passo.
Peça a causa.
Sem mexer no resto.
⚡ Fase 4 — Optimize
O que é
Com o básico funcionando, "funciona" vira "funciona bem". Você melhora em camadas, em uma ordem de prioridade: (1) tratamento de erro — o que quebra; (2) lógica — o que é ineficiente; (3) qualidade da saída — a experiência (formatação, assinatura); (4) performance — velocidade do gatilho até a entrega. Uma mudança por vez, testando a cada passo.
O que é?Caso de borda (edge case) — situação incomum que pode quebrar o fluxo (e-mail sem assinatura, campo vazio, remetente automático). Otimizar é, em boa parte, cobrir esses casos.
Por que aprender
Polir a saída antes de tratar erro é perda de tempo: um e-mail bonito não vale nada se o e-mail não chega. A ordem de prioridade garante que você gasta energia onde o retorno é maior — e fazer uma mudança por vez mantém cada problema localizável.
🎯 Objetivo: otimizar em uma camada por vez, ancorado no que já existe.
No workflow já existente chamado "<nome exato do workflow>", aplique UMA melhoria: <descreva a mudança, ex.: "quando a busca não achar uma política, em vez de inventar, envie uma resposta dizendo que vamos pesquisar e retornar">. Não crie um workflow novo — edite este. Me explique o que vai mudar antes de aplicar, e depois me diga como testar essa mudança especificamente.
✅ Como verificar: a IA edita o workflow nomeado (não cria outro), explica a mudança e indica o teste exato. Você testa só essa camada antes da próxima.
Conceitos-chave
Uma por vez.
Erro > lógica > saída.
Nomeie o workflow.
A cada camada.
🔬 Verificação & testes de verdade
O que é
A habilidade que atravessa todas as fases: testar com cenários reais (caminho feliz, casos de borda e fora de escopo), conferir números e fatos contra a fonte, e exigir que o agente recuse inventar o que não sabe. A regra de ouro permanece: verde ≠ correto — rodar sem erro não prova que a resposta está certa.
Por que aprender
Para testar um filtro, você precisa enviar exatamente o tipo de entrada que ele deve pegar. Um teste "fora de escopo" (ex.: perguntar algo que não está na base) é o que revela se o agente é honesto ou se ele alucina. Um bom agente diz "não tenho essa informação" — e isso é desejável, não um bug.
🎯 Objetivo: montar um plano de teste que cubra feliz, borda e fora de escopo.
Monte um plano de teste para <descreva o que foi construído> com 3 categorias: 1. Caminho feliz: <ex.: uma pergunta dentro do escopo, com resposta na base>. 2. Caso de borda: <ex.: entrada incompleta / formato incomum>. 3. Fora de escopo: <ex.: algo que NÃO está na base> — aqui o agente deve dizer honestamente que não sabe, sem inventar. Para cada teste, diga: a entrada exata, o resultado esperado e como conferir (números/fatos contra a fonte). Lembre: green ≠ correto.
✅ Como verificar: você roda os três tipos. O caminho feliz acerta o conteúdo (não só "verde"); o fora de escopo gera uma recusa honesta, não uma resposta inventada.
🎯 Dica prática
Confira os números com precisão: "30 dias" e "um ano" são respostas diferentes. Abra o resultado e compare com a fonte — não confie só no indicador verde.
Conceitos-chave
Rodar não é acertar.
Feliz, borda, fora.
Números e fontes.
"Não sei" é bom.
💾 Backup antes de mudar
O que é
A disciplina que torna o ciclo seguro: antes de qualquer mudança, faça um backup (duplique ou exporte em JSON) e estabeleça uma linha de base testada. Assim, se a próxima otimização quebrar algo, você reverte sem perder o que já funcionava.
O que é?Export JSON — salvar o workflow como um arquivo de texto que você pode reimportar para restaurar exatamente o estado anterior. Linha de base — uma versão que você confirmou que funciona, usada como ponto de retorno.
Por que aprender
Sem linha de base, você corre dois riscos: não conseguir voltar quando algo der errado, e culpar a mudança nova por um problema que já existia. Confirmar que o caminho feliz funciona antes e depois de cada mudança mantém o diagnóstico honesto.
🎯 Objetivo: criar uma linha de base segura antes de otimizar.
Antes de eu começar a otimizar, me guie a: 1. Fazer um backup do estado atual (export em JSON ou duplicar) e onde salvá-lo. 2. Rodar um teste de caminho feliz para registrar a linha de base que funciona. Confirme que está tudo verde e correto AGORA. Só depois disso seguimos para as melhorias — uma de cada vez, testando após cada uma.
✅ Como verificar: você tem um arquivo de backup salvo e um teste de caminho feliz passando. Se algo quebrar depois, você reimporta o JSON e volta ao estado bom.
Conceitos-chave
Salve antes.
Ponto de retorno.
Reimporte e volte.
Não culpe o novo.
Seu fluxo executou sem nenhum erro (tudo verde), mas ao abrir o rascunho você vê que ele citou "um ano" quando a política diz "30 dias". O que isso significa?
📌 Resumo do Módulo
Próximo Módulo:
3.3 — Biblioteca de Prompts Prontos (copy-run)