🛠️ Como usar este módulo
Este é o módulo onde o protótipo vira produto. Você não precisa escrever código: quem escreve o TypeScript é o Claude Code. Seu papel é entender os dois lugares — onde o código fica guardado (GitHub) e onde ele roda sozinho (Trigger.dev) — e saber dar os comandos certos. Os blocos "copie e rode" são prontos para colar no terminal ou no chat da IA.
Antes dos sete tópicos, fixe o desenho geral. Na sua máquina o agente até roda — mas só enquanto seu computador está ligado. Em produção, o código mora no GitHub (com histórico) e roda no Trigger.dev (na nuvem, no horário marcado), com a IA escrevendo e você supervisionando pelo dashboard.
Diagrama ilustrativo — o ciclo de produção: você itera no Claude Code, o código sobe ao GitHub e de lá vai para o Trigger.dev, que executa na nuvem com confiabilidade. Os arquivos mais recentes do GitHub estão sempre no ar.
🐙 GitHub como armazenamento de código
O que é
O GitHub é armazenamento de código na nuvem. Em vez de o seu projeto viver só na pasta do seu computador, ele fica num servidor acessível de qualquer lugar. A consequência prática é grande: na hora do deploy, a plataforma de hospedagem puxa o código da nuvem, não da sua máquina — então o seu PC pode estar desligado que a automação continua de pé.
O que é?Repositório (repo) — a pasta do seu projeto, versionada, dentro do GitHub. Commit — um "snapshot" salvo com uma descrição do que mudou. Push — o ato de enviar seus commits da máquina local para o GitHub.
Cada commit guarda um ponto no tempo. Isso te dá um histórico completo: se uma mudança quebrar tudo, você reverte para um commit anterior e está de volta ao que funcionava. Para automações que cuidam de dados ou dinheiro, essa rede de segurança não é luxo — é o que permite mexer sem medo. Crie o repo como privado e inicialize com um README.
Por que aprender
O GitHub é o pré-requisito da hospedagem. Plataformas de deploy (incluindo o Trigger.dev) integram direto com o repo: você empurra o código e elas cuidam do resto. Sem repo, não há pipeline.
- •Acessível de qualquer lugar: o código não fica preso a um computador.
- •Histórico para reverter: volte a qualquer commit anterior em segundos.
- •Integra com deploy: a fonte da verdade de onde a nuvem puxa o código.
Conceitos-chave
Pasta do projeto na nuvem.
Snapshot com descrição.
Enviar à nuvem.
Reverter quando quebrar.
🚫 gh CLI & .gitignore — o .env nunca sobe
O que é
A GitHub CLI (o comando gh) é a ferramenta de linha de comando que autentica você no GitHub e conecta o projeto ao repo — tudo pelo terminal, sem abrir o site. O .gitignore é um arquivo de texto que lista o que nunca deve subir. E a regra de ouro deste módulo inteiro: o .env (que guarda suas chaves de API) jamais pode ir para o GitHub.
O que é?.env — arquivo local com segredos (chaves de API, tokens). .gitignore — lista de arquivos/pastas que o Git ignora e nunca envia. O Claude Code adiciona o .env ao .gitignore automaticamente — mas é seu dever conferir.
Por que aprender
Um .env vazado é um segredo vazado. Repositórios são rastreados o tempo todo; uma chave exposta pode ser usada em minutos — e você paga a conta. O .gitignore é a sua primeira linha de defesa. Use um nome de usuário profissional (ele aparece em links públicos), mantenha o repo privado e não estranhe se o terminal pedir permissão de comando várias vezes — é o comportamento normal de aprovação.
✓ Higiene de segredos
- ✓Confirme que o
.envaparece no.gitignore. - ✓Crie o repositório como privado.
- ✓Inicialize com README para abrir o repo "vazio mas vivo".
✗ Receita de vazamento
- ✗Dar push antes de checar o
.gitignore. - ✗Criar o repo público "só para testar".
- ✗Colar a chave de API direto no código (hard-code).
🎯 Objetivo: autenticar no GitHub e conectar o projeto ao repo, via 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
✅ Como verificar: abra o repo no GitHub e veja o .gitignore + o README presentes — e nenhum .env na lista de arquivos.
🎯 Objetivo: garantir que o segredo nunca suba — o .env listado no .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
✅ Como verificar: rode git status — o .env não deve aparecer entre os arquivos a serem commitados.
Conceitos-chave
Autentica via navegador.
Lista o que não sobe.
Padrão para automações.
O .env jamais no repo.
⚙️ Trigger.dev — sem timeout, retries, traces, alertas
O que é
O Trigger.dev é o motor de execução na nuvem. Pense na diferença entre um post-it grudado no monitor (que você pode esquecer, que some quando o PC desliga) e um assistente confiável que executa a tarefa, tenta de novo se falhar e te avisa do resultado. O Trigger.dev é o assistente. Ele roda tarefas sem timeout, com retries automáticos, trace completo de cada passo e alertas de falha.
O que é?Retry — quando a tarefa falha (ex.: a internet caiu), ela é tentada de novo sozinha. Trace — o registro passo a passo do que aconteceu na execução. Webhook — um endereço que dispara a tarefa quando um evento externo acontece.
Diagrama ilustrativo — o Trigger.dev fecha o "agentic gap": dá visibilidade e robustez justamente quando a IA não está mais assistindo a execução.
Por que aprender
Em produção, ninguém está olhando a execução em tempo real. Quando o agente roda às 7h da manhã e algo dá errado, você precisa de retry, log e alerta — senão o erro passa despercebido. O Trigger.dev fecha esse "agentic gap": a ponte entre "rodou no meu chat" e "roda sozinho e me avisa". Ele roda TypeScript (não Python) — mas isso não muda nada para você: o Claude Code escreve o TypeScript, e a sua abordagem vibe-code continua igual.
🎯 Dica prática
Não se assuste com "é TypeScript". Você nunca digita TypeScript à mão: descreve o resultado em português e o Claude Code escreve o código. O Trigger.dev é amigável a IA via um servidor MCP oficial, então a IA gerencia tarefas, vê runs e ajusta tudo conversando com você.
Conceitos-chave
Tarefas longas rodam.
Tenta de novo, registra tudo.
A IA escreve por você.
Teste e produção separados.
🔌 Inicializar projeto + MCP do Trigger.dev
O que é
Inicializar o projeto é a sequência que liga o seu código ao Trigger.dev. Você se cadastra com a conta do GitHub, cria uma organização e um projeto (use o mesmo nome do repo, para não se perder), copia o Project ID e instala o MCP oficial do Trigger.dev no Claude Code. Depois, dois comandos: o init cria a estrutura, e o dev sobe o worker local que escuta a sua máquina.
O que é?Project ID — o identificador único do seu projeto no Trigger.dev (em Project Settings > General). MCP — o protocolo que dá ferramentas à IA; aqui, o MCP do Trigger.dev deixa o Claude Code gerenciar tarefas e runs. Worker local — o processo que roda as tasks na sua máquina durante o desenvolvimento.
⚠️ O erro mais comum
Depois de instalar qualquer MCP, reinicie o Claude Code. Se você não reiniciar, a IA não enxerga as novas ferramentas e parece que "o MCP não funciona". Reiniciar resolve a grande maioria dos casos.
Por que aprender
Com o MCP instalado, você gerencia o projeto conversando — "crie uma task que faz X", "mostre a última run" — sem decorar comandos. Sem o MCP, você cai no terminal e perde a fluidez vibe-code. Sempre abra a pasta do projeto no VS Code, para que o Claude Code consiga ler e editar os arquivos enquanto vocês conversam. O init é interativo e às vezes precisa ser rodado direto no terminal.
🎯 Objetivo: inicializar o Trigger.dev no projeto e subir o 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)
✅ Como verificar: abra o dashboard do Trigger.dev no ambiente dev — a sua task deve aparecer na lista assim que o worker conectar.
🎯 Objetivo: no Claude Code (plan mode), preparar a pasta do projeto e conectar tudo.
> 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.
✅ Como verificar: a pasta local fica sincronizada com o repo, o trigger.config.ts existe e o Claude Code consegue listar suas tasks pelo MCP.
Conceitos-chave
Em Settings > General.
Cria estrutura, sobe worker.
Após instalar qualquer MCP.
Abra a pasta para a IA gerir.
⏰ Cron (5 campos)
O que é
O cron é o "despertador" da automação: um padrão de cinco campos que define quando a tarefa roda. Os campos são, em ordem: minuto, hora, dia-do-mês, mês e dia-da-semana. O exemplo clássico é 0 7 * * * = minuto 0, hora 7, todos os dias — ou seja, todo dia às 7h da manhã. O asterisco * significa "qualquer valor".
O que é?Cron — sintaxe padrão de agendamento, usada em servidores há décadas. * = qualquer; */5 = "a cada 5". Alguns ajustes do nó só aceitam modos específicos: pedir "a cada 5 minutos" pode virar o cron */5 * * * * nos bastidores.
Diagrama ilustrativo — leia o cron da esquerda para a direita: minuto, hora, dia-do-mês, mês, dia-da-semana. Os dois primeiros campos fixam o horário; os três asteriscos dizem "em qualquer dia".
Por que aprender
O cron é o que faz a automação rodar sem você presente — o pulo do "aparecer e disparar manualmente" para o "roda sozinho na hora certa". Saber ler os cinco campos te dá controle: você confere se o agente vai mesmo rodar quando deveria, em vez de torcer.
🎯 Objetivo: ler e variar o padrão 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)
✅ Como verificar: peça ao Claude Code "explique em português o que este cron faz" e confira se bate com a sua intenção antes de agendar.
Conceitos-chave
min · hora · dia · mês · semana.
Todo dia às 7h.
Sem restrição no campo.
Intervalo regular.
📊 Anatomia do dashboard
O que é
O dashboard do Trigger.dev é a sua janela para a produção. Nele você vê: a visão da task, a lista de Runs (cada execução), os traces de cada run (cada linha = um passo), a timeline, os painéis de payload (o que entrou) e output (o que saiu), e as seções de Schedules, Queues e Alerts. Tudo isso em dois ambientes: dev (teste) e prod (no ar de verdade).
O que é?Run — uma execução individual da task. Payload — os dados de entrada daquela run. Output — o resultado produzido. Trace — o passo a passo, útil para descobrir onde falhou.
Do teste à produção (timeline)
1. dev — você testa
O worker local conecta; você dispara a task manualmente e lê os traces até estar redonda.
2. deploy — sobe para prod
O código vai do GitHub para o Trigger.dev; o ambiente prod passa a executar de verdade.
3. agenda dispara — runs aparecem
No horário do cron, novas runs surgem na lista; cada uma com seu payload e output.
4. você supervisiona — traces & alertas
Se algo falha, o alerta chega e o trace mostra o passo culpado. O dashboard é o seu posto de observação.
Por que aprender
Em produção, o Claude Code não está mais assistindo a execução — o dashboard é onde você vê o que aconteceu. Saber ler runs e traces é o que transforma "acho que rodou" em "sei exatamente o que rodou e onde travou". Como o modelo é interpretativo, o output pode variar de uma run para outra: verifique o resultado (cumpriu o objetivo?), não a redação exata.
🎯 Dica prática
Teste sempre em dev antes de liberar em prod. E lembre do "trust but verify" da Trilha 1: verde ≠ correto. Uma run pode terminar "verde" (sem erro) e ainda assim ter produzido a saída errada — leia o output, não só o status.
Conceitos-chave
Cada execução listada.
Linha = um passo.
O que entrou e saiu.
Teste, depois libere.
🎬 Deploy a partir do 1º prompt
O que é
A disciplina final: construir já pensando em deploy desde o primeiro prompt — o "um prompt inicial para reinar sobre todos". Em produção a IA não está ali para consertar na hora, então o que você não pediu no prompt simplesmente não vem de graça. Por isso, todo build para rodar sozinho precisa de quatro requisitos novos no seu jeito de pedir.
O que é?Repository Secret — um segredo guardado no próprio GitHub (em Settings > Secrets and Variables > Actions) que o deploy usa sem expor a chave. O TRIGGER_ACCESS_TOKEN é o que autoriza o GitHub a publicar no Trigger.dev.
Os 4 requisitos para builds não assistidos
✓ Peça no prompt
- ✓Inputs fixos: a task recebe dados previsíveis, não improvisa de onde vêm.
- ✓Saída estruturada: formato previsível (campos definidos), fácil de consumir.
- ✓Tratamento de erro: o que fazer quando algo falha, embutido desde já.
- ✓Log em cada passo: para o trace contar a história depois.
✗ Não deixe para depois
- ✗"Depois eu adiciono tratamento de erro" — em prod, "depois" é tarde.
- ✗Saída solta e livre que muda de forma a cada run.
- ✗Zero log — o trace fica mudo e você não sabe o que aconteceu.
- ✗Esperar a agenda para testar — dispare manualmente primeiro.
Por que aprender
O pipeline completo amarra tudo o que você viu: você itera no Claude Code → dá push no GitHub → o GitHub faz deploy no Trigger.dev. Assim, os arquivos mais recentes estão sempre no ar, sem passos manuais. Adicione o TRIGGER_ACCESS_TOKEN como Repository Secret no GitHub para o deploy automático funcionar — e, depois de publicar, dispare a task manualmente para testar, em vez de esperar a próxima janela do cron.
🎯 Dica prática
No GitHub, vá em Settings > Secrets and Variables > Actions e cadastre o TRIGGER_ACCESS_TOKEN como Repository Secret. É o que permite ao push virar deploy sem você colar o token em lugar nenhum do código.
Conceitos-chave
Pense em prod já no prompt.
Input, saída, erro, log.
GitHub publica no Trigger.dev.
Teste sem esperar o cron.
Fixando o cron: qual expressão significa "todo dia às 7h da manhã"?
📌 Resumo do Módulo
gh auth login; a regra de ouro é o .env nunca subir.init e dev.0 7 * * * = todo dia às 7h.Próximo Módulo:
6.2 — Secrets & Segurança