🛠️ Cómo usar este módulo
Este es el módulo donde el prototipo se convierte en producto. No necesitas escribir código: quien escribe el TypeScript é o Claude Code. Tu papel es entender los dos lugares: dónde se guarda el código (GitHub) y dónde se ejecuta por su cuenta (Trigger.dev) — y saber dar las instrucciones correctas. Los bloques «copia y ejecuta» están listos para pegar en la terminal o en el chat de la IA.
Antes de los siete temas, fija el diseño general. En tu máquina el agente sí funciona, pero solo mientras tu computadora está encendida. En producción, el código reside en GitHub (con historial) y se ejecuta en Trigger.dev (en la nube, en el horario programado), con la IA escribiendo y tú supervisando desde el dashboard.
Diagrama ilustrativo — el ciclo de producción: iteras en Claude Code, el código se sube a GitHub y de ahí va a Trigger.dev, que lo ejecuta en la nube con confiabilidad. Los archivos más recientes de GitHub siempre están disponibles.
🐙 GitHub como almacenamiento de código
Qué es
O GitHub es almacenamiento de código en la nube. En vez de que tu proyecto viva solo en la carpeta de tu computadora, queda en un servidor al que se puede acceder desde cualquier lugar. La consecuencia práctica es grande: cuando llega el momento del deploy, la plataforma de alojamiento obtiene el código de la nube, no en tu computadora; así que puedes tener la PC apagada y la automatización seguirá funcionando.
¿Qué es?Repositorio (repo) — la carpeta de tu proyecto, con control de versiones, dentro de GitHub. Commit — una «instantánea» guardada con una descripción de lo que cambió. Push — el acto de enviar tus commits desde la máquina local a GitHub.
Cada commit guarda un punto en el tiempo. Eso te da un historial completo: si un cambio lo rompe todo, vuelves a un commit anterior y recuperas lo que funcionaba. Para automatizaciones que manejan datos o dinero, esta red de seguridad no es un lujo — es lo que te permite hacer cambios sin miedo. Crea el repo como privado e inicialízalo con un README.
Por qué aprender
GitHub es el requisito previo para el hosting. Las plataformas de deploy (incluido Trigger.dev) se integran directamente con el repo: subes el código y ellas se encargan del resto. Sin repo, no hay pipeline.
- •Accesible desde cualquier lugar: el código no queda atado a una computadora.
- •Historial para revertir: vuelve a cualquier commit anterior en segundos.
- •Integra con deploy: la fuente de verdad de la que la nube obtiene el código.
Conceptos clave
Carpeta del proyecto en la nube.
Snapshot con descripción.
Enviar a la nube.
Revertir cuando se rompa.
🚫 gh CLI y .gitignore — el .env nunca se sube
Qué es
A GitHub CLI (el comando gh) es la herramienta de línea de comandos que te autentica en GitHub y conecta el proyecto al repo, todo desde la terminal y sin abrir el sitio. El .gitignore es un archivo de texto que enumera lo que nunca debe subirse. Y la regla de oro de todo este módulo: el .env (que guarda tus claves de API) jamás puede ir a GitHub.
¿Qué es?.env — archivo local con secretos (claves de API, tokens). .gitignore — lista de archivos/carpetas que Git ignora y nunca envía. Claude Code agrega el .env al .gitignore automáticamente — pero es tu deber revisarlo.
Por qué aprender
Un .env filtrado es un secreto expuesto. Los repositorios se rastrean todo el tiempo; una clave expuesta puede usarse en minutos — y tú pagas la cuenta. El .gitignore es tu primera línea de defensa. Usa un nombre de usuario profesional (aparece en enlaces públicos), mantén el repo privado y no te extrañes si el terminal pide permiso para ejecutar comandos varias veces: es el comportamiento normal de aprobación.
✓ Higiene de secretos
- ✓Confirma que el
.envaparece en el.gitignore. - ✓Crea el repositorio como privado.
- ✓Inicializa con README para abrir el repo «vacío pero vivo».
✗ Receta para una filtración
- ✗Hacer push antes de comprobar el
.gitignore. - ✗Crear el repo público «solo para probar».
- ✗Pegar la clave de API directamente en el código (hard-code).
🎯 Objetivo: autenticarse en GitHub y conectar el proyecto al repo desde la terminal.
# 1) instalar a GitHub CLI (escolha o seu gerenciador) brew install gh # macOS (Homebrew) winget install GitHub.cli # Windows (WinGet) # 2) autenticar — responda: GitHub.com / HTTPS / login via web browser gh auth login # o terminal mostra um código de uso único; cole no navegador # 3) no Claude Code, em plan mode, peça (descreva o resultado): > conecte este projeto a um repositório PRIVADO no GitHub chamado <meu-repo>, inicialize com README e garanta que o .env esteja listado no .gitignore antes de qualquer push
✅ Cómo verificar: abre el repo en GitHub y mira el .gitignore + el README presentes — y ninguno .env en la lista de archivos.
🎯 Objetivo: garantizar que el secreto nunca se suba: el .env enumerado en el .gitignore.
# .gitignore — o que o Git deve IGNORAR .env # ← a regra de ouro: segredos nunca sobem .env.local node_modules/ # dependências (pesadas, reinstaláveis) .trigger/ # artefatos locais do Trigger.dev
✅ Cómo verificar: ejecuta git status — o .env no debe aparecer entre los archivos que se van a commitear.
Conceptos clave
Se autentica mediante el navegador.
Lista lo que no se sube.
Patrón para automatizaciones.
El .env nunca va en el repo.
⚙️ Trigger.dev — sin timeout, con retries, traces y alertas
Qué es
O Trigger.dev es el motor de ejecución en la nube. Piensa en la diferencia entre un nota adhesiva pegado al monitor (que puedes olvidar, que desaparece cuando se apaga la PC) y un asistente confiable que ejecuta la tarea, vuelve a intentarlo si falla y te avisa del resultado. Trigger.dev es el asistente. Ejecuta tareas sin timeout, con reintentos automáticos, trace completo de cada paso y alertas de error.
¿Qué es?Reintento — cuando la tarea falla (p. ej., se cayó Internet), se vuelve a intentar automáticamente. Trace — el registro paso a paso de lo que ocurrió durante la ejecución. Webhook — una dirección que activa la tarea cuando ocurre un evento externo.
Diagrama ilustrativo — Trigger.dev cierra la «brecha agéntica»: da visibilidad y robustez justo cuando la IA ya no está supervisando la ejecución.
Por qué aprender
En producción, nadie está supervisando la ejecución en tiempo real. Cuando el agente se ejecuta a las 7h de la mañana y algo sale mal, necesitas retry, log y alerta; si no, el error pasa desapercibido. Trigger.dev resuelve este "agentic gap": el puente entre «funcionó en mi chat» y «funciona solo y me avisa». Se ejecuta TypeScript (no Python), pero eso no cambia nada para ti: Claude Code escribe el TypeScript y tu enfoque de vibe coding sigue igual.
🎯 Consejo práctico
No te asustes con «es TypeScript». Nunca escribes TypeScript a mano: describes el resultado en portugués y Claude Code escribe el código. Trigger.dev es amigable con la IA mediante un servidor MCP oficial, entonces la IA gestiona tareas, revisa las ejecuciones y ajusta todo conversando contigo.
Conceptos clave
Las tareas largas se ejecutan.
Inténtalo de nuevo, registra todo.
La IA escribe por ti.
Prueba y producción por separado.
🔌 Inicializar proyecto + MCP de Trigger.dev
Qué es
Inicializar el proyecto es la secuencia que conecta tu código con Trigger.dev. Te registras con la cuenta de GitHub, crea una organización y un proyecto (usa el mismo nombre del repo para no perderte), copia el Project ID e instala el MCP oficial de Trigger.dev en Claude Code. Después, dos comandos: el init crea la estructura, y el dev inicia el worker local que escucha en tu máquina.
¿Qué es?Project ID — el identificador único de tu proyecto en Trigger.dev (en Project Settings > General). MCP — el protocolo que proporciona herramientas a la IA; aquí, el MCP de Trigger.dev permite que Claude Code gestione tareas y runs. Worker local — el proceso que ejecuta las tasks en tu máquina durante el desarrollo.
⚠️ El error más común
Después de instalar cualquier MCP, reinicia Claude Code. Si no lo reinicias, la IA no ve las nuevas herramientas y parece que "el MCP no funciona". Reiniciarlo resuelve la gran mayoría de los casos.
Por qué aprender
Con el MCP instalado, gestionas el proyecto conversando — «crea una task que haga X», «muestra la última run» — sin memorizar comandos. Sin el MCP, terminas en la terminal y pierdes la fluidez del vibe-code. Siempre abre la carpeta del proyecto en VS Code, para que Claude Code pueda leer y editar los archivos mientras conversan. El init é interactivo y a veces hay que ejecutarlo directamente en el terminal.
🎯 Objetivo: inicializar Trigger.dev en el proyecto y levantar el worker local.
# 1) cria trigger.config.ts + a pasta de tasks (interativo: # cole o Project ID quando pedir <seu-project-id>) npx trigger.dev@latest init # 2) sobe o worker local — deixe rodando enquanto desenvolve npx trigger.dev@latest dev # (depois de instalar o MCP do Trigger.dev: REINICIE o Claude Code)
✅ Cómo verificar: abre el dashboard de Trigger.dev en el entorno dev — tu tarea debe aparecer en la lista en cuanto se conecte el worker.
🎯 Objetivo: en Claude Code (plan mode), preparar la carpeta del proyecto y conectar todo.
> crie uma pasta de projeto, conecte ao repo <meu-repo> no GitHub e prepare para Trigger.dev (gerenciador npm). Use o Project ID <seu-project-id>, rode o init e confirme que o .env está no .gitignore. Antes de executar, me mostre o plano.
✅ Cómo verificar: la carpeta local queda sincronizada con el repo, el trigger.config.ts existe y Claude Code puede listar sus tasks a través de MCP.
Conceptos clave
En Settings > General.
Crea la estructura e inicia el worker.
Después de instalar cualquier MCP.
Abre la carpeta para que la IA la gestione.
⏰ Cron (5 campos)
Qué es
O cron es el «despertador» de la automatización: un patrón de cinco campos que define cuándo se ejecuta la tarea. Los campos son, en orden: minuto, hora, día-del-mes, mes e día-de-la-semana. El ejemplo clásico es 0 7 * * * = minuto 0, hora 7, todos los días — es decir, todos los días a las 7 de la mañana. El asterisco * significa «cualquier valor».
¿Qué es?Cron — sintaxis estándar de programación de tareas, usada en servidores desde hace décadas. * = cualquiera; */5 = "cada 5". Algunos ajustes del nodo solo aceptan modos específicos: pedir "cada 5 minutos" puede convertirse en el cron */5 * * * * entre bastidores.
Diagrama ilustrativo — lee el cron de izquierda a derecha: minuto, hora, día del mes, mes, día de la semana. Los dos primeros campos fijan el horario; los tres asteriscos dicen «cualquier día».
Por qué aprender
El cron es lo que hace que la automatización se ejecute sin que estés presente — el salto de «aparecer y activar manualmente» a «ejecutarse solo en el momento adecuado». Saber leer los cinco campos te da control: puedes comprobar si el agente realmente se ejecutará cuando debe, en vez de cruzar los dedos.
🎯 Objetivo: leer y variar el patrón cron de 5 campos.
# ordem dos campos: minuto hora dia-do-mês mês dia-da-semana 0 7 * * * # todo dia às 7h da manhã (o clássico) */5 * * * * # a cada 5 minutos 0 */2 * * * # a cada 2 horas, no minuto 0 30 8 * * 1 # toda segunda-feira às 8h30 0 <hora> * * * # todo dia na <hora> que você escolher (0–23)
✅ Cómo verificar: pídele a Claude Code «explica en portugués qué hace este cron» y comprueba que coincida con lo que quieres antes de programarlo.
Conceptos clave
min · hora · día · mes · semana.
Todos los días a las 7h.
Sin restricciones en el campo.
Intervalo regular.
📊 Anatomía del dashboard
Qué es
El dashboard de Trigger.dev es tu ventana para producción. En él ves: la visión de la tarea, la lista de Runs (cada ejecución), los traces de cada run (cada línea = un paso), la timeline, los paneles de payload (lo que entró) y output (lo que salió), y las secciones de Schedules, Queues e Alerts. Todo esto en dos entornos: dev (prueba) y prod (en producción).
¿Qué es?Run — una ejecución individual de la task. Payload — los datos de entrada de esa run. Output — el resultado producido. Trace — el paso a paso, útil para descubrir dónde falló.
De la prueba a producción (cronología)
1. dev — tú pruebas
El worker local se conecta; activas la task manualmente y lees los traces hasta que esté lista.
2. deploy — sube a prod
El código pasa de GitHub a Trigger.dev; el entorno prod empieza a ejecutarse de verdad.
3. la agenda se activa — aparecen runs
A la hora del cron, aparecen nuevas runs en la lista; cada una con su payload y output.
4. tú supervisas — traces & alertas
Si algo falla, llega una alerta y el trace muestra el paso culpable. El dashboard es tu puesto de observación.
Por qué aprender
En producción, Claude Code ya no está supervisando la ejecución: el dashboard es donde ves lo que pasó. Saber leer runs y traces es lo que transforma «creo que se ejecutó» en «sé exactamente qué se ejecutó y dónde se atascó». Como el modelo es interpretativo, el output puede variar de una ejecución a otra: verifica el resultado (¿cumplió el objetivo?), no la redacción exacta.
🎯 Consejo práctico
Prueba siempre en dev antes de habilitar en prod. Y recuerda el «trust but verify» de la Trilha 1: verde ≠ correcto. Una run puede terminar "en verde" (sin errores) y aun así haber producido el resultado equivocado: lee el output, no solo el estado.
Conceptos clave
Cada ejecución listada.
Fila = un paso.
Lo que entró y salió.
Prueba y luego libera.
🎬 Deploy desde el primer prompt
Qué es
La disciplina final: construir pensando en el deploy desde el primer prompt — el "prompt inicial para gobernarlos a todos". En producción, la IA no está allí para corregir las cosas en el momento, así que lo que tú no lo que pediste en el prompt simplemente no viene gratis. Por eso, cada build para ejecutarse por sí solo necesita cuatro requisitos nuevos en tu forma de pedir.
¿Qué es?Repository Secret — un secreto guardado en el propio GitHub (en Settings > Secrets and Variables > Actions) que el deploy usa sin exponer la clave. El TRIGGER_ACCESS_TOKEN es lo que autoriza a GitHub a publicar en Trigger.dev.
Los 4 requisitos para builds sin supervisión
✓ Pídelo en el prompt
- ✓Entradas fijas: la task recibe datos predecibles; no improvisa de dónde vienen.
- ✓Salida estructurada: formato predecible (campos definidos), fácil de consumir.
- ✓Tratamiento de errores: qué hacer cuando algo falla, incorporado desde el inicio.
- ✓Log en cada paso: para que el trace cuente la historia después.
✗ No lo dejes para después
- ✗"Después agrego el manejo de errores" — en producción, "después" es demasiado tarde.
- ✗Salida suelta y libre que cambia de forma en cada run.
- ✗Sin logs: el trace queda mudo y no sabes qué pasó.
- ✗Esperar al horario para probar — actívalo manualmente primero.
Por qué aprender
El pipeline completo conecta todo lo que viste: tú iterar en Claude Code → se puede push en GitHub → o GitHub implementa el deploy en Trigger.dev. Así, los archivos más recientes siempre están en línea, sin pasos manuales. Agrega el TRIGGER_ACCESS_TOKEN como Repository Secret en GitHub para que funcione el deploy automático y, después de publicar, activa la task manualmente para probar, en vez de esperar a la siguiente ventana del cron.
🎯 Consejo práctico
En GitHub, ve a Settings > Secrets and Variables > Actions y registra el TRIGGER_ACCESS_TOKEN cómo Repository Secret. Es lo que permite que el push se convierta en deploy sin que pegues el token en ninguna parte del código.
Conceptos clave
Piensa en producción desde el prompt.
Entrada, salida, error, log.
GitHub publica en Trigger.dev.
Prueba sin esperar al cron.
Fijando el cron: ¿qué expresión significa "todos los días a las 7 a. m."?
📌 Resumen del módulo
gh auth login; la regla de oro es el .env nunca subir.init e dev.0 7 * * * = todos los días a las 7 h.Siguiente módulo:
6.2 — Secrets y seguridad