🔄 El ciclo en una frase
Plan (define el qué y el cómo) → Build (la IA construye y valida) → Solución de problemas (devuelves el error con contexto) → Optimize (mejoras por capas). Y, para todo: verifica de verdad y haz un respaldo antes de cada cambio.
El ciclo no es una línea recta con un final: después de optimizar, normalmente vuelves a depurar (¿el cambio rompió algo?) o incluso a planificar (surgió un requisito nuevo). Por eso se dibuja como un loop, y la copia de seguridad es lo que hace que ese loop sea seguro.
Diagrama ilustrativo — el ciclo es un loop, no una fila. El coordinador (la IA) lee el error que le devuelves y propone la corrección; optimizar suele llevarte de nuevo a depurar.
🗺️ Fase 1 — Plan
Qué es
La fase de alineación. En el Plan Mode, la IA investiga los recursos adecuados, hace preguntas para aclarar (¿intervalo? ¿columnas? ¿qué cuenta como «urgente»?) y propone un plan numerado para que lo apruebes. Todavía no construiste nada: estás definiendo qué y cómo, en la etapa en que cambiar de idea cuesta menos.
¿Qué es?Preguntas aclaratorias — las preguntas que plantea la IA antes de construir (formato de salida, fuente de datos, casos de excepción). Responderlas bien es la mitad del trabajo.
Por qué aprender
Omitir el plan es la causa nº 1 de trabajo repetido: la IA construye una cosa, tú querías otra y ahora hay nodos que rehacer. Acordar el plan cuesta una conversación; ponerse de acuerdo después cuesta una reconstrucción.
🎯 Objetivo: obtener un plan que se pueda aprobar antes de cualquier 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.
✅ Cómo verificar: la respuesta incluye preguntas + un plan + la lista de credenciales. Respondes, ajustas el plan y lo apruebas; solo entonces empieza el build.
Conceptos clave
Recursos adecuados.
Resolver dudas antes.
Numerado y aprobable.
Tú das el "ok".
🏗️ Fase 2 — Build
Qué es
Con el plan aprobado, la IA construye el workflow/proyecto y se valida sola lo que puede hacer (corrige automáticamente los problemas de validación). En bypass permissions, la ejecuta sin pedir confirmación a cada paso. Recuerda: el resultado puede variar entre ejecuciones; no compares pantalla por pantalla.
Por qué aprender
Observar el build desde temprano tiene dos beneficios: aprendes cómo funciona el sistema y puedes interrumpir rápido si la IA se desvía — ahorrando tiempo y tokens. El bypass acelera, pero dejas de ver cada paso; úsalo con criterio.
🎯 Objetivo: construir lo que se aprobó y validar antes de probar.
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.
✅ Cómo verificar: el build aparece armado y validado; la IA enumera lo que es manual. No intentes probarlo antes de saber qué falta configurar.
🎯 Consejo práctico
Si tu versión tiene nombres y diseño diferentes a los de un tutorial, no pasa nada: la IA es no determinista. Evalúa el comportamiento final, no la apariencia paso a paso.
Conceptos clave
La IA se corrige automáticamente.
Sin interrumpir.
Interrumpe si falla.
Esperada, no es un defecto.
🙅 Lo que la IA NO hace
Qué es
La frontera de lo automático. Algunas etapas te necesitan: crear credenciales OAuth (iniciar sesión con tu cuenta), crear la hoja de cálculo/carpeta de destino, y mapear campos (indicar qué valor va en cada columna). Y la regla de oro: la clave/el secreto nunca en el chat — solo en un archivo de entorno.
¿Qué es?OAuth — la forma segura de autorizar a una app para acceder a tu cuenta (Gmail, Sheets) sin entregar la contraseña. Mapear campos — vincular cada dato de entrada (remitente, asunto) con la columna o salida correcta.
✓ La IA hace
- ✓Elegir y armar los nodos/archivos.
- ✓Validar y corregir automáticamente lo que se pueda.
- ✓Sugerir las columnas y el mapeo.
- ✓Decirte exactamente qué falta hacer a mano.
✗ Tú lo haces (manual)
- ✗Crear las credenciales OAuth (iniciar sesión en las cuentas).
- ✗Crear la hoja de cálculo/carpeta de destino.
- ✗Confirma el mapeo final de los valores.
- ✗Guarda la clave en el .env — nunca la pegues en el chat.
Por qué aprender
Sin conocer los límites, te quedas esperando a que la IA haga algo que solo tú puedes hacer (autorizar tu propia cuenta) o, peor aún, pegas una clave en el chat por impaciencia. Conocer esa división acelera el build y mantiene los secretos seguros.
🎯 Objetivo: obtener una lista de verificación de lo que debe hacerse manualmente antes de probar.
Antes de que yo haga las pruebas, dame una lista de verificación de lo que SOLO YO puedo hacer: - Qué credenciales OAuth crear y en qué nodos/servicios. - Qué destinos necesito crear (hoja de cálculo, carpeta) y con qué columnas. - Cómo se mapea cada campo de entrada a la salida. Para las claves y los secretos, dime dónde colocarlos en el archivo de entorno; nunca me pidas que pegue una clave aquí en el chat.
✅ Cómo verificar: recibes una lista clara de acciones manuales. Ninguna instrucción te pide pegar secretos en el chat.
Conceptos clave
Tú autorizas.
Crea la hoja de cálculo/carpeta.
Valor → columna.
Nunca en el chat.
🔧 Fase 3 — Troubleshoot
Qué es
Cuando algo se rompe, lo correcto es devolver el error con contexto: copia el mensaje completo, indica en qué nodo/paso ocurrió y qué esperabas, y pide un diagnóstico + causa + corrección. La IA lee los inputs/outputs de cada paso y lo corrige. Después vuelves a ejecutarlo: una corrección a la vez.
Diagrama ilustrativo — leer la entrada, el paso y la salida esperada permite localizar el error. Lo que la IA necesita es el mensaje literal + dónde ocurrió.
Por qué aprender
"Hubo un error" sin contexto se convierte en una adivinanza. El mensaje exacto + el lugar + lo que esperabas transforman el problema en una solicitud accionable — y la IA suele encontrar la causa real (un formato de modelo incorrecto, una expresión de tiempo no válida, un campo leído con mayúsculas diferentes) y corregirla rápido.
🎯 Objetivo: devolver el error de forma que la IA lo corrija a la primera.
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.
✅ Cómo verificar: la IA explica la causa y aplica una corrección puntual. Recarga o vuelve a ejecutar; si sigue fallando, repite la plantilla con el nuevo error.
Conceptos clave
Pega exactamente.
Qué nodo/paso.
Pide la causa.
Sin tocar el resto.
⚡ Fase 4 — Optimize
Qué es
Con lo básico funcionando, «funciona» pasa a ser «funciona bien». Mejoras en capas, en orden de prioridad: (1) manejo de errores: qué se rompe; (2) lógica: qué es ineficiente; (3) calidad del resultado: la experiencia (formato, firma); (4) rendimiento: velocidad desde el disparador hasta la entrega. Un cambio a la vez, probando en cada paso.
¿Qué es?Caso límite (edge case) — situación inusual que puede romper el flujo (correo sin firma, campo vacío, remitente automático). Optimizar consiste, en gran parte, en cubrir estos casos.
Por qué aprender
Pulir el resultado antes de tratar el error es una pérdida de tiempo: un correo bonito no sirve de nada si no llega. El orden de prioridad garantiza que dediques energía donde el retorno es mayor, y hacer un cambio a la vez permite localizar cada problema.
🎯 Objetivo: optimizar en una capa a la vez, basándote en lo que ya 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.
✅ Cómo verificar: la IA edita el workflow indicado por nombre (no crea otro), explica el cambio e indica la prueba exacta. Prueba solo esta capa antes de pasar a la siguiente.
Conceptos clave
Una a la vez.
Error > lógica > salida.
Nombra el workflow.
En cada capa.
🔬 Verificación y pruebas reales
Qué es
La habilidad que atraviesa todas las fases: probar con escenarios reales (el camino ideal, los casos límite y lo que queda fuera del alcance), compara números y datos con la fuente y exige que el agente niégate a inventar lo que no sabe. La regla de oro sigue siendo: verde ≠ correcto — que se ejecute sin errores no demuestra que la respuesta sea correcta.
Por qué aprender
Para probar un filtro, necesitas enviar exactamente el tipo de entrada que debe detectar. Una prueba «fuera de alcance» (p. ej., preguntar algo que no está en la base) revela si el agente es honesto o si alucina. Un buen agente dice «no tengo esa información»; eso es deseable, no un error.
🎯 Objetivo: armar un plan de pruebas que cubra casos exitosos, límite y fuera de alcance.
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.
✅ Cómo verificar: ejecutas los tres tipos. El caso esperado acierta el contenido (no solo aparece "verde"); el caso fuera de alcance genera una negativa honesta, no una respuesta inventada.
🎯 Consejo práctico
Verifica los números con precisión: "30 días" y "un año" son respuestas diferentes. Abre el resultado y compáralo con la fuente; no confíes solo en el indicador verde.
Conceptos clave
Ejecutarse no es acertar.
Feliz, borde, fuera.
Números y fuentes.
"No sé" es bueno.
💾 Hacer una copia de seguridad antes de cambiar
Qué es
La disciplina que hace seguro el ciclo: antes de cualquier cambio, haz un copia de seguridad (duplica o exporta en JSON) y establece una línea base probada. Así, si la siguiente optimización rompe algo, puedes revertirla sin perder lo que ya funcionaba.
¿Qué es?Export JSON — guardar el workflow como un archivo de texto que puedes volver a importar para restaurar exactamente el estado anterior. Línea de base — una versión que confirmaste que funciona, usada como punto de retorno.
Por qué aprender
Sin una línea de base, corres dos riesgos: no poder volver atrás cuando algo salga mal, y culpar al cambio nuevo por un problema que ya existía. Confirmar que el flujo correcto funciona antes y después de cada cambio mantiene el diagnóstico honesto.
🎯 Objetivo: crear una línea base segura antes de optimizar.
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.
✅ Cómo verificar: tienes un archivo de respaldo guardado y una prueba del caso esperado aprobada. Si algo se rompe después, vuelves a importar el JSON y recuperas el estado correcto.
Conceptos clave
Guarda antes.
Punto de retorno.
Vuelve a importar y regresa.
No culpes al nuevo.
Tu flujo se ejecutó sin ningún error (todo en verde), pero al abrir el borrador ves que citó "un año" cuando la política dice "30 días". ¿Qué significa esto?
📌 Resumen del módulo
Siguiente módulo:
3.3 — Biblioteca de prompts listos (copy-run)