E não deixe de assinar minha nova newsletter The M.Akita Chronicles!

–

274 commits. 8 dias. 4 aplicações. 1.323 testes. Um sistema completo em produção — com assinantes reais recebendo uma newsletter toda segunda-feira às 7h, um podcast gerado por IA no Spotify, um blog estático no Netlify, e um bot no Discord que é minha interface operacional.

Fiz isso com um parceiro: Claude Code, um agente de IA rodando no terminal. E a lição mais importante que tirei não é que “IA programa sozinha” — é que IA programando sozinha é a receita pro desastre. O que funciona é algo que já tem nome e décadas de história: Extreme Programming. Só que agora o par no pair programming não é humano.

Eu preciso que todos vocês passem por uma experiência: uma IMERSÃO DE 1 SEMANA completamente DESAPEGADO do código, usando a IA como pair programming, indo do zero até produção em qualquer projetinho pequeno. Vai por mim, até vocês fazerem pelo menos, não vão entender. Mas depois muda tudo.

O Mito do “One-Shot Prompt”

Tem uma narrativa crescente de que “vibe coding” é escrever uma spec detalhada, dar pro agente de IA, e ele entrega o sistema pronto. Tipo aqueles vídeos de “criei um SaaS em 10 minutos com o Cursor”. Parece mágico até você olhar o que foi realmente entregue: um protótipo sem testes, sem segurança, sem tratamento de erros, sem deploy, sem nada que faça um sistema sobreviver ao contato com usuários reais.

A realidade dos meus 274 commits conta outra história:

Só 37% dos commits são features. O resto é o trabalho que faz um software de verdade: corrigir bugs, endurecer contra falhas, proteger contra ataques, deployar, testar, documentar. Quem mostra só a parte das features está vendendo uma ilusão.

E mais: muitas das features surgiram porque a iteração revelou que eram necessárias. ContentPreflight não estava no plano original — nasceu quando a segunda newsletter saiu com uma seção vazia porque um job falhou silenciosamente. RecoverStaleDeliveriesJob nasceu quando percebi que um crash no meio do envio deixava emails num limbo eterno. StealthBrowser nasceu quando o Morningstar bloqueou o HTTParty. Nenhum spec do mundo prevê isso. O sistema correto emerge da iteração, não da especificação.

Pair Programming Com Um Agente de IA

Eu não uso o Claude Code como um gerador de código. Uso como um par de pair programming.

A diferença é fundamental. Um gerador de código recebe uma spec e devolve output. Um par de pair programming conversa. Eu interrompo quando ele toma um caminho errado. Dou contexto que ele não tem. Questiono decisões. Peço alternativas. Às vezes digo “para, isso tá ficando complicado demais” e ele simplifica.

Alguns exemplos reais dos 274 commits:

Interrupção por excesso de engenharia. Quando pedi o sistema de email delivery, a primeira proposta tinha uma state machine com 8 estados, retry queues separadas, e dead letter handling. Interrompi: “Simplifica. Quatro estados: pending, sending, sent, unknown. Na dúvida, não reenvia.” O resultado foi o SendSingleEmailJob com a variável ses_accepted como pivô — 40 linhas que resolvem o problema inteiro.

Contexto que o agente não tem. Quando estávamos no Yahoo Finance, o Claude tentou usar HTTParty. Expliquei: “Yahoo faz TLS fingerprinting, vai bloquear qualquer HTTP client que não seja browser real.” Resultado: headless Chromium com crumb authentication. Isso não está em nenhum tutorial — é o tipo de conhecimento que vem de tentar e falhar.

Decisão de arquitetura conjunta. O podcast pipeline poderia ser um monolito Python. Sugeri: “Rails orquestra, Python serve TTS via HTTP, conteúdo integra por filesystem.” O resultado — QwenTtsClient no Ruby chamando podcast-tts em Python — mantém cada linguagem no que faz melhor.

Prompt refinement iterativo. As primeiras newsletters saíam genéricas. Os comentários do Akita e do Marvin soavam iguais. Fui ajustando prompts com ele: “Akita nunca diz ’talvez’. Marvin usa ‘bom…’ e ’enfim’. O LLM vai suavizar opiniões se você não for explícito.” Cada ajuste era um commit de prompt, testado com dados reais.

O padrão é: eu trago o quê e o porquê. O agente traz o como — e o como é frequentemente melhor do que eu faria sozinho. Mas o como sem o quê produz código correto que resolve o problema errado. E o quê sem o como produz specs que nunca saem do papel.

Extreme Programming Não É Moda dos Anos 2000

Tudo que fizemos tem nome no XP. Não porque planejei — porque são as práticas que naturalmente emergem quando você programa com feedback rápido:

Pair Programming

Já expliquei. O par é o agente. A dinâmica é a mesma: um pilota, outro navega. Eu navego mais do que piloto — defino direção, questiono decisões, corrijo rota. O agente pilota mais do que navega — escreve código, roda testes, propõe soluções. Quando inverte (eu ditando código exato, ele apenas digitando), o resultado sempre piora.

Small Releases

Dos 274 commits, cada um passa no CI. Sem exceção. Não existe “commit quebrando que vai ser consertado no próximo”. Cada commit em master é production-ready.

O CI roda em cada commit: RuboCop (estilo) → bundler-audit (vulnerabilidades de gems) → Brakeman (segurança estática) → testes completos. São ~22 segundos. Parece pouco, mas multiplicado por 274 commits são 100+ minutos de validação automatizada que eu não precisei fazer manualmente.

A distribuição de commits por dia mostra o ritmo:

A “explosão” do dia 2 não é caos — são small releases empilhadas. Cada uma adiciona uma feature, roda CI, está pronta pra deploy. Não é waterfall de 2 semanas seguido de big bang merge. É integração contínua de verdade.

Test-Driven Development

1.323 testes. 970 no marvin-bot (6 segundos em paralelo), 353 no newsletter (1 segundo em paralelo). Ratio:

Mais linhas de teste do que de código. Em ambas as aplicações. E isso não é vanidade — é a infraestrutura que permite velocidade.

Coverage por SimpleCov:

Não é 100% — e nunca será. Os 17-18% não cobertos são majoritariamente integração com APIs externas (Discord, SES, OpenRouter) que são mockadas nos testes. O coverage real em lógica de negócio está acima de 95%.

A pergunta que importa: esses testes são úteis? A prova empírica: em 274 commits, eu vi o CI falhar e pegar um bug real mais de 50 vezes. Sem esses testes, cada um desses bugs teria ido pra produção. O agente propõe uma mudança, o teste pega a regressão, a mudança é corrigida antes de commitar. Sem testes, o agente te entrega código plausível que silenciosamente quebra algo que funcionava ontem.

TDD com um agente de IA é multiplicativo. O agente é bom em gerar testes — sabe os padrões, sabe os edge cases comuns, sabe a estrutura do Minitest. E os testes que ele gera viram a rede de segurança das mudanças que ele mesmo faz depois. É um ciclo virtuoso: testes permitem velocidade, velocidade gera mais testes.

Refactoring Contínuo

27 commits explícitos de refactoring. Alguns exemplos:

• Extract StealthBrowser wrapper — O código de headless browser com stealth patches estava duplicado em 4 clients. Extraiu pra um serviço, 4 clientes ficaram com 5 linhas cada.
• DRY section rendering: collapse 5 bubble methods + 7 Hugo shortcodes — 5 métodos de renderização de bolha no MarkdownToHtml que eram copy-paste com cores diferentes colapsados em 1 método parametrizado. 7 shortcodes Hugo delegando pra 1 partial.
• Replace market recap LLM generation with Yahoo Finance real data — O LLM inventava números de mercado. Substituí por dados reais do Yahoo Finance + commentary do LLM. Melhor resultado, menor custo.
• Replace DuckDuckGo with Brave Search API — DuckDuckGo não tem API estável. Brave Search tem API oficial com 2.000 queries/mês grátis. Troca limpa.
• Rework ArticleFetcher: browser-first with anti-detection — Duas reescrituras completas. A primeira tentou HTTP-first com fallback pra browser. A segunda inverteu: browser-first porque a maioria dos links de leitores são SPAs. Cada reescritura manteve os testes passando.

O refactoring é onde o par de pair programming brilha. Eu digo “esse código tá duplicado, extrai um concern” e o agente faz em 2 minutos o que me levaria 20. Mas eu decido o quê extrair e como a interface deveria ser. O agente sozinho não refatora — ele empilha código novo em cima do existente.

Integração Contínua

O CI já descrito acima: rubocop + bundler-audit + brakeman + testes. Roda em cada commit, em ambas as apps. Brakeman merece destaque:

Zero warnings de segurança em ambos. As 2 ignored no newsletter são false positives documentados (SQL interpolation com paths de config, não user input).

Brakeman pegou problemas reais durante o desenvolvimento: SQL injection numa query de busca, path traversal no controller de imagens, redirect aberto no unsubscribe. Cada um corrigido antes de ir pra produção, no mesmo commit que o CI flaggou.

A Anatomia de Uma Feature: Do Pedido ao Deploy

Vou pegar um exemplo concreto pra ilustrar como o fluxo funciona na prática. O List-Unsubscribe (commit 5950ccc).

Contexto: emails de confirmação não chegavam no Gmail. Tudo verde — DKIM, SPF, DMARC, SES aceitando. Mas Gmail jogava no spam silenciosamente.

Investigação (eu + agente): pesquisamos. Desde fevereiro de 2024, Gmail exige List-Unsubscribe + List-Unsubscribe-Post em todo email de bulk sender. Sem eles, penaliza o domínio inteiro — incluindo emails transacionais.

Implementação (agente executa, eu valido): header no SesMailer, endpoint RFC 8058 no UnsubscriptionsController (skip CSRF pra email clients, retorna 200 ao invés de redirect), testes cobrindo ambos os flows.

CI: rubocop OK, brakeman pegou o skip_forgery_protection como warning (correto — validamos que é condicional). Testes passam.

Deploy: kamal deploy. Em 2 minutos, a correção está em produção. Reputação do domínio leva 1-2 dias pra se recuperar. No dia seguinte, emails de confirmação voltam a chegar.

Tempo total: ~25 minutos do “por que o Gmail tá rejeitando?” ao deploy em produção. Sem o agente, seriam horas de leitura de RFC, implementação manual, e esperança de que não esqueci nada.

O Que a IA Faz Bem (E o Que Faz Mal)

Depois de 274 commits com um agente de IA, tenho uma noção bem clara dos pontos fortes e fracos:

Faz bem:

• Boilerplate e scaffolding: jobs, services, testes, migrations — o agente produz na velocidade de digitação
• Testes: surpreendentemente bom em identificar edge cases e gerar testes abrangentes
• Refactoring mecânico: renomear, extrair métodos, mover código entre arquivos — rápido e preciso
• Pesquisa contextual: “como funciona RFC 8058?” produz resposta acionável em segundos
• Consistência: segue padrões estabelecidos no projeto (concerns, naming conventions, test structure) sem esquecer

Faz mal:

• Decisões de arquitetura: tende a over-engineer. Precisa de freio humano constante
• Conhecimento de domínio específico: não sabe que o Yahoo faz TLS fingerprinting ou que o VoiceDesign do Qwen produz sotaque europeu
• Opiniões: suaviza tudo. Prompts de personalidade viram mush genérico sem instruções explícitas
• Segurança proativa: implementa o que você pede, mas raramente sugere proteções que você não pediu (SSRF, rate limiting, encryption at rest)
• Priorização: executa qualquer coisa com igual entusiasmo. Não diz “isso é perda de tempo” ou “faça X antes de Y”

IA não programa sozinha, e não é inútil. É um multiplicador do programador, não um substituto. Um programador medíocre com IA produz código medíocre mais rápido. Um programador experiente com IA produz código bom na velocidade que antes só era possível com equipes.

Os Números que Importam

Vamos ao tamanho real do que foi construído em 8 dias:

Código

Total de código funcional: ~16.000 linhas. Total com testes: ~36.000 linhas.

Componentes

• 43 services no marvin-bot (scrapers, AI, parsers, validators, uploaders)
• 38 jobs no marvin-bot (geração de conteúdo, daily digest, podcast, infraestrutura)
• 12 services no newsletter (email delivery, publishing, assembly)
• 11 jobs no newsletter (sending, recovery, backup, blog publishing)
• 23 prompt templates de IA (personalidade, geração, podcast, tools)
• 17 shortcodes Hugo (renderização de seções no blog)
• 3 RubyLLM tools (image generation, web search, web fetch)

Pipeline

• 10 seções de conteúdo geradas por semana (anime, hacker news, youtube, market, world events, history x3, holidays, closing remarks)
• 10 daily digest jobs postando no Discord às 8h
• 1 podcast de ~30 minutos gerado por semana (script + TTS + assembly + S3)
• 1 newsletter montada, publicada no blog, e enviada por email toda segunda

Isso É 200 User Stories?

Olhei os 274 commits e tentei mapear pra user stories no sentido ágil. Nem todo commit é uma story — muitos são fixes dentro da mesma feature, ajustes de prompt, ou cleanup de CI. Mas a contagem conservadora de features distintas, cada uma com critérios de aceitação implícitos (funciona, tem teste, passa no CI, deploya):

Estimativa: ~180-200 user stories.

Isso inclui:

• Cada seção de newsletter (10 geradores distintos com scraping, AI, validação, fallback)
• O pipeline de email (delivery tracking, claiming atômico, recovery, List-Unsubscribe)
• O pipeline de podcast (script LLM, TTS dual-model, assembly, S3, RSS)
• O Discord bot (15+ comandos, embeds, context, multi-turn /ask, daily digest)
• O blog (Hugo + Hextra, 17 shortcodes, RSS podcast, SEO, GA)
• A subscription page (confirmação, temas, LGPD, termos de serviço)
• Infraestrutura (Kamal deploy, Cloudflare, SES config, RunPod, backups)
• 21 commits de segurança (SSRF, CSP, rate limiting, encryption, path traversal)

Em Scrum tradicional com uma equipe de 2-3 devs, uma story bem feita (com code review, QA, deploy) leva em média 1-2 dias. 200 stories × 1.5 dias / 2 devs = ~150 dias de trabalho, ou ~30 semanas em sprints de 2 semanas (contando planning, review, retro, e o overhead inevitável de coordenação entre pessoas).

Sendo generoso — equipe sênior, stories bem definidas, sem impedimentos — talvez 10-15 semanas.

Nós fizemos em 8 dias. Uma pessoa e um agente de IA.

Mas — e isso é crucial — eu não sou um dev qualquer e isso não é um projeto qualquer. Eu tenho 30 anos de experiência em software. Sei quais decisões importam e quais não. Sei quando parar de engenheirar e shipar. Sei quando o agente está errado antes de ele terminar de gerar o código. E o projeto é solo-developer, sem code review externo, sem QA separado, sem coordenação entre equipes.

O multiplicador real do agente não é “10x mais código”. É eliminar o tempo morto. Sem agente, 70% do meu tempo seria digitando boilerplate, lendo docs de API, escrevendo testes mecânicos, debugando typos. Com agente, esse tempo vira zero e eu foco 100% em decisões de arquitetura, domínio, e qualidade.

O CLAUDE.md: A Spec que Evolui

Uma coisa que funciona excepcionalmente bem com agentes de IA é ter um documento vivo que descreve o projeto. O CLAUDE.md do projeto tem 702 linhas e cobre:

• Visão geral da arquitetura
• Stack tecnológico completo
• Todas as variáveis de ambiente
• Estrutura do diretório de conteúdo
• Serviços, jobs e models de cada app
• 12 “common hurdles” com soluções documentadas
• 14 design patterns do projeto
• Pipeline semanal completo com horários
• Checklist pós-implementação

Esse documento não foi escrito de uma vez. Ele evoluiu com o projeto. Cada vez que descobríamos um hurdle (Yahoo Finance precisa de Chromium, HN RSS muda de formato, LLM suaviza opiniões), documentávamos no CLAUDE.md. Na próxima sessão, o agente já sabe.

É o equivalente do onboarding doc de uma equipe — mas o “novo membro da equipe” é o agente, e ele lê o doc inteiro em 2 segundos antes de cada interação. O investimento em documentação retorna exponencialmente com agentes de IA porque eles realmente leem.

As Lições

1. Vibe coding sem disciplina é protótipo descartável. 274 commits com CI, testes, security scanning, e small releases é o oposto de vibe coding. É engenharia de software com um copiloto que digita rápido.

2. TDD é mais importante com IA, não menos. O agente modifica código com confiança porque tem 1.323 testes como rede de segurança. Sem testes, cada mudança é uma aposta.

3. O humano decide o quê. O agente decide o como. Inverta e o resultado piora dramaticamente.

4. Refactoring contínuo é obrigatório. O agente empilha código. Se você não poda regularmente — extrair concerns, DRY duplicações, simplificar interfaces — a base de código vira um monólito de 500 linhas por arquivo.

5. Documentação é investimento com retorno imediato. Cada hora documentando no CLAUDE.md economiza horas de contexto perdido em sessões futuras.

6. Small releases são a chave. Cada commit é production-ready. Se algo der errado, reverte um commit. Se a feature era má ideia, nunca dependeu de outra. Isso só funciona com CI automático.

7. Segurança não é fase — é hábito. 21 commits de segurança espalhados por 8 dias, não concentrados numa “sprint de segurança” no final. Brakeman roda em todo commit. Vulnerabilidades são corrigidas no momento que aparecem.

8. O agente nunca diz “não”. Isso é um bug, não uma feature. Se você pede algo over-engineered, ele implementa com entusiasmo. Se pede algo inseguro, ele implementa sem reclamar. Você é o freio. Você é o code review. Você é o adulto na sala.

O Contra-Exemplo: FrankMD

Tudo que descrevi acima pode soar teórico. “Claro que TDD e refactoring contínuo são importantes” — todo mundo concorda em tese. Então vou provar empiricamente com um contra-exemplo do mesmo desenvolvedor, com o mesmo agente de IA, duas semanas antes.

Antes do M.Akita Chronicles, eu construí o FrankMD — um editor Markdown em Rails, estilo Obsidian/VSCode. 212 commits em 19 dias. Mesmo setup: eu + Claude Code como par de pair programming.

A diferença: no FrankMD, eu fiz o que qualquer desenvolvedor faz quando “é só um projetinho pessoal”. Foquei em features. Testes? Depois. Refactoring? Quando necessário. CI? Roda quando lembrar.

A Espiral do app_controller.js

O FrankMD é um SPA-like com Stimulus. No início, todo o JavaScript vivia em um único arquivo: app_controller.js. Aqui está o que aconteceu com ele ao longo dos commits:

O padrão é claro: construir-construir-construir-PARAR-refatorar. O arquivo cresceu 10x em 54 commits, atingiu quase 5.000 linhas, e então precisei de 6 rodadas de refatoração pra trazer de volta ao aceitável. Cada parada foi um commit grande (centenas de linhas movidas, dezenas de arquivos criados), não um ajuste cirúrgico.

O CSS seguiu o mesmo padrão: 1.053 linhas num único application.css, até o commit de refactoring que explodiu em 10 arquivos de tema + 9 arquivos de componente.

Testes: Antes vs. Depois

No FrankMD, o 2º commit foi “Add comprehensive test suite” — testes de sistema (integração browser). Parece responsável, mas esses testes cobriam o happy path e nada mais. Os testes de unidade JavaScript vieram só no commit #52, depois que o app_controller.js já tinha 5.000 linhas — porque eu precisava de testes pra refatorar com segurança. Testes retroativos.

A cobertura Ruby reflete isso: teve que ser empurrada de 77% pra 89% num commit explícito de “Add tests for untested success paths”. Não era TDD — era preencher buracos depois.

Os Números Lado a Lado

O número que importa: commits por dia. O M.Akita Chronicles teve 3x mais throughput — com TDD, CI, e refactoring contínuo — porque nunca precisou parar. Nenhum commit de “parar tudo e refatorar 5.000 linhas em 10 arquivos”. Nenhum momento de “preciso adicionar testes retroativos pra poder mexer nesse código sem medo”.

A Lição Concreta

Os 6 refactors grandes do FrankMD não foram “refactoring contínuo”. Foram cirurgias de emergência em dívida técnica acumulada. Cada um levou horas — não os 2 minutos do “extrai um concern” descrito acima. E cada um introduziu riscos: quando você move 1.500 linhas de um arquivo pra 10 arquivos novos, a chance de quebrar algo é proporcional ao tamanho da mudança.

Com TDD e refactoring contínuo, o M.Akita Chronicles nunca acumulou essa dívida. Os 27 refactors são commits pequenos — “Extract StealthBrowser”, “DRY bubble methods” — que levam minutos e são protegidos por 1.323 testes que já existiam quando o refactoring foi feito.

Mesmo desenvolvedor. Mesmo agente de IA. Duas abordagens diferentes. Resultado: o projeto disciplinado entregou mais, em menos tempo, com menos dor.

Conclusão

Esse projeto não é um showcase de IA. É um showcase de engenharia de software acelerada por IA. E a prova mais forte é que o mesmo desenvolvedor com o mesmo agente produziu resultados radicalmente diferentes dependendo do processo.

No FrankMD, sem disciplina, o resultado foi previsível: um arquivo de 5.000 linhas, 6 cirurgias de emergência, testes retroativos, e 11 commits por dia. No M.Akita Chronicles, com XP, o resultado foi 34 commits por dia, zero paradas forçadas, 1.323 testes orgânicos, e um sistema em produção em 8 dias. A variável não foi a IA — foi o processo.

274 commits em 8 dias não acontecem porque o agente é mágico. Acontecem porque Extreme Programming — pair programming, TDD, small releases, refactoring contínuo, integração contínua — funciona tão bem com um par de IA quanto funciona com um par humano. Talvez melhor em alguns aspectos: o agente nunca cansa, nunca discute por ego, nunca diz “mas sempre fizemos assim”, e lê 700 linhas de documentação antes de cada interação sem reclamar.

O futuro do desenvolvimento não é “IA substituindo programadores”. É programadores que sabem usar IA como ferramenta — com a mesma disciplina que sempre usaram com qualquer outra ferramenta — produzindo em uma semana o que equipes inteiras levam trimestres.

Não porque a IA é genial. Porque o processo é genial. O XP tinha razão desde o começo. Só faltava um par que nunca cansa e digita a 1000 palavras por minuto.

Lembrem-se:

“A IA é seu espelho, ele revela mais rápido quem você é. Se for incompetente, vai produzir coisas ruins mais rápido. Se for competente, vai produzir coisas boas mais rápido.” - by Akita

E não deixe de assinar minha nova newsletter The M.Akita Chronicles!

–

Testes unitários são a zona de conforto de todo desenvolvedor. Você mocka tudo, isola tudo, roda em milissegundos, e o verde no terminal te dá uma falsa sensação de segurança. Até o dia que você deploya e descobre que o serviço A grava num formato que o serviço B não consegue ler. Ou que o RSS do Hacker News mudou de Atom pra RSS e seu parser explodiu. Ou que a Yahoo Finance começou a retornar 429 depois do terceiro ticker porque o rate limit que funcionava em teste não existe na vida real.

Testes unitários provam que as peças funcionam isoladas. Testes de integração provam que o sistema funciona. E num projeto com múltiplas aplicações compartilhando dados via filesystem, a diferença entre os dois é a diferença entre “o código compila” e “a newsletter chega na inbox”.

O Problema: Três Apps, Um Filesystem, Zero Garantias

O projeto tem uma arquitetura incomum: três aplicações Rails/Hugo num monorepo, integradas via um diretório content/ compartilhado:

akitando-news/
├── marvin-bot/    # Gera conteúdo (Discord bot, AI, scraping)
├── newsletter/    # Monta e envia a newsletter
├── blog/          # Hugo + Hextra → Netlify
├── podcast-tts/   # Servidor TTS (Python/FastAPI)
└── content/       # Markdown + YAML, a cola entre tudo

O marvin-bot escreve Markdown com frontmatter YAML em content/anime/, content/hacker_news/, etc. O newsletter lê esses arquivos pra montar a newsletter. O blog serve o mesmo conteúdo como páginas estáticas. O podcast lê a newsletter montada pra gerar o script de diálogo.

O contrato entre esses sistemas é implícito. Não tem schema. Não tem API versionada. Não tem protobuf. O contrato é: “o arquivo Markdown tem esse frontmatter, com esses campos, nessa estrutura”. Se o marvin-bot muda o formato de um campo — digamos, muda image de string pra array — o newsletter quebra silenciosamente. Nenhum teste unitário de nenhum dos dois apps detecta isso.

Essa é a falha fundamental de testar sistemas distribuídos com testes unitários: você está testando cada lado do contrato separadamente, mas nunca o contrato em si.

Camada 1: Testes Unitários com Isolamento Paranoico

Antes de falar de integração, preciso explicar o que os testes unitários fazem nesse projeto — porque sem essa base, os testes de integração não teriam onde pisar.

Os 977 testes do marvin-bot rodam em paralelo usando todos os cores da máquina. Cada worker de teste tem seu próprio diretório:

parallelize(workers: :number_of_processors)

parallelize_setup do |worker|
  Rails.application.config.content_dir =
    Rails.root.join("tmp", "test_content_w#{worker}").to_s
end

Mas worker-level não é suficiente. Dentro de cada worker, múltiplos testes rodam sequencialmente — e se um teste deixa um arquivo em content/stories/, o próximo teste pode encontrar dados espúrios. A solução: um diretório único por teste:

setup do
  @base_content_dir = Rails.application.config.content_dir
  @test_content_dir = File.join(@base_content_dir, SecureRandom.hex(8))
  Rails.application.config.content_dir = @test_content_dir

  FileUtils.mkdir_p(File.join(@test_content_dir, "stories"))
  FileUtils.mkdir_p(File.join(@test_content_dir, "newsletters"))
  FileUtils.mkdir_p(File.join(@test_content_dir, "images"))
end

teardown do
  FileUtils.rm_rf(@test_content_dir) if @test_content_dir
  Rails.application.config.content_dir = @base_content_dir if @base_content_dir
end

Presta atenção na linha do teardown que restaura @base_content_dir. Sem ela, o próximo teste criaria seu diretório dentro do diretório do teste anterior — tmp/test_content_w3/abc123/def456/ — e em 50 testes você teria um caminho com 50 níveis de profundidade. Aprendi isso perdendo uma tarde inteira debugando por que os testes ficavam cada vez mais lentos ao longo da suite.

Esse padrão — worker-level base + per-test subdirectory + restore no teardown — é idêntico nos dois apps. E é o que permite rodar 977 testes em 7 segundos com 32 workers paralelos.

A regra de ouro: o content_dir de teste NUNCA pode apontar pro ../content real. Se apontar, o rm_rf do teardown apaga os prompts de produção. Não é hipotético — aconteceu durante o desenvolvimento.

Camada 2: O Ambiente de Integração

Testes unitários mockam tudo: APIs externas, AI, Discord, SES. Isso é correto — você não quer gastar $2 em tokens do GPT-5.2 toda vez que roda bin/rails test. Mas significa que os testes nunca exercitam o pipeline real.

O projeto tem um terceiro environment além de development e test: integration. Não é test. Não é staging. É um modo específico pra rodar o pipeline completo com dados reais, usando APIs reais, mas sem mandar emails de verdade:

# config/environments/integration.rb

# Jobs rodam inline (perform_later vira perform_now)
config.active_job.queue_adapter = :inline

# Emails salvos em arquivo ao invés de enviados via SES
config.action_mailer.delivery_method = :file
config.action_mailer.file_settings = {
  location: Rails.root.join("tmp/integration_emails")
}

O queue_adapter = :inline é crucial. Em produção, perform_later enfileira o job no SolidQueue e um worker separado executa. Em integração, executa na hora, no mesmo processo. Isso transforma o pipeline assíncrono de produção num pipeline síncrono que você pode rodar, observar, e debugar sequencialmente.

O SES é substituído por escrita em disco — cada email vira um arquivo HTML em tmp/integration_emails/. Depois de rodar o pipeline, você abre esses HTMLs no browser pra validar visualmente que o email renderiza correto.

Camada 3: DevCache — LLM Não É Idempotente

Aqui está um problema que quem trabalha com IA em produção conhece: chamar o GPT-5.2 com o mesmo prompt duas vezes não retorna a mesma resposta. E cada chamada custa dinheiro. Se você está iterando no pipeline de integração — rodando, ajustando um prompt, rodando de novo — gastar $3 por iteração fica caro rápido.

A solução é o DevCache: um cache file-based que só ativa no env de integração:

module DevCache
  CACHE_TTL = 1.day
  CACHE_ENVS = %w[integration].freeze

  def self.fetch(namespace, key)
    return yield unless enabled?

    path = cache_path(namespace, key)
    if path.exist? && File.mtime(path) > CACHE_TTL.ago
      return JSON.parse(path.read, symbolize_names: true)
    end

    result = yield
    path.write(JSON.generate(result))
    result
  end
end

Em produção e em test, DevCache.fetch executa o bloco direto. Em integração, salva o resultado como JSON e retorna o cached na próxima execução. TTL de 1 dia — suficiente pra iterar no mesmo dia sem recalcular, curto o bastante pra não servir dados velhos.

O código de geração usa assim:

summary = DevCache.fetch("summarize", url_key) do
  AiChat.summarize(article[:content], source_url: url)
end

Primeira execução: chama o GPT-5.2, paga $0.02, salva em tmp/dev_cache/summarize/{md5}.json. Segunda execução: lê do cache, custo zero. O FORCE=1 busta o cache quando você quer forçar regeneração — mas como flag explícita, não como default.

O DevCache existe em ambos os apps (marvin-bot e newsletter) com implementação idêntica. Quando roda integration:clean, ambos os caches são limpos.

Ponto: cache de LLM em ambiente de desenvolvimento não é otimização — é requisito. Sem ele, iterar num prompt que precisa de 8 chamadas de API fica financeiramente inviável.

Camada 4: Dados Reais via Rsync

Aqui é onde a maioria dos projetos para. Eles têm testes unitários, talvez um ambiente de staging, e mandam pro ar. O problema: staging usa dados de teste. Dados de teste são limpos demais. Não têm os edge cases que dados reais têm:

• Artigos com títulos em japonês (anime ranking)
• URLs que redirecionam 3 vezes antes de chegar no destino
• Imagens que retornam 200 com Content-Type text/html (CloudFlare error page)
• Newsletters anteriores com formatos de frontmatter ligeiramente diferentes
• Stories com score: null porque foram criadas antes de o campo existir

A solução: rsync de produção.

# Limpa conteúdo gerado (preserva stories e imagens de produção)
cd marvin-bot && bin/rails integration:clean

# Sincroniza content/ de produção pra local
rsync -avz --delete production:/path/to/content/ ../content/

# Roda o pipeline completo com dados reais
RAILS_ENV=integration bin/rails integration:pipeline

O integration:clean é cirúrgico: remove diretórios gerados (anime/, hacker_news/, newsletters/, podcasts/) mas preserva stories/ e images/ — que são dados submetidos pelo usuário via Discord. Depois do rsync, o diretório local é uma cópia exata da produção.

O pipeline então gera todas as seções a partir desses dados reais. Se um parser quebra com um título em coreano, você descobre aqui — não em produção às 17h de domingo quando os 8 jobs rodam em paralelo.

Camada 5: O Pipeline Completo

O coração do sistema de integração é o integration:pipeline. Ele simula a semana inteira de produção em uma execução:

RAILS_ENV=integration bin/rails integration:pipeline

O pipeline roda em ondas, respeitando dependências:

Wave 1 (paralelo, 8 jobs):
  Book, Holidays, History, Geek History,
  Anime, Hacker News, YouTube, World Events

Wave 2 (depende de World Events):
  Market Recap

Wave 3 (depende de tudo):
  Closing Remarks

Preflight → Newsletter Assembly → Podcast

Cada wave roda seus jobs em threads paralelas, exatamente como a produção faz com SolidQueue. A execução paralela não é um detalhe de implementação — é uma feature de teste. Se dois jobs tentam escrever no mesmo arquivo, ou se um job lê um arquivo que outro está no meio de escrever, o bug aparece aqui.

threads = to_run.map do |name, klass|
  Thread.new do
    ActiveRecord::Base.connection_pool.with_connection do
      run_single_job(name, klass, target_date, results)
    end
  end
end
threads.each(&:join)

O with_connection é necessário porque cada thread precisa de sua própria conexão SQLite — sem ele, conexões vazam e o pool esgota.

Ao final, o pipeline imprime uma tabela de status e um resumo de billing:

Esse billing summary não é vaidade — é controle de custos. Se um prompt refatorado aumenta o output tokens em 3x, você vê aqui antes de ir pra produção e gastar 10x num domingo com 200 stories.

Camada 6: Preflight — Validação Estrutural Automatizada

Depois de gerar todas as seções, o pipeline roda o ContentPreflight. Ele não valida o conteúdo — valida a estrutura. Cada seção é checada:

• Arquivo existe? Se content/anime/2026-02-16.md não existe, algo falhou.
• Item count mínimo? A seção de anime precisa de pelo menos 3 itens. Se tem 1, o gerador teve um problema.
• Markers obrigatórios? O Markdown precisa ter [COMMENTARY] e [AKITA] — sem eles, a newsletter assembly não sabe onde cortar.
• Dados específicos? Market recap precisa de pelo menos 5 ticker rows.

O resultado é um status por seção: pass, degraded, fail, ou skip. O pipeline usa isso pra decidir se a newsletter pode ser montada automaticamente ou se precisa de intervenção humana:

Em produção, esse resultado vai pro Discord como um embed. No pipeline de integração, é printado no terminal. A lógica é a mesma — o que muda é o canal de notificação.

Camada 7: Cross-App — Newsletter Assembly

Aqui está onde o monorepo paga dividendos. O marvin-bot precisa invocar o newsletter pra montar a newsletter final. Em produção, são servidores diferentes. No pipeline de integração, é um system() call:

env_vars = "RAILS_ENV=integration CONTENT_DIR=#{Shellwords.escape(content_dir)}"
cmd = "cd #{newsletter_dir} && #{env_vars} bin/rails integration:generate_all"
system(cmd)

O newsletter lê os arquivos que o marvin-bot acabou de gerar em content/, monta a newsletter, e salva o resultado em content/newsletters/. O CONTENT_DIR é passado explicitamente — os dois apps apontam pro mesmo diretório.

Se o formato do frontmatter mudou e o newsletter não consegue parsear, o erro aparece aqui. Se o SectionParser do newsletter divergiu do SectionParser do marvin-bot (são cópias idênticas, mas manuais), aqui é onde você descobre.

Depois da newsletter, o podcast: o pipeline invoca podcast:integration, que gera o script de diálogo a partir da newsletter montada, sintetiza o áudio via TTS, e monta o MP3 final. É o pipeline mais longo — de newsletter Markdown a MP3 pronto pro Spotify, passando por LLM de duas passadas e síntese de voz por turn.

O Valor de Testar com Dados de Produção

Vou dar exemplos concretos de bugs que só apareceram com dados reais:

1. Títulos de anime em japonês quebravam o slugify. O ContentWriter.slugify usava parameterize do Rails, que strip caracteres non-ASCII. Título: “進撃の巨人 Season 4” → slug: “season-4”. Dois animes com subtítulo “Season 4” collidiam no filesystem. Nunca apareceu em teste porque os fixtures usavam títulos em inglês.

2. O parser de HackerNews assumia RSS, mas o feed mudou pra Atom. rss/channel/item virou feed/entry. Testes unitários mockavam o XML. O parser em si nunca foi testado contra o feed real. Na integração com rsync do feed real, o parser retornou zero itens — detectado pelo preflight como fail.

3. Yahoo Finance retornava 429 depois do 5º ticker. O rate limiting não existia em teste (HTTP era mockado). Na integração real, os primeiros 5 tickers passavam, depois tudo falhava. A solução — sleep entre requests — nunca seria implementada sem dados reais revelando o problema.

4. Imagens com URL válida mas Content-Type errado. Uma CDN retornava 200 para URLs de imagem, mas com body HTML (Cloudflare error page). O UrlValidator.reachable? retornava true. O ImageProcessor.download_image baixava o HTML e tentava redimensionar. O mini_magick crashava com um erro obscuro. O fix: validar Content-Type no HEAD response — mas esse cenário nunca apareceria com URLs mockadas.

5. O newsletter assembly falhava com stories que tinham score: null. Stories antigas, criadas antes do campo score ter um default, tinham nil no frontmatter. O assembly tentava fazer sort_by { |s| s[:frontmatter]["score"] } — nil <=> "high" levanta ArgumentError. Só apareceu quando rsynquei dados de produção que tinham 3 meses de stories acumuladas.

Nenhum desses bugs seria pego por teste unitário. Todos foram pegos pelo pipeline de integração com dados reais.

Dicas Práticas

1. Separe Custo de Fidelidade

O pipeline de integração completo custa ~$0.40 em API calls. Não é muito, mas se você roda 10 vezes num dia iterando, são $4. O DevCache resolve isso: primeira execução paga, as seguintes são grátis.

Mas tem cenários onde você quer pagar de novo — quando muda um prompt e precisa ver o resultado real. O FORCE=1 busta o cache seletivamente. E o SKIP_EXISTING=1 pula seções que já foram geradas, economizando tempo quando você só quer re-rodar uma seção específica.

2. O Integration Environment Não É Staging

Staging é um servidor que roda 24/7 simulando produção. O integration environment é um modo de execução local que você liga quando precisa e desliga quando terminou. Não precisa de infraestrutura dedicada. Não precisa de database separado. É o mesmo código, na mesma máquina, com flags diferentes.

A diferença é filosófica: staging testa “o sistema funciona no servidor de staging?”. Integration testa “o sistema funciona com esses dados específicos?”. O primeiro é environment-dependent. O segundo é data-dependent. E bugs de dados são mais comuns que bugs de environment.

3. Clean Antes de Rsync, Não Depois

A ordem importa: limpe o conteúdo gerado antes de sincronizar de produção. Se fizer o contrário — rsync primeiro, clean depois — você perde os dados de produção que acabou de baixar.

O integration:clean é cirúrgico por design. Remove anime/, hacker_news/, newsletters/ (gerados), mas preserva stories/ e images/ (produção). Isso permite um workflow iterativo: rsync uma vez, roda o pipeline, ajusta um prompt, roda de novo — sem re-baixar 500MB de content.

4. Preflight É Seu Smoke Test

Não confie que “rodou sem exceção = está correto”. Um job de geração pode rodar, produzir um Markdown com 2 itens ao invés de 10, e retornar sucesso. O preflight detecta isso verificando contagens mínimas, markers obrigatórios, e estrutura esperada.

Na prática, todo bug de LLM que encontrei foi detectado pelo preflight: respostas truncadas, formato errado, seções faltando. O GPT-5.2 é bom, mas não é determinístico — e quando erra, erra de formas criativas que nenhum schema validation pegaria.

5. Billing Summary Não É Opcional

Se você está usando LLM em produção, todo pipeline de teste precisa reportar custo. Não por contabilidade — por engenharia. Um prompt que funciona mas custa 3x mais que o anterior é um bug de performance. Tokens de input e output por provider, custo por job, custo total — tudo visível a cada execução.

6. Monorepo Facilita, Mas Não Resolve

Ter os três apps no mesmo repositório facilita: um git bisect cobre mudanças em ambos os lados do contrato. Um PR que muda o formato do frontmatter no marvin-bot pode também atualizar o parser no newsletter — no mesmo commit.

Mas “pode” não é “garante”. O contrato entre os apps é file-based e implícito. Não tem tipo compartilhado, não tem interface comum. O SectionParser é copiado manualmente entre os dois apps. Se alguém edita um e esquece do outro, divergem. O teste de integração é a única verificação de que os dois lados concordam.

7. Preview Antes de Enviar

O pipeline não termina na geração. O newsletter tem um newsletter:preview que renderiza o resultado final em HTML light e dark:

cd newsletter
FILE=../content/newsletters/2026-02-16.md bin/rails newsletter:preview
# → tmp/preview/newsletter_light.html
# → tmp/preview/newsletter_dark.html

Abrir esses HTMLs no browser é o teste de integração visual. O Markdown pode estar perfeito, o frontmatter correto, todos os campos presentes — mas a imagem de um anime aparece esticada porque o aspect ratio mudou. Ou o bloco de comentário do Marvin não tem contraste suficiente no dark mode. Esses bugs são visuais — nenhum teste automatizado pega.

8. O Pipeline de CI É Diferente do Pipeline de Integração

São coisas diferentes. CI roda em todo commit:

bin/ci  # rubocop + bundler-audit + brakeman + tests (~22s)

Integração roda quando você quer validar o pipeline end-to-end — antes de um deploy, depois de mudar prompts, ou depois de rsync de dados novos de produção. CI é rápido e barato. Integração é lento e custa dinheiro. Os dois são necessários.

O Custo de Não Ter Integração

Vou ser direto: se esse projeto não tivesse o pipeline de integração, eu teria enviado pelo menos 3 newsletters quebradas.

Uma com seção de anime faltando porque o parser de XML assumia RSS e o feed era Atom. Uma com todas as imagens de YouTube apontando pra 404 porque o padrão de URL de thumbnail mudou. E uma com o market recap mostrando tickers do mês passado porque o Yahoo Finance bloqueou as requests e o job falhou silenciosamente.

Testes unitários teriam passado em todos esses cenários. O CI teria dado verde. O deploy teria ido pro ar. E às 7 da manhã de segunda-feira, 300 pessoas teriam recebido uma newsletter com buracos.

O pipeline de integração é caro — em tempo de setup, em custo de API, em complexidade de manutenção. Mas é ordens de magnitude mais barato que enviar conteúdo quebrado pra assinantes reais. Especialmente quando você só tem uma chance por semana.

Conclusão

A hierarquia de testes nesse projeto é:

1. Testes unitários (1.330 nos dois apps, 7 segundos em paralelo, $0): prova que cada peça funciona isolada
2. CI pipeline (rubocop + audit + brakeman + tests, ~22 segundos, $0): prova que o código está saudável
3. Pipeline de integração (dados reais, APIs reais, ~3 minutos, ~$0.40): prova que o sistema funciona
4. Preview visual (HTML no browser, manual, $0): prova que o resultado final é apresentável

Cada camada pega um tipo diferente de bug. Nenhuma sozinha é suficiente. E a que mais surpreende — a que pega os bugs que você jurava que não existiam — é a terceira: dados reais, pipeline real, sem mocks.

A confiança que você tem no seu sistema é proporcional ao quão reais são os dados nos seus testes. Mocka tudo e você tem 100% de coverage e zero de confiança. Testa com dados de produção e você tem a verdade — por mais inconveniente que seja.

E não deixe de assinar minha nova newsletter The M.Akita Chronicles!

–

Se eu te dissesse que dá pra rodar uma aplicação Rails completa em produção — com banco de dados, fila de jobs, cache — num único VPS de $12/mês sem instalar PostgreSQL, Redis, ou qualquer outro serviço externo, você acreditaria?

Pois é. Esse é o Rails 8 com SQLite e Kamal.

SQLite no Rails 8: agora é pra valer

O Rails 8 trouxe o SQLite como opção real de produção, não como brinquedo de desenvolvimento. E quando digo “real”, quero dizer que o rails new gera tudo pronto: banco principal em SQLite, SolidQueue (jobs) em SQLite, SolidCache (cache) em SQLite, SolidCable (WebSocket) em SQLite.

Quatro serviços que antes precisavam de PostgreSQL + Redis + Memcached agora são arquivos .sqlite3 no disco.

O WAL mode (Write-Ahead Logging) habilita leituras concorrentes enquanto uma escrita acontece. Pra aplicações com dezenas de milhares de requisições por dia — que é a imensa maioria das aplicações Rails no mundo — SQLite é mais que suficiente. E a latência de leitura é medida em microsegundos, não milissegundos. É acesso a disco local, não round-trip de rede.

# database.yml — produção com SQLite
production:
  primary:
    <<: *default
    database: storage/production.sqlite3
  queue:
    <<: *default
    database: storage/production_queue.sqlite3
    migrations_paths: db/queue_migrate
  cache:
    <<: *default
    database: storage/production_cache.sqlite3
    migrations_paths: db/cache_migrate

Três arquivos. Sem conexão TCP. Sem pooling. Sem “o PostgreSQL tá aceitando conexões?”. Backup é um VACUUM INTO e pronto — um comando SQL que produz uma cópia atômica. Restore? Cola o arquivo de volta. Tenta fazer isso com um dump de PostgreSQL de 2GB.

Kamal: Docker Deploy Sem Kubernetes

O Kamal é o deployer do Rails 8. Pensa nele como “SSH + Docker, mas inteligente”. Sem Kubernetes. Sem Helm charts. Sem YAML de 300 linhas descrevendo um Ingress Controller.

A configuração inteira cabe em um arquivo:

# config/deploy.yml
service: minha-app
image: meuregistry/minha-app

servers:
  web:
    hosts:
      - 107.170.70.49
    options:
      network: minha-network
    volumes:
      - minha-app-storage:/rails/storage
      - minha-app-content:/rails/content

proxy:
  ssl: true
  host: app.meudominio.com

builder:
  arch: amd64

env:
  clear:
    RAILS_LOG_LEVEL: info
  secret:
    - RAILS_MASTER_KEY
    - DATABASE_URL

O que o Kamal faz quando você roda kamal deploy:

1. Builda a imagem Docker localmente (ou em CI)
2. Pusha pro registry
3. SSH no servidor
4. Puxa a nova imagem
5. Roda migrations
6. Reinicia o container com zero downtime via kamal-proxy

O kamal-proxy é o segredo: ele funciona como reverse proxy na frente dos seus containers. Quando o deploy acontece, ele sobe o novo container, espera ele ficar healthy, redireciona o tráfego, e depois derruba o antigo. Seus usuários não percebem nada.

Volumes Docker: O Segredo do SQLite em Produção

O ponto crítico de SQLite em Docker é: os dados não podem morrer com o container. Docker volumes resolvem isso:

volumes:
  - minha-app-storage:/rails/storage

O diretório storage/ contém todos os bancos SQLite. Com o volume Docker, eles persistem entre deploys. O container é efêmero; os dados são permanentes.

Mas tem um detalhe que pega muita gente: se você roda dois serviços diferentes que compartilham dados via arquivos (não banco), precisa de um volume compartilhado:

# Serviço A escreve conteúdo
volumes:
  - content-compartilhado:/rails/content

# Serviço B lê conteúdo
volumes:
  - content-compartilhado:/rails/content

O mesmo volume Docker montado em dois containers. Simples, funciona, e não precisa de NFS, S3, ou qualquer coisa sofisticada. É um diretório no disco do servidor.

Múltiplos Serviços no Mesmo VPS

Uma vantagem pouco discutida do Kamal: você pode rodar múltiplas aplicações no mesmo servidor. O kamal-proxy roteia por hostname:

app.meudominio.com    → container-app
bot.meudominio.com    → container-bot

Cada serviço tem seu próprio deploy.yml, sua própria imagem Docker, seu próprio ciclo de deploy. Mas todos rodam no mesmo VPS, compartilhando a mesma rede Docker para comunicação interna.

O SSL é automático via Let’s Encrypt — o kamal-proxy cuida disso. Cada hostname ganha seu certificado sem você configurar nada.

Hooks: Automação no Deploy

O Kamal suporta hooks em vários pontos do ciclo de deploy. O mais útil é o pre-deploy, que roda antes do container novo substituir o antigo:

# .kamal/hooks/pre-deploy
#!/bin/sh
# Roda migrations antes do container ficar ativo
ssh root@$KAMAL_HOSTS \
  "docker exec minha-app-web bin/rails db:migrate"

Outros hooks úteis:

• post-deploy — notificar equipe, limpar cache
• pre-connect — verificar saúde do servidor
• docker-setup — instalar dependências no host

O Dockerfile que o Rails Gera

O Rails 8 gera um Dockerfile otimizado de produção. Alguns destaques:

# Multi-stage build: build stage grande, runtime stage mínima
FROM ruby:3.3-slim AS base

# Instala apenas dependências de runtime
RUN apt-get install -y libsqlite3-0

FROM base AS build
# Aqui instala tudo pra compilar gems nativas
RUN apt-get install -y build-essential libsqlite3-dev

# Copia e instala gems
COPY Gemfile* ./
RUN bundle install --without development test

# Stage final: só o necessário pra rodar
FROM base
COPY --from=build /usr/local/bundle /usr/local/bundle
COPY . .
RUN bundle exec bootsnap precompile --gemfile app/ lib/

Multi-stage build significa que a imagem final não tem compiladores, headers de desenvolvimento, ou qualquer coisa desnecessária. A imagem de produção fica enxuta.

Secrets: Sem .env em Produção

O Kamal tem um sistema de secrets que lê de um arquivo local (.kamal/secrets) e injeta como variáveis de ambiente no container. Esse arquivo nunca vai pro git:

# .kamal/secrets (gitignored)
RAILS_MASTER_KEY=abc123...
AWS_ACCESS_KEY_ID=AKIA...

No deploy.yml, você referencia:

env:
  secret:
    - RAILS_MASTER_KEY
    - AWS_ACCESS_KEY_ID

O Kamal lê do arquivo local e configura no servidor. Simples, seguro, sem HashiCorp Vault ou AWS Secrets Manager (a menos que você queira — Kamal suporta adaptadores).

Backup de SQLite: Absurdamente Simples (Se Fizer Certo)

Quer backup? Um comando SQL:

VACUUM INTO '/tmp/backup/newsletter.sqlite3';

O VACUUM INTO é atômico — produz uma cópia consistente e desfragmentada do banco, mesmo com escritas acontecendo. Roda enquanto a aplicação está servindo requests normalmente. E a cópia resultante é um banco SQLite completo e funcional — abre, consulta, restaura.

Atenção: copiar o arquivo .sqlite3 diretamente (cp, tar, rsync) de um banco em uso pode corromper o backup. Se uma escrita estiver em andamento no momento da cópia, você fica com um arquivo meio-escrito. O SQLite tem WAL (Write-Ahead Log) e journaling que protegem o banco ativo — mas a cópia crua não herda essa proteção.

Na prática, automatizei isso com um job Rails que roda a cada hora:

class BackupDatabaseJob < ApplicationJob
  def perform
    backup_dir = File.join(Rails.configuration.content_dir, "backups")
    FileUtils.mkdir_p(backup_dir)
    dest = File.join(backup_dir, "newsletter.sqlite3")
    ActiveRecord::Base.connection.execute("VACUUM INTO '#{dest}'")
  end
end

O backup vai pro diretório compartilhado de conteúdo — o mesmo que já é sincronizado com rsync pra máquina local. Sem agente de backup extra, sem serviço externo, sem snapshot de volume. Um SQL, um arquivo, um rsync.

Compara isso com pg_dump de um banco PostgreSQL de produção com dezenas de tabelas e constraints. O SQLite backup é um comando que produz um arquivo funcional. Restaurar? Copia de volta e reinicia.

Quando NÃO Usar SQLite

Vou ser honesto: SQLite não é pra tudo.

• Múltiplos servidores web escrevendo no mesmo banco? Não. SQLite é single-writer. Se você precisa de horizontal scaling com múltiplos nós, vai de PostgreSQL.
• Datasets massivos (centenas de GB)? PostgreSQL tem melhor query planning e paralelismo.
• Replicação e alta disponibilidade? PostgreSQL com streaming replication.

Mas a pergunta honesta é: quantas aplicações realmente precisam disso? A vasta maioria roda num único servidor e nunca vai precisar de mais. E pra essas, SQLite + Kamal é a combinação mais produtiva que existe hoje.

O Custo Real

Vamos fazer a conta:

E o custo cognitivo? Ao invés de debugar “por que o Redis perdeu meus jobs?”, “por que o PostgreSQL tá rejeitando conexões?”, “por que o cert expirou?”, você foca no que importa: o produto.

Conclusão

SQLite + Kamal não é downgrade. É que a maioria das aplicações nunca precisou da complexidade que a gente achava que precisava. O Rails 8 abraçou isso e entregou uma experiência de deploy que é, sem exagero, a mais simples que já existiu no ecossistema Ruby.

Um VPS. Um comando. Zero serviços externos. E uma aplicação que roda tão rápido quanto qualquer setup enterprise com 15 serviços no docker-compose.

E não deixe de assinar minha nova newsletter The M.Akita Chronicles!

–

Todo projeto Rails começa igual: você cria um admin panel. Active Admin, Administrate ou um CRUD caseiro. Tabelas, formulários, botões. E a cada semana, você usa 5% das telas que construiu.

Agora imagine que seu admin panel é uma conversa. Você cola um link; o sistema processa. Digita /week e vê o resumo. /approve e a newsletter está agendada. /ask akita como funciona o pipeline de podcast? e uma IA te explica a arquitetura do seu próprio sistema.

Esse é o Discord como interface operacional. Não é gambiarra — é a melhor interface CRUD que existe pra um time de uma pessoa.

Por Que Discord e Não Um Web Admin?

Vamos ser honestos sobre o que um admin panel exige:

1. Autenticação: login, sessão, CSRF, password reset
2. Autorização: roles, permissions, who can do what
3. UI: tabelas, paginação, formulários, validação client-side
4. Deployment: outra rota, outro controller, outro set de testes
5. Mobile: responsive? App? PWA?

E o que o Discord já te dá de graça:

1. Auth: Discord cuida. Você verifica o author_id
2. Autorização: uma lista de admin IDs e pronto
3. UI: embeds com cores, campos, thumbnails, reações como status
4. Deployment: zero. Usa o que já está deployado
5. Mobile: app nativo no iOS e Android, push notifications

O trade-off? Não serve pra tudo. Um CRUD complexo com formulários de 20 campos? Melhor um web admin. Mas pra operações de comando/resposta — que são 90% do que você faz no dia a dia — Discord é imbatível.

discordrb: A Gem Que Funciona

A gem discordrb (fork do shardlab, versão 3.7.2) é a mais madura pra Ruby. Não é perfeita — tem idiossincrasias. Mas funciona de verdade em produção.

O setup mínimo:

bot = Discordrb::Bot.new(
  token: token,
  intents: Discordrb::INTENTS[:server_messages] |
           Discordrb::INTENTS[:direct_messages] |
           (1 << 15)  # message_content intent
)

bot.message do |event|
  # Toda mensagem passa por aqui
end

bot.run

Aquele (1 << 15) é o Message Content Intent. Sem ele, seu bot recebe eventos mas o event.content vem vazio. Precisa habilitar no Discord Developer Portal > Bot > Privileged Gateway Intents. É a primeira armadilha que pega todo mundo.

Não vou detalhar como configurar um bot no Discord, tem vários tutoriais pra isso já, você acha fácil online. Vou focar só no meu caso de uso como exemplo.

Padrão 1: Parser + Dispatcher

Misturar parsing de comandos com lógica de negócio é receita pra espaguete. Separa em três camadas:

Discord Event → Parser → Dispatcher → Job/Service

O runner (que conversa com a API do Discord) é burro de propósito:

bot.message do |event|
  next if event.author.bot_account?

  parsed = SlashCommandParser.parse(event.content, attachments: urls)

  case parsed
  when SlashCommandParser::Command
    CommandDispatcher.dispatch(parsed, channel_id: channel_id)
    event.message.react("\u{2705}")  # checkmark
  when SlashCommandParser::Submission
    ProcessMessageJob.perform_later(url: parsed.url, tags: parsed.tags)
    event.message.react("\u{1F916}")  # robot
  end
rescue StandardError => e
  event.message.react("\u{274C}")  # red X
end

Três resultados visuais instantâneos: checkmark (comando aceito), robô (URL sendo processada), X vermelho (erro). O usuário sabe o que aconteceu sem esperar nenhuma resposta textual.

O parser retorna objetos tipados, não strings. O dispatcher faz um case gigante mas cada handler é um método isolado. Cada handler chama um job ou service. Nada de lógica de negócio no runner.

Evolução: Discord Application Commands

A versão inicial parseava texto puro — o usuário digitava /week e o parser interpretava. Funciona, mas tem limitações: sem autocomplete, sem validação de argumentos, sem documentação inline.

O Discord tem um sistema nativo de Application Commands — slash commands registrados na API que aparecem com autocomplete, descrição, e tipagem de parâmetros. Quando o usuário digita /, o Discord mostra todos os comandos disponíveis com descrição.

bot.register_application_command(:week, "List this week's stories", server_id: guild_id)
bot.register_application_command(:approve, "Approve newsletter for sending", server_id: guild_id)
bot.register_application_command(:ask, "Ask AI a question", server_id: guild_id) do |cmd|
  cmd.string("question", "Your question", required: true)
  cmd.string("personality", "AI personality", choices: { "Akita" => "akita", "Marvin" => "marvin" })
end

O handler usa bot.application_command ao invés de parsear texto:

bot.application_command(:week) do |event|
  CommandDispatcher.dispatch_week(channel_id: event.channel.id)
  event.respond(content: "Listing stories...")
end

Os dois sistemas coexistem: Application Commands pra quem prefere autocomplete, texto puro pra quem prefere digitar rápido. O dispatcher é o mesmo — a diferença é só como o comando chega.

Padrão 2: Reações Como Status

A feature mais subestimada do Discord pra bots é reações. Elas são feedback visual instantâneo que não polui o canal com mensagens:

• Checkmark = comando recebido e enfileirado
• Robô = processamento assíncrono iniciado
• X vermelho = erro (detalhes no embed que segue)

O usuário cola um link. Vê o robô aparecer. 30 segundos depois, um embed rico aparece com título, resumo, imagem e comentário da IA. Se algo falhar, aparece um embed vermelho com a mensagem de erro.

Isso é melhor que qualquer spinner de loading numa web UI.

Padrão 3: Embeds Ricos Como Dashboard

Discord embeds são surpreendentemente poderosos:

embed = {
  title: "Story Preview",
  url: source_url,
  color: 0xFF4500,           # vermelho-alaranjado pra high priority
  description: summary,
  thumbnail: { url: image },  # imagem do artigo
  fields: [
    { name: "M.Akita diz", value: akita_comment, inline: false },
    { name: "M.Arvin diz", value: marvin_comment, inline: false },
    { name: "File", value: "`stories/2026-02-16-titulo.md`", inline: false }
  ],
  footer: { text: "fire high | tech_news | verified" }
}

Discordrb::API::Channel.create_message(token, channel_id, "", false, [embed])

Cores indicam prioridade (vermelho = high, âmbar = medium, verde = low). O footer mostra score, seção e status de fact-check tudo numa linha. Você bate o olho e sabe o estado da coisa.

Para relatórios, múltiplos embeds lado a lado (Discord aceita até 10 por mensagem) funcionam como um mini-dashboard. O comando /week lista todas as histórias com ações inline — /load @a3f2b1 pra ver detalhes, /delete @a3f2b1 pra remover. O hash é estável (baseado no path do arquivo), então não muda quando você deleta outra história.

Padrão 4: Context Per Channel

Quando o usuário digita /load #3, o #3 se refere à listagem mais recente. Mas e se dois canais estão sendo usados simultaneamente?

class ChannelContext < ApplicationRecord
  EXPIRY_DURATION = 2.hours

  def self.for_channel(channel_id)
    find_or_create_by!(channel_id: channel_id.to_s)
  end

  def set_week_stories!(hash)
    update!(week_stories_json: hash.to_json, expires_at: EXPIRY_DURATION.from_now)
  end

  def resolve_story_reference(ref)
    if ref.match?(/\A@[a-f0-9]+\z/i)
      # Hash reference (stable across re-listings)
      hash = ref.delete("@").downcase
      week_stories.values.find { |path| md5_prefix(path) == hash }
    elsif ref.match?(/\A#?\d+\z/)
      week_stories[ref.delete("#")]
    end
  end
end

Cada canal tem seu próprio contexto com expiração de 2 horas. O /week armazena o mapeamento número→arquivo. Depois, /load #3 consulta esse contexto. Se expirou, o bot diz “run /week first”.

E o detalhe mais útil: referências por hash (@a3f2b1) ao invés de número. Quando você deleta a história #2, a #3 vira #2 — mas o hash @a3f2b1 continua apontando pro mesmo arquivo. Isso evita o clássico “deletei a errada porque a lista mudou”.

Padrão 5: Admin Check Simples

Nada de RBAC complexo. Uma lista de IDs:

ADMIN_COMMANDS = %i[delete update_score approve newsletter publish_blog].freeze

def self.dispatch(command, channel_id:, author_id:)
  if ADMIN_COMMANDS.include?(command.type) && !admin?(author_id)
    send_error(channel_id, "Permission denied. Admin privileges required.")
    return
  end
  # ...
end

def self.admin?(author_id)
  admin_ids = ENV["DISCORD_ADMIN_USER_IDS"].to_s.split(",")
  return true if admin_ids.empty?  # dev: sem IDs = tudo permitido
  admin_ids.include?(author_id)
end

Em dev, sem DISCORD_ADMIN_USER_IDS configurado, tudo é permitido. Em produção, é uma lista de Discord user IDs. Sem banco, sem roles table, sem middleware. Dez linhas resolvem autorização.

Padrão 6: Operações Assíncronas com Feedback

Operações lentas (gerar imagem, processar artigo, chamar IA) vão pra background jobs. O feedback visual é em três tempos:

def self.handle_ask(personality, question, attachments, channel_id)
  # 1. Feedback imediato: "estou pensando"
  thinking_id = DiscordNotifier.send_message(channel_id, content: "Thinking...")

  # 2. Job faz o trabalho pesado em background
  AskJob.perform_later(
    question,
    channel_id: channel_id,
    thinking_message_id: thinking_id
  )
end

# No AskJob:
def perform(question, channel_id:, thinking_message_id: nil)
  result = AiChat.ask_multimodal(question, tools: [GenerateImageTool])

  # 3. Remove "Thinking..." e mostra resultado
  DiscordNotifier.delete_message(channel_id, thinking_message_id)
  DiscordNotifier.send_message(channel_id, content: "**Marvin:** #{result[:text]}")
end

O “Thinking…” aparece instantaneamente, o job roda em background, e quando termina, a mensagem temporária some e o resultado real aparece. Se o job falhar, o “Thinking…” some e um embed de erro aparece.

Sem isso, o usuário manda uma pergunta e fica olhando pra tela sem saber se o bot ouviu. UX terrível.

Padrão 7: RubyLLM + Tool Calling No Discord

A parte mais poderosa: dar ferramentas pro LLM. O /ask tem três tools disponíveis: GenerateImageTool (gera imagens via Gemini), WebSearchTool (busca na web via Brave Search), e WebFetchTool (busca e resume páginas web). O LLM decide sozinho qual usar baseado na pergunta. Quando o usuário pede “gera uma imagem de um gato programando”, o LLM escolhe o tool certo:

class GenerateImageTool < RubyLLM::Tool
  description "Generate an image using Gemini. Use when the user asks to create or draw."
  param :prompt, desc: "Image description"
  param :aspect_ratio, desc: "1:1 or 16:9", required: false

  def execute(prompt:, aspect_ratio: "1:1")
    image_data = ImageGenerator.generate(prompt: prompt)
    return "Failed to generate image" unless image_data

    path = save_temp_file(image_data)
    Thread.current[:generated_images] << path

    "Image generated successfully. Tell the user it's ready."
  end
end

O Thread.current[:generated_images] é o truque pra passar dados de volta do tool pro job. O LLM chama o tool durante chat.ask, o tool salva o arquivo e registra o path. Depois que chat.ask retorna, o job pega os paths e manda pro Discord como file uploads.

Por que thread-local e não retorno direto? Porque o LLM pode chamar múltiplos tools numa única resposta, e o retorno do tool volta pro LLM (não pro seu código) — é ele que decide o que responder ao usuário. O thread-local é o side channel pra seu código saber o que aconteceu.

Padrão 8: Notificações de Status Em Produção

Todo job de geração de conteúdo notifica um canal dedicado:

module DiscordStatus
  def notify_start(label)
    DiscordNotifier.send_to_status_channel("Starting #{label}...")
  end

  def notify_done(label)
    DiscordNotifier.send_to_status_channel("#{label} complete.")
  end

  def notify_error(label, error)
    DiscordNotifier.send_to_status_channel("#{label} FAILED: #{error}")
  end
end

O canal de status é separado do canal de operação. Quando os 8 jobs de geração de conteúdo rodam no domingo às 17h, o canal de status vira um log em tempo real:

Starting Anime Ranking...
Starting Hacker News...
Starting YouTube Digest...
Anime Ranking complete.
YouTube Digest complete.
Hacker News complete.
Starting Market Recap...  (wave 2, after world events)
...

De manhã, se algo deu errado, você abre o Discord no celular e sabe exatamente o quê — sem SSH no servidor, sem grep em logs.

E quando o bot reinicia após um deploy:

bot.ready do |_event|
  status_channel = ENV["DISCORD_STATUS_CHANNEL_ID"]
  DiscordNotifier.send_message(status_channel, content: "Bot reconnected and ready.")
end

Simples, mas você sabe que o deploy funcionou sem checar nada.

Padrão 9: Cross-App Communication

O sistema tem dois apps Rails que precisam se falar. A newsletter precisa notificar o Discord quando termina de montar uma edição. Mas a newsletter não tem conexão Discord — quem tem é o marvin-bot.

Solução: HTTP relay.

# Na newsletter — manda pro marvin-bot
class DiscordRelayClient
  def self.send_embed(title:, description:, color:)
    post("/api/discord_notify",
      type: "embed",
      payload: { title: title, description: description, color: color }
    )
  end
end

# No marvin-bot — recebe e repassa pro Discord
class Api::DiscordNotifyController < ApplicationController
  def create
    case params[:type]
    when "embed"
      DiscordNotifier.send_embed(status_channel, params[:payload])
    when "message"
      DiscordNotifier.send_message(status_channel, content: params[:payload][:content])
    end
  end
end

A newsletter fala HTTP. O marvin-bot traduz pra Discord. Um ADMIN_TOKEN compartilhado autentica. Todos os métodos resgatam erros e retornam nil — se o Discord estiver fora, a newsletter não trava. Fire and forget.

Mas tem um segundo fluxo cross-app mais interessante: o trigger de podcast. Quando a newsletter é aprovada, ela precisa avisar o marvin-bot pra gerar o podcast:

# Na newsletter — dispara geração de podcast no marvin-bot
class MarvinBotClient
  def self.trigger_podcast(date:)
    post("/api/trigger/podcast", date: date.to_s)
  end
end

Isso inicia um pipeline inteiro no marvin-bot: script LLM de duas passadas → TTS por turno na GPU → assembly com loudnorm → upload S3. E o PublishAndSendJob da newsletter fica esperando (via retry_on PodcastNotReady) até o podcast ficar pronto. Dois apps, duas linguagens de backend (Ruby e Python), conectados por HTTP fire-and-forget com polling de resultado. Não é elegante — mas funciona toda semana sem intervenção.

Padrão 10: Cost Tracking Integrado

Cada chamada de IA é rastreada com tokens e custo estimado:

def self.create_chat(caller:, model:, provider:)
  chat = RubyLLM.chat(model: model, provider: provider)
  chat.on_end_message do |message|
    ApiUsage.create!(
      caller_name: caller,
      input_tokens: message.input_tokens,
      output_tokens: message.output_tokens,
      cost_usd: estimate_cost(model, message)
    )
  end
  chat
end

E no Discord: /cost mostra o gasto por mês, ano, e por provider. Sem dashboard separado, sem Grafana, sem nada. Um comando e a informação que importa.

Padrão 11: Nunca Falhe Silenciosamente

Esse é o padrão que eu devia ter implementado desde o começo, mas só aprendi da pior maneira — em produção.

O projeto tem ~10 daily jobs que buscam dados de fontes externas (Hacker News, GitHub Trending, Morningstar, etc.) e postam embeds no Discord. Cada client segue um padrão “defensivo”:

# O padrão que PARECE correto:
class DailyDevClient
  def self.fetch_popular(limit: 10)
    response = HTTParty.get(API_URL, headers: { "Authorization" => "Bearer #{token}" })
    return [] unless response.success?
    parse(response.body)
  rescue StandardError => e
    Rails.logger.warn("DailyDevClient failed: #{e.message}")
    []
  end
end

# E no job:
class DailyDailyDevJob < ApplicationJob
  def perform
    posts = DailyDevClient.fetch_popular(limit: 10)
    return if posts.empty?  # ← O PROBLEMA
    # ... posta embed no Discord
  end
end

Esse código nunca crasheia. Nunca levanta exceção. Nunca enche o log de erros. É o código mais “robusto” possível.

É também completamente inútil pra diagnóstico. Quando deployei e rodei os daily jobs manualmente, só um dos dez funcionou. Mas não havia nenhum erro nos logs. Nenhum. O return [] unless response.success? engolia o HTTP 401 sem logar. O return if posts.empty? descartava o resultado sem avisar ninguém. Tudo verde, tudo silencioso, zero dados.

A correção tem duas partes:

Parte 1: Clients logam o código HTTP:

unless response.success?
  Rails.logger.warn("DailyDevClient: API returned HTTP #{response.code}")
  return []
end

Parece óbvio, mas é fácil esquecer quando você escreve return [] como reflexo defensivo. O response.code é a informação que diferencia “token expirado” (401) de “rate limited” (429) de “API fora do ar” (503). Sem ele, tudo parece igual: array vazio.

Parte 2: Jobs avisam no Discord quando não têm dados:

module DailyDiscordEmbed
  def report_empty(title)
    Rails.logger.warn("#{self.class.name}: #{title} returned no results")
    channel_id = Rails.application.config.discord.channel_ids.first
    return unless channel_id.present?

    embed = {
      title: "⚠️ #{title}",
      description: "#{self.class.name} returned no results. Check logs.",
      color: 0xFFA500,  # laranja = warning, não vermelho = error
      timestamp: Time.current.iso8601
    }
    DiscordNotifier.send_embed(channel_id, embed)
  rescue StandardError => e
    Rails.logger.error("#{self.class.name} empty report failed: #{e.message}")
  end
end

Agora quando um daily job não traz dados:

def perform
  posts = DailyDevClient.fetch_popular(limit: 10)
  if posts.empty?
    report_empty("daily.dev Popular")
    return
  end
  # ...
end

Um embed laranja aparece no Discord. De manhã, abro o canal e vejo: “⚠️ daily.dev Popular returned no results”. Vou nos logs e descubro: “DailyDevClient: API returned HTTP 401”. Token expirado. Corrigido em 2 minutos.

Sem esse padrão, eu teria descoberto semanas depois — quando alguém perguntasse “por que nunca tem posts do daily.dev?”.

A lição: rescue => [] não é error handling. É error hiding. Cada ponto de falha precisa de dois sinais: um log com o detalhe técnico (HTTP code, mensagem de exceção) e uma notificação visual no canal onde você já está olhando (Discord). Se o bot É sua interface operacional, falhas do bot precisam aparecer NA interface.

Padrão 12: Conversas Com Memória (/ask Multi-Turn)

A primeira versão do /ask criava um RubyLLM::Chat novo a cada invocação. Funcionava, mas era como conversar com alguém que tem amnésia:

/ask o que é Ruby?
→ Ruby é uma linguagem de programação criada por Matz em 1995...

/ask compare com Python
→ Comparar o quê com Python? Poderia ser mais específico?

O ruby_llm já mantém histórico internamente — cada chat.ask() appende à lista de mensagens e manda o contexto completo pro modelo. O que faltava era persistir o objeto Chat entre invocações.

A solução é um store in-memory com três safeguards:

class AskSessionStore
  MAX_SESSIONS = 100       # total across all users
  SESSION_TTL = 2.hours    # inactivity timeout
  MAX_MESSAGES = 50        # ~25 exchanges, then auto-reset

  Session = Struct.new(:chat, :last_used, keyword_init: true)

  def get_or_create(author_id, personality, system_prompt:, tools:)
    synchronize do
      cleanup_expired
      key = [author_id, personality]

      if (session = @sessions[key])
        session.last_used = Time.current
        if session.chat.messages.length > MAX_MESSAGES
          @sessions.delete(key)
          return create_session(key, system_prompt: system_prompt, tools: tools)
        end
        session.chat
      else
        evict_oldest if @sessions.size >= MAX_SESSIONS
        create_session(key, system_prompt: system_prompt, tools: tools)
      end
    end
  end
end

A chave vai ser (author_id, personality) — cada usuário tem sessões separadas pro Marvin e pro Akita. Volátil de propósito: reiniciou o servidor, perdeu o histórico. Sem banco, sem serialização, sem complexidade. É memória de trabalho, não persistência.

O /ask clear reseta a sessão. Sem isso, não tem como “começar de novo” quando a conversa fica confusa.

Agora:

/ask o que é Ruby?
→ Ruby é uma linguagem de programação criada por Matz em 1995...

/ask compare com Python
→ Ruby e Python têm filosofias parecidas — ambas priorizam felicidade do
  programador — mas Ruby abraça blocos e metaprogramação enquanto Python
  prefere explicitness...

O LLM sabe que “compare” se refere a Ruby porque o histórico da sessão inclui a pergunta anterior. É a diferença entre um chatbot e um assistente.

Padrão 13: Registrando Application Commands (Autocomplete Nativo)

A seção sobre Application Commands acima mostrou o conceito simplificado. Na prática, registrar 18 comandos com subcommands, parâmetros tipados e choices exige uma estrutura dedicada. Veja como o projeto resolve isso.

O Problema Com Texto Puro

Quando o bot só parseia texto, o usuário precisa decorar a sintaxe:

/update score #1 #2 #3 high       ← funciona
/update score #1 #2 #3 alta       ← falha silenciosamente
/update scoree #1 high             ← ignorado

Sem autocomplete, sem validação de parâmetros, sem documentação inline. O usuário digita / e não sabe o que está disponível.

O Módulo DiscordCommands

Toda a definição de comandos vive num módulo separado com dois métodos públicos: register! (cadastra os comandos na API do Discord) e setup_handlers! (conecta os handlers ao bot):

module DiscordCommands
  SCORE_CHOICES  = { "High" => "high", "Medium" => "medium", "Low" => "low" }.freeze
  SECTION_CHOICES = {
    "Tech" => "tech", "Global" => "global", "Financial" => "financial",
    "Q&A" => "qa", "Entertainment" => "entertainment", "Open Source" => "opensource",
    "Product" => "product", "Book" => "book"
  }.freeze
  PERSONALITY_CHOICES = { "Marvin (default)" => "marvin", "Akita" => "akita" }.freeze

  def self.register!(bot)
    server_id = Rails.application.config.discord.server_id
    sid = server_id.present? ? server_id.to_i : nil

    register_week(bot, sid)
    register_add(bot, sid)
    register_update(bot, sid)
    register_ask(bot, sid)
    # ... mais 14 comandos
  end

  def self.setup_handlers!(bot)
    setup_week_handlers(bot)
    setup_add_handler(bot)
    setup_update_handlers(bot)
    setup_ask_handlers(bot)
    # ... mais 14 handlers
  end
end

Guild vs Global

O server_id (ou sid) controla o escopo do registro. Com server_id, o comando aparece instantaneamente no servidor especificado. Sem, o comando é global — disponível em todos os servidores, mas pode levar até uma hora pra propagar.

Para um bot privado de operações internas, sempre use guild-scoped. O env var DISCORD_SERVER_ID é configurado no deploy:

sid = server_id.present? ? server_id.to_i : nil
bot.register_application_command(:week, "Story list and weekly report", server_id: sid)

Se sid for nil, o discordrb registra globalmente. Em dev, é conveniente; em produção, guild-scoped é mais rápido e permite comandos diferentes por servidor.

Anatomia De Um Comando

O método mais simples — sem parâmetros:

def self.register_count(bot, sid)
  bot.register_application_command(:count, "Show story count for this week", server_id: sid)
end

Com parâmetros tipados:

def self.register_add(bot, sid)
  bot.register_application_command(:add, "Submit a URL for the newsletter", server_id: sid) do |cmd|
    cmd.string(:url, "The URL to submit", required: true)
    cmd.string(:tags, "Tags (e.g. #tech #high)")
    cmd.string(:comment, "Optional comment about this link")
  end
end

O Discord mostra isso como um formulário inline: campo url obrigatório, tags e comment opcionais. O usuário vê a descrição de cada parâmetro enquanto preenche.

Subcommands: Agrupando Ações

Comandos complexos usam subcommands. /update sozinho não faz nada — o usuário precisa escolher o que atualizar:

def self.register_update(bot, sid)
  bot.register_application_command(:update, "Update story properties", server_id: sid) do |cmd|
    cmd.subcommand(:score, "Update story priority score") do |sub|
      sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
      sub.string(:level, "Priority level", required: true, choices: SCORE_CHOICES)
    end
    cmd.subcommand(:tag, "Update story section tag") do |sub|
      sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
      sub.string(:section, "Section tag", required: true, choices: SECTION_CHOICES)
    end
    cmd.subcommand(:image, "Update story image") do |sub|
      sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
      sub.attachment(:file, "Image file (omit for AI generation)")
    end
    # ... mais subcommands: title, description, comment, source
  end
end

Quando o usuário digita /update, o Discord mostra uma lista de subcommands: score, tag, title, description, comment, image, source. Ao escolher score, aparece o campo stories (texto livre) e level (dropdown com High/Medium/Low). Impossível errar a sintaxe.

Choices: Dropdowns Nativos

O hash SCORE_CHOICES vira um dropdown no Discord. A chave é o label visível (“High”), o valor é o que chega no handler (“high”):

SCORE_CHOICES = { "High" => "high", "Medium" => "medium", "Low" => "low" }.freeze

# No registro:
sub.string(:level, "Priority level", required: true, choices: SCORE_CHOICES)

O usuário não precisa lembrar se é “high”, “HIGH”, “alta”, ou “3”. Seleciona no dropdown e pronto. Isso elimina uma categoria inteira de erros de input.

Attachments: Upload de Arquivos

O Discord suporta parâmetros do tipo attachment — o usuário pode arrastar um arquivo direto no comando:

cmd.subcommand(:image, "Update story image") do |sub|
  sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
  sub.attachment(:file, "Image file (omit for AI generation)")
end

No handler, os attachments resolvidos vêm como URLs do CDN do Discord:

def self.resolve_attachments(event)
  return [] unless event.resolved&.attachments&.any?
  event.resolved.attachments.values.map(&:url)
end

Lifecycle: Onde Registrar, Onde Conectar Handlers

Esse é o ponto que mais confunde. Os handlers precisam ser registrados antes do bot.run. O registro na API do Discord pode acontecer no bot.ready (que dispara após a conexão WebSocket):

class MarvinBotRunner
  def self.run!
    bot = Discordrb::Bot.new(token: token, intents: ...)

    # 1. Handlers ANTES do bot.run (senão o bot não sabe como responder)
    DiscordCommands.setup_handlers!(bot)

    bot.ready do |_event|
      # 2. Registro na API DEPOIS da conexão (idempotente, safe on reconnect)
      DiscordCommands.register!(bot)
    end

    bot.run
  end
end

Por que no bot.ready? Porque o bot pode reconectar (Discord fecha WebSockets periodicamente). O register! é idempotente — registrar o mesmo comando duas vezes não duplica, só atualiza. Colocar no ready garante que os comandos existem mesmo após um reconnect.

Bridge: Application Command → CommandDispatcher

O ponto mais elegante da arquitetura: o handler de Application Command não tem lógica de negócio. Ele traduz os parâmetros do Discord pro formato que o CommandDispatcher já espera:

def self.dispatch_interaction(event, type, match: [nil], attachments: [])
  event.respond(content: "\u{2705}", ephemeral: true)  # checkmark só visível pro autor
  command = SlashCommandParser::Command.new(
    type: type,
    args: { match: match, attachments: attachments }
  )
  CommandDispatcher.dispatch(command,
    channel_id: event.channel.id.to_s,
    message_id: nil,
    author_id: event.user.id.to_s
  )
rescue StandardError => e
  Rails.logger.error("Discord interaction error (#{type}): #{e.message}")
end

Cada handler de subcommand é um one-liner que monta os argumentos e chama dispatch_interaction:

bot.application_command(:update).subcommand(:score) do |event|
  stories = event.options["stories"]
  level = event.options["level"]
  dispatch_interaction(event, :update_score, match: [nil, stories, nil, level])
end

O CommandDispatcher não sabe se o comando veio de texto puro ou de Application Command. A mesma lógica, a mesma autorização, os mesmos jobs. Nenhum código duplicado.

O Resultado

O projeto registra 18 Application Commands com combinações de subcommands, parâmetros tipados, dropdowns e upload de arquivos. O usuário digita / e vê tudo disponível com descrição. Escolhe um comando e o Discord guia o preenchimento campo a campo. Erros de sintaxe são impossíveis — o Discord valida antes de enviar.

E os dois sistemas coexistem: quem prefere autocomplete usa Application Commands, quem prefere digitar rápido usa texto puro. O CommandDispatcher recebe os dois da mesma forma. Adicionar um novo comando é adicionar um register_*, um setup_*_handler, e um método no dispatcher — sem mexer no runner.

As Armadilhas do discordrb

Nem tudo são flores. Algumas dores reais:

Gateway disconnects: O WebSocket com o Discord cai de vez em quando. O discordrb reconecta automaticamente, mas seus handlers bot.ready e bot.message precisam ser resilientes a reconexões.

Message Content Intent: Desde 2022, bots em mais de 75 servidores precisam de aprovação pra ler conteúdo de mensagens. Pra bots privados (que é o caso de operação interna), isso não é problema. Mas se você planeja distribuir o bot, prepare o paperwork.

API Rate Limits: O Discord rate-limita por rota. Mandar 10 embeds de uma vez pro mesmo canal? Vai bater no limite. O discordrb faz rate limit handling internamente, mas chamadas rápidas demais causam delays visíveis.

Embed Limits: Título máximo 256 chars. Description 4096. Field value 1024. Excedeu? Erro silencioso. Sempre trunca antes de enviar.

File Uploads: Limit de 25MB no plano gratuito, 50MB com Nitro. Pra imagens de IA geradas isso nunca é problema, mas se for mandar PDFs ou áudio, cuidado.

Quando NÃO Usar Discord Como Admin

• Formulários complexos: editar 15 campos de um registro? Tela web
• Bulk operations: importar CSV com 1000 registros? Script
• Visualização de dados: gráficos, dashboards analíticos? Grafana/Metabase
• Aprovação multi-step: workflows com 5 etapas de aprovação? Precisa de estado persistido

Mas pra o dia a dia operacional — curar conteúdo, aprovar newsletters, monitorar jobs, checar custos, conversar com IA — Discord é a interface mais produtiva que já usei. E o melhor: os assinantes nunca vão saber que a newsletter semanal deles foi curada por um cara digitando comandos no Discord do celular enquanto toma café.

Conclusão

Usar Discord como admin panel não é preguiça — é pragmatismo. A melhor interface é a que você já usa o dia inteiro. Auth, push notifications, mobile, rich formatting, file sharing — tudo de graça. Você só constrói a lógica de negócio.

A gem ruby_llm com tool calling leva o bot de “executor de comandos” pra “assistente que pensa”. Com memória de sessão, pensa e lembra. Quando o LLM pode gerar imagens, buscar na web, manter contexto entre perguntas, e responder sobre a arquitetura do próprio sistema — aí deixou de ser CRUD e virou co-piloto.

E o padrão Parser → Dispatcher → Job mantém tudo testável. O parser não sabe nada de Discord. O dispatcher não sabe nada de IA. Os jobs não sabem nada de interface. Troca qualquer uma dessas camadas e as outras nem percebem.

No fim, a melhor admin UI é a que não precisa de deploy separado. E o pior bug é o que falha em silêncio — se o bot é sua interface operacional, as falhas do bot precisam aparecer na interface, não escondidas num log que ninguém lê.

E não deixe de assinar minha nova newsletter The M.Akita Chronicles!

–

Vou ser direto: a maioria dos desenvolvedores trata background jobs como se fossem scripts que rodam uma vez e pronto. “Ah, coloca num Sidekiq e tá bom.” Não, não tá bom. Jobs que processam coisas importantes — enviar emails, publicar conteúdo, chamar APIs externas — precisam ser tratados como cidadãos de primeira classe na sua arquitetura.

Neste post vou mostrar como o Rails 8 com ActiveJob e SolidQueue mudou minha perspectiva sobre processamento assíncrono. Não é teoria — são padrões que emergiram de um sistema real rodando em produção toda semana.

O Problema: Jobs São Frágeis por Natureza

Pense no cenário: você tem um job que monta uma newsletter, publica num blog via API do GitHub, espera um podcast ficar pronto, e depois dispara emails para centenas de assinantes. Qualquer passo pode falhar. A API pode dar timeout. O podcast pode demorar mais que o esperado. O servidor pode reiniciar no meio do envio.

Se você tratar isso como um script linear, vai sofrer. A pergunta certa não é “como faço esse job rodar?” — é “como faço esse job se recuperar quando algo der errado?”

Padrão 1: retry_on Com Exceções Específicas

O retry_on do ActiveJob é absurdamente poderoso, mas a maioria usa errado. Olha o anti-padrão clássico:

class MeuJob < ApplicationJob
  retry_on StandardError, wait: 5.seconds, attempts: 3
end

Isso re-tenta qualquer erro 3 vezes e desiste. Serve pra quase nada no mundo real. O padrão que funciona é criar exceções específicas para estados transitórios:

class PodcastNotReady < StandardError; end

class PublishAndSendJob < ApplicationJob
  retry_on PodcastNotReady, wait: 15.minutes, attempts: 16

  def perform(newsletter_id)
    metadata = check_podcast_metadata(newsletter_id)
    raise PodcastNotReady, "Aguardando podcast" unless metadata
    # continua o trabalho...
  end
end

Percebe o que está acontecendo? O job espera até 4 horas (15min × 16) pelo podcast ficar pronto, fazendo polling a cada 15 minutos. Não é um loop infinito — tem um limite claro. E quando estoura esse limite, você trata o timeout explicitamente:

rescue PodcastNotReady => e
  if executions >= 16
    # Publica sem podcast e avisa a equipe
    publish_without_podcast(newsletter)
    notify_team("Podcast não ficou pronto a tempo")
  else
    raise # re-raise pra SolidQueue agendar o próximo retry
  end
end

Isso é degradação graciosa. O sistema não para porque um componente falhou — ele se adapta e continua.

Padrão 2: Locks Distribuídos

Quando você tem múltiplos caminhos que podem disparar o mesmo job (um cron de segurança, um trigger manual, uma API), precisa garantir que só uma instância roda por vez.

O conceito é simples: um lock baseado em arquivo (ou banco) que expira automaticamente:

class DeployLock
  LOCK_DIR = Rails.root.join("tmp/locks")
  DEFAULT_TTL = 30.minutes

  def self.with_lock(name, ttl: DEFAULT_TTL)
    acquire!(name, ttl: ttl)
    yield
  ensure
    release(name)
  end
end

Com SQLite, isso é trivial — sem Redis, sem coordenação externa. O lock tem TTL pra não travar se o processo morrer. E o ensure garante que libera mesmo se o bloco levantar exceção.

Padrão 3: Envio Atômico de Emails

Aqui é onde a maioria dos sistemas de newsletter falha espetacularmente. O cenário: você está enviando 500 emails e o servidor reinicia no email 247. O que acontece quando o job re-executa?

Se você só iterou uma lista, vai reenviar os primeiros 247. Seus assinantes vão adorar receber a newsletter duas vezes.

A solução é claiming atômico por destinatário:

# Antes de enviar, cria um registro por assinante
subscribers.each do |sub|
  EmailDelivery.create!(
    newsletter: newsletter,
    subscriber: sub,
    status: "pending"
  )
end

# Na hora de enviar, faz claim atômico
delivery = EmailDelivery
  .where(status: ["pending", "failed"])
  .lock
  .first

delivery.update!(status: "sending")
send_email(delivery)
delivery.update!(status: "sent")

Se o servidor morrer entre sending e sent, o registro fica como “sending” — e um job de recuperação (RecoverStaleDeliveriesJob) periodicamente move esses registros para “unknown” depois de um timeout, pra que nunca sejam automaticamente reenviados. Emails ambíguos nunca são reenviados automaticamente. Esse é o tipo de detalhe que separa um sistema hobby de um sistema de produção.

Padrão 4: Jobs Orquestradores

Um erro comum é colocar lógica demais num único job. O padrão que funciona é ter jobs orquestradores que delegam para jobs especializados:

PublishAndSendJob (orquestrador)
  ├── Espera podcast (retry_on PodcastNotReady)
  ├── PublishToBlogJob.publish(newsletter)
  └── SendNewsletterJob.perform_now(newsletter.id)
        └── SendSingleEmailJob (por assinante)

O orquestrador coordena a sequência. Cada job especializado sabe fazer exatamente uma coisa e pode ser re-executado independentemente. Se o envio de emails falhar, você pode re-disparar só o SendNewsletterJob sem republicar o blog.

Padrão 5: Safety Nets com Cron

Não confie em uma única cadeia de execução. O cron do SolidQueue (config/recurring.yml) serve como rede de segurança:

send_newsletter:
  class: SendNewsletterJob
  schedule: "0 12 * * 1"  # Segunda 9h BRT (UTC-3)

Se o PublishAndSendJob das 7h falhou catastroficamente, o cron das 9h dispara o SendNewsletterJob como fallback. O job verifica se a newsletter já foi enviada e faz no-op se sim. Idempotência é a palavra-chave aqui — o job pode rodar quantas vezes quiser e o resultado é sempre o mesmo.

Mas cuidado com o inverso: um job que se reagenda infinitamente quando não encontra trabalho é uma bomba-relógio. Se o job não encontra newsletter pronta, ele simplesmente retorna. O cron cuida de tentar de novo na próxima semana.

Padrão 6: Notificações de Status

Todo job de longa duração deve comunicar seu progresso. Um concern simples resolve:

module DiscordStatus
  extend ActiveSupport::Concern

  def notify_start(message)
    DiscordNotifier.send(channel: status_channel, text: "▶️ #{message}")
  end

  def notify_done(message)
    DiscordNotifier.send(channel: status_channel, text: "✅ #{message}")
  end

  def notify_error(message)
    DiscordNotifier.send(channel: status_channel, text: "❌ #{message}")
  end
end

Cada job inclui o concern e chama notify_start no início, notify_done no sucesso, notify_error no rescue. Quando algo dá errado às 3 da manhã, você acorda e vê exatamente onde parou — sem precisar cavar logs.

SolidQueue: O Fim da Dependência de Redis

Uma nota sobre SolidQueue, que veio como padrão no Rails 8: usar o mesmo banco SQLite para jobs e dados da aplicação simplifica drasticamente a operação. Não precisa de Redis rodando separado. Não precisa se preocupar com o Redis reiniciar e perder jobs que estavam na memória.

Os jobs ficam persistidos no banco. Se o servidor reiniciar, eles estão lá esperando. O retry state é preservado. É absurdamente mais simples que a alternativa, e pra 99% dos casos, a performance é mais que suficiente.

Conclusão

O Rails 8 com ActiveJob e SolidQueue não inventou nada revolucionário. O que ele fez foi deixar ridiculamente fácil de implementar padrões que antes precisavam de infraestrutura pesada:

• retry_on com exceções específicas e limites claros
• Locks distribuídos com TTL automático
• Claiming atômico pra operações que não podem duplicar
• Jobs orquestradores que delegam e se recuperam
• Crons de segurança como fallback
• Notificações pra visibilidade operacional

Nenhum desses padrões é complicado sozinho. Mas juntos, é o que faz a diferença entre um sistema que quebra na primeira falha e um que aguenta o tranco em produção — e te deixa dormir tranquilo na segunda-feira.

E não deixe de assinar minha nova newsletter The M.Akita Chronicles!

–

Existe uma obsessão no mercado de que frontend = React. Ou Vue. Ou Svelte. Ou o framework da semana. E se eu te disser que é possível ter um frontend moderno, responsivo, com dark mode, email-compatible, multi-plataforma — sem uma única linha de JavaScript framework?

Não estou falando de sites estáticos dos anos 2000. Estou falando de Tailwind CSS v4 no Rails, Hugo com tema Hextra pro blog, e templates de email que funcionam do Gmail ao Outlook 2016. Tudo no mesmo projeto, com um desenvolvedor.

Tailwind CSS v4: O Fim do CSS Artesanal

Eu tenho uma confissão: CSS sempre foi minha kryptonita. Não porque é difícil — mas porque é imprevisível. Você muda um margin-top e quebra o layout de uma página que nem tocou. Cascata, especificidade, herança — é um campo minado.

Tailwind resolve isso da forma mais pragmática possível: classes utilitárias direto no HTML.

<div class="flex items-center gap-4 p-6 bg-white dark:bg-gray-800
            rounded-xl shadow-sm border border-gray-200 dark:border-gray-700">
  <img class="w-12 h-12 rounded-full" src="/images/avatar.jpg">
  <div>
    <h3 class="font-semibold text-gray-900 dark:text-gray-100">Título</h3>
    <p class="text-sm text-gray-500 dark:text-gray-400">Descrição</p>
  </div>
</div>

“Mas isso é inline style com passos extras!” — Não, não é. É um sistema de design com constraints. Você não escolhe “margin: 17px” — você escolhe m-4 (16px) ou m-5 (20px). Esse constraint force consistência visual sem precisar de um design system documentado em 40 páginas.

E o Tailwind v4, que veio com o Rails via tailwindcss-rails, tem uma mudança fundamental: CSS-first configuration. Acabou o tailwind.config.js. Tudo é CSS:

@import "tailwindcss";

@theme {
  --color-brand: #8b5cf6;
  --font-sans: "Inter", system-ui, sans-serif;
}

Menos um arquivo de config. Menos um passo de build. Mais simples.

Dark Mode: Respeite Seu Usuário

Uma coisa que me irrita profundamente é site que ignora preferência de tema do sistema operacional. O usuário configurou dark mode no OS — respeita.

Com Tailwind, dark mode é trivial:

<body class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">

O dark: prefixo aplica o estilo quando o sistema operacional está em dark mode (via prefers-color-scheme: dark). Não precisa de JavaScript. Não precisa de toggle. Não precisa de cookie. Funciona.

Mas “funciona” é o mínimo. O desafio real é manter consistência entre dezenas de componentes. Toda cor que você usar precisa de uma variante dark:. Todo background, todo texto, toda borda.

O truque: crie convenções e siga. Background principal? bg-white dark:bg-gray-900. Texto primário? text-gray-900 dark:text-gray-100. Texto secundário? text-gray-500 dark:text-gray-400. Bordas? border-gray-200 dark:border-gray-700. Com 4-5 pares definidos, 90% dos componentes ficam cobertos.

Hugo + Hextra: Blog Sem Banco de Dados

O blog do projeto roda Hugo com o tema Hextra. Hugo é um gerador de sites estáticos escrito em Go — absurdamente rápido. Rebuild completo em <500ms mesmo com dezenas de páginas.

O que torna o Hextra especial é que ele é um tema de documentação adaptado pra blog. Sidebar de navegação, search integrado, table of contents — tudo pronto. E customizável via layouts parciais:

layouts/
├── _partials/
│   ├── custom/
│   │   └── head-end.html          # Injeta analytics, fonts, CSS customizado
│   └── section-box.html           # Partial compartilhado (DRY, veja abaixo)
├── blog/
│   └── home.html                  # Homepage customizada
├── newsletters/
│   └── single.html                # Template de newsletter individual
├── podcast-transcripts/
│   └── list.html                  # Listagem de episódios
└── shortcodes/                    # 17 shortcodes — componentes sem JS
    ├── podcast-turn.html          # Balão de fala no transcript
    ├── akita-comment.html         # Comentário do Akita
    ├── marvin-comment.html        # Comentário do Marvin
    ├── history-timeline.html      # Timeline de eventos históricos
    ├── market-ticker.html         # Tabela de tickers financeiros
    ├── market-map.html            # Mapa FinViz S&P 500
    ├── subscribe-cta.html         # Call-to-action de inscrição
    ├── score.html                 # Badge de relevância (high/medium/low)
    ├── holidays.html              # Feriados e datas comemorativas
    ├── ref-stories.html           # Links de referência
    ├── book-downloads.html        # Links de download do livro
    ├── hacker-news.html           # ┐
    ├── anime-ranking.html         # │ Section boxes — delegam para
    ├── youtube-digest.html        # │ section-box.html (ver abaixo)
    ├── world-events.html          # │
    ├── market-news.html           # │
    └── qa.html                    # ┘

Cada tipo de conteúdo tem seu template. Newsletters têm sidebar de navegação e seções visuais. Transcrições de podcast têm player embutido e formatação de diálogo. O mesmo conteúdo Markdown é renderizado de formas diferentes dependendo do type no frontmatter.

Shortcodes: Componentes Sem JavaScript

Hugo shortcodes são o equivalente a componentes React, mas sem build step:

<!-- layouts/shortcodes/podcast-turn.html -->
{{ $speaker := .Get "speaker" }}
{{ $isAkita := eq $speaker "akita" }}

<div class="podcast-turn" style="display: flex; {{ if $isAkita }}flex-direction: row{{ else }}flex-direction: row-reverse{{ end }};">
  <img src="/images/{{ $speaker }}.jpg"
       style="width: 40px; height: 40px; border-radius: 50%;">
  <div class="bubble {{ if $isAkita }}akita-bubble{{ else }}marvin-bubble{{ end }}">
    {{ .Inner | markdownify }}
  </div>
</div>

No Markdown, o autor escreve:

{{< podcast-turn speaker="akita" >}}
Então, vamos falar sobre o que aconteceu essa semana no mundo tech...
{{< /podcast-turn >}}

E o Hugo renderiza um balão de chat estilizado, com avatar, alinhamento correto, e markdown processado. Zero JavaScript. Zero framework. HTML + CSS + template logic.

DRY com Partial Compartilhado

Com 17 shortcodes, duplicação vira problema rápido. Sete deles — os “section boxes” que envolvem seções da newsletter (Hacker News, Anime, YouTube, etc.) — têm a mesma estrutura visual: ícone, título, borda colorida, conteúdo Markdown. Só mudam a cor e o label.

A solução é um partial compartilhado que recebe parâmetros:

<!-- layouts/partials/section-box.html -->
<div class="section-box {{ .class }}">
  <div class="section-box-header">
    <span>{{ .icon }}</span> {{ .label }}
  </div>
  <div class="section-box-content">{{ .content | markdownify }}</div>
</div>

E cada shortcode vira uma linha:

<!-- layouts/shortcodes/hacker-news.html -->
{{ partial "section-box" (dict "class" "hacker-news" "icon" "&#128274;" "label" "The Hacker News" "content" .Inner) }}

É o equivalente Hugo de herança de componentes: um partial polimórfico parametrizado por dict. O CSS em custom.css define cores por classe (.hacker-news, .anime-ranking, etc.) com variantes light/dark. Resultado: 7 shortcodes que antes tinham HTML duplicado agora são 7 linhas + 1 partial + CSS.

Mas tem um pegadinho crucial: shortcodes são exclusivos do Hugo. O mesmo conteúdo que vai pro blog também vai por email. E email não entende shortcodes.

O Desafio: Mesmo Conteúdo, Dois Renders

Aqui está o problema central de frontend nesse tipo de projeto: o mesmo arquivo Markdown precisa funcionar em dois contextos completamente diferentes.

No blog (Hugo):

• Shortcodes funcionam (\{\{< subscribe-cta >\}\})
• CSS com classes (Tailwind, Hextra)
• Dark mode via prefers-color-scheme
• Imagens responsive
• Layout flexível

No email (Rails → Amazon SES):

• Shortcodes são texto morto — precisam ser removidos
• CSS deve ser inline (muitos clientes de email ignoram <style>)
• Dark mode? Esqueça pra 80% dos clientes
• Imagens com URLs absolutas e tamanho fixo
• Layout com <table> (sim, em 2026)

A solução: dois pipelines de renderização independentes. O conteúdo Markdown é a source of truth. O Hugo transforma pra web. O Rails transforma pra email. Cada um com suas regras.

No lado do Rails, o serviço MarkdownToHtml precisa:

1. Processar Markdown padrão
2. Converter \{\{< shortcode >\}\} em HTML equivalente ou removê-los — via um hash de SHORTCODE_PATTERNS que mapeia cada shortcode a uma regex + template inline com CSS
3. Aplicar tema (light/dark baseado na preferência do assinante)
4. Injetar CSS inline pra compatibilidade de email clients
5. Reescrever URLs de imagem pra absolutas

É mais trabalho que parece. Cada shortcode precisa de um equivalente email-safe. Avatares de comentário precisam de URLs absolutas. Seções com background colorido precisam de <td style="background-color:..."> ao invés de classes CSS.

Email HTML: O Pior Frontend do Mundo

Se você acha que cross-browser compatibility é difícil, tente cross-email-client compatibility. O Outlook 2016 renderiza HTML usando o engine do Microsoft Word. Sim, Word. Não é piada.

As regras de sobrevivência:

1. Layout com <table>. display: flex? grid? Não existem no Outlook.
2. CSS inline em todo elemento. <style> tags são ignoradas por vários clients.
3. Sem margin em imagens. Use padding na <td> pai.
4. Fonts web não funcionam. Use font stack: font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
5. Temas são preferência do assinante, não detecção automática — muitos email clients não suportam prefers-color-scheme.

O template de email do projeto é um ERB que recebe variáveis de tema:

<td style="padding: 8px 28px; color: <%= @theme[:text] %>;
           background: <%= @theme[:card_bg] %>;">
  <%= raw @content %>
</td>

O tema define todas as cores:

THEMES = {
  light: {
    text: "#1a1a1a",
    card_bg: "#ffffff",
    link_color: "#7c3aed",
    # ...
  },
  dark: {
    text: "#e6edf3",
    card_bg: "#161b22",
    link_color: "#a78bfa",
    # ...
  }
}

Cada assinante escolhe seu tema na hora de se inscrever. O email é renderizado com as cores corretas pra aquela pessoa. Sem media queries, sem detecção automática — porque email clients não suportam de forma confiável. É mais simples dar a escolha pro usuário.

Paleta de Cores: HSL e a Ciência por Trás das Escolhas

“Mas como vocês escolheram essas cores?” — Não foi no olhômetro. Existe uma ciência por trás, e ela se chama HSL (Hue, Saturation, Lightness).

A maioria dos desenvolvedores pensa em cor como hex (#e8eef8) ou RGB (rgb(232, 238, 248)). São formatos de máquina — úteis pra renderizar, inúteis pra projetar. Quando você olha #3b50a2 e #c93030 lado a lado, não tem como saber intuitivamente se vão funcionar juntas. São só números.

HSL resolve isso. Em vez de misturar canais de luz (Red, Green, Blue), você descreve cor em termos humanos:

• Hue (matiz): a posição no círculo cromático, de 0° a 360°. Vermelho = 0°, verde = 120°, azul = 240°.
• Saturation (saturação): quão “viva” é a cor. 0% = cinza, 100% = cor pura.
• Lightness (luminosidade): quão clara ou escura. 0% = preto, 100% = branco.

Com HSL, você controla cada dimensão independentemente. E é aí que entra a construção da paleta.

Passo 1: Distribuir Matizes no Círculo Cromático

A newsletter tem 8 tipos de seção, cada uma com cor própria. Pra que todas “pertençam” visualmente ao mesmo projeto, os matizes são distribuídos uniformemente no círculo de 360°:

Oito matizes espaçados ao redor do círculo. Não é aleatório — é a mesma lógica de uma paleta policromática em teoria das cores. Quando os matizes são equidistantes, o olho humano percebe harmonia mesmo com cores completamente diferentes. É o mesmo princípio que artistas usam com um círculo cromático de 12 cores desde o século XVIII.

Passo 2: Fixar Saturação e Luminosidade por Camada

Aqui está o truque que faz tudo funcionar junto. Cada “camada” visual (background, texto, borda) tem saturação e luminosidade fixas — só o matiz muda:

Tema claro:

• Backgrounds: ~92-95% luminosidade, saturação moderada. Com luminosidade tão alta, mesmo saturações diferentes resultam em cores pastel com peso visual parecido — nenhuma seção “grita” mais que outra.
• Texto: ~15-20% luminosidade. Escuro o suficiente pra garantir ratio de contraste >7:1 contra o background claro (acima do mínimo WCAG AAA de 7:1).
• Bordas: ~45-55% luminosidade. O acento cromático — visível mas não dominante.

Tema escuro:

• Backgrounds: ~10-12% luminosidade. Profundidade uniforme — todas as seções têm a mesma “escuridão”.
• Texto: ~80-85% luminosidade. Claro o suficiente pra ratio de contraste >6:1 no fundo escuro.
• Bordas: mesma faixa de luminosidade que no tema claro — funcionam como acento nos dois contextos.

Na prática, isso significa que gerar a variante dark de qualquer cor é mecânico: mantém o matiz, inverte a luminosidade. Background que era 94% vira 11%. Texto que era 18% vira 83%. Não é design — é aritmética.

Passo 3: Verificar Contraste (WCAG)

Cores bonitas que ninguém consegue ler não servem pra nada. O padrão WCAG (Web Content Accessibility Guidelines) define ratios mínimos:

• AA: 4.5:1 pra texto normal, 3:1 pra texto grande
• AAA: 7:1 pra texto normal, 4.5:1 pra texto grande

Os backgrounds claros com ~95% luminosidade contra texto com ~20% luminosidade dão ratio >7:1 — WCAG AAA. Os backgrounds escuros (~11%) contra texto claro (~82%) dão >6:1 — confortavelmente WCAG AA, próximo de AAA.

Isso não é por altruísmo. Email com baixo contraste é mais difícil de ler, gera menos engajamento, e em casos extremos é sinalizado por filtros de acessibilidade de email clients.

O Resultado

Quando você abre a newsletter e vê a seção do Hacker News (roxa), seguida pelo YouTube (vermelha), seguida pelo Anime (azul) — elas parecem “do mesmo projeto” apesar de cores completamente diferentes. Isso é o HSL trabalhando: matizes diferentes, mesma saturação, mesma luminosidade. O olho percebe coerência sem saber explicar por quê.

E a melhor parte: adicionar uma seção nova é trivial. Escolhe um matiz que não está ocupado no círculo, aplica as mesmas regras de saturação/luminosidade por camada, e a nova seção automaticamente “pertence” ao design existente.

# O comentário no código resume as regras:
# - Hues evenly spaced: blue 210, green 140, sepia 35, amber 45, royal 225, purple 270, red 0, teal 180
# - Light backgrounds: ~95% lightness, ~25% saturation
# - Light text: ~20% lightness (>7:1 contrast ratio on light bg)
# - Dark backgrounds: ~10-12% lightness
# - Dark text: ~80-85% lightness (>6:1 contrast ratio on dark bg)
# - Borders: ~45-55% lightness

Seis regras. Oito matizes. Dois temas. 100% determinístico. Nenhuma decisão subjetiva de “acho que esse azul fica bonito” — é sistema de design derivado de propriedades geométricas do espaço de cor HSL.

HTML Bem Formado: O Filtro de Spam que Ninguém Te Conta

Tudo que descrevi acima — tables, CSS inline, font stacks — resolve o problema de renderização. Mas tem um segundo motivo pra seguir essas regras que a maioria dos desenvolvedores ignora: provedores de email analisam a qualidade do seu HTML pra decidir se é spam.

Gmail, Outlook, Yahoo — todos passam o HTML do seu email por heurísticas antes de mostrar pro usuário. HTML malformado é um dos sinais clássicos de spam. Faz sentido: spammers não testam templates. Eles cospem HTML quebrado gerado por ferramentas de mass-mailing baratas. Se seu email parece output de spammer, vai ser tratado como spam.

Os sinais que disparam filtros:

1. Tags não fechadas ou mal aninhadas. Um <div> que abre e nunca fecha, ou um </td> antes do </tr>, é flag imediata. Provedores esperam HTML que parse sem erros — não HTML “que o browser conserta”.
2. Ratio imagem/texto desbalanceado. Email que é basicamente uma imagem gigante com pouco texto? Spam clássico. Provedores querem ver texto real — não texto dentro de imagens. A regra de ouro é manter pelo menos 60% texto, 40% imagem.
3. Atributo alt ausente em imagens. Além de acessibilidade, alt vazio ou ausente é sinal de descuido — e descuido correlaciona com spam. Toda <img> precisa de alt descritivo.
4. CSS que esconde conteúdo. display: none, visibility: hidden, font-size: 0, texto da mesma cor que o background — são técnicas clássicas de keyword stuffing. Mesmo que você use legitimamente pra responsive email, o filtro não sabe a diferença.
5. HTML excessivamente pesado. Email com 500KB de HTML levanta suspeita. Mantenha leve — o conteúdo real raramente precisa de mais de 100KB de HTML.
6. Links com texto que não corresponde ao href. <a href="https://site-real.com">https://site-falso.com</a> é phishing textbook. Mesmo discrepâncias sutis (domínio no texto diferente do domínio no link) são penalizadas.

O ponto que conecta tudo: as mesmas práticas que fazem email renderizar corretamente no Outlook são as que mantêm seus emails fora do spam. Tables com estrutura limpa? HTML bem formado. CSS inline em cada elemento ao invés de hacks com <style>? Sem CSS escondido. Imagens com dimensões explícitas e alt text? Conteúdo legítimo.

Não é coincidência. Provedores de email calibraram seus filtros observando o que spammers fazem — e spammers fazem exatamente o oposto de HTML email bem construído. Quando você segue as melhores práticas de compatibilidade, de graça você também está sinalizando legitimidade pros filtros de spam.

A lição prática: trate o HTML do seu email como se fosse um documento XML. Valide, teste, e garanta que todo tag abre e fecha na ordem certa. Use ferramentas como Email on Acid ou Litmus pra testar em múltiplos clients — eles também reportam problemas de spam scoring. E resista à tentação de copiar templates prontos da internet sem validar — muitos são um desastre de HTML malformado que passa despercebido no Gmail mas faz o Outlook ter um ataque cardíaco e faz o filtro de spam do Yahoo te marcar como suspeito.

RSS Feeds: O Frontend Esquecido

Um detalhe que desenvolvedores web ignoram: RSS é um frontend. Podcasts no Spotify e Apple Podcasts são consumidos via RSS. O feed precisa de:

• XML válido (parsers de podcast são rígidos)
• Metadata completa (título, descrição, duração, tamanho do arquivo)
• URLs de imagem que realmente funcionam (Spotify valida)
• Cover art com dimensões mínimas (1400×1400 pra Spotify)
• GUIDs únicos por episódio

Hugo gera RSS automaticamente, mas o template padrão não tem os campos que plataformas de podcast exigem. Um template customizado com tags iTunes é necessário:

<itunes:duration>{{ .Params.duration_seconds }}</itunes:duration>
<itunes:image href="{{ .Params.cover_image | absURL }}"/>
<enclosure url="{{ .Params.audio_url }}"
           length="{{ .Params.file_size }}"
           type="audio/mpeg"/>

A Filosofia: Conteúdo Primeiro, Framework Nunca

O padrão que emerge de todo esse setup é: o conteúdo é soberano. Markdown com frontmatter YAML é o formato universal. Cada frontend (blog, email, RSS, podcast player) consome o mesmo conteúdo e renderiza do seu jeito.

Não existe “componente React que busca dados de uma API”. Existe um arquivo Markdown que é lido por quem precisar. Isso é radicalmente simples — e radicalmente poderoso. Trocar o blog engine de Hugo pra outro? Muda os templates, o conteúdo fica igual. Trocar o provedor de email de SES pra Sendgrid? Muda o mailer, os templates ficam iguais.

É o Unix philosophy aplicado a frontend: cada ferramenta faz uma coisa bem feita, conectadas por um formato universal (Markdown + YAML).

Conclusão

Você não precisa de React pra ter frontend moderno. Tailwind v4 te dá design system com constraints, dark mode nativo, e zero JavaScript. Hugo te dá um blog absurdamente rápido com templates flexíveis. ERB com CSS inline te dá emails que funcionam em qualquer client.

O investimento real é entender as restrições de cada plataforma e construir pipelines de renderização pra cada uma. Não é aprender o framework da moda que vai morrer em 18 meses.

No final das contas, a melhor abstração de frontend é nenhuma. HTML, CSS, e Markdown. Simples, debugável, e vai funcionar daqui a 10 anos.

E não deixe de assinar minha nova newsletter The M.Akita Chronicles!

Já vou falar do podcast hoje; lembrem-se de que o episódio piloto já está no ar (transcripts e RSS pra assinar) e no canal no Spotify.

–

Todo tutorial de IA começa com “instale o modelo, rode inference, pronto!”. Nenhum te conta o que acontece quando você precisa rodar isso em produção com uptime real, custo controlado, e qualidade consistente.

Vou contar como foi colocar um modelo de TTS (Text-to-Speech) em produção numa GPU na nuvem. Porque se você está pensando em servir modelos de IA, precisa saber no que está se metendo.

O Cenário

O objetivo: gerar um podcast de ~30 minutos a partir de texto, com duas vozes distintas, qualidade de broadcast, pronto pra Spotify. Toda semana, automaticamente, sem intervenção humana.

O modelo escolhido: Qwen3-TTS, um modelo de text-to-speech que suporta voice cloning e fine-tuning. Roda em GPU — precisa de pelo menos 6GB de VRAM pra inference.

A plataforma: RunPod, que oferece GPUs serverless com cobrança por segundo de uso.

Parece simples, né? Pois aguarde.

Problema 1: Cold Start — O Assassino Silencioso

GPU serverless funciona assim: quando não tem requisição, o worker desliga. Quando chega uma requisição, ele liga, carrega o modelo na VRAM, e processa.

O tempo de “carregar o modelo na VRAM” é o cold start. Pra um modelo de ~4GB, estamos falando de 30 a 90 segundos. Sua requisição HTTP fica pendurada, esperando. Se seu timeout é de 30 segundos, você nem chega a ver o modelo funcionar — só vê timeout.

A solução ingênua: “aumenta o timeout!”. A solução real: health check com polling.

@app.get("/health")
async def health():
    if not model_loaded:
        return JSONResponse(
            status_code=503,
            content={"status": "loading", "detail": "Model loading..."}
        )
    return {"status": "ready"}

O cliente (no caso, um job Rails) faz polling no /health antes de mandar a requisição real:

def wait_for_server(max_wait: 180)
  deadline = Time.current + max_wait
  loop do
    response = http_get("/health")
    return if response.code == 200
    raise "Server não iniciou a tempo" if Time.current > deadline
    sleep 5
  end
end

Parece primitivo? É. Mas funciona melhor do que qualquer solução sofisticada de “warm pool” que custa 10x mais.

Problema 2: Onde Ficam os Pesos do Modelo?

Um modelo de 4GB precisa estar disponível quando o worker inicia. Três opções:

1. Bake no Docker: Imagem de 4GB+. Build lento. Push lento. Pull lento.
2. Download do HuggingFace no boot: Depende de rede. Pode falhar. Adiciona minutos ao cold start.
3. Network Volume: Disco persistente montado no worker.

A opção 3 é a correta. O RunPod oferece Network Volumes que persistem entre execuções. O modelo fica lá, sempre pronto. O cold start é só o tempo de carregar da disk pra VRAM, sem download.

Mas tem uma pegadinha: o volume pode estar montado ou não, dependendo de como o worker é configurado. Então o código de setup precisa ser resiliente:

NETWORK_VOLUME = "/runpod-volume"
LOCAL_FALLBACK = "/workspace/models"

def resolve_model_path():
    if os.path.isdir(NETWORK_VOLUME):
        base = os.path.join(NETWORK_VOLUME, "huggingface")
        os.environ["HF_HOME"] = base
        return os.path.join(base, "hub", "models--Qwen--Qwen3-TTS")
    # Fallback: download local
    return LOCAL_FALLBACK

Auto-detecção. Se o volume existe, usa. Se não, funciona do mesmo jeito (mais lento no primeiro boot). Nunca assuma que a infraestrutura está perfeita.

Problema 3: Dois Modos de Voz, Dois Conjuntos de Parâmetros

Aqui está algo que nenhuma documentação vai te dizer: modelos de TTS com voice cloning e fine-tuning precisam de parâmetros de sampling completamente diferentes dependendo do modo.

Com uma voz fine-tuned (treinada especificamente no modelo), você quer parâmetros conservadores:

temperature: 0.5
top_p: 0.8
repetition_penalty: 1.1

Com voice cloning (voz base + áudio de referência), os mesmos parâmetros produzem ruído branco. Literalmente. White noise. Porque o modelo de clone precisa de mais “criatividade” pra reconstruir as características vocais:

temperature: 0.9
top_p: 0.95
repetition_penalty: 1.05

Descobri isso depois de horas gerando áudio inutilizável. A documentação do modelo não menciona. Os papers acadêmicos não mencionam. É o tipo de conhecimento que só vem de experimentação em produção.

Problema 4: O Áudio de Referência Importa Mais que o Modelo

Voice cloning usa um trecho de áudio como referência pra replicar a voz. Parece simples: grava 10 segundos, passa pro modelo e pronto.

Exceto que se o áudio de referência começa com a fala imediatamente — sem nem 200 milissegundos de silêncio no início — o modelo aprende que “o áudio começa sem onset”. E toda geração subsequente vai cortar a primeira sílaba.

Isso não é um bug do modelo. É o modelo fazendo exatamente o que você pediu: “gere áudio que começa igual a essa referência”. Se a referência começa cortada, a geração começa cortada.

A correção não é pós-processamento (o áudio já foi gerado sem a sílaba). É corrigir a referência: garantir pelo menos 300ms de silêncio antes da fala.

Pra quem vem do mundo de software, isso é contra-intuitivo. Estamos acostumados a tratar dados de entrada como imutáveis e consertar na saída. Com modelos generativos, a qualidade da entrada é tudo.

Problema 5: Timeout e Limites de Geração

Um modelo de TTS gera áudio token por token. Se você não limitar, ele pode gerar indefinidamente — e no RunPod, você paga por segundo de GPU. Um turno de diálogo de 30 palavras não deveria gerar 3 minutos de áudio, mas sem limite, pode.

MAX_NEW_TOKENS = 720  # ~60 segundos de áudio a 12Hz
GENERATION_TIMEOUT = 180  # 3 minutos absolutos

with ThreadPoolExecutor(max_workers=1) as executor:
    future = executor.submit(model.generate, **params)
    result = future.result(timeout=GENERATION_TIMEOUT)

Dupla proteção: limite de tokens na geração e timeout absoluto no processo. Se qualquer um disparar, o turno falha e pode ser re-tentado com parâmetros ajustados.

Problema 6: Pós-Processamento é Metade do Trabalho

O modelo gera WAV cru. Pra chegar em áudio de podcast quality, o caminho é longo:

1. Normalização de loudness: Spotify exige -14 LUFS. Sem normalização, cada turno tem volume diferente.
2. Re-encoding: Os WAVs do modelo podem ter formatos sutilmente diferentes (sample rate, bit depth). Concatenar com -c copy causa segmentos silenciosos. Precisa re-encodar tudo pro mesmo formato.
3. Conversão pra MP3: CBR 192kbps, 44.1kHz, com metadata ID3.

E a normalização de loudness precisa ser two-pass: primeiro mede, depois aplica. Single-pass é chute — e chute em produção gera áudio com volume inconsistente entre episódios.

# Pass 1: análise
ffmpeg -i input.wav -af loudnorm=I=-14:print_format=json -f null -

# Pass 2: aplicação dos valores medidos
ffmpeg -i input.wav -af loudnorm=I=-14:measured_I=-18.5:measured_TP=-2.1:... output.wav

Tudo isso roda no servidor, depois da geração do TTS. E precisa de ffmpeg instalado no container — mais uma dependência pra gerenciar.

Problema 7: O Script Importa Mais que o Modelo de Voz

Depois de resolver GPU, cold start, voice cloning, sampling, normalização — o podcast sai. E soa… robótico. Não por causa do TTS. O TTS é excelente. Soa robótico porque o texto é robótico.

Esse é o problema que ninguém menciona em pipelines de TTS: a qualidade do áudio começa no script, não no modelo de voz. Um TTS perfeito lendo um texto seco e formal produz áudio seco e formal. Garbage in, garbage out — mas num nível que você não espera.

Duas Passadas: Draft e Refine

A solução é gerar o script em duas passadas de LLM:

Passada 1 (Draft): Transforma a newsletter em diálogo. Aqui o LLM recebe o conteúdo completo e cria a estrutura — quem fala o quê, em que ordem, com quais transições. Sem mudar o conteúdo, só a forma!

Passada 2 (Refine): Pega o draft e torna natural. Adiciona hesitações, reações, interrupções, auto-correções. Transforma “script lido” em “conversa real”.

Por que não fazer tudo numa passada? Porque são tarefas cognitivamente diferentes. Estruturar conteúdo e adicionar naturalidade ao mesmo tempo resulta num texto que não faz nem um nem outro direito. Duas passadas especializadas produzem resultado consistentemente melhor.

Personalidade Precisa de Instruções Brutalmente Específicas

“Faça o Akita soar confiante” não funciona. O LLM vai produzir confiança genérica — frases motivacionais, tom positivo. Não é isso. Akita é confiante porque é assertivo e impaciente. A diferença está nos detalhes do prompt:

## Akita Delivery Style

- **Declarative, not tentative**: "Isso é óbvio" not "Eu acho que talvez isso seja..."
- **Dismissive of nonsense**: "Isso é bobagem", "Não tem nenhum mistério aqui"
- **Owns his track record**: "Eu avisei", "Quem assistiu meu canal já sabe"
- **Never hedges**: No "talvez", "quem sabe", "pode ser que"
- **Impatient with the obvious**: "Vocês já sabem como funciona"

E pro Marvin (o co-host robô):

- **Filler words** (Marvin only): "bom...", "olha...", "enfim", "pois é"
- **Self-corrections** (Marvin only): "quer dizer...", "ou melhor..."
- Akita doesn't second-guess himself — if he corrects, it's
  "Não, peraí" and he restates with even MORE conviction

Sem esse nível de especificidade, os dois personagens soam iguais. O LLM precisa de exemplos concretos de como cada um fala, não de descrições abstratas de personalidade.

Normalização Pra Fala: O Que Parece Certo no Texto Soa Errado no Áudio

Siglas. O inimigo invisível do TTS. “EUA” no texto é perfeitamente legível. Falado pelo TTS, sai “éu-á” — incompreensível. O prompt precisa de regras explícitas de normalização:

## Spoken Text Normalization (MANDATORY)

- `EUA` → `Estados Unidos`
- `UE` → `União Europeia`
- `IA` → `inteligência artificial`
- `LLM` → `modelo de linguagem`
- `API` → `interface de programação`

Isso precisa estar no prompt de ambas as passadas (draft e refine), porque o LLM tem tendência a reintroduzir siglas que removeu na passada anterior.

O LLM Vai Reescrever Suas Opiniões (Se Você Deixar)

Essa foi a lição mais sutil. A newsletter tem comentários opinativos do Akita e do Marvin em cada seção. Quando o LLM transforma em diálogo, ele substitui as opiniões por versões mais “balanceadas” e “nuançadas”. Akita que dizia “isso é bobagem” vira Akita dizendo “isso tem seus méritos, mas…”. Marvin pessimista vira Marvin “levemente cético”.

O LLM faz isso porque foi treinado pra ser helpful e balanced. Opiniões fortes parecem “unhelpful” pro modelo, então ele suaviza. A instrução original — “use os comentários da newsletter como sementes pra conversa” — era vaga demais. Dava liberdade pro modelo reinterpretar.

A correção é ser explícito e inflexível:

**PRESERVE THE ORIGINAL OPINIONS**: The newsletter contains Akita and
Marvin commentary on each topic. These opinions are the author's real
voice — you MUST preserve their substance, stance, and conclusions.
Make the delivery conversational, but do NOT change what they actually
think. If Akita's comment says "isso é bobagem", the podcast version
must convey the same dismissal. Rephrase for spoken delivery, but
never substitute a different opinion.

É a diferença entre “adapte pra conversa” (LLM entende: “reescreva como quiser”) e “mude o COMO, nunca o QUÊ” (LLM entende: “mantenha a opinião, troque a embalagem”).

E isso vale pra qualquer prompt engineering com conteúdo autoral: o LLM vai homogeneizar sua voz se você não for explícito sobre preservá-la. E num podcast onde a personalidade dos hosts É o produto, perder a voz é perder tudo.

O Custo Real de IA em Produção

Vamos ser práticos sobre custos no RunPod:

O custo por episódio é baixo. O custo de descobrir como fazer funcionar é alto. Foram dezenas de horas de experimentação, logs incompreensíveis de CUDA, gerações falhadas, e áudio com qualidade inutilizável antes de chegar numa pipeline estável.

E o custo cognitivo: manter dois ecossistemas (Python pra ML, Ruby pra aplicação) sincronizados, com interfaces HTTP entre eles, e debugging que cruza fronteiras de linguagem.

De qualquer forma, pra quem pensou “Por que não Elevenlabs?”, bom, eu consegui qualidade similar, numa fração do custo, e aprendi muito no processo (e vocês também, lendo aqui).

Lições

1. Cold start é um requisito, não um bug. Design seu sistema esperando que o modelo demore pra carregar.

2. Network volumes são obrigatórios pra modelos grandes. Não bake pesos no Docker, não faça download no boot.

3. Parâmetros de sampling não são universais. Cada modo de operação do mesmo modelo pode precisar de configuração completamente diferente.

4. A qualidade da entrada domina a qualidade da saída. Tanto pro áudio de referência do TTS quanto pro script. Se a referência corta a primeira sílaba, toda geração corta. Se o script é genérico, o áudio é genérico.

5. Timeouts em todas as camadas. Token limit, process timeout, HTTP timeout. Se não limitar, o custo escala e a geração trava.

6. Pós-processamento é metade do pipeline. O modelo gera matéria-prima. Normalização, encoding, metadata — tudo isso é trabalho real.

7. Separe o servidor de ML da aplicação. Python pra inference, Ruby pra orquestração. Tentar fazer tudo numa linguagem é receita pra frustração.

8. Prompts precisam de duas passadas pra conteúdo complexo. Estruturar e naturalizar são tarefas diferentes. Forçar as duas numa passada produz resultado medíocre em ambas.

9. O LLM vai homogeneizar sua voz. Opiniões fortes viram “nuanced takes” se você não for explícito sobre preservá-las. Instrua o modelo a mudar a embalagem, nunca o conteúdo.

Conclusão

IA em produção não é um tutorial de HuggingFace com 10 linhas. É infraestrutura, é experimentação, é debugging de problemas que não existem em software tradicional. Mas quando funciona — quando seu sistema gera um podcast inteiro automaticamente toda semana, com qualidade broadcast, sem intervenção humana — a sensação é que valeu cada hora de dor de cabeça.

O truque é não subestimar a complexidade. E ter um sistema robusto (como os jobs do Rails que mencionei no primeiro post) orquestrando tudo — porque IA sem orquestração confiável é só um script caro que trava.

E não deixe de assinar minha nova newsletter The M.Akita Chronicles!

–

Dez anos atrás, buscar dados em um site era trivial. Quatro linhas de Ruby: Net::HTTP.get, Nokogiri parse, CSS selector, pronto. O mundo inteiro estava aberto pra qualquer script com um User-Agent decente.

Hoje? Metade dos sites que preciso ler pra montar minha newsletter retorna “Are you a robot?” pra qualquer requisição HTTP convencional. A outra metade renderiza o conteúdo inteiramente em JavaScript — não há HTML nenhum na resposta do servidor. E os mais paranoicos combinam as duas coisas.

Meu objetivo era criar uma rotina diária pro M.arvin me devolver as principais notícias pela manhã no meu Discord. Assim eu não preciso sair caçando as notícias do dia. Parecia simples… no começo.

Este post é sobre como passei de “uma chamada HTTP” pra “empacotar um Chromium inteiro no Docker” — e por que isso é a realidade de qualquer projeto que precisa ler a web programaticamente em 2026.

A Idade de Ouro: HTTP Simples

Vamos começar pelo que ainda funciona. Alguns serviços oferecem dados estruturados sem nenhuma resistência:

# RSS feeds: o formato mais resiliente da web
uri = URI("https://news.google.com/rss/search?q=when:24h+allinurl:reuters.com/world")
xml = Net::HTTP.get(uri)
doc = REXML::Document.new(xml)
doc.get_elements("//item").each do |item|
  title = item.get_text("title").to_s
  url   = item.get_text("link").to_s
end

# APIs públicas: JSON limpo, documentado, estável
response = HTTParty.get("https://api.jikan.moe/v4/top/anime?filter=airing")
animes = response.parsed_response["data"]

# GitHub trending: HTML server-rendered sem proteção
html = HTTParty.get("https://github.com/trending").body
doc = Nokogiri::HTML(html)
repos = doc.css("article.Box-row")

Hacker News, GitHub Trending, APIs de anime, feeds RSS, Project Gutenberg — todos funcionam com um GET e um parser. Sem JavaScript, sem autenticação implícita, sem fingerprinting. Assim como a web deveria ser.

O problema é que esses são a exceção. Os sites que têm dados financeiros, notícias exclusivas ou conteúdo premium — exatamente os dados que mais importam — estão cada vez mais blindados.

O Primeiro Obstáculo: SPAs e JavaScript Rendering

Quando o servidor retorna algo tipo:

<html>
<body>
  <div id="root"></div>
  <script src="/app-3fa8c2.js"></script>
</body>
</html>

Seu Net::HTTP.get retorna exatamente isso: uma div vazia e um link pra um bundle de 2 MB. O conteúdo real — artigos, preços, listas — é montado no browser por React, Vue, Angular ou o framework da semana.

Pra um script, essa página é inútil. Pra extrair o conteúdo, você precisa executar o JavaScript. Isso significa rodar um browser real.

No mundo Ruby, a resposta é a gem ferrum — um cliente CDP (Chrome DevTools Protocol) que controla o Chromium programaticamente:

browser = Ferrum::Browser.new(headless: "new", timeout: 30)
browser.go_to("https://www.morningstar.com/markets")
browser.network.wait_for_idle  # espera o JS terminar de carregar
html = browser.body  # agora sim o DOM está populado
browser.quit