Una especificación de workflow n8n desde una descripción de una línea

La mayoría de los prompts de «hazme un workflow de n8n» te devuelven el camino feliz y nada más. Describes una automatización, el modelo arma una cadena limpia de trigger a acción y todo se ve terminado. Hasta que el proveedor del webhook reintenta tras un timeout, el workflow se dispara dos veces y le mandas el mismo correo de factura a un cliente que ya pagó. El fallo nunca estuvo en los nodos que ves. Estuvo en el reintento, en el duplicado y en el crash de las 3am que nadie especificó. Esta plantilla obliga a meter todo eso en el diseño desde el principio. Abajo tienes el prompt completo, luego cómo leer su salida, cómo adaptarlo, las variables que tocas, algunas variantes y los detalles a cuidar que de verdad muerden.

01 · La plantilla

Esto es todo. Pégala en Claude (o en cualquier chat capaz) como tu primer mensaje, reemplaza los dos placeholders entre corchetes y deja que produzca una especificación que puedas revisar antes incluso de abrir n8n.

Eres un ingeniero de automatización senior diseñando un workflow de n8n. Te voy
a dar una descripción en lenguaje sencillo. Produce una ESPECIFICACIÓN nodo por
nodo, no un JSON terminado ni un discurso de venta. Asume que esto va a correr
sin supervisión en producción.

QUÉ QUIERO AUTOMATIZAR:
[UNA A TRES FRASES — el trigger, los pasos, y cómo se ve "listo"]

ENTORNO:
[DÓNDE CORRE + QUÉ TOCA — p. ej. n8n self-hosted, habla con Stripe + Postgres +
un canal de Slack; o: n8n Cloud, solo un webhook entrante y un email]

Produce la especificación en exactamente estas secciones:

1. TRIGGER
   - Tipo de nodo (Webhook / Schedule / trigger de app) y por qué.
   - El payload exacto que recibe (lista los campos que de verdad vas a usar).
   - ¿Puede este trigger dispararse más de una vez para el mismo evento lógico?
     (Los webhooks reintentan ante una respuesta non-2xx. Los schedules se
     traslapan si una ejecución va lenta.) Dilo.

2. PLAN NODO POR NODO
   - Numera cada nodo. Por cada uno: tipo, propósito en una línea, los campos
     de entrada clave que lee y la salida clave que produce.
   - Marca cada nodo que produzca un EFECTO SECUNDARIO (envía, cobra, escribe,
     borra) — esos son los que nunca deben correr dos veces.

3. IDEMPOTENCIA (esto no te lo saltes)
   - ¿Cuál es la CLAVE de dedup para este evento? (un id de orden, un id de
     mensaje, un hash del payload: algo estable entre reintentos.)
   - ¿Dónde dejamos registrado "ya procesado"? (una fila en la DB, un SETNX de
     Redis, una verificación en el static data de n8n, una restricción única que
     haga que el segundo insert falle a gritos.)
   - Por cada nodo de efecto secundario del paso 2, di exactamente cómo se evita
     una re-ejecución o cómo se hace seguro repetirla.

4. MANEJO DE ERRORES
   - ¿Qué nodos pueden fallar de verdad (red, auth, rate limit, datos malos)?
   - El workflow de Error Trigger: qué se registra, qué dispara alerta y si el
     item se reintenta, se manda a dead-letter o se descarta.
   - Distingue fallos REINTENTABLES (timeouts) de fallos VENENOSOS (input malo
     que nunca va a funcionar): necesitan manejo distinto.

5. SECRETOS Y ACCESO
   - Lista cada credencial que haga falta SOLO POR NOMBRE (p. ej. "Stripe API
     key", "Postgres prod read-write"). Nunca devuelvas un valor ni un
     placeholder que parezca uno.
   - Anota el alcance mínimo que necesita cada credencial. Marca cualquier cosa
     que correría con más acceso del que pide la tarea.

6. CHECK DE COMPLEJIDAD (sé honesto)
   - Si algún paso necesita más de ~3 nodos de branching/looping/reshaping,
     dilo y esboza la versión con nodo Code o servicio externo.
   - Si todo el asunto va camino de pasar de ~15 nodos, nombra la costura donde
     debería volverse un sub-workflow llamado o pasar a código de verdad.

REGLAS:
- Sin lenguaje de marketing. Nada de "sin fricción", "robusto", "potente".
- Si a mi descripción le falta algo que necesitas (una clave de dedup, una
  política de error, una credencial), PREGUNTA antes de adivinar: lista los
  huecos como preguntas.
- Prefiere menos nodos. Un workflow que puedo leer a las 3am le gana a uno
  ingenioso.

02 · Cómo leer la especificación que te da

La salida es un documento de revisión, no una orden de armado. Léela en un orden concreto, porque los errores baratos se esconden siempre en el mismo sitio.

1. Lee primero la sección 3. Si la idempotencia está contada en vago, tipo "verificamos si ya existe", sin nombrar la clave ni el store, el resto de la especificación está armado sobre arena. Un efecto secundario sin clave de dedup tarde o temprano se dispara doble. Es solo cuestión de tráfico.
2. Cruza la 2 contra la 3. Cada nodo marcado como efecto secundario en la sección 2 tiene que tener su frase correspondiente en la sección 3 explicando cómo se hace segura una re-ejecución. Un nodo de efecto secundario sin línea de idempotencia es el bug que estás a punto de entregar.
3. Después lee la sección 4 junto con la 3. Reintentos e idempotencia son el mismo problema visto desde dos lados. La sección 4 decide qué reintentar, la sección 3 hace que el reintento sea seguro. Si se contradicen, tipo "reintenta tres veces" sin dedup, esa es la contradicción que tienes que resolver antes de armar nada.
4. La sección 5 es una auditoría de fugas. Revísala buscando cualquier valor que parezca real. Si el modelo escribió una key o una URL con pinta de verdadera, eso es un fallo del prompt. Regenera.

03 · Las tres cosas que esto fuerza y que de otro modo olvidarías

Una clave de dedup que sobreviva a un reintento

Los proveedores de webhooks reintentan ante cualquier respuesta non-2xx, incluido el timeout en el que tu workflow en realidad sí funcionó pero respondió lento. El propio n8n vuelve a ejecutar workflows en el retry manual y en algunas reentregas del queue mode. Así que "¿esto ya corrió?" es una pregunta que cada nodo de efecto secundario tiene que poder responder, y la única forma honesta de responderla es con una clave derivada del evento, como un id de orden, un id de evento de Stripe o un id de mensaje, que verificas contra un store antes de correr el efecto secundario.

-- El store de dedup confiable más barato: una restricción única que hace que el
-- segundo intento falle a gritos en vez de actuar dos veces. Inserta ANTES del
-- efecto secundario; si el insert falla por conflicto, el evento ya se manejó.
create table processed_events (
  event_key   text primary key,
  workflow    text not null,
  processed_at timestamptz not null default now()
);

-- En el workflow: intenta el insert primero.
insert into processed_events (event_key, workflow)
values ('stripe_evt_3Nq...redactado', 'invoice-paid')
on conflict (event_key) do nothing
returning event_key;
-- 0 filas devueltas -> ya procesado, DETENTE. 1 fila -> sigue.

Una ruta de error que distinga reintentable de veneno

Un timeout hay que reintentarlo; un payload mal formado, no: reintentarlo solo quema ejecuciones y te vuelve a alertar para siempre. La especificación obliga a hacer esa división para que tu workflow de Error Trigger sepa la diferencia entre "vuelve a intentar en un minuto" y "este item nunca va a funcionar, mándalo a dead-letter y sigue".

Secretos que existen solo por nombre

Una especificación que lista "Stripe API key (solo scope de cobro), Postgres prod (read-write a processed_events + invoices)" es un checklist de credenciales que puedes pasarle a tu setup de secretos. El mismo instinto detrás de Infuse, donde el valor nunca vive dentro de la cosa que lo usa. Una especificación que pega una key en un parámetro de nodo es una fuga esperando a que la subas a un export del workflow.

04 · Variables y cómo adaptarla

La plantilla tiene dos placeholders entre corchetes y varias perillas que puedes mover.

• [UNA A TRES FRASES] es tu automatización en palabras sencillas. Nombra el trigger, los pasos y qué significa "listo". Una frase honesta le gana a tres rellenas de paja. Y si además puedes decir qué es lo que no debe pasar dos veces, dilo. Eso prepara la sección de idempotencia.
• [DÓNDE CORRE + QUÉ TOCA] es lo que vuelve concretas las secciones de secretos y de errores. "n8n self-hosted detrás de Traefik, habla con Stripe + Postgres + Slack" produce una especificación mucho más afilada que dejarlo en blanco, porque el modelo sabe qué credenciales y qué modos de fallo entran siquiera en juego.

Las perillas que vale la pena mover:

1. El techo de complejidad. La plantilla usa ~15 nodos como la línea a partir de la cual sugiere partir en un sub-workflow o pasar a código. Bájalo a ~8 si mantienes tus workflows chicos a propósito. Súbelo solo si de verdad tienes un pipeline lineal largo sin branching.
2. El store de dedup. Si no corres Postgres, cambia el enfoque de restricción única de la sección 3 por lo que tengas a mano: el SETNX de Redis, el static data del workflow de n8n o una clave única en tu sistema destino. La idea es "store nombrado", no "Postgres".
3. La regla de preguntar-antes-de-adivinar. Es muro de carga. Si lo que quieres es un borrador totalmente sin supervisión, cámbiala por "haz el supuesto más seguro y márcalo", pero entonces te toca leer las marcas, porque una clave de dedup adivinada es peor que no tener especificación.

05 · Variantes

Mismo esqueleto, distinto énfasis. Adapta la lista de secciones al trabajo que tengas.

• Disparado por Schedule, no por webhook. Los triggers de cron e intervalo no reintentan, pero se traslapan. Si una ejecución tarda más que el intervalo, n8n puede arrancar la siguiente antes de que termine la primera. Reemplaza el lenguaje de reintento de webhook en la sección 1 por una pregunta de traslape, "¿pueden estar corriendo dos ejecuciones de esto a la vez?", y haz que la especificación defina un run-lock (un flag en el static data de n8n o un lock a nivel de fila en tu DB) para que una ejecución lenta no quede pisada por la siguiente.
• Fan-out / procesamiento en lote. Cuando el workflow itera sobre muchos items (filas, archivos, destinatarios), la idempotencia tiene que ser por item, no por ejecución. Pídele a la especificación que haga la clave de dedup a nivel de item y que defina el comportamiento ante un fallo parcial: si el item 47 de 200 falla, ¿el lote se detiene, salta-y-sigue o hace rollback? Esta es la variante donde la mayoría de los equipos entrega un bug silencioso.
• Paso de IA en el medio. Si un nodo llama a un LLM, agrega una sección para el contrato de structured output (la forma JSON exacta que esperas de vuelta) y un fallback para cuando el modelo devuelva algo fuera de forma. Esto se parece a cómo se prepara un pipeline estilo Agent Orchestra. La salida del modelo es solo otro input no confiable, y el workflow tiene que validarla como tal.

06 · Detalles a cuidar

Los modos de fallo, más o menos en orden de cuán seguido muerden:

• Sin clave de dedup, acción doble silenciosa. La omisión más cara de todas. Un efecto secundario sin verificación de idempotencia funciona en todas las pruebas (solo disparas una vez) y falla en producción (el webhook reintenta). Nunca dejes pasar la revisión a un nodo de efecto secundario sin una clave nombrada.
• Una clave de dedup que cambia en el reintento. Peor que no tener ninguna, porque parece que está resuelta. Un timestamp, un id aleatorio o now() como clave no deduplica nada. La clave tiene que salir del evento para que el reintento produzca la misma clave.
• Insertar el registro de dedup DESPUÉS del efecto secundario. Si mandas el correo y después registras "procesado", un crash en el medio hace que el próximo reintento lo vuelva a mandar. Registra primero (o usa una restricción que falle antes de la acción), y luego actúa.
• Reintentar veneno para siempre. Un payload mal formado reintentado en el mismo horario que un timeout te va a volver a alertar en cada ciclo hasta que silencies la alerta, y ahí te quedas volando a ciegas. Separa lo reintentable de lo venenoso en la sección 4.
• El monstruo de 40 nodos. n8n es excelente pegamento y mal lugar para criar lógica de aplicación. Cuando la sección 6 te dice que muevas un paso a un nodo Code o a un servicio de verdad, no es el modelo tirando la toalla. Es la llamada honesta. Un workflow que no puedes leer a las 3am es un pasivo, no una automatización.

Una buena especificación de n8n no te dibuja el canvas. Saca a la luz el reintento, el duplicado y el crash mientras todavía son baratos de manejar. Lee primero la sección de idempotencia, haz que cada efecto secundario demuestre que no puede dispararse doble y trata el check de complejidad como permiso para dejar de cablear y empezar a programar. El objetivo no es un workflow terminado. Es uno que sigue haciendo lo correcto la segunda vez que llega el webhook.