Antes dos sete tópicos, veja o que muda. Numa sessão interativa, a IA lê o erro e conserta na hora — um loop que se cura sozinho. Mas a tarefa hospedada roda sem ninguém olhando: ela executa, mas não se adapta. Você recria esse loop com recursos de plataforma (logs, retries, alertas) e prompts melhores; depois, fecha o ciclo do dinheiro com Stripe.

Diagrama ilustrativo — confiabilidade recria, com plataforma e prompts, o loop de cura que você tinha de graça na sessão interativa; a monetização fecha o ciclo transformando o workflow em produto.

O que é

Durante o desenvolvimento, você e o Claude Code trabalham num loop que se cura sozinho: a tarefa roda, dá erro, a IA lê o erro na hora e conserta. Mas quando a tarefa é deployada e passa a rodar sozinha — por agenda (cron) ou por evento (webhook) na nuvem — esse loop desaparece. O agentic gap é exatamente essa lacuna: a tarefa hospedada executa, mas não se adapta, e ninguém está lendo os erros.

Concretamente: você fecha o terminal, vai dormir, e às 7h o cron dispara a tarefa. Se a API de uma fonte estiver fora do ar, a tarefa pode travar e morrer — e como o Claude Code não está mais assistindo, a falha passa despercebida até alguém reclamar. A solução não é "torcer": você fecha o gap com recursos da plataforma (retries, traces, alertas) e com prompting melhor (tratamento de erro e logging pedidos desde o primeiro prompt).

Por que aprender

Sem fechar o gap, "rodou na demo" não significa "roda em produção". Uma automação que falha calada é pior do que nenhuma: você acredita que está cuidando de algo que parou há dias. Entender o gap muda a forma como você constrói — você passa a pedir robustez antes do deploy, não depois do incidente.

Conceitos-chave

O que é

O Trigger.dev te dá visibilidade (traces) e retries automáticos, mas ele só consegue retentar o que reconhece como falha — e você só consegue diagnosticar o que o log conta. Logging significativo é pedir à IA um log claro em cada passo importante, com contexto específico: não "task failed", mas "Firecrawl retornou 429 na fonte 3". O log vago é inútil; o log específico é acionável.

Diagrama ilustrativo — a mesma falha, dois logs. O específico carrega contexto suficiente para você (ou a IA) agir sem adivinhar.

Por que aprender

Quando algo falha às 3h da manhã, o log é tudo o que você terá. Um trace cheio de "ok" e "erro" genéricos te força a reproduzir o problema do zero; um trace com mensagens ricas te diz, em segundos, qual fonte caiu, com qual código, em qual passo. Pedir bons logs desde o primeiro prompt é mais barato do que adicioná-los depois do incidente.

Revise os arquivos da task <nome-da-task> e adicione um log claro
em cada passo significativo. Em vez de mensagens genéricas como
"task failed", logue o contexto: serviço, código de status e qual item.

Exemplos do que eu quero ver nos logs:
  - "Firecrawl retornou 429 na fonte 3 (rate limit)"
  - "Supabase: gravada linha parcial para lead <id> (1 fonte faltando)"
  - "OpenAI ok: resumo gerado para <empresa> em 1.4s"

Use o logger do Trigger.dev (logger.info / logger.warn / logger.error)
para que apareçam no trace do dashboard.

Conceitos-chave

O que é

Toda chamada a uma API externa pode falhar — a rede cai, o serviço retorna erro, a resposta vem num formato inesperado. O try/catch é o padrão que envolve essa chamada para que, se ela falhar, a tarefa capture o erro em vez de morrer: você loga o erro com contexto, continua onde for possível e só lança (interrompe de vez) em falhas realmente críticas. É isso que permite a tarefa gravar uma linha parcial em vez de explodir quando uma fonte cai.

Por que aprender

Há um caso real que prova o ponto: o Firecrawl retornou success:false com os resultados sob a chave web em vez de data. Sem tratamento de erro, isso teria quebrado a leitura e derrubado a task. Com o try/catch no lugar, a tarefa detectou o formato inesperado, logou o problema e não travou — gravou o que conseguiu. Tratamento de erro não é luxo: é o que mantém a automação de pé quando o mundo externo se comporta mal.

// TypeScript — chamada a uma API externa dentro da task
let dadosFonte = null;

try {
  const resp = await fetch(`https://api.<servico>.com/<rota>`, {
    headers: { Authorization: `Bearer ${process.env.<CHAVE>}` },
  });

  if (!resp.ok) {
    // falha não-crítica: loga COM contexto e continua
    logger.warn(`<Servico> retornou ${resp.status} na fonte ${fonteId}`);
  } else {
    dadosFonte = await resp.json();
  }
} catch (err) {
  // erro de rede/timeout: registra e segue sem essa fonte
  logger.error(`Falha ao chamar <Servico> (fonte ${fonteId}): ${err.message}`);
}

// grava a linha mesmo parcial — não descarta o que deu certo
await salvarLinha({ ...resto, fonte: dadosFonte ?? "faltando" });

// só lança se faltar algo CRÍTICO (sem isso não há resultado)
if (!dadoEssencial) throw new Error("Dado essencial ausente — abortando");

Conceitos-chave

O que é

Você configura retries na própria definição da task (ex.: até 3 tentativas, com backoff exponencial começando em 30s). Se a tarefa falhar por um motivo passageiro, o Trigger.dev espera e tenta de novo, dobrando o intervalo a cada vez. A regra de ouro: retries resolvem falhas transitórias (timeout, rate limit, instabilidade de rede) — mas não resolvem bugs de lógica no seu código.

Diagrama ilustrativo — se as 3 tentativas falham igual, o problema não é o momento: é a lógica. Retentar um bug para sempre só queima recursos.

Por que aprender

Saber a diferença evita os dois erros opostos: não ter retries (uma instabilidade boba derruba a run que teria funcionado 30s depois) e confiar demais neles (um bug de lógica é retentado infinitamente, mascarando o problema real e gastando execuções). Se as três tentativas falham com o mesmo erro, pare de retentar e vá depurar — assunto do tópico 6.

// trigger/<sua-task>.ts — configuração de retries
export const minhaTask = task({
  id: "<id-da-task>",
  retry: {
    maxAttempts: 3,            // até 3 tentativas
    minTimeoutInMs: 30_000,    // backoff começa em 30s
    factor: 2,                 // exponencial: 30s → 60s → 120s
  },
  run: async (payload) => {
    // ... sua lógica aqui ...
  },
});

Conceitos-chave

O que é

Logs e traces te contam o que aconteceu — se você for olhar. Alertas invertem isso: eles te procuram. No Trigger.dev, em Project Settings > Alerts, você configura notificações por e-mail, Slack ou webhook disparadas em falhas de deploy ou de run, com ambiente e tipo de falha configuráveis. Leva menos de dois minutos para montar.

Por que aprender

Esta é a regra que fecha o agentic gap na prática: toda task deployada precisa ter alerta de falha. Sem isso, você está apostando que vai checar o dashboard exatamente quando der problema — o que nunca acontece. Com alertas, o sistema te chama; você troca "esperança" por "aviso". Como é configurável por ambiente, deixe alertas de produção sempre ligados.

Conceitos-chave

O que é

O Claude ainda depura — só não automaticamente mais. Em produção, o loop de cura existe, mas com você no meio: a tarefa falha, o alerta chega, e você (o humano) faz a ponte. Abre o trace vermelho no dashboard, copia o erro, cola no Claude ("aqui está o trace que falhou: <erro>, o que está errado e como conserto?"), deixa o Claude identificar o conserto, faz o redeploy e testa. O trace + o Claude dão diagnóstico rápido; o humano só precisa passar o erro adiante.

Linha do tempo ilustrativa — o loop é o mesmo da sessão interativa (erro → diagnóstico → fix → redeploy → teste), mas agora você é quem leva o erro até o Claude.

Por que aprender

É aqui que tudo se conecta: o log significativo (tópico 2) torna o trace legível, os alertas (tópico 5) te avisam para abrir esse trace, e os retries (tópico 4) já te dizem se vale depurar (erro igual 3x = bug). O ciclo é rápido porque o trace + o Claude fazem o diagnóstico pesado; sua parte é só a ponte. Dominar esse loop é o que mantém uma automação hospedada viva ao longo das semanas.

Aqui está o trace que falhou:

<cole o erro completo copiado do dashboard do Trigger.dev>

Contexto: é a task <nome-da-task>, rodou via <cron/webhook> em produção.
O que está errado e como conserto? Aplique o fix nos arquivos da task
e me explique em uma frase a causa raiz.

Conceitos-chave

O que é

O passo que transforma a automação num SaaS: adicionar pagamentos com Stripe num modelo freemium — um tier grátis limitado (ex.: 2 qualificações de lead por dia) e um tier pro pago (ex.: US$ 29/mês, ilimitado), tudo via Stripe Checkout. A motivação não é só ganhar dinheiro: é limitar o uso para você não pagar a conta de IA dos usuários consumindo sem teto. É o que fecha a transição de "só um workflow" para "um app que gera receita".

A boa notícia: você não escreve a integração na mão. Você descreve o resultado e o Claude Code implementa — mas você precisa criar as contas, copiar as quatro chaves e rodar a migração. A sequência abaixo é a parte manual; o código é com o Claude.

Linha do tempo ilustrativa — quatro chaves (publishable, secret, price ID, webhook secret), uma tabela nova e um endpoint de webhook: é o esqueleto de qualquer cobrança por assinatura.

Por que aprender

Sem um limite de uso, cada usuário gratuito pode disparar consumo ilimitado de IA — e a fatura cai no seu colo. O freemium resolve os dois lados: o tier grátis (2/dia) é vitrine e proteção de custo; o tier pro (US$ 29/mês ilimitado) é a receita. Com isso, o que era um workflow técnico vira um produto que se sustenta — o salto final da trilha.

Adicione pagamentos Stripe ao app com modelo freemium:

  - Tier grátis: até 2 qualificações de lead por dia.
  - Tier pro: US$ 29/mês, ilimitado, via Stripe Checkout.

Use as env vars: STRIPE_PUBLISHABLE_KEY, STRIPE_SECRET_KEY,
STRIPE_PRICE_ID, STRIPE_WEBHOOK_SECRET.
Crie a rota /api/stripe-webhook escutando checkout.session.completed,
customer.subscription.updated e customer.subscription.deleted,
e atualize a tabela subscriptions no Supabase conforme o status.
Bloqueie o uso acima do limite no tier grátis.

Conceitos-chave