Eu comecei a gostar do milenar jogo de Go por causa do mangá Hikaru no Go. Cheguei a escrever sobre isso em 2008, num post que ainda está no ar, defendendo por que programadores deveriam jogar Go. De lá pra cá pouca coisa mudou no meu caso de uso: eu tenho um goban físico em casa, mas nunca tive a menor intenção de entrar em grupo de estudo, federação ou competição. Eu só gosto de jogar sozinho, resolver uns tsumego (os quebra-cabeças de vida e morte do Go), e carregar partidas famosas pra estudar, como os lendários jogos do Lee Sedol contra o AlphaGo em 2016.

Pra quem não conhece o mangá: Hikaru no Go (roteiro de Yumi Hotta, arte de Takeshi Obata, o mesmo de Death Note) rodou na Shonen Jump entre 1998 e 2003 e causou um boom de interesse por Go no Japão inteiro. E tem um detalhe que pouca gente sabe: praticamente todas as partidas que aparecem no mangá são baseadas em jogos históricos reais, recriados quadro a quadro. Guarda essa informação, porque ela volta daqui a pouco.

SGF e o problema do material espalhado

Existem vários programas open source muito bons pra carregar partidas de Go ou até jogar online. Partidas de Go são gravadas num formato chamado SGF (Smart Game Format), um formato de texto puro que existe desde o fim dos anos 80: cada jogada vira uma coordenada (;B[pd] é uma pedra preta no ponto 4-4), e o formato suporta árvores de variação, comentários e metadados da partida. É o padrão de facto do mundo do Go: todo cliente lê SGF, todo servidor exporta SGF, e existe um acervo gigantesco de partidas históricas e problemas nesse formato acumulado ao longo de décadas.

E aí mora o problema: esse acervo está espalhado pela internet inteira. Um site tem as coleções clássicas de tsumego, outro tem as partidas históricas, um repositório do GitHub tem os problemas comentados, outro tem os kifu (registros de partida) profissionais. Eu não estava com o menor humor de baixar tudo manualmente, organizar pasta por pasta e configurar cliente por cliente. Eu queria um app bom o suficiente, bonito o suficiente, com tudo embutido.

2008: a era GNU Go

Aqui vale o contexto histórico, porque ele é a parte divertida. Em 2008, quando escrevi aquele post, a única “IA” de Go acessível era o GNU Go. E olha, a gente nem pode chamar aquilo de IA: era um monte de heurísticas empilhadas. E era terrível. Até um amador como eu conseguia ver que ele fazia jogadas sem fluxo nenhum, sem sentido de direção, pedras soltas que não conversavam entre si. Ganhava de iniciante por pura tática local e só.

O que aconteceu nos 18 anos seguintes é uma das histórias mais bonitas da computação. Primeiro vieram os métodos de Monte Carlo Tree Search, que já melhoraram bastante o nível.

Aí em março de 2016 o AlphaGo do DeepMind venceu Lee Sedol, um dos maiores jogadores da história, por 4 a 1. Foi a série da famosa jogada 37 da partida 2 (o “ombro” que nenhum humano jogaria) e da resposta à altura do Lee Sedol: a jogada 78 da partida 4, a “mão de Deus” que lhe deu sua única vitória. Se você nunca viu, existe um documentário excelente sobre essa série na Netflix, que vale a pena até pra quem não sabe nada de Go.

E depois que o DeepMind publicou os papers, a comunidade open source correu atrás: primeiro o Leela Zero reimplementando o AlphaZero, e depois o KataGo indo além. Hoje qualquer um tem um jogador sobre-humano de Go rodando de graça no próprio computador. Eu queria ver de perto o quanto essas IAs amadureceram em 20 anos.

Foi dessa vontade que nasceu meu novo projeto de brinquedo: o Frank GO.

Sabaki + KataGo

Pedi pro Claude Code pesquisar os apps e engines open source de Go mais populares (a pesquisa inteira está documentada no próprio repositório, como manda o figurino). No fim escolhi dois projetos como base:

O Sabaki, do Yichuan Shen, é o front-end. É provavelmente o editor de SGF e tabuleiro de Go open source mais bonito e bem cuidado que existe, feito em Electron, com suporte a árvores de variação, análise e engines via protocolo GTP. Elegante e minimalista.

O KataGo, do David Wu, é a IA. É o motor open source mais forte do mundo, sobre-humano, herdeiro da linhagem do AlphaZero mas com uma diferença que importa demais pro meu caso: além da taxa de vitória, o KataGo estima pontuação e domínio de território ponto a ponto. Ele responde “quem está ganhando, por quantos pontos, e quais áreas do tabuleiro pertencem a quem”. É exatamente o tipo de informação que um iniciante precisa e que os engines antigos escondiam.

O Frank GO é um fork do Sabaki que amarra o KataGo pra sessões de jogo solo, e embute tudo aquilo que eu queria ter num lugar só:

• Mais de 4.700 tsumego das coleções clássicas (a Enciclopédia do Cho Chikun, o Gokyo Shumyo, o Xuanxuan Qijing), transcritas pelo Vít Brunner no tsumego.tasuki.org e convertidas pra SGF pelo projeto tasuki2sgf, mais os 420 problemas comentados do go-problems do Go Game Guru (do An Younggil, profissional 8-dan), organizados em 10 níveis de dificuldade. Resolve 5 seguidos e sobe de nível. Um seletor de foco filtra por vida e morte, tesuji, ko ou semeai (corrida de capturas).
• Os puzzles revidam: com o KataGo instalado, ele responde suas jogadas dentro do problema, e quando ele desiste da área o app julga o resultado e marca o problema como resolvido automaticamente.
• Partidas históricas famosas pra estudar, do Jogo da Orelha Vermelha (1846, do lendário Honinbo Shusaku) até AlphaGo vs Lee Sedol, curadas do banco de partidas do Andries Brouwer no CWI, cada uma com a história por trás, e as do AlphaGo com comentário jogada a jogada. Dá pra assistir em auto-play ou ligar o modo “adivinhe a jogada” e tentar achar o lance do profissional.
• As partidas do Hikaru no Go: lembra que os jogos do mangá são reais? Pois é, 15 deles estão embutidos com referência de capítulo e curiosidades, usando o mapeamento capítulo-a-partida que a comunidade compilou na Sensei’s Library. A partida de internet do Sai contra o Toya Meijin, por exemplo, é um jogo real decidido por meio ponto.
• Dicionário de joseki (o Kogo’s Joseki Dictionary, referência clássica de aberturas de canto), drills de escada, drill de “quem está ganhando?”, e um teste de rank de dez problemas que estima seu nível e te larga direto na prática certa.

Lembra do problema do material espalhado? Essas coleções aí de cima são exatamente ele: cada uma vivia num canto da internet. A procedência e o licenciamento de cada conjunto estão documentados no data/SOURCES.md do repositório, porque acervo dos outros se usa dando o devido crédito.

Overlays pra quem está começando

A parte em que eu mais mexi no Sabaki foi criar sobreposições visuais amigáveis pra iniciante. A principal é a pintura de área: um overlay que pinta a influência de cada jogador como um gradiente suave e o território consolidado em cor sólida, então você literalmente vê o que as pedras estão fazendo, quais áreas estão mortas e quais estão em disputa.

Junto vem o placar em tempo real considerando o komi (a compensação de pontos do branco por jogar em segundo), que avisa quando você está irremediavelmente atrás ou quando o jogo já está decidido. E passando o mouse no tabuleiro aparecem os nomes das jogadas (“Hane”, “One-Point Jump”), o vocabulário que os livros usam e que iniciante demora a absorver.

Esse era o meu problema com todo software de Go que já testei: são ferramentas feitas por jogadores fortes pra jogadores fortes. Winrate em porcentagem não diz nada pra quem está aprendendo. “Você está 12 pontos atrás e o canto inferior esquerdo morreu” diz tudo. O KataGo sempre soube calcular isso; faltava alguém colocar na tela de um jeito que iniciante entende.

A ideia é ser um balcão único, sem configuração nenhuma, pra iniciante e estudante aprender Go no próprio ritmo. E tem build pra todo lugar. No Arch Linux é yay -S frank-go via AUR. No Windows tem instalador e versão portátil nos Releases; o instalador não tem assinatura digital, então o SmartScreen reclama na primeira execução, é só clicar em “Mais informações → Executar assim mesmo” (eu explico por que não assino build de Windows no post de boas práticas). No macOS é brew install --cask akitaonrails/tap/frank-go, ou o .dmg pra Apple Silicon e Intel; esse build é assinado com Developer ID e notarizado pela Apple, abre sem drama nenhum. E em qualquer plataforma dá pra rodar do fonte com npm install.

Em todos os casos o app baixa um engine de CPU pequeno com um clique, sem GPU, sem conta, sem servidor, totalmente offline. A exceção é o macOS, onde o KataGo não tem binário oficial: um brew install katago destrava o jogo contra a IA, e todo o resto (tsumego, estudo, drills, pintura de área) funciona sem ele. O progresso fica na sua máquina.

E quando você quiser jogar contra gente

O Frank GO é deliberadamente um app de estudo solo. Quando você aprender e quiser jogar contra humanos, o caminho natural são os servidores online, e aí os apps mais avançados servem melhor. O OGS (Online Go Server) é o mais amigável hoje, roda direto no navegador. O KGS e o Pandanet IGS (o Internet Go Server original, no ar desde o começo dos anos 90) são os veteranos, e os servidores asiáticos como Fox e Tygem concentram os jogadores mais fortes. O mundo do Go organizado gira em torno da IGF (International Go Federation) e das associações nacionais, com rankings e torneios pra quem quiser levar a sério.

Eu não quero. E esse é o ponto do projeto inteiro: como eu disse lá em cima, não tenho nenhuma vontade de competir. Eu queria, há literalmente anos, um jeito de jogar e me divertir com Go no meu ritmo, com material de estudo decente num lugar só, contra uma IA que joga bonito em vez de cuspir pedras sem sentido como o GNU Go de 2008. Acho que finalmente consegui.

O código é MIT, o repositório é github.com/akitaonrails/frank_go, e contribuições são bem-vindas. Tem inclusive uma issue aberta pedindo retratos dos personagens pro modo Hikaru no Go, se alguém quiser desenhar. O Sai agradece.

Eu sou assinante do app MANGA Plus by Shueisha na Google Play Store do Android. Pra quem não conhece, é o canal oficial da Shueisha (editora japonesa por trás da Shonen Jump) pra ler os mangás dela legalmente, capítulo lançando semanalmente quase no mesmo dia da publicação no Japão. Por dois dólares por mês dá acesso ao catálogo inteiro, com tradução oficial em inglês.

Tenho um Samsung ZFold 7, que é uma das poucas exceções de celular que serve bem pra ler mangá e Kindle (já comentei sobre isso e sobre o Frank Yomik no ranking final da maratona de IA). O Fold aberto dá uma tela maior que celular normal e ajuda muito. Mas tem dia que meu olho já está cansado de telinha pequena, e o que eu queria mesmo era ler num monitor OLED de 32 polegadas que está bem na minha frente, perfeito pra leituras longas.

O problema é que MANGA Plus não tem site oficial pra leitura. A assinatura está presa ao Android. Existe uma versão pra iOS também, mas web não tem. Tablet ajuda, mas nada bate o conforto de uma tela grande e estática quando você quer ler um arco inteiro de One Piece numa tacada só.

Pra contexto, ultimamente coloquei muita coisa em dia: finalmente fechei Chainsaw Man, Dan Da Dan, Jujutsu Kaisen, Kagurabachi, Akane-banashi, Sakamoto Days e, claro, One Piece. Tem muito mais que eu quero acompanhar, e o conforto do monitor grande virou um problema real pra resolver.

O foco começa no Frank Manga+, que resolve o buraco da Shueisha no desktop. No fim também falo de dois complementos do meu setup: Prettify Manga Reader, pra transformar sites de fansub e Kindle Web em leitores decentes, e Frank Yomik no navegador, pra furigana/tradução em Kindle Japan e Naver.

Decompilando o app

Resolvi atacar. Sentei com o Claude Code e baixamos o xapk oficial do MANGA Plus. Decompilamos pra fonte Java com jadx e fomos navegando até entender como o app se autentica com a API da Shueisha.

A conclusão é direta: a “assinatura” do usuário, do ponto de vista do app, é um deviceSecret de 32 caracteres hexadecimais guardado num arquivo XML simples dentro dos shared preferences do Android. O app gera esse segredo uma vez quando você loga, e a partir daí toda chamada à API (jumpg-api.tokyo-cdn.com) é assinada com ele. Sem DRM elaborado, sem token rotativo, sem nada disso. É um segredo único e estático por aparelho.

O detalhe é que extrair esse segredo do app dá trabalho, porque por padrão você não tem acesso ao /data/data/jp.co.shueisha.mangaplus/shared_prefs/config.xml num Android sem root. Existem três caminhos:

1. Celular rooteado: roda adb shell su -c "cat /data/data/jp.co.shueisha.mangaplus/shared_prefs/config.xml" e procura o <string name="secret">...</string>.
2. Emulador com root: instala o Android Studio, cria um AVD com Google Play x86_64, aplica o rootAVD pra ter root via Magisk, loga na sua conta Google que tem a assinatura, instala o MANGA Plus pela Play Store, e roda o mesmo adb shell de cima.
3. Captura de rede com mitmproxy (mais avançado): roda o emulador root, injeta o CA do mitmproxy via Conscrypt APEX, e intercepta o segredo na primeira chamada autenticada do app.

Os três caminhos estão documentados em detalhe nos docs/install.md e docs/debugging.md do repositório. Não vou repetir aqui passo a passo porque é mais ferramenta do que técnica em si, e quem topa o trabalho vai querer ler o original. O importante é que funciona, e que basta fazer uma vez: depois de extraído, o segredo serve pro app desktop pelo tempo que durar sua assinatura.

Sim, é chato. Mas é o preço de ter um único ponto de configuração que destrava o resto.

O app desktop

Com o segredo na mão, o resto foi fácil. Montei o Frank Manga+, um app nativo em Rust + Tauri, com WebView SvelteKit no frontend e cliente Rust com reqwest no backend conversando direto com a API da Shueisha. Pra carregar imagens dos capítulos sem vazar URL nem ter dor de cabeça com CORS, criei um esquema custom mpimg:// interceptado pelo Tauri, que baixa, descriptografa (a API entrega as páginas com XOR simples) e devolve pro WebView.

O app abre numa visão de biblioteca com busca:

Clicando num título você vai pra página de detalhe com a lista completa de capítulos e um botão “Continue” que retoma do último capítulo lido:

O leitor abre em página única, com snap por página e as zonas de clique no estilo mangá: clica na metade esquerda da página pra avançar e na direita pra voltar (sentido de leitura japonês, da direita pra esquerda). Quem prefere teclado tem seta, espaço, j/k e PageUp/PageDown, tudo funciona. Quando você chega no fim de um capítulo, o próximo já vem em prefetch e é anexado no scroll, então não precisa voltar pra lista de capítulos toda hora. E o resume é por capítulo: se você sai no meio, da próxima vez que abrir aquele capítulo cai exatamente na página onde parou. Pra séries gigantes como One Piece (1100+ capítulos), a lista é virtualizada, então abre instantâneo:

Num monitor de 32 polegadas, página única desperdiça metade da tela. Por isso tem o modo página dupla: aperta D (ou clica no ícone de layout no cabeçalho) e o leitor junta as páginas que formam par: a dobra inteira preenche a tela do jeito que o autor desenhou. É como mangá foi feito pra ser lido.

E dá pra ver como isso importa quando compara com encadernação barata. Paperback ruim engole o meio da dobra, exatamente onde a arte deveria se conectar. No digital, quando o leitor junta direito, a cena respira:

Frank Manga+ juntando a página dupla	Paperback barato engolindo a dobra

O D cicla por três layouts: single (uma página por vez), double (pares sequenciais a partir da página 1) e double-cover (a primeira página de cada capítulo sozinha e o resto em pares, que é como mangá impresso encaderna a capa solta antes da primeira dobra). A escolha persiste entre capítulos e sessões, então você configura uma vez e esquece.

Tem também um filtro de leitura noturna. Aperta F (ou clica no ícone de lua no cabeçalho) e os brancos da página esquentam pro sépia. Branco de LCD castiga a vista no escuro, e isso suaviza sem achatar o contraste:

O F cicla por quatro níveis: off → low → med → high → off. O botão fica âmbar e mostra de um a três pontinhos pro nível ativo, e a escolha fica salva no localStorage igual às outras preferências do leitor. Por baixo é um filtro CSS de sepia + brightness + saturate na pilha inteira de páginas: o sépia empurra a cor pro âmbar mas preserva a faixa de luminância, então preto continua preto e o contraste da arte fica intacto.

Estado de leitura (último capítulo, página corrente) fica no localStorage do WebView. Cache de imagens em ~/.cache/mangaplus-reader/. O deviceSecret extraído fica em ~/.config/mangaplus-reader/secret (Linux/macOS) ou %APPDATA%\mangaplus-reader\secret (Windows). Dá pra sobrescrever com a variável de ambiente MANGAPLUS_SECRET se preferir.

Instalação

Tem build pronto pra todas as plataformas principais:

• Linux: AppImage, .deb, .rpm, ou via AUR (yay -S mangaplus-reader-bin).
• macOS: .dmg separado pra Apple Silicon (aarch64) e Intel (x64).
• Windows: instalador .exe. Não está assinado, então o Windows SmartScreen vai reclamar — clica em “More info → Run anyway”.

Todos os artefatos saem nos Releases do GitHub.

Status e contribuições

Isso é beta. Funciona pro meu uso (leio várias séries por semana sem dor de cabeça), mas tem features que faltam: filtros de gênero na busca, modo offline real (hoje guarda em cache só o que já foi lido), e o caminho de extração do segredo pra usuários menos técnicos.

Se você assina o MANGA Plus e topa testar, manda issue ou PR. O código é Rust + Svelte, MIT, contribuição bem-vinda: github.com/akitaonrails/frank_mangaplus.

Agora finalmente leio One Piece no monitor grande, sem precisar segurar celular ou ficar de pescoço torto. Já valeu o trabalho.

Bônus: Prettify Manga Reader pra sites de fansub

Além do app desktop, mantenho uma extensão mais simples: Prettify Manga Reader. Ela não traduz nada. O objetivo é arrumar a leitura.

A maioria dos sites de fansub é feia, cheia de banner, e claramente pensada pra celular: uma página embaixo da outra, scroll vertical infinito, boa sorte. Isso é prático pra ler no telefone, mas mangá não foi desenhado como feed de Instagram. Mangá foi pensado pra virar página. Duas páginas abertas ao mesmo tempo. O ritmo de leitura, a virada, o respiro entre quadros, tudo considera esse par.

E vários autores usam isso pra fazer spread de duas páginas. Kaiju No. 8 faz várias vezes. Se o site joga uma página embaixo da outra, você até lê os balões, mas perde a composição inteira. Você está vendo metade da arte de cada vez e achando que viu tudo.

O normal nesses sites é isso:

O Prettify abre um overlay escuro, encaixa a arte na tela e junta páginas no centro quando está em Book ou Double. O spread volta a parecer uma página dupla de verdade:

Ele tem três modos: Single (uma página por tela), Double (pares desde o começo) e Book (primeira página sozinha, depois pares, que é o jeito de encadernação). Abre em Book por padrão. Se a imagem já é horizontal, mantém como spread em tela cheia. Tem scroll snap pra cada página parar no lugar certo, atalho de teclado, controles pequenos de mouse, ajuda com ?, e um cartão no fim do capítulo tentando achar próximo/anterior quando o site deixa isso claro.

Também tem filtro noturno em três níveis. Aperta N e ele esquenta a página com sepia, brilho e contraste, sem transformar o desenho num cinza morto. Página branca no monitor grande de noite é uma lanterna na cara. Isso resolve.

Pra instalar, vai no GitHub do Prettify Manga Reader, baixa o zip em Releases, descompacta numa pasta permanente, abre chrome://extensions ou brave://extensions, liga Developer mode, clica em Load unpacked e escolhe a pasta descompactada. Se quiser montar do fonte, clona o repo, roda npm test, depois npm run package, descompacta o zip gerado em dist/ e carrega essa pasta.

No Kindle Web Reader, o Prettify faz menos de propósito. Em URLs tipo read.amazon.com/manga/..., read.amazon.co.jp/manga/..., read.amazon.co.uk/manga/... e domínios read.kindle.*, não tenta reconstruir o livro numa overlay própria. O leitor da Amazon já resolve conta, página e DRM; a extensão só injeta uma barrinha discreta no canto inferior direito e atalhos de teclado por cima do reader nativo.

Espaço, PageDown e setas avançam página; Shift+Space, PageUp e setas opostas voltam; Home/End vão pro começo ou fim quando o reader nativo aceita, com fallback de scroll; N cicla o filtro noturno. Não guarda credenciais da Amazon, não mexe em sessão, não precisa token no código. É só conforto visual e teclado em cima do Kindle Web que já existe.

Bônus 2: Frank Yomik agora também no desktop via extensão

Quem leu o balanço da maratona de IA lembra do Frank Yomik, meu projeto self-hosted que pega uma página de mangá ou webtoon, detecta os balões com RT-DETR-v2, faz OCR, manda pro Ollama local (qwen3:14b) traduzir, e devolve a página com o texto traduzido no lugar. Já expliquei a história e os detalhes técnicos no post Meu primeiro fracasso com Vibe Code e como consertei | Frank Yomik. Aqui o ponto é o pedaço novo no desktop.

Originalmente tinha só cliente Flutter pra Android e Linux, que abria Kindle Japan e Naver Webtoon dentro de um WebView. Acontece que rodar app Flutter dentro de WebView no desktop pra ler Kindle é meio canhão pra mosca. No desktop você já tem Chromium aberto. O que faltava era uma extensão de navegador.

Nas últimas semanas adicionei isso. Extensão Manifest V3 pra Chromium/Brave/Edge, conversando com o mesmo servidor self-hosted do Yomik. Roda em read.amazon.co.jp, read.kindle.co.jp, comic.naver.com e na versão mobile do Naver. A página fica visualmente idêntica ao original, sem botão injetado nem HUD na cara do leitor. Toda configuração mora no popup:

O content script pega a imagem da página atual e manda pro servidor. O bearer token fica no service worker, então não vaza pro JS da página. Quando a tradução volta, a imagem é trocada na hora no lugar da original. Tem cache local pra não retraduzir página já vista, botão de “force reprocess” pra quando precisa reportar bug, e autosave de configuração. Detalhes no README da extensão, e o zip pra Load Unpacked sai nos Releases do repo.

Na prática, hoje o monitor de 32" virou minha mesa de leitura. Frank Manga+ abre o catálogo oficial da Shueisha em inglês (One Piece, Chainsaw Man, e o que mais a Shonen Jump publicar). Quando é fansub ou Kindle Web e só quero conforto visual, o Prettify resolve reader, teclado e filtro noturno. Quando quero ler coisa japonesa sem tradução oficial, abro Kindle Japan numa aba e o Yomik manda furigana ou tradução LLM em cima da página. Pra webtoon coreano da Naver, mesma história, mesma extensão.

A parte boa é que cada projeto resolve um pedaço diferente e eles se completam. Frank Manga+ existe porque a Shueisha não tem site. Prettify deixa readers de navegador menos sofridos. O Yomik existe porque o resto do mangá que eu leio não tem tradução oficial decente em tempo hábil. Pra quem é doente de mangá igual eu, é o setup que eu queria há anos.

Eu sempre gostei de karaokê. De vez em quando saio pra cantar com família ou amigos. Em São Paulo tem bons lugares na Liberdade e no Bom Retiro, por exemplo, com cabines no estilo japonês. Se você nunca foi num karaokê desses: você aluga uma sala privada por hora, tem um catálogo enorme de músicas, dois microfones, e um sistema de pontuação que avalia seu canto em tempo real. Os melhores sistemas são japoneses, como o Joysound e o DAM. Nota acima de 90 (de 100) é considerada avançada. O DAM, na série LIVE DAM Ai, até usa IA pra dar notas mais “humanas”.

Mas nem todo lugar tem esse nível.

O problema com karaokê no Brasil

No Brasil a gente cresceu com o Videokê, a marca que o coreano Seok Ha Hwang trouxe pro país em 1996, importando equipamento da Coreia. Virou febre nos anos 90 e 2000, apareceu em todo bar, churrasco e festa de aniversário. O problema é que esses aparelhos pararam no tempo. Os modelos atuais, como o VSK 5.0, vêm com uns 12-13 mil músicas no catálogo, que você expande comprando cartuchos ou pacotes de música. Na prática, o repertório é velho, a interface é dos anos 2000, e se a música que você quer cantar saiu depois de 2015, boa sorte.

A solução que muitos bares adotaram foi permitir Chromecast ou espelhamento de tela pra que os clientes busquem músicas direto no YouTube. Faz sentido: no YouTube você encontra karaokê de qualquer música. Versão com letra, versão instrumental, versão com guia vocal.

Mas tem um downgrade: você perde a pontuação. Uma das coisas mais divertidas do karaokê é a competição. Ver sua nota subindo, comparar com os amigos, tentar bater o recorde da noite. Se você está só cantando em cima de um vídeo do YouTube, não tem feedback nenhum. É como jogar boliche sem placar.

E comprar um sistema profissional pra casa? Importar um Joysound F1 sai por mais de US$ 2.000 só o hardware, fora a assinatura mensal do catálogo. Pra uso casual não faz sentido.

A ideia: YouTube com pontuação em tempo real

O Frank Karaoke surgiu dessa frustração. Se o YouTube já tem todas as músicas, por que não fazer um app que funciona como wrapper do YouTube com overlay de pontuação em tempo real? Você busca qualquer vídeo de karaokê, canta junto, e o app analisa sua voz pelo microfone e mostra uma nota ao vivo.

É um app Flutter pra Android. Internamente ele carrega o YouTube numa webview e injeta um overlay em HTML/CSS/JavaScript direto na página. O display de score, o trail de pitch, o painel de configurações, o seletor de modo, tudo renderizado dentro da webview via injeção de JS.

Scoring sem referência

Agora, o problema real. Todos os sistemas profissionais de karaokê dependem de arquivos de referência pré-fabricados pra cada música. Todos.

O SingStar da Sony, que vendeu mais de 12 milhões de cópias entre 2004 e o fim do PS3, tinha um track de notas feito à mão pra cada música. Cada nota, cada sílaba, tudo mapeado manualmente. O mecanismo comparava o pitch do cantor via FFT contra essa referência em tempo real. Detalhe que eu achei esperto: a oitava era ignorada. Se a nota certa era um Dó, tanto faz se você cantou Dó3 ou Dó4. Homens cantam músicas femininas sem problema.

O Joysound e o DAM no Japão vão além e avaliam três dimensões separadas: precisão de pitch (音感), ritmo/timing (リズム感) e expressividade/dinâmica de volume (表現力). Tudo baseado em dados MIDI do servidor do operador. O formato open source equivalente é o UltraStar, onde cada música tem um arquivo .txt assim:

: 12 4 5 Hel-    (TipoNota BeatInicial Duração Pitch Sílaba)

Pitch 5 = MIDI 65 (F4). A pontuação compara o pitch do cantor com o da nota, módulo oitava, com tolerância de 1 semitom.

O Frank Karaoke funciona com qualquer vídeo do YouTube. Não tem arquivo de referência. Não tem MIDI. Não tem anotação de melodia. Zero metadata sobre qual nota você deveria estar cantando.

Eu não sei nada de pontuação de karaokê. Não sei nada de processamento de áudio, detecção de pitch, teoria musical aplicada a software. Nada. Então pedi pro Claude Code fazer uma pesquisa extensiva sobre o assunto. O que ele trouxe de volta está documentado em docs/scoring.md no repositório, e é bastante coisa: papers acadêmicos sobre avaliação de canto (Nakano et al. 2006, Tsai & Lee 2012, Molina et al. 2013), patentes (a Yamaha tem uma de 1999, US5889224A, que detalha pontuação por MIDI com 3 faixas de tolerância), e o código fonte de projetos open source como UltraStar Deluxe, AllKaraoke, Vocaluxe e Nightingale.

A conclusão da pesquisa: sem referência por música, você precisa avaliar qualidade vocal de forma genérica. Medir como a pessoa canta, não o que ela deveria estar cantando. E como não existe uma métrica única que funcione pra todos os casos, decidimos implementar quatro modos de pontuação diferentes, cada um medindo uma dimensão diferente da qualidade vocal.

O problema do microfone do celular

Antes dos modos de pontuação, preciso explicar um problema mais fundamental que a pesquisa revelou: o microfone do celular.

Quando você canta karaokê com o celular, o microfone capta três coisas ao mesmo tempo: sua voz, a música saindo do alto-falante, e ruído ambiente da sala. Sua voz está fisicamente mais perto do microfone, então domina o sinal. Mas não o suficiente pra uma separação limpa.

Tentei várias abordagens pra isolar a voz:

Subtração espectral usando o áudio de referência do YouTube. Abandonei. O CDN do YouTube bloqueia extração direta de áudio por user-agent não-browser, e mesmo com o áudio de referência, a equalização do alto-falante, a reverberação da sala e o delay de Bluetooth tornam o sinal diferente demais do que o microfone capta. Subtração simples gera artefatos piores que nenhuma subtração.

Pré-ênfase + center clipping. Abandonei também. O center clipping destrói a forma de onda que o algoritmo YIN precisa pra autocorrelação, e a pré-ênfase amplifica ruído tanto quanto voz.

O que funciona é um filtro bandpass de 200-3500 Hz: um filtro IIR de segunda ordem (Butterworth, Q=0.707) em cascata. O high-pass em 200 Hz elimina baixo, bumbo, bass guitar do bleed do alto-falante. O low-pass em 3500 Hz elimina pratos, hi-hats, ruído de alta frequência. Os fundamentais da voz humana (85-300 Hz) e os formantes (300-3000 Hz) passam pelo filtro. Não é isolamento perfeito, mas melhora bastante a razão voz/música pra detecção de pitch.

Mas o bandpass sozinho não resolve tudo. Guitarras, sintetizadores e piano produzem sinais periódicos na mesma faixa de frequência da voz, e o YIN detecta pitch neles também. Pra lidar com isso, o app faz uma calibração adaptativa: nos primeiros 5 segundos de warmup (quando ninguém está cantando), ele coleta amostras de RMS do sinal pra estabelecer um baseline do nível do alto-falante. Durante a música, mantém esse baseline atualizado (percentil 25 dos últimos ~4 segundos de frames). Pra um frame ser pontuado, o RMS precisa estar pelo menos 1.3x acima do baseline. A voz está mais perto do microfone, então empurra o RMS acima do nível do alto-falante. A melodia instrumental fica perto do baseline e é filtrada. Nos testes, o cantor original saindo pelo alto-falante marcava uns 37 pontos com dots esparsos no trail, enquanto alguém cantando de verdade marcava ~59 com dots densos.

Outro detalhe chato: no Android, especificamente nos Samsung, o AutomaticGainControl (AGC) do DSP atenua o sinal em vez de amplificar. Nos Galaxy, habilitar AGC reduz o pico do microfone de ~0.06 pra ~0.003. Silêncio pra detecção de pitch. Então o app desabilita AGC, echo cancellation e noise suppression. Quando o pico fica abaixo de 0.01, aplica ganho por software (até 30x) pra trazer o sinal a níveis usáveis.

O algoritmo YIN

Pra detectar o pitch da voz eu uso o YIN, de Alain de Cheveigné (IRCAM-CNRS) e Hideki Kawahara (Universidade de Wakayama). É um estimador de frequência fundamental no domínio do tempo. A ideia central é a Cumulative Mean Normalized Difference Function (CMNDF), que basicamente mede o quão periódico é o sinal em cada lag, normaliza pra reduzir falsos positivos, e usa interpolação parabólica pra refinar o resultado. É leve o suficiente pra rodar em tempo real no celular, o que importa aqui.

No app, o threshold do YIN é 0.70 (ajustado pra sinais mistos de voz + música), e frames com confiança abaixo de 0.3 são descartados. Abaixo disso, provavelmente é ruído ou instrumento.

Os 4 modos de pontuação

Cada modo avalia um aspecto diferente da qualidade vocal. Todos compartilham o mesmo pipeline de áudio (bandpass → YIN → gate de confiança). A diferença é como interpretam o pitch detectado.

Pitch Match

Mede o quão limpo você sustenta as notas. Usa decaimento gaussiano baseado no desvio padrão dos valores MIDI numa janela rolante de ~15 frames. Notas firmes (desvio < 0.3 semitons) pontuam 85-100%. Voz tremendo (desvio > 2 semitons) pontua perto de zero. Bom pra músicas que você já conhece bem.

Contour

Mede a forma melódica do seu canto. Não importa qual nota exata você acerta, só a direção e o fluxo. Avalia a amplitude do pitch e movimentos melódicos (saltos > 0.5 semitom) numa janela rolante. Canto monótono pontua ~10%. Movimento melódico suave com amplitude de 2-6 semitons pontua 70-100%. Bom pra quando você está aprendendo uma música nova.

Intervals

Mede a qualidade musical dos saltos entre notas consecutivas. Tom inteiro (2 semitons) pontua mais alto. Terças e quartas pontuam bem. Saltos descontrolados de uma oitava ou mais pontuam baixo. Usa uma curva gaussiana centrada no tom inteiro. Funciona quando você está cantando numa tonalidade diferente da original.

Streak

É o Pitch Match com multiplicador combo. Cada frame consecutivo com score acima de 0.4 incrementa o contador de streak. O streak adiciona pontos bônus (até +0.4 em streak de 30+). Quebrar um streak > 5 frames empurra uma penalidade de 0.05 no EMA. Silêncio congela o streak, então pausas instrumentais não te prejudicam. O modo mais divertido pra festas.

A lógica por trás desses quatro modos veio da pesquisa que o Claude fez nos papers acadêmicos. Cada um mede uma dimensão diferente: afinação, contorno melódico, fraseado e consistência. Nenhum deles sozinho é suficiente, mas juntos cobrem razoavelmente bem o que dá pra avaliar sem ter a melodia de referência da música.

O Pitch Oracle

Além dos quatro modos puramente vocais, o app tem o que eu chamo de Pitch Oracle. A ideia: em vez de avaliar sua voz isoladamente, o app baixa o áudio de referência do vídeo via youtube_explode_dart, decodifica pra PCM, roda o YIN nele, e constrói um timeline de pitch com timestamp da música inteira. Durante a pontuação, se o pitch do microfone bate com o pitch da referência naquele momento do vídeo, provavelmente é bleed do alto-falante, e é ignorado. Se difere, é sua voz, e é pontuado.

A sincronização funciona pelo currentTime do elemento de vídeo HTML5, enviado pro Dart via um listener JS de timeupdate a cada ~250ms. O oracle consulta o pitch de referência na posição exata do playback, levando em conta pause, seek e mudança de velocidade.

Na primeira vez que você toca uma música, o oracle leva uns 5-15 segundos pra baixar e analisar o áudio. Mas o timeline é salvo como JSON no cache local do app (pitch_oracle/<videoId>.json). Se você tocar a mesma música de novo, carrega instantaneamente do cache, sem request de rede. Isso também resolve o problema de rate limiting do YouTube pras músicas que você mais canta.

Com o oracle ativo, os modos mudam de comportamento. Pitch Match compara a classe de pitch do cantor contra a da referência (agnóstico à oitava, como o SingStar). Contour usa correlação cruzada entre o movimento de pitch do cantor e o da referência. Intervals compara os saltos em semitons contra os da referência.

Quando o YouTube bloqueia o download por rate limiting (acontece depois de muitos requests seguidos do mesmo IP, limpa em 15-30 minutos), o oracle falha silenciosamente e os modos voltam pra análise puramente vocal.

O caminho até aqui

O app que você vê agora passou por muita iteração antes de chegar nesse estado.

Primeiro, eu tentei fazer uma versão desktop Linux pra facilitar o debug. Faz sentido, né? Testa no desktop, itera rápido, depois porta pro celular. O problema é que o Flutter não tem backend de webview pra Linux desktop. O webview_flutter simplesmente não funciona. Tentei o webview_cef, que é baseado no Chromium Embedded Framework. O CEF spawna seu próprio processo de GPU, e no Hyprland (compositor Wayland baseado no wlroots) isso conflita com o pipeline de renderização do compositor. No meu setup com NVIDIA, a sessão inteira do Hyprland congelou. Tela travada, sem resposta a teclado, tive que matar pelo TTY. Fora que o CEF exige download de um binário de ~200MB na primeira build. Desisti do CEF e escrevi com o Claude uma bridge nativa em C++ usando WebKitGTK com method channels do Flutter. Funcionou, mas cada peculiaridade do YouTube exigia código separado pro Linux e pro Android. O just_audio também não tem implementação pra Linux desktop. No fim a versão Linux virou peso morto. Deletei ~1.500 linhas de código Linux-específico e foquei só no Android.

Depois veio a saga do microfone no Samsung. No meu Galaxy Z Fold, o microfone captava um sinal absurdamente baixo. Pico de ~0.005, basicamente silêncio pro detector de pitch. Fiquei umas duas horas tentando entender. Baixei thresholds, aumentei ganho por software até 50x, desabilitei preprocessadores de áudio. Nada funcionava direito. Até que descobri o problema real: o AutomaticGainControl do Android. O nome diz “controle automático de ganho”, o que sugere que ele amplifica sinais fracos. Na implementação DSP dos Samsung, ele faz o oposto. Ele atenua o sinal pra um nível de referência baixo, otimizado pra chamadas de voz. Com AGC ligado, o pico caía de ~0.06 pra ~0.003. Desligar o AGC resolveu. Mas aí o pacote audio_session religava o AGC por baixo dos panos. Removi ele também. Foram três rodadas de fix, cada uma achando mais uma camada do problema.

E a pontuação. A pontuação levou mais tempo que todo o resto junto. A primeira implementação usava média cumulativa, que deixava a nota travada num valor e não respondia ao canto em tempo real. Troquei pra janela rolante. Aí a nota ficava presa em ~50% por causa de um bug no peso da pontuação primária. Consertei, e ela passou a começar em 70% mesmo sem ninguém cantando. Consertei de novo. O modo Streak não resetava direito no silêncio. O chromatic snap dava nota alta pra qualquer coisa. O histórico de pitch não era limpo nos gaps de silêncio e os modos ficavam estagnados. Cada bug corrigido revelava outro. Foram mais de 25 commits só ajustando a pontuação, do primeiro protótipo até o estado atual.

O resultado não é perfeito. Eu sei. Mas funciona o suficiente pra ser divertido, que era o objetivo desde o começo.

Configurações

O painel de configurações fica no ícone de engrenagem do overlay. Tem três presets de microfone pra diferentes ambientes (microfone externo limpo, sala normal, festa barulhenta), cada um ajustando thresholds de confiança e amplitude. Tem pitch shift pra quando a música é aguda demais pra sua extensão vocal. O ajuste muda tanto o áudio do vídeo quanto a pontuação ao mesmo tempo: usa o playbackRate do elemento HTML5 com preservesPitch=false, então +2 semitons acelera o áudio pra 1.12x (pitch sobe) e -2 semitons desacelera pra 0.89x (pitch desce). A pontuação compensa o offset, então você canta na sua faixa confortável e o sistema avalia corretamente. Tem calibração de microfone, um processo de 3 segundos que mede o ruído da sala e adapta os thresholds. E tem restart pra zerar a pontuação sem recarregar o vídeo.

Pra trocar de modo de pontuação, toque na caixa de score durante a reprodução.

Fluxo de uso

1. Abra o app. O YouTube carrega dentro do app com o logo do Frank Karaoke.
2. Busque um vídeo de karaokê. Qualquer vídeo funciona, mas faixas instrumentais com letra na tela dão melhores resultados.
3. O vídeo pausa brevemente pra inicializar o microfone, baixar dados da música pro pitch oracle, e preparar o overlay. Na primeira vez com uma música nova isso leva uns 5-15 segundos. Se você já tocou essa música antes, carrega do cache instantaneamente.
4. Cante. O score “live” reflete sua performance atual (média exponencial com alpha 0.15, resposta em ~1 segundo). O score “overall” é a média cumulativa da música inteira.
5. Quando o vídeo pausa, a pontuação pausa junto (pra não pontuar ruído ambiente). Se fizer seek, o score zera e tem 5 segundos de warmup.

Como instalar

O app ainda não está na Play Store, estou esperando o Google verificar minha identidade de desenvolvedor. Deve aparecer lá nos próximos dias. Enquanto isso, é um projeto aberto e dá pra instalar direto.

O jeito mais fácil é baixar o APK assinado direto da página de releases do GitHub. No celular ou tablet Android, baixe o FrankKaraoke-0.2.0-android.apk, abra e toque em Instalar. Se o Android reclamar de “fontes desconhecidas”, habilite em Configurações > Segurança pro seu navegador. Na primeira execução o app pede permissão de microfone. Depois vá nas configurações (ícone de engrenagem) e calibre o microfone antes de cantar, são 3 segundos.

Se você quer compilar do fonte ou contribuir, o repositório está no GitHub. Precisa de Flutter SDK 3.10+, Android SDK API 24+, e um dispositivo físico pra testar microfone (emulador não dá resultados representativos).

git clone https://github.com/akitaonrails/frank_karaoke.git
cd frank_karaoke
flutter pub get
flutter run -d <device_id>

O README tem o resto.

Stack: Flutter + Riverpod pra state management, webview_flutter pro YouTube, youtube_explode_dart pra extração de áudio, record pra captura PCM do microfone, audio_decoder pra decodificação de referência via Android MediaCodec, e o algoritmo YIN implementado em Dart puro.

A documentação técnica do sistema de pontuação está em docs/scoring.md no repositório. Cobre como SingStar, Joysound e DAM funcionam, os papers acadêmicos, a arquitetura do pitch oracle, os problemas de isolamento de voz no Android, e o roadmap.

A pontuação é experimental

Preciso ser direto: o sistema de pontuação é experimental. Sem arquivos de referência por música, a avaliação é aproximada. O app mede se você está afinado, se segue um contorno melódico, se seus intervalos são musicais, se é consistente. Mas não te diz se você está cantando a melodia certa desta música específica (a menos que o pitch oracle consiga baixar o áudio, e nem sempre consegue).

Se você tem experiência com processamento de áudio, detecção de pitch, ou avaliação musical, o repositório está aberto e a documentação de pesquisa em docs/scoring.md detalha o que foi tentado, o que funciona e o que não funciona. Em particular: calibração dos thresholds dos modos, melhorias no isolamento de voz, e integração com o UltraSinger (que gera arquivos de referência a partir de músicas usando Demucs + basic-pitch + WhisperX) são áreas onde contribuição de quem entende do assunto faria diferença. Apreciamos qualquer ajuda de especialistas na calibração desses sistemas.

Ah, e o nome. Frank Karaoke. É uma homenagem ao Sinatra. Quem mais?

Projeto no GitHub: github.com/akitaonrails/frank_karaoke

Dito isso, deixa eu explicar por que eu fiz isso.

O problema com a mídia brasileira

Eu cansei.

Cansei de abrir o jornal e ter que fazer ginástica mental pra separar informação de narrativa. Cansei de publicações como Folha de São Paulo, UOL, Carta Capital, Brasil 247, O Globo e várias outras que usam manchetes enganosas, omitem contexto de propósito, transpõem evidências de outros países sem nenhuma ressalva, e criam uma aparência de consenso entre veículos que estão todos dizendo a mesma coisa porque seguem a mesma pauta coordenada.

Isso não é teoria da conspiração. É padrão editorial verificável. E o pior: a maioria dos leitores não tem tempo nem ferramentas pra perceber. Você lê o título, lê os dois primeiros parágrafos, e segue com a impressão que o artigo plantou na sua cabeça.

O que o Frank Investigator faz

Você dá uma URL de artigo de notícia. O sistema busca o artigo com Chromium headless (pra passar por paywalls e cookie walls), extrai o conteúdo filtrando propaganda e sidebar, e decompõe o texto em afirmações verificáveis. Aí começa a análise de verdade: divergência entre manchete e corpo, falácias retóricas (falsa causalidade, apelo a autoridade, espantalho, bait-and-pivot), distorção de fontes, manipulação temporal, citação seletiva, authority laundering. Expande os links citados no artigo pra verificar se as fontes dizem o que o autor afirma. Avalia cada claim com consenso de 3 modelos de IA (Claude Sonnet 4.6, GPT-5.4, Gemini 3.1 Pro) via OpenRouter. Detecta lacunas contextuais, campanha coordenada entre veículos, e mede a proporção entre paixão e evidência. São 15 etapas ao todo.

O princípio central é “Verdade Acima do Consenso”: uma fonte primária (dado oficial, documento de governo, estudo acadêmico original) veta qualquer quantidade de fontes secundárias repetindo a mesma informação. Dez jornais repetindo a mesma coisa sem fonte primária continuam valendo zero.

Deixa eu mostrar cinco exemplos reais.

Exemplo 1: O caso Noelia Castillo (BBC)

A BBC publicou uma matéria com o título “Morre Noelia Castillo: a luta de uma jovem de 25 anos na Justiça contra seu pai para receber a eutanásia na Espanha”. À primeira vista parece uma história sobre direito à eutanásia e uma disputa familiar. Uma jovem tetraplégica que lutou contra a oposição do pai religioso pra exercer seu direito de morrer.

Só que ao comparar com outros veículos, como a Veja, aparecem fatos que a BBC omitiu quase completamente. E esses fatos mudam tudo.

Noelia foi retirada da família pelo governo espanhol aos 13 anos e colocada sob custódia do estado. Enquanto estava sob essa custódia, sofreu múltiplos estupros coletivos. A violência sexual resultou em danos psiquiátricos graves e um histórico de saúde mental que já somava 67% de grau de invalidez antes dos eventos de 2022. Quando tentou suicídio em outubro de 2022, jogando-se do quinto andar de um prédio, ficou paraplégica. O grau de invalidez subiu pra 74%.

O pedido de eutanásia foi aprovado pela Comissão de Garantia e Avaliação da Catalunha. A data marcada pro procedimento foi 2 de agosto de 2024, mas ficou suspensa por mais de 600 dias por causa dos recursos judiciais do pai. Cinco instâncias judiciais se pronunciaram. O Tribunal Constitucional descartou violação de direitos fundamentais. O Supremo Tribunal da Espanha recusou o recurso. O Tribunal Europeu de Direitos Humanos rejeitou o pedido de suspensão. Na sexta-feira, 26 de março de 2026, Noelia foi submetida à eutanásia no Hospital Residencial Sant Camil, na comarca catalã de Garraf.

Mas tem um detalhe que a Veja menciona e que é perturbador: Noelia teria manifestado dúvidas antes do procedimento. E o hospital teria acelerado o processo porque os órgãos já estavam comprometidos pra doação.

O relatório do Frank Investigator comparou a cobertura de vários veículos.

A análise cruzada entre os artigos analisados mostrou que alguns veículos, como a BBC, omitiram fatos que alteram a interpretação do caso inteiro. Outros, como a Veja, trouxeram o contexto completo. O episódio de violência sexual coletiva de outubro de 2022, a investigação criminal, o histórico psiquiátrico desde os 13 anos, tudo isso aparece em algumas coberturas mas está completamente ausente em outras. E entre os veículos que omitiram, nenhum tocou na questão ética de que o fundamento físico pro pedido de eutanásia deriva de uma tentativa de suicídio.

O enquadramento convergente entre os veículos é de “batalha judicial”, “morte que pediu”, “deixar de sofrer”, “partir em paz”, suavizando o caráter definitivo do procedimento e posicionando Noelia como protagonista heroica e o pai como antagonista obstrutivo. O pai, Gerônimo Castillo, e seus Advogados Cristãos são qualificados como “ultracatólicos” ou “ultraconservadores” sem fonte independente que sustente essa classificação editorial.

A coordenação narrativa ficou em 55%. Não parece ser coordenação ativa entre redações, mas alinhamento editorial temático: todo mundo comprou a narrativa de autonomia individual sem questionar. O que eleva o score é a convergência de omissões. Nenhum veículo explica a distinção jurídica entre o TEDH “autorizar ativamente” a eutanásia e simplesmente recusar medidas cautelares provisórias pedidas pelo pai, que é o que de fato aconteceu. As implicações médicas e bioéticas de aprovar eutanásia em caso decorrente de tentativa de suicídio não aparecem em lugar nenhum. E qualquer voz crítica ao procedimento é automaticamente enquadrada como religiosa ou ideológica, nunca como médica ou jurídica.

É o tipo de caso onde a omissão é a manipulação. Os veículos que omitiram esses fatos não mentiram em nenhum momento. Mas ao enquadrar como “disputa familiar sobre direito à eutanásia” e omitir a cadeia causal (custódia do estado → estupros coletivos → dano psiquiátrico → tentativa de suicídio → paraplegia → eutanásia), o leitor fica com uma impressão radicalmente diferente da realidade. A comparação entre coberturas é exatamente o tipo de coisa que o investigator faz bem: expor o que cada veículo escolheu mostrar e o que escolheu esconder.

Exemplo 2: “Governo corta imposto de quase mil importados” (UOL)

O UOL publicou que o governo cortou impostos de importação de quase mil produtos, de remédios a lúpulo. Manchete positiva, tom de benefício ao consumidor. Vários outros veículos publicaram a mesma coisa com enquadramento parecido: o governo fez algo bom, preços vão cair.

Só que a Gazeta do Povo conta a outra metade da história. O governo não cortou impostos antigos. O que aconteceu foi: em algum momento anterior a fevereiro de 2025, o governo aumentou tarifas de importação de mais de 1.200 itens, uma medida que geraria R$ 14 bilhões em arrecadação estimada. Depois, sob pressão nas redes sociais e pressão popular público, recuou parcialmente. Zerou tarifas de uns 970 itens de capital, informática e telecomunicações. Reduziu impostos de 120 produtos de informática. E agora chama isso de “corte de impostos”.

Ou seja: aumentaram, tomaram pressão popular, voltaram atrás em parte, e reembalaram como se fosse uma concessão generosa. A maioria dos mais de 1.200 itens que tiveram tarifas elevadas continua com tarifas mais altas do que antes. Nenhum preço caiu pro consumidor final. Os preços voltaram ao que eram pra alguns produtos, e continuam mais altos pra maioria.

O relatório do Frank Investigator cruzou os artigos e expôs o que foi omitido.

O que a comparação entre artigos expõe: nenhum dos veículos com enquadramento positivo menciona que a maioria dos 1.200+ itens com tarifas elevadas continua com tarifas mais altas após as duas rodadas de “cortes”. O impacto fiscal sobre a meta de arrecadação de R$ 14 bilhões prevista com os aumentos originais, ninguém calcula. Vozes da indústria nacional que pode ser prejudicada pela redução tarifária de concorrentes importados, nenhuma. Critérios objetivos do Gecex pra definir “oferta insuficiente no mercado interno”, não aparecem.

Os dois artigos analisados constroem o mesmo enquadramento positivo pro governo. O paradoxo de que os “cortes” são reversão parcial de aumentos feitos pelo mesmo governo no ano anterior fica enterrado ou simplesmente ausente.

É o tipo clássico de manipulação por reenquadramento. Ninguém mentiu. Mas “governo corta imposto” e “governo recua de aumento após pressão popular” descrevem o mesmo evento com impressões opostas. A escolha editorial de qual versão publicar já é a manipulação.

Exemplo 3: “Globo se desculpa por PowerPoint” (Brasil 247)

Esse caso explodiu nos últimos dias. A GloboNews mostrou um diagrama no programa Estúdio I conectando o presidente Lula, seus ministros e Daniel Vorcaro, dono do Banco Master, que está no centro de fraudes documentadas. A Globo depois se retratou publicamente, chamou o material de “errôneo e incompleto”, e demitiu uma editora.

O Brasil 247 publicou uma matéria com o título “Globo se desculpa por PowerPoint que tentou jogar o caso Master no colo de Lula”.

O relatório do Frank Investigator expôs o que está acontecendo por baixo:

O fato central é real: a Globo pediu desculpas e demitiu alguém. Mas o enquadramento do Brasil 247 vai muito além do que os fatos sustentam. O título diz “tentou jogar no colo de Lula” atribuindo intenção deliberada onde os documentos apontam pra falha editorial. A retratação da Globo falou em material “errôneo e incompleto”, não em tentativa de incriminar ninguém.

O que chama atenção nesse caso é a campanha coordenada. O investigator deu 62% de coordenação narrativa.

Vários veículos editorialmente alinhados ao governo usaram a expressão “sem provas” de forma convergente pra descrever a associação entre Lula e o caso Master. Todos focaram no erro da Globo como ponto central da narrativa, em vez de investigar as conexões reais. Nenhum veículo mencionou quais outros nomes políticos foram excluídos do PowerPoint original. Nenhum investigou as conexões documentadas de Vorcaro com diferentes esferas do poder. O foco é meta-jornalístico: criticam a emissora em vez de cobrir o escândalo.

As falácias detectadas: linguagem carregada (“tentou jogar”, “sem provas” usados pra enquadrar erro editorial como ataque político deliberado), falsa causalidade (a retratação da Globo não prova que as conexões são falsas), cherry-picking (destaca a omissão de nomes ligados ao governo Lula sem contextualizar quais outros nomes foram omitidos), e bait-and-pivot (usa o pedido de desculpas da Globo como gancho pra minimizar o escândalo do Banco Master).

E as perguntas que nenhum desses veículos fez: quais nomes de ministros do Supremo e políticos de outros partidos também foram excluídos do PowerPoint? O caso Master tem conexões documentadas com figuras do governo Lula, ou se restringem a governos anteriores? O Brasil 247, que publica esse artigo, tem alinhamento editorial declarado com o governo Lula? Qual foi a reação do Conselho de Ética jornalístico?

Confiança geral: 13%. O artigo não fabrica fatos. Mas seleciona, enquadra e omite de forma a construir uma narrativa que os dados não sustentam.

Exemplo 4: “Por que combustível caro é bom” (Folha)

O economista Bernardo Guimarães publicou uma coluna na Folha defendendo que combustível caro é bom pra sociedade porque estimula inovação em energia limpa. Ele cita artigos acadêmicos reais (Popp 2002, NBER) e tem credenciais acadêmicas verificáveis (doutorado em Yale, professor na FGV EESP). Parece sólido.

O relatório completo do Frank Investigator mostra outro quadro.

O artigo acerta ao citar estudos reais. Mas omite quem paga a conta. A coluna ignora completamente o impacto distributivo: populações de baixa renda, moradores de áreas periféricas e rurais, que dependem mais de veículos próprios e têm menos acesso a alternativas limpas. Pra um economista, ignorar efeitos distributivos é ou incompetência ou escolha editorial.

Tem um problema pior. As evidências empíricas que ele cita (patentes nos EUA, dados de veículos elétricos na Califórnia entre 2014-2017) são transpostas pro Brasil sem ressalva nenhuma. O Brasil tem uma matriz de etanol e infraestrutura flex-fuel que altera completamente o mecanismo causal. O artigo trata como se o consumidor brasileiro estivesse na mesma situação que o californiano, o que é falso.

E tem o contexto que o artigo menciona de passagem mas não desenvolve: a Guerra no Irã está fazendo os preços de combustível subirem no mundo todo. O Brasil deveria estar numa posição privilegiada por causa do pré-sal e do etanol. Mas décadas de má gestão e corrupção na Petrobras fizeram com que a gente pague o mesmo preço que o resto do mundo. Em vez de questionar isso, a coluna vende a ideia de que “pelo menos vai estimular energia limpa”. É uma racionalização de um problema que não deveria existir.

O investigator identificou 5 questões que o artigo se recusou a abordar, com 35% de completude contextual. As falácias detectadas incluem falso dilema (apresenta combustível caro como a única opção viável de política climática), cherry-picking (reconhece inelasticidade de curto prazo mas enfatiza apenas efeitos de longo prazo), e linguagem carregada (descreve alternativas como “brincar de plantar uma mudinha”).

Confiança geral: 25%. Não é desinformação fabricada. É opinião com seleção de evidências a favor da tese e omissão de contrapontos relevantes.

Exemplo 5: “Não existe cinema forte sem regulamentação do streaming” (O Globo)

Renata Magalhães, presidente da Academia Brasileira de Cinema, deu uma entrevista na coluna da Miriam Leitão no O Globo defendendo que regulamentar o streaming é condição necessária pra fortalecer o cinema brasileiro.

O relatório do Frank Investigator encontrou problemas sérios.

Primeiro: a afirmação central de que “muitos filmes têm baixa audiência” aparece sem nenhum dado empírico. Nenhum número, nenhuma série histórica. É afirmação de autoridade pura, sem base analítica.

Segundo: tem uma contradição interna que o artigo não resolve. O texto abre dizendo que o cinema brasileiro está “em destaque internacional” (prêmios, festivais). E logo em seguida argumenta que a ausência de regulamentação impede o fortalecimento da indústria. Mas se o cinema brasileiro já está ganhando prêmios internacionais sem essa regulamentação, o argumento de que a regulamentação é condição necessária cai por terra. O artigo não endereça essa contradição.

E é aqui que entra o elefante na sala que nenhum desses artigos menciona: as pessoas simplesmente não querem assistir a maioria desses filmes. O cinema brasileiro premiado internacionalmente é feito pra competir em Cannes e no Oscar, não pra lotar sala de cinema no Brasil. Em vez de se perguntar por que o público brasileiro não se interessa, a indústria prefere pedir regulamentação do streaming pra forçar plataformas a financiar e exibir conteúdo que não tem audiência espontânea. É o modelo clássico: usa dinheiro público e regulação pra manter viva uma indústria que não se sustenta no mercado.

A entrevistada é presidente da Academia Brasileira de Cinema. Tem interesse institucional direto na regulamentação. O artigo não apresenta nenhuma voz contrária e não discute os custos pro consumidor: aumento de preço de assinatura, redução de catálogo. Uma fonte só, com conflito de interesse declarado, sem contraponto.

E aqui vem a campanha coordenada, com 55% de coordenação narrativa. Múltiplos veículos reproduzem o mesmo enquadramento emocional: cinema “em risco”, regulamentação como “essencial”. Nenhuma das fontes identificadas discute evidências empíricas internacionais comparáveis sobre a eficácia de cotas de conteúdo (a Europa tem experiências com resultados contraditórios). Nenhuma menciona os conflitos de interesse da Academia Brasileira de Cinema. O fato de que as produções brasileiras premiadas internacionalmente foram feitas sem a regulamentação proposta é omitido convergentemente em todos os veículos. Apenas um site isolado (targethd.net) mencionou impactos negativos pro consumidor.

Confiança geral: 9%. O artigo é advocacy editorial legítimo, mas com falhas analíticas que limitam seu valor informativo a quase zero.

O que o investigator analisa

Os 5 exemplos acima mostram padrões diferentes, mas os critérios de análise são os mesmos.

O sinal mais forte de manipulação é a omissão. Não é o que o artigo diz que engana, é o que ele deixa de dizer. A análise de lacunas contextuais identifica as perguntas que o artigo deveria ter respondido e não respondeu, e busca contra-evidência pra cada uma. Nos exemplos acima, artigos que omitem a maior parte do contexto relevante não estão informando ninguém. E quando a comparação cruzada entre veículos mostra que uns cobriram os fatos e outros não, como no caso Noelia ou no corte de impostos, fica difícil argumentar que a omissão foi acidental.

Depois vem a detecção de campanha coordenada. Vários jornais cobrirem o mesmo assunto é normal. Todos usarem a mesma linguagem carregada, focarem nos mesmos pontos e omitirem os mesmos contrapontos ao mesmo tempo não é. O sinal mais forte de coordenação não é o que os veículos dizem em comum, mas o que omitem em comum.

Tem também o reenquadramento, que é mais sutil. No caso dos impostos, o governo aumentou tarifas, recuou sob pressão, e os veículos chamaram de “corte”. Ninguém mentiu tecnicamente, mas a escolha de enquadramento muda completamente a interpretação. Esse tipo de manipulação é mais difícil de detectar porque cada afirmação individual é defensável.

As falácias retóricas pegam construções específicas: falso dilema (“ou regula ou o cinema morre”), bait-and-pivot (abre com fato positivo e pivota pra narrativa de crise), linguagem carregada (“sem provas” usado pra atribuir intencionalidade). Cada falácia detectada vem com a citação exata do trecho e a explicação de por que aquela construção é problemática.

E tem o princípio que costura tudo: se 10 veículos repetem a mesma afirmação citando uns aos outros, o consenso de LLMs tem que refletir que a cadeia de evidência é circular, não que a afirmação é bem suportada. Volume de cobertura não é proxy pra verdade.

Por que você não pode “só perguntar pro ChatGPT”

A primeira reação de muita gente vai ser: “por que eu preciso disso se eu posso colar o artigo no ChatGPT e pedir pra ele analisar?”

Tenta. Pega um artigo político e pede pro ChatGPT criticar. Ele vai criticar. Pega o mesmo artigo e pede pra confirmar. Ele vai encontrar argumentos pra confirmar. O LLM não está buscando a verdade. Ele está prevendo qual resposta você mais provavelmente espera ouvir dado o enquadramento da sua pergunta. Se você pede “analise os problemas desse artigo”, o modelo vai achar problemas. Se você pede “esse artigo está correto?”, ele vai encontrar méritos. É viés de confirmação automatizado.

Tem outro problema. Os LLMs generalistas foram treinados pra ser agradáveis. A tendência sycophantic (de concordar com o usuário) é documentada em todos os modelos grandes. Se o seu histórico de conversa indica que você é de esquerda, o modelo tende a enquadrar as respostas de uma forma que agrade esse perfil. Se você é de direita, mesma coisa pro outro lado. Ele não está mentindo de propósito. Ele está otimizando pra satisfação do usuário, que é literalmente a métrica pela qual foi treinado via RLHF.

E o pior: LLMs alucinam. Se não têm evidência suficiente pra sustentar a resposta que acham que você quer ouvir, inventam. Fabricam citações e dados plausíveis, atribuem declarações a pessoas que nunca as fizeram. Se você pede pra ele criticar um artigo sobre combustível, ele pode inventar um estudo fictício que “prova” o contrário do artigo. Parece convincente. Mas não existe.

O Frank Investigator foi construído pra evitar exatamente esses problemas. A primeira decisão de design é que nenhum humano faz pergunta ao LLM. Não existe prompt aberto tipo “analise esse artigo”. Cada etapa do pipeline tem prompts estruturados que pedem análises específicas: “liste as falácias retóricas neste trecho”, “identifique que informações contextuais estão ausentes”, “compare a manchete com o corpo do texto”. O modelo não sabe se o operador concorda ou discorda do artigo, porque o operador não opina em nenhum momento. Isso elimina o viés de confirmação na raiz.

Pra lidar com alucinação, todo analisador que usa LLM inclui a instrução “CRITICAL – NO HALLUCINATION: Only reference URLs, sources, claims, quotes, and data that are EXPLICITLY present in the input provided to you. Do not invent, guess, or fabricate any URL, source name, statistic, quote, or claim. If you cannot verify something from the provided text, mark it as unverifiable – never fill in details.” Não elimina alucinação completamente, mas reduz muito. E como são 3 modelos de empresas diferentes (Anthropic, OpenAI, Google) respondendo as mesmas perguntas, quando um alucina os outros dois geralmente discordam. O consenso é ponderado por confiança, não por maioria simples. Se dois modelos dão “supported” com 70% de confiança e um dá “mixed” com 95%, o “mixed” pesa mais. Quanto mais distante a discordância, maior a penalização na confiança final. Se um modelo começa a dar respostas inconsistentes, ele é colocado em quarentena e os outros dois continuam.

Mas a salvaguarda que eu considero mais importante é o primary source veto. Se uma fonte primária (dado do IBGE, decisão judicial, estudo original) contradiz uma claim, a confiança é capada em 60% e o veredicto é forçado pra “mixed”, mesmo que os 3 LLMs digam “supported”. Dez artigos de jornal repetindo uma afirmação não superam um dado oficial que a contradiz. Na mesma linha, se 5 matérias “confirmam” uma claim mas todas são do mesmo grupo editorial (Folha/UOL, Globo/G1/Valor), o sistema sabe que são a mesma voz e reduz o peso. Volume não substitui independência.

Nada disso torna o sistema perfeito. Mas é categoricamente diferente de colar texto no ChatGPT e perguntar “o que você acha?”.

Os números

Stack: Ruby 4.0.1, Rails 8.1.2, SQLite com WAL mode, Solid Queue (jobs dentro do Puma), Solid Cable (WebSockets), Tailwind CSS v4, Chromium headless via Ferrum CDP, deploy com Kamal pro GitHub Container Registry. AGPL-3.0.

O processo de desenvolvimento

O projeto tem 129 commits em 9 dias de trabalho ativo (11-16 e 25-27 de março). O primeiro dia foi o mais pesado: mais de 60 commits só em 11 de março, começando do zero e chegando num sistema funcional com extração de conteúdo, decomposição de claims, avaliação por LLM, e interface web com live updates via Turbo Streams.

Os commits contam a história. Começou com a fundação:

1e32d5a - Initial Frank Investigator foundation
564eb97 - Add recursive source crawling and RubyLLM scaffold
c8c5357 - Add Brazil source registry and authority connectors
3d30617 - Add U.S. authority profiles, source role modeling, and specialized connectors

Depois vieram os analisadores de desinformação, um por um:

a65fef7 - Add rhetorical fallacy analyzer for detecting narrative manipulation
5dcf99d - Add headline-body divergence detection and headline citation amplification
a113efd - Add smear campaign defense with circular citation and viral volume detection
56d501a - Add media ownership modeling, syndication detection, and independence analysis

A fase de hardening contra ruído e falsos positivos foi a que mais consumiu tempo:

46e4bc5 - Add pre-fetch defenses: URL filtering, circuit breaker, fetch prioritization
168fea1 - Add post-fetch content gate, claim noise filter, and duplicate content skip
b2843d7 - Add paywall detection, pricing noise filter, and ofertas.* host rejection
b1b230d - Rewrite Chromium fetcher with Ferrum CDP for anti-bot evasion

Depois veio a interface, deploy, e os analisadores mais avançados:

c5afcea - Replace custom CSS with Tailwind CSS v4 and rewrite all templates
95a8ec4 - Add Docker deployment with bin/deploy script
ccfacc9 - Add coordinated narrative detection across media outlets
ba3e2f4 - Add 6 new misinformation detection analyzers with cross-analysis
fda984b - Add LLM-generated investigation summary with quality assessment
a4ebe78 - Add contextual gap analysis to detect manipulation through omission

E nos últimos commits, o consenso de 3 modelos simultâneos e otimização de testes:

5cc9c05 - Enable 3-model LLM consensus: Sonnet 4.6, GPT-4.1 Mini, Gemini 2.5 Pro
cdf5fb5 - Batch 5 content analyzers into single LLM call, add anti-hallucination
28c305e - Add WebMock stubs for LLM and web search — tests run in 1.4s (was 540s)

Os testes que rodavam em 9 minutos agora rodam em 1.4 segundo com WebMock stubbing de todas as chamadas de LLM e web search. Isso fez diferença enorme na velocidade de iteração.

Limitações

Fact-checking de notícias é um problema difícil. Um artigo sozinho não contém tudo que é necessário pra uma análise completa. O autor escolheu o que incluir e o que omitir, e essa escolha já é o primeiro nível de manipulação. As fontes citadas dentro do artigo foram selecionadas pelo autor pra sustentar a narrativa dele, não pra dar uma visão equilibrada.

O Frank Investigator não diz o que é verdade e o que é mentira. O resultado é um relatório com pontos fortes e fracos, não um selo de “verdadeiro” ou “falso”. Mesmo com todas as salvaguardas que descrevi acima, a contra-evidência buscada automaticamente pode não ser a mais relevante. As falácias detectadas podem ter falsos positivos. A análise de campanha coordenada depende do que o web search retorna no momento da busca.

Use os relatórios como ponto de partida pra formar sua própria opinião, não como veredicto final.

O projeto é open source, AGPL-3.0. Se quiser contribuir, testar, reportar bugs ou sugerir melhorias: GitHub. Se quiser acompanhar as análises, a newsletter The Makita Chronicles vai ter a seção “Notícias Duvidosas” com resumo e link pro relatório completo de cada investigação.

Até “funciona”, mas esse projeto foi mais pelo exercício. Dito isso, deixa eu contar por que fiz isso.

O problema com o OpenClaw

O OpenClaw é um gateway que conecta canais de mensagem (Telegram, Discord, Slack, WhatsApp, etc.) a provedores de IA (OpenAI, Anthropic, Ollama). Você configura, sobe o servidor, e pode conversar com LLMs direto pelo Telegram ou qualquer outro canal. É um projeto popular e com bastante atividade.

Atividade demais, na verdade.

Eu fiz um clone depth-1 do repositório e rodei um tokei:

Mais de um milhão de linhas de TypeScript. Os 2.799 arquivos de teste parecem bastante em número absoluto, mas proporcionalmente ao tamanho do codebase, a cobertura é baixa. A maior parte do código está em 29 pacotes de um monorepo com 21 extensões.

Fui buscar mais commits pra entender o ritmo de desenvolvimento. Nos 100 commits que consegui puxar, todos caíram em apenas 2 dias (9 e 10 de março). ~50 commits por dia, de 42 contribuidores diferentes. Vibe coding ao extremo.

A conclusão é a que você imagina: volumes enormes de código gerado por IA sendo despejados num repositório a uma velocidade que impossibilita review humano sério. E isso me incomodou o suficiente pra ir investigar mais a fundo.

A auditoria de segurança

Pedi pro Claude fazer uma auditoria de segurança completa no código do OpenClaw. O relatório encontrou:

Sete vulnerabilidades críticas. Deixa eu listar algumas:

• Timing side-channel na comparação de tokens – o safeEqualSecret() faz um return antecipado no type-check, permitindo que um atacante distinga tokens malformados de tokens errados medindo latência.
• eval() no browser tool – execução arbitrária de JavaScript sem sandbox.
• Shell sem allowlist – qualquer tool pode executar qualquer comando no sistema.
• Webhooks do Slack sem verificação de assinatura nenhuma.
• Transcripts e config em texto puro no disco, sem criptografia.
• Sem rate limiting efetivo – IPs podem ser spoofados se o operador configura trusted proxies de forma ampla.

Essas são só as que o Claude encontrou numa varredura automatizada. Provavelmente tem mais.

Eu não vou rodar isso na minha máquina. Nem dentro de um container Docker. Um gateway que recebe webhooks da internet, executa comandos shell, se conecta a APIs de IA com suas chaves, e guarda histórico de conversas, tudo isso com 7 vulnerabilidades críticas conhecidas? Não, obrigado.

Então eu fiz o que qualquer desenvolvedor racional faria: decidi construir o meu.

A primeira tentativa: Claude Code

Comecei do jeito mais direto. Clonei o OpenClaw, apontei o Claude Code pro código, e pedi: “reescreve isso em Rust.”

Não funcionou. O codebase é grande demais. Mais de um milhão de linhas de TypeScript espalhadas em 29 pacotes. O Claude não consegue manter tudo em contexto. O resultado inicial foi muito incompleto: muitos tipos criados mas sem implementação, todo!() por toda parte, boilerplate demais e funcionalidade de menos.

Troquei pro Codex 5.4 pra testar. Mesma coisa: pedi pra analisar e reescrever. Melhorou um pouco em certos aspectos, mas o problema fundamental é o mesmo. Nenhuma IA hoje pega um projeto desse tamanho e reescreve inteiro de uma vez. O contexto não cabe.

A técnica que funciona

O que funciona é ir devagar. Um passo de cada vez.

Pede pro Claude (ou Codex) analisar o código original em etapas. Faz um plano longo detalhando cada feature. Depois implementa uma feature por vez em Rust, com testes, faz commit, e repete. É tedioso, mas é o que produz código que compila e funciona de verdade.

O motivo é simples: o código original é tão massivo que nenhum agente de IA (nem vários em paralelo) consegue manter tudo em contexto ao mesmo tempo. Você precisa decidir o que importa, implementar aquilo, validar, e seguir pro próximo.

E precisa decidir o que cortar. O OpenClaw tem 21 extensões de canal: Google Chat, iMessage, IRC, Teams, Matrix, Mattermost, Nostr, Twitch… Eu não preciso de nenhuma dessas. Mantive os canais mainstream: Web, Telegram, Discord, Slack, Signal, WhatsApp e Email. TTS? Fora. Polls? Fora. WhatsApp Web via Baileys? Fora, uso a Cloud API oficial. São features que adicionam complexidade sem valor proporcional.

Descobrindo o IronClaw

No meio do desenvolvimento, descobri o IronClaw, que se apresenta como “OpenClaw em Rust”. Ótimo, pensei. Vou ver o que eles fizeram.

Clonei o repositório e pedi pro Claude escrever um relatório de comparação. O IronClaw tem coisas boas. Adotei 12 features:

Circuit breaker com retry e backoff exponencial pra resiliência de providers LLM. Detecção de leak de credenciais no output. Cache de respostas LLM com SHA-256 da prompt. Cost tracking com budget guards (aviso em 80%, bloqueio em 100%). Extended thinking pra Claude 3.7+ e o1. MCP client pra tool servers externos. Lifecycle hooks em inbound, tool calls e outbound. Smart model routing que joga queries simples pra modelos mais baratos. Suporte a túneis (cloudflared, ngrok, tailscale). REPL interativo (frankclaw chat). Routines com event triggers além de cron. Job state machine com auto-repair.

Mas o IronClaw depende de PostgreSQL + pgvector, tem sandbox WASM (wasmtime adiciona ~10MB), e é parte do ecossistema NEAR AI. Eu quero um binário único com SQLite embarcado e zero dependências externas.

O que o FrankClaw traz do OpenClaw

O core do OpenClaw está lá: 7 canais de mensagem, multi-provider com failover, agent runtime, sistema de comandos, skills, subagents, browser automation via CDP, bash tool com allowlist, cron jobs, REPL interativo. Mais as 12 features do IronClaw que listei acima.

Mas vários pedaços precisaram ser reescritos de um jeito que o original não fez. A compactação de contexto, por exemplo, usa sliding window com estimativa de tokens, pruning de mensagens e repair automático de tool pairs que ficam órfãos quando o contexto é cortado. O failover entre providers agora é model-aware: se você pede um modelo Claude e o provider da vez é OpenAI, ele pula automaticamente em vez de dar erro. O canvas renderiza SVG, HTML e Markdown com detecção de conflitos de revisão. São coisas que no OpenClaw ou não existiam ou estavam pela metade.

Depois veio a fase de adicionar o que faltava pra paridade. O FrankClaw hoje tem 30+ LLM tools: web_fetch (SSRF-safe com HTML-to-text), web_search (Brave API), file_read/file_write/file_edit (sandboxed no workspace com proteção contra path traversal), pdf_read, image_describe (via modelos de vision), audio_transcribe, sessions_list/sessions_history/sessions_delete, message_send/message_react, cron_list/cron_add/cron_remove, config_get (auto-redação de secrets), agents_list, memory_get/memory_search, mais os browser tools (browser_open, browser_extract, browser_snapshot, browser_click, browser_type, browser_wait, browser_press, browser_sessions, browser_close, browser_aria).

Algumas adições que não existem no OpenClaw original: um sistema de memória/RAG com SQLite FTS5 e embeddings (OpenAI, Gemini, Voyage) que sincroniza arquivos do workspace automaticamente. Uma API compatível com OpenAI (/v1/chat/completions e /v1/models), então qualquer cliente que fala esse protocolo (Cursor, Continue, Open WebUI) pode usar o FrankClaw como backend sem adaptação. Uma TUI em ratatui pra quem prefere terminal. Aprovação interativa de tools destrutivos antes de executar.

Tem coisas menores que fazem diferença na prática. Você pode configurar múltiplas API keys por provider com round-robin e backoff automático, então se uma key estourar o rate limit, a próxima assume. O model catalog já sabe context windows e custos dos modelos OpenAI e Anthropic sem você ter que configurar. Extração de URLs de mensagens tem blocklist de IPs privados contra SSRF. O sistema de comandos aceita directives inline (/think, /model) além de aliases.

Do lado de operação: ACP (Agent Client Protocol) via JSON-RPC 2.0 sobre NDJSON pra quem quer integrar programaticamente. Sistema de plugins com manifests e lifecycle de enable/disable. i18n com 9 locales via FRANKCLAW_LANG. Workspace identity files (SOUL.md, IDENTITY.md) pra definir a personalidade do bot por projeto. Health monitor nos canais com auto-restart. WebSocket com ping keepalive que sobrevive timeouts de proxy e túnel. frankclaw start/stop/status pra quem quer rodar como daemon com PID tracking. E toda a configuração migrou de JSON pra TOML.

Hardening: onde está o diferencial

O relatório de auditoria que rodamos no OpenClaw encontrou 7 vulnerabilidades críticas e 9 high. O FrankClaw resolve todas:

O FrankClaw compila com #![forbid(unsafe_code)] em todos os 13 crates. Zero blocos unsafe.

E a auditoria não parou no OpenClaw. Fizemos uma auditoria por componente em 14 fases comparando cada parte do FrankClaw contra o original: canais, providers, runtime, tools, sessions, crypto, cron, webhooks. Tudo documentado.

Deploy: como instalar

O FrankClaw roda com Docker Compose. Três containers: gateway, Chromium headless (pra browser tools), e Cloudflare tunnel (pra receber webhooks).

1. Clonar e configurar

git clone https://github.com/akitaonrails/frankclaw.git
cd frankclaw
cp .env.docker.example .env.docker

Edite o .env.docker com suas chaves:

# Providers de IA (preencha os que usar)
OPENAI_API_KEY=
ANTHROPIC_API_KEY=

# Canais (preencha os que quiser usar)
TELEGRAM_BOT_TOKEN=         # via @BotFather
WHATSAPP_TOKEN=             # Meta Business Platform
WHATSAPP_PHONE_ID=
WHATSAPP_VERIFY_TOKEN=
DISCORD_BOT_TOKEN=
SLACK_BOT_TOKEN=
SLACK_APP_TOKEN=

# Embedding providers (só se usar memória/RAG)
# GEMINI_API_KEY=
# VOYAGE_API_KEY=

# Opcional: criptografia de sessions (recomendado)
# Gere com: openssl rand -base64 32
FRANKCLAW_MASTER_KEY=

# Opcional: scan de malware em uploads
VIRUSTOTAL_API_KEY=

2. Configurar o gateway

O arquivo frankclaw.toml define agentes, modelos e canais. Use o wizard ou os exemplos:

# Gerar config base com canal web
cargo run -- onboard --channel web

# Ou copiar dos exemplos
ls examples/channels/

Pra cada canal, o CLI tem templates prontos:

cargo run -- config-example --channel telegram
cargo run -- config-example --channel whatsapp

3. Cloudflare Tunnel (pra receber webhooks)

Se você vai usar canais que precisam de webhook (Telegram, Discord, Slack, WhatsApp), precisa de um túnel público. O Docker Compose já inclui o cloudflared:

# Copie suas credenciais do Cloudflare
cp docker/cloudflared/config.yml.example docker/cloudflared/config.yml
cp ~/.cloudflared/<tunnel-id>.json docker/cloudflared/credentials.json
cp ~/.cloudflared/cert.pem docker/cloudflared/cert.pem
# Edite config.yml com seu hostname

4. Subir

docker compose up -d

O gateway sobe na porta 18789 (interna ao Docker). O cloudflared roteia o tráfego externo. O Chromium fica na rede interna pra browser tools.

Pra testar local sem Docker:

cargo run -- chat

Abre o REPL interativo direto no terminal (agora também tem uma TUI em ratatui com dark mode e tabs). Sem gateway, sem webhook. Bom pra validar que o provider de IA está respondendo antes de configurar canais.

Validação

cargo run -- check     # valida config
cargo run -- doctor    # diagnóstico completo
cargo run -- audit     # auditoria de segurança com severity ratings

O audit é o que eu mais gosto. Ele verifica se você tem criptografia habilitada, se as permissões de arquivo estão corretas, se os webhooks têm verificação de assinatura, se o bash tool está em deny-all. Sai com exit code non-zero se encontra problemas críticos, então dá pra colocar no CI.

O processo de desenvolvimento

O projeto tem 178 commits em ~5 dias de trabalho (10-16 de março). Quase 57 mil linhas de Rust em 120 arquivos, organizados em 13 crates.

Os commits contam a história. As primeiras dezenas foram scaffold: estrutura do workspace, tipos básicos, o gateway HTTP/WebSocket, primeira versão dos channel adapters. Código gerado em massa, muita coisa incompleta.

Depois começaram os adapters de canal, um por um:

236aa1c - Minimal Discord channel adapter
fd67017 - Minimal Slack channel adapter
9f51373 - Minimal Signal channel adapter
1052e47 - WhatsApp channel webhook adapter
035f86e - Email channel adapter (IMAP inbound, SMTP outbound)

Quando os canais básicos estavam no lugar, veio a integração do IronClaw num commit grande:

c87ab32 - IronClaw-derived features: circuit breaker, retry, leak detection, cache, cost tracking, extended thinking

E aí veio o hardening. Essa foi a fase que eu mais tive que intervir manualmente, porque o Claude gera código funcional mas não pensa em vetores de ataque sozinho:

db34198 - Prompt injection sanitization, external content wrapping, prompt size limit
5719b34 - Optional VirusTotal malware scanning for file uploads
ccd2b2b - Harden input validation across all user-facing entry points
aa918ee - Optional ai-jail sandbox for bash tool
2d7b1df - Security audit command with severity-rated findings
d12cc97 - 3-tier ToolRiskLevel system replacing binary browser mutation flag
21e0c91 - Timing-safe token comparison in WhatsApp, crypto audit tests
e240c1b - Webhook replay prevention with timestamp verification
876a78c - Gateway & media: SSRF redirect validation, filename hardening

22 commits de security hardening. Mais 10 de auditoria por componente. Cada achado virou um commit com fix.

Depois vieram as auditorias específicas por canal, cada uma descobrindo edge cases diferentes:

43b085f - Discord audit: HELLO timeout, fatal close codes, message chunking
12c7cff - Telegram audit: caption overflow, parse fallback, edit idempotency
f515062 - WhatsApp audit: message type filtering, send error classification
3c42aff - Slack audit: fatal auth errors, send error classification

Browser tools precisaram de atenção extra. Um headless Chrome que recebe URLs de um LLM é um vetor de ataque óbvio:

3217a96 - Browser automation: CDP timeout, SSRF guard, session limits, crash recovery
d98a803 - Gate mutating browser tools behind operator approval
014f56e - Browser screenshot/ARIA tools for accessibility tree inspection

Nos commits mais recentes, o projeto começou a divergir do OpenClaw:

5d73c4d - OpenAI-compatible HTTP API (/v1/chat/completions, /v1/models)
d832c36 - Memory/RAG system with SQLite FTS5, embeddings, and file sync
2b05f47 - Interactive tool approval for mutating/destructive tools
49034eb - Web console: dark mode, 8 tabs, focus mode, tool sidebar
9f51a18 - TUI, Gemini/Voyage embeddings, plugin management, ACP protocol
3c0703b - Config migration from JSON to TOML
eb130ad - Channel health monitor with auto-restart and rate limiting
2c3ea7e - Workspace bootstrap files (SOUL.md, IDENTITY.md) to system prompt
9df61bf - Model-aware failover routing, canvas SVG rendering
c7ba108 - WebSocket ping keepalive and auto-reconnect to web console

A API compatível com OpenAI é a que eu mais uso no dia a dia. Cursor, Continue, Open WebUI, qualquer coisa que fala o protocolo OpenAI consegue usar o FrankClaw como backend sem mexer em nada do lado do cliente.

Os números

Comparado ao OpenClaw:

Os números não são diretamente comparáveis. O OpenClaw tem 21 extensões de canal que eu cortei, uma UI web mais completa, e features de nicho que não portei. Mas o core (gateway, canais mainstream, providers, runtime, sessions, tools, memória) está lá com 22x menos código.

Como ajudar (beta testing)

O FrankClaw funciona pra conversa básica via Web e Telegram (testei ambos). WhatsApp funciona pra mensagens simples. Discord, Slack, Signal e Email estão implementados mas não tiveram teste extensivo. Não fizemos nenhum workflow complicado ainda.

Se você quer testar: clone o repositório, suba com Docker Compose, configure pelo menos um canal (Telegram é o mais fácil) e tente usar normalmente. Mande mensagens, teste tool calls, tente quebrar o sistema. Abra Issues no GitHub com o que encontrar.

O que eu sei que precisa de mais olhos: workflows com tools (browser, bash, MCP), subagent orchestration, failover entre providers, session persistence com criptografia, smart routing entre modelos, scheduled jobs, o sistema de memória/RAG, e a API OpenAI-compatible. Basicamente tudo que vai além de “manda mensagem, recebe resposta”.

Não precisa ser desenvolvedor Rust. O valor maior está em usar o sistema de formas que eu não pensei e encontrar os edge cases que só aparecem com uso real.

O FrankClaw não substitui o OpenClaw hoje. O OpenClaw tem mais canais, mais features, mais gente trabalhando nele. Mas carrega o peso de mais de um milhão de linhas de TypeScript geradas a 50 commits por dia por dezenas de contribuidores, com vulnerabilidades críticas documentadas. O FrankClaw é a alternativa pra quem olha pra isso e pensa “eu não vou rodar esse código na minha máquina”.

Mas vou ser honesto: apesar de ter sido divertido construir, eu pessoalmente não sei se preciso disso. O FrankClaw é um gateway genérico, feito pra ser flexível, conectar qualquer canal a qualquer provider, com runtime de agentes, tools, subagents, jobs, hooks. É muita infraestrutura.

O que eu descobri nos últimos meses é que eu consigo construir bots customizados pra tarefas específicas muito mais rápido. Em 1 dia eu tenho um bot funcionando, focado no que eu preciso, sem carregar o peso de um framework genérico. Foi o que eu fiz com o Marvin no projeto da newsletter, por exemplo. Um bot de Discord feito sob medida, que faz exatamente o que eu preciso e nada mais.

Um gateway genérico como o FrankClaw faz mais sentido pra quem quer uma interface unificada entre vários canais de chat e vários modelos de IA sem programar. Se esse é o seu caso, experimenta. Se você é desenvolvedor e sabe o que quer, talvez um bot customizado te sirva melhor. Fica a seu critério.

O repositório está aqui. AGPL-3.0.

Mas o terceiro projeto é de outra natureza. É um projeto de segurança. E a motivação vem de uma dor antiga.

O problema: emails demais

Como ex-YouTuber e criador de conteúdo, eu recebo uma quantidade absurda de emails. Convites pra eventos, propostas de collab, ofertas de patrocínio, pedidos de divulgação. Todo tipo de abordagem.

Eu deleto 100% deles. Não leio. A maioria eu marco como SPAM sem sequer abrir. A forma mais fácil de ser reportado é me mandar um email – eu não ligo, porque eu não preciso. Eu também não atendo telefone. Nunca. E bloqueio automaticamente qualquer pessoa que mande mensagem direto no meu WhatsApp, independente do conteúdo. Meu tempo é valioso demais pra eu ficar triando mensagem de desconhecido. Deleto tudo e sigo em frente.

Funciona pra mim. Mas eu sei que a maioria das pessoas não opera assim.

O veneno é a VAIDADE

A maioria das pessoas que cai em phishing por email não cai por ignorância técnica. Cai por VAIDADE.

“Olá, queremos te convidar pra nosso evento exclusivo.” “Sua marca foi selecionada para uma parceria especial.” “Parabéns, você foi indicado como referência no seu setor.”

A dopamina bate antes da razão ter chance de intervir. Alguém reconheceu seu trabalho, alguém quer te dar dinheiro. É exatamente aí que o golpista te pega.

Não é o CEO de multinacional que cai no golpe do príncipe nigeriano. É o microinfluencer que recebe uma proposta de patrocínio “boa demais pra ser verdade”. É o pequeno empresário que recebe um convite pra um evento que parece legítimo. A vaidade desliga o senso crítico.

E os golpes estão cada vez mais sofisticados. Com LLMs, qualquer criminoso gera emails perfeitos em português, sem erros gramaticais, com formatação profissional, com domínios que imitam empresas reais. O velho “olha os erros de português” já não serve mais como filtro.

A ideia: Frank FBI

Em vez de tentar ensinar todo mundo a identificar phishing (o que não funciona, porque a vaidade é mais forte que o treinamento), por que não criar uma ferramenta que faça isso automaticamente?

Recebeu um email suspeito? Encaminha pra um endereço dedicado. Em poucos minutos, recebe de volta um relatório detalhado com tudo que a ferramenta conseguiu descobrir sobre aquele email.

Assim nasceu o Frank FBI – Fraud Bureau of Investigation.

Como funciona

Você configura uma conta Gmail dedicada (pode ser qualquer Gmail com App Password). Cadastra os emails autorizados a usar o serviço. A partir daí, o fluxo é:

1. Recebe email suspeito na sua caixa pessoal
2. Encaminha pro endereço do Frank FBI
3. O sistema analisa automaticamente
4. Recebe a resposta na mesma thread, com o relatório completo

Pra dar uma ideia do resultado, aqui está um relatório de um email legítimo (cold outreach de uma empresa real):

E aqui um email suspeito, onde o domínio do remetente tenta se passar por outra empresa:

O Frank FBI roda 6 camadas de análise, cada uma com peso específico na pontuação final:

Camada 1 – Autenticação de headers (peso 15%)

SPF, DKIM, DMARC. O Reply-To bate com o From? Tem headers antispam suspeitos? Essa camada responde a pergunta mais básica: o email realmente veio de quem diz que veio?

Camada 2 – Reputação do remetente (peso 15%)

Consulta a idade do domínio via WHOIS (domínio registrado semana passada já é um sinal), verifica se o IP está em listas negras de DNS (DNSBL), e mantém um banco de reputação local que melhora conforme mais emails são analisados. Se o remetente finge ser uma empresa mas manda de um Gmail, isso pesa.

Camada 3 – Análise de conteúdo (peso 15%)

Aqui entra o pattern matching: urgência artificial (“sua conta será bloqueada em 24h”), pedidos de dados pessoais, impersonação de autoridade, ofertas financeiras. Também detecta URL shorteners e links onde o texto exibido não bate com o href real – aquele clássico “clique aqui” que aponta pra um domínio completamente diferente. Verifica anexos perigosos (.exe, .scr, macros em Office).

Camada 4 – APIs externas (peso 15%)

O URLhaus (abuse.ch) mantém um banco de URLs maliciosas conhecido. O VirusTotal agrega resultados de dezenas de antivírus. Se alguma URL do email já foi flagada como malware ou phishing por essas bases, o score sobe. Resultados ficam em cache com TTL pra não estourar os rate limits das APIs gratuitas.

Camada 5 – Verificação de entidade (peso 10%)

Essa camada eu acho a mais interessante. O Frank FBI faz OSINT – Open Source Intelligence. Usa o Brave Search pra verificar se o remetente ou empresa realmente existe. Faz WHOIS do domínio diretamente. Captura screenshot do site com Chrome headless. Cruza tudo pra tentar responder: “essa entidade é real e é quem diz ser?”

Olha um exemplo real dessa camada em ação, analisando um email que tentava se passar por uma empresa legítima:

O domínio tinha 83 dias de vida, registrado via Namecheap, sem presença online verificável. O sistema encontrou divergências entre o nome no email e os registros públicos, e identificou que o domínio legítimo da empresa real era outro.

Camada 6 – Análise por LLM (peso 30%)

Consulta 3 modelos de IA em paralelo: Claude Sonnet (Anthropic), GPT-4o (OpenAI) e Grok 4 (xAI), via OpenRouter. Cada modelo analisa o email de forma independente. Um sistema de consenso com peso por confiança combina os resultados. Se os 3 concordam que é fraude, a confiança é alta. Se divergem, o sistema pondera. Se todos os LLMs falharem, cai pra um score neutro de 50 em vez de adivinhar – melhor admitir ignorância do que alucinar.

A pontuação final é uma média ponderada com ajuste de confiança. Vereditos possíveis: Legítimo (0-25), Suspeito OK (26-50), Suspeito Fraude (51-75) ou Fraudulento (76-100). Existe ainda uma política de escalação de risco que impõe pisos mínimos: se indicadores críticos foram detectados (URLs maliciosas confirmadas, DKIM falhou), o score não pode ficar abaixo de certos limiares, mesmo que outras camadas não tenham achado nada.

Self-hosted: seus dados ficam com você

O Frank FBI é self-hosted. Você roda no seu próprio servidor. Seus emails não passam por nenhum serviço de terceiro (exceto as APIs de verificação como VirusTotal, que recebem apenas URLs, não o conteúdo do email).

Dá pra instalar no seu home server, como eu fiz, ou dentro da infraestrutura da sua empresa pra que seus funcionários usem. O deploy é via Docker Compose com 4 containers: aplicação Rails, worker de jobs em background, poller IMAP, e um setup inicial de banco. Sobe tudo com um docker compose up -d e está funcionando.

Reportando fraudes pra comunidade

Além de analisar emails pra você, o Frank FBI pode opcionalmente reportar fraudes confirmadas pra bancos de dados comunitários. Isso só acontece quando o score é >= 85 e o veredito é “fraudulento”. É opt-in.

O ThreatFox (abuse.ch) é um banco de dados aberto de indicadores de comprometimento (IOCs) mantido pela comunidade de segurança. Quando você reporta uma URL ou domínio malicioso lá, firewalls, filtros de email e SIEMs ao redor do mundo podem consumir essa informação pra bloquear a ameaça.

O AbuseIPDB é a mesma ideia, mas pra IPs. Se o IP do remetente do email fraudulento é reportado aqui, provedores de email e administradores de rede podem bloquear tráfego malicioso antes que chegue aos usuários.

E o SpamCop é um dos serviços mais antigos de reporting de spam. O Frank FBI encaminha o email completo pro SpamCop, que analisa os headers e reporta pros provedores responsáveis. É denunciar direto pra quem pode agir.

Cada report é uma contribuição pra que outras pessoas não caiam no mesmo golpe. E é automatizado: se o email é claramente fraudulento, o report sai sem intervenção manual.

Mas reportar coisas erradas causa dano. Por isso o sistema tem proteções anti-envenenamento: uma lista de ~40 domínios conhecidos (Microsoft, Apple, Google, Amazon, PayPal, governos) que nunca são reportados; domínios com scan limpo são excluídos; IPs de infraestrutura de cloud (Google, Microsoft, Cloudflare) são filtrados; domínios de email gratuito são ignorados. Só IOCs genuinamente maliciosos chegam aos bancos comunitários.

Deploy: como colocar pra rodar

Vou explicar como eu fiz o deploy no meu home server. Se você tem um VPS, NAS ou qualquer máquina Linux com Docker, o processo é o mesmo.

1. Clonar e buildar a imagem

Você precisa de um registry privado pra guardar a imagem Docker. Eu uso Gitea no meu home server – é um GitHub self-hosted leve que inclui container registry. Se você já tem um GitHub privado, pode usar o GitHub Container Registry (ghcr.io) em vez disso.

# Clonar o repositório
git clone https://github.com/akitaonrails/frank_fbi.git
cd frank_fbi

# Buildar a imagem Docker
# Se usa Gitea (troque pelo IP/porta do seu registry):
docker build -t seu-servidor:3007/frank_fbi:latest .
docker push seu-servidor:3007/frank_fbi:latest

# Se usa GitHub Container Registry:
docker build -t ghcr.io/seu-usuario/frank_fbi:latest .
docker push ghcr.io/seu-usuario/frank_fbi:latest

2. Configurar o .env

Copie o .env.example e preencha. As variáveis obrigatórias:

# Gere com: ruby -rsecurerandom -e 'puts SecureRandom.hex(64)'
SECRET_KEY_BASE=

# Gere com: bin/rails db:encryption:init (roda local, copia os 3 valores)
ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=

# Gmail dedicado pro Frank FBI (crie uma conta só pra isso)
# Ative 2FA e gere um App Password em https://myaccount.google.com/apppasswords
GMAIL_USERNAME=seu-frank-fbi@gmail.com
GMAIL_PASSWORD=xxxx-xxxx-xxxx-xxxx
GMAIL_IMAP_HOST=imap.gmail.com
GMAIL_SMTP_HOST=smtp.gmail.com

# Senha do ingress do Action Mailbox (qualquer string aleatória)
RAILS_INBOUND_EMAIL_PASSWORD=uma-senha-qualquer-longa

# LLM via OpenRouter (obrigatório pra Camada 6)
OPENROUTER_API_KEY=sua-chave-openrouter

# Seu email de admin (pra gerenciar remetentes autorizados)
ADMIN_EMAIL=seu-email@pessoal.com

As APIs externas são opcionais mas recomendadas. Sem elas, as camadas correspondentes simplesmente não rodam:

# VirusTotal (grátis, 4 requests/min) - https://virustotal.com
VIRUSTOTAL_API_KEY=

# WhoisXML (grátis, 500 requests/mês) - https://whoisxmlapi.com
WHOISXML_API_KEY=

# Brave Search (grátis, 1 req/s) - https://brave.com/search/api/
BRAVE_SEARCH_API_KEY=

E o community reporting, que é totalmente opt-in. Deixe em branco se não quiser reportar:

THREATFOX_AUTH_KEY=
ABUSEIPDB_API_KEY=
SPAMCOP_SUBMISSION_ADDRESS=

3. Docker Compose no servidor

Crie o docker-compose.yml no seu servidor. Troque a imagem pelo seu registry:

services:
  setup:
    image: seu-servidor:3007/frank_fbi:latest  # ou ghcr.io/seu-usuario/frank_fbi:latest
    command: ["./bin/rails", "db:prepare"]
    env_file: .env
    environment:
      - RAILS_ENV=production
    volumes:
      - ./storage:/rails/storage

  app:
    image: seu-servidor:3007/frank_fbi:latest
    env_file: .env
    environment:
      - RAILS_ENV=production
    volumes:
      - ./storage:/rails/storage
      - ./emails:/rails/emails
    depends_on:
      setup:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/up"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 15s
    restart: unless-stopped

  worker:
    image: seu-servidor:3007/frank_fbi:latest
    command: ["./bin/jobs"]
    env_file: .env
    environment:
      - RAILS_ENV=production
    volumes:
      - ./storage:/rails/storage
    depends_on:
      setup:
        condition: service_completed_successfully
    restart: unless-stopped

  mail_fetcher:
    image: seu-servidor:3007/frank_fbi:latest
    command: ["./bin/rails", "frank_fbi:fetch_mail"]
    env_file: .env
    environment:
      - RAILS_ENV=production
      - APP_HOST=http://app:3000
    volumes:
      - ./storage:/rails/storage
    depends_on:
      app:
        condition: service_healthy
    restart: unless-stopped

4. Subir e cadastrar o primeiro usuário

docker compose up -d

O setup roda as migrations e sai. O app sobe o Rails, o worker processa os jobs em background, e o mail_fetcher fica fazendo polling IMAP a cada 30 segundos.

Pra cadastrar remetentes autorizados, mande um email do seu ADMIN_EMAIL pro endereço do Frank FBI com o assunto add email1@exemplo.com, email2@exemplo.com. Pra listar quem está cadastrado, mande com assunto list. Pra ver estatísticas, stats.

A partir daí, qualquer remetente cadastrado pode encaminhar emails suspeitos e receber os relatórios de análise.

O processo de desenvolvimento

Esse projeto começou como uma ideia simples: “e se eu pudesse encaminhar emails suspeitos pra algum lugar e receber uma análise?”. Mas projetos de segurança não são como projetos normais.

Num projeto comum, um bug é inconveniente. Num projeto de segurança, um bug pode ser uma vulnerabilidade. Se o sistema diz que um email fraudulento é legítimo, alguém pode perder dinheiro. Se reporta incorretamente um domínio legítimo como malicioso, pode prejudicar uma empresa inocente. Se um email malicioso consegue explorar o próprio analisador, o atacante ganha acesso ao servidor.

Isso muda o mindset de desenvolvimento. Cada decisão precisa considerar: “como alguém mal-intencionado poderia abusar disso?”

Evolução via commits

Deixa eu mostrar como o projeto evoluiu olhando os commits mais relevantes.

O projeto começou com a estrutura básica de análise de email e logo precisou de controle de acesso:

eb59474 - Add admin access control and allowed senders whitelist
036e9f1 - Harden access control against email spoofing and admin impersonation

O primeiro adiciona a lista de remetentes autorizados. O segundo resolve o problema óbvio: e se alguém spoofar o email de um remetente autorizado? O sistema passou a verificar SPF/DKIM antes de aceitar qualquer submissão. Rate limiting por remetente veio junto, pra evitar abuso.

Depois vieram as preocupações com a qualidade do scoring:

e891270 - Fix zero-dilution scoring bug and add critical alert UX
2cbb272 - Harden fraud scoring and reporting
50d96a1 - Move text pattern detection from regex to LLM consensus layer

O bug de zero-dilution é sutil: quando uma camada falha e retorna score 0 com confiança baixa, ela diluía a média geral pra baixo, fazendo emails fraudulentos parecerem mais seguros do que eram. A correção implementou dampening que descarta camadas de baixa qualidade em vez de deixá-las puxar o score pra baixo.

A mudança de regex pra LLM no pattern detection foi pragmática. Padrões de fraude em linguagem natural são difíceis de capturar com regex. Falsos positivos demais. LLMs entendem contexto e intenção de um jeito que regex não consegue.

As race conditions apareceram quando o pipeline começou a rodar camadas em paralelo:

2e4276d - Fix race conditions across pipeline and add Brave Search rate limiting
ac433d9 - Fix WHOIS race condition and Brave Search gzip error logging

Jobs concorrentes tentando escrever no mesmo registro de email, consultas WHOIS pisando uma na outra, rate limits de APIs externas sendo estourados. O clássico “funciona no teste sequencial, quebra em produção”.

A prevenção de alucinação dos LLMs mereceu um commit dedicado:

e08da9e - Prevent LLM hallucination in fraud reports

LLMs inventam coisas. Se o modelo diz “este domínio foi registrado ontem” sem evidência nos dados, o relatório fica comprometido. Esse commit implementou validação cruzada: claims dos LLMs são verificados contra os dados concretos das camadas determinísticas. Se o LLM afirma algo que contradiz os fatos, a informação é descartada ou sinalizada.

E quando o community reporting foi implementado:

a01d769 - Add community threat intelligence reporting
1b64eee - Harden community reporting against poisoning and add rate limiting

O primeiro commit implementa a funcionalidade. O segundo adiciona as proteções anti-envenenamento. Se um atacante percebe que o Frank FBI reporta automaticamente, ele pode tentar enviar emails que contenham IOCs de empresas legítimas como “fraude”, fazendo o sistema reportar domínios inocentes pras bases comunitárias. Isso é IOC poisoning, e é um ataque real contra sistemas de threat intelligence.

Hardening contínuo

9430c63 - Harden risky attachment analysis and warnings
bdc503d - Harden screenshot capture with failure recovery and pipeline timeout
125e73a - Separate suspect content from submitter signature in forwarded emails
6f7a522 - Handle forwarded message fidelity

Anexos maliciosos que poderiam explorar o parser. Screenshots de sites que poderiam travar o Chrome headless. Assinaturas do remetente que estavam sendo confundidas com conteúdo do email suspeito. Emails encaminhados que perdiam fidelidade no forward. Cada um desses resolve um vetor de ataque ou edge case diferente.

Segurança não é uma feature que você implementa uma vez. É um processo contínuo de “o que eu não pensei que poderia dar errado?”

Os números

860 linhas por hora. Obviamente desenvolvimento assistido por IA. Mas olha os commits de hardening: nenhum deles veio do LLM sugerindo “ei, vamos proteger contra spoofing”. Fui eu que parei e pensei “espera, e se alguém spoofar o remetente autorizado?”, “e se um atacante usar IOC poisoning contra o meu sistema de reporting?”. Esse tipo de pergunta o LLM não faz sozinho. Ele implementa quando você pede, mas quem precisa perceber o buraco é você.

Um aviso sério: NÃO ofereça isso como serviço

Se você olhou pro Frank FBI e pensou “legal, vou oferecer isso como SaaS pra outras pessoas”, eu tenho um conselho: NÃO faça isso.

Eu consigo pensar em várias formas de explorar um serviço desses oferecido ao público. O operador teria acesso a todos os emails encaminhados pelos usuários – informações pessoais, dados corporativos, correspondência sensível. Um serviço centralizado vira um alvo de alto valor: comprometa o servidor e você tem acesso a um fluxo contínuo de emails confidenciais de pessoas que já estão em situação vulnerável.

Eu conheço gente o suficiente pra saber que quem deployaria isso como serviço não ia se preocupar com criptografia em repouso nem com destruir os emails após análise. E quem garante que o operador não vai ler os emails dos usuários? Ninguém. É o tipo de coisa que parece um serviço útil mas na prática cria um honeypot de dados sensíveis gerenciado por alguém sem incentivo pra protegê-los.

O Frank FBI foi feito pra ser self-hosted. Pra rodar no seu servidor, sob seu controle, com seus dados ficando com você. Ou na infraestrutura da sua empresa, gerenciado pela sua equipe de TI.

E o projeto está licenciado sob AGPL-3.0. Se você usar meu código e oferecer como serviço de rede, você é obrigado por lei a abrir todo o código derivado. Sem exceções. Eu escolhi AGPL por esse motivo – pra garantir que ninguém pegue o projeto, adicione tracking e telemetria, e ofereça como “serviço gratuito de verificação de email” enquanto coleta dados de usuários por baixo dos panos.

O repositório está aqui. AGPL-3.0.

–

Eu tenho uma coleção enorme de mangás comprados na Amazon.co.jp que leio pelo Kindle web. Mangás shounen normalmente têm furigana — aquele texto pequeno em hiragana ao lado dos kanjis — que me ajudam a ler, porque, apesar de ter estudado japonês, nunca fui treinado formalmente. Mas mangás para público adulto (seinen, não pornô) geralmente vêm sem furigana. São kanjis puros e minha leitura deles fica muito lenta.

Faz anos que quero uma ferramenta que resolva isso. A ideia é simples: detectar os balões de fala numa página de mangá, extrair o texto com OCR, e ou adicionar furigana nos kanjis, ou traduzir direto pro inglês e renderizar de volta no balão. Parece fácil, certo?

*(kanji sem legenda/furigana)

*(com furigana injetado em tempo real)

Pois é, parecia. E por saber que parecia fácil, mas que não seria, eu nunca tive paciência pra fazer. Eu sei fazer os 80% iniciais de qualquer projeto. O problema são os 20% finais — aquela fase de experimentação, tweaking, ajuste fino, tratar edge cases — que consomem mais tempo que todo o resto junto. E num projeto de visão computacional, esses 20% são especialmente traiçoeiros.

Mas aí chegou a era do vibe coding. E eu pensei: talvez agora os 20% sejam viáveis. Iniciei o projeto no dia 24 de fevereiro de 2026, às 23:10 da noite. E este se tornou um exemplo de como é muito fácil fazer grandes volumes de código inútil.

A Ideia Original: OpenCV e Heurísticas

Meu plano original - o conceito que imaginei por anos - era: usar OpenCV - que é uma biblioteca famosa e antiga de visão de computador - pra detectar os balões de fala. Balões de mangá são tipicamente áreas brancas com contorno preto dentro de painéis. Em teoria, basta fazer threshold da imagem pra pegar regiões brancas, encontrar contornos, filtrar por tamanho e formato, e pronto.

Em 24 horas eu já tinha uma prova de conceito funcional: detecção de balões, OCR com manga-ocr (modelo treinado especificamente em texto japonês de mangá), furigana com MeCab pra análise morfológica, tradução com Ollama rodando Qwen3:14b local, e renderização do texto de volta no balão. O commit inicial (9169d73) do dia 24/fev já fazia tudo isso.

No dia seguinte, 25 de fevereiro, eu já estava estendendo o pipeline com pipeline de tradução de webtoons coreanos. 27 commits nesse dia. Tudo parecia estar fluindo.

E aí começou o inferno.

O Inferno dos Falsos Positivos

O problema com detecção de balões via OpenCV é que o manga não é um documento padronizado. Cada artista tem traço próprio, a qualidade de scan varia enormemente entre eras de impressão, e páginas coloridas precisam de parâmetros completamente diferentes de páginas P&B. E a coisa que mais se parece com um balão de fala branco numa página de mangá é… um rosto.

Rostos de personagens são áreas claras, relativamente arredondadas, com contorno escuro. Exatamente como balões de fala. E não importa quantos filtros você empilhe, sempre aparece um caso onde o rosto de um personagem com cabelo azul passa por todos os seus filtros, ou onde um balão legítimo é rejeitado porque tem formato incomum.

Olha como ficou meu detector de balões no pico da complexidade — 551 linhas com 7 camadas de filtros de falso-positivo (versão resumida):

# --- False positive filters ---

# 1. Edge density
edge_pixels = cv2.countNonZero(cv2.bitwise_and(edges, edges, mask=mask))
edge_density = edge_pixels / area
if edge_density > max_edge_density:
    continue

# 2. Bright pixel ratio
bright_pixels = cv2.countNonZero(cv2.bitwise_and(bright_thresh, mask))
bright_ratio = bright_pixels / area
if bright_ratio < min_bright_ratio:
    continue

# 3. Mid-tone ratio
mid_mask = cv2.inRange(gray, 80, 220)
mid_pixels = cv2.countNonZero(cv2.bitwise_and(mid_mask, mask))
mid_ratio = mid_pixels / area
if mid_ratio > max_mid_ratio:
    continue

# 4. Contour circularity
circularity = 4 * np.pi * area / (perimeter * perimeter)
if circularity < 0.10:
    continue

# 5. Border darkness
border_mean = cv2.mean(gray, mask=border_only)[0]
if border_mean > 160:
    continue

# 6. Background uniformity (white_std)
white_pixels = gray[(mask > 0) & (gray > 200)]
if float(np.std(white_pixels)) > 15:
    continue

# 7. Dark content analysis (text strokes)
very_dark = np.sum((inner_mask > 0) & (gray < 60))
dark_ratio_60 = very_dark / inner_area
if dark_ratio_60 < min_dark_ratio:
    continue

Cada um desses filtros foi adicionado em resposta a um falso-positivo específico. Edge density separava balões (que têm traços esparsos de texto) de rostos (que têm cabelo, olhos, nariz criando bordas densas). Bright pixel ratio verificava se a região era realmente branca. Circularity descartava formas muito irregulares. E por aí vai.

Mas o pior é que esses filtros interagiam entre si de formas imprevisíveis. Olha esse commit do dia 26/fev (70c814a):

“Revert rect_dark, mid_ratio, and early-split changes that caused face FPs”

Eu tinha tentado relaxar dois thresholds — rect_dark de 0.10 pra 0.11, mid_ratio de 0.15 pra 0.16 — pra recuperar balões que estavam sendo perdidos. Resultado: rostos e regiões de corpo começaram a passar como falsos positivos em mangá do Adachi. Tive que reverter tudo.

Esse é o padrão que se repetiu durante dias: recuperar um balão perdido significava abrir porta pra falsos-positivos. Corrigir um falso-positivo significava perder um balão legítimo. Era um whack-a-mole infinito.

Os Paliativos: CLAHE, Detecção por Borda, Watershed

Quando os 7 filtros básicos não foram suficientes, comecei a empilhar passes adicionais.

Commit 294e785 (26/fev): adicionei CLAHE (Contrast Limited Adaptive Histogram Equalization) como segundo passe de detecção. Balões com brilho médio, perto do threshold de 200, estavam sendo perdidos. O CLAHE equalizava o contraste e revelava esses balões borderline.

Mas o CLAHE também fazia rostos passarem pelos filtros porque inflava artificialmente o brilho de pele. Então precisei adicionar uma função inteira de validação contra a imagem original:

def _validate_on_original(candidate, gray_orig):
    """Check if a CLAHE-detected candidate looks bubble-like on original."""
    roi = gray_orig[y1:y2, x1:x2]
    mean_brightness = roi.mean()

    # Already bright enough for pass 1 — rejected for good reason
    if mean_brightness > 215:
        return False

    # Must have text strokes (dark pixels)
    dark_ratio = np.sum(roi < 60) / roi.size
    if dark_ratio < 0.07:
        return False

    # White pixel variance: text creates high std, face skin is uniform
    white_pixels = roi[roi > 200]
    if len(white_pixels) > 50:
        if float(np.std(white_pixels)) < 9:
            return False

    return True

Commit 5dddb31 (1/mar): adicionei um terceiro passe inteiro de detecção baseado em bordas (edge-based segmentation). Pra pegar balões onde o interior branco se fundia com o fundo branco da página. Dilatava as bordas Canny, invertia, fazia AND com regiões brilhantes, e procurava contornos no resultado.

Commit b695295 (26/fev): adicionei recuperação de balões pequenos via gradiente morfológico + validação por OCR. Se o OCR confirmava que tinha texto japonês válido na região, provavelmente era um balão real.

Cada paliativo adicionava 50-100 linhas de código e mais uma camada de complexidade. E cada um tinha seus próprios edge cases e falsos-positivos.

A Conta Final da v0.1

No dia 1 de março, marquei a tag v0.1. Nesse ponto eu tinha:

• 90 commits em 6 dias de desenvolvimento (24/fev a 1/mar)
• 551 linhas só no bubble_detector.py
• 7 camadas de filtro de falso-positivo, cada uma com thresholds empíricos
• Dois passes de detecção completos (original + CLAHE)
• Um terceiro passe baseado em bordas
• Validação cruzada contra imagem original
• Separação de watershed pra balões sobrepostos
• Perfis separados de threshold pra páginas coloridas vs preto-e-branco
• 20+ magic numbers ajustados empiricamente contra uma amostra limitada de páginas
• Testes de regressão travando cada falso-positivo específico (face de menina com cabelo azul, moldura de janela, tira fina horizontal, chão de concreto…)

E mesmo com tudo isso, ainda não era confiável. Cada novo mangá que eu testava revelava algum pequeno caso que quebrava o detector. Era um monolito extremamente frágil.

SINTOMA: você faz correção pra corrigir a correção que corrigia outra correção, e quando mexe num pedaço, quebra outro sem querer: significa que o código é brittle, frágil, uma casa de cartas que vai cair a qualquer momento. Esse é o ponto pra desistir e repensar!

A Decisão: Pesquisar Alternativas

Na v0.1 eu parei e fiz a pergunta que deveria ter feito no começo: será que já existe alguém que treinou um modelo de ML pra fazer exatamente isso?

Pedi pro Claude pesquisar modelos disponíveis de detecção de balões em quadrinhos. A pesquisa resultou no documento docs/yolo_bubble_detection_plan.md, onde analisamos as alternativas.

A primeira que apareceu foi um YOLOv8 Medium do ogkalu (comic-speech-bubble-detector-yolov8m), treinado em ~8.000 imagens de manga, webtoon, manhua e quadrinhos ocidentais. Detecta só uma classe (speech bubble). Mas pesquisando mais, achamos outro modelo do mesmo autor: ogkalu/comic-text-and-bubble-detector, um RT-DETR-v2 com backbone ResNet-50-vd (42.9M parâmetros), treinado em ~11.000 imagens, com três classes: bubble, text_bubble e text_free. Ambos Apache 2.0.

Também avaliamos o comic-text-detector (DBNet + YOLOv5, ~13.000 imagens do Manga109), mas esse detectava regiões de texto e não balões. E como dados de treinamento futuro, havia o Roboflow com 4.492 imagens já etiquetadas, e o Manga109 dataset com 147.918 anotações em 21.142 páginas.

O RT-DETR-v2 com 3 classes era o mais promissor porque distinguia balões de fala, texto dentro de balões e texto livre (narração, SFX). Poderia substituir tanto o bubble_detector.py quanto o text_detector.py em uma única passada de inferência.

A conclusão do documento de pesquisa era direta:

“Mesmo sem ajustes finos, esses modelos foram treinados com 8 a 11 mil imagens de diversos quadrinhos. Eles devem lidar com a diversidade de estilos artísticos que nossos filtros manuais têm dificuldade em processar. A cascata heurística de 7 filtros e seus números mágicos seriam completamente eliminados.”

E se não fosse suficiente, incluímos um plano de fine-tuning usando dados pareados (páginas originais em japonês vs fan translations em inglês) que geravam labels automaticamente por diff de imagem. Mas primeiro queríamos testar o baseline.

Trocando Tudo: RT-DETR-v2

No dia 4 de março, fiz o commit 0df63f2: “Replace OpenCV heuristic detection with RT-DETR-v2, add bubble shape masking”.

O diff fala por si:

16 files changed, 732 insertions(+), 1112 deletions(-)

1.112 linhas deletadas. Mais linhas removidas do que adicionadas. O detector de balões de 551 linhas foi substituído por 262 linhas — e dessas, a maior parte é extração de máscara de formato (contour mask) a partir do bbox detectado, não detecção em si.

O núcleo da detecção virou isso:

MODEL_ID = "ogkalu/comic-text-and-bubble-detector"
DEFAULT_CONFIDENCE = 0.35

def detect_bubbles(img_cv, confidence=DEFAULT_CONFIDENCE):
    model, processor, device = _get_model()
    img_pil = Image.fromarray(img_cv[:, :, ::-1])  # BGR→RGB
    inputs = processor(images=img_pil, return_tensors="pt").to(device)

    with torch.no_grad():
        outputs = model(**inputs)

    results = processor.post_process_object_detection(
        outputs, target_sizes=target_sizes, threshold=confidence
    )
    # ... map classes, deduplicate, sort

Sem thresholds mágicos. Sem perfis separados pra cor vs P&B. Sem CLAHE. Sem detecção por borda. Sem watershed. Sem 7 camadas de filtro. Um modelo que foi treinado em 11.000 imagens diversas de quadrinhos já sabe distinguir balão de rosto melhor do que meus montes de “ifs”.

O que também sumiu junto:

• O text_detector.py inteiro (387 linhas) — substituído pela classe text_free do RT-DETR
• O sistema de feedback de falsos-positivos — RT-DETR detections são confiáveis o suficiente pra não precisar de marcação manual
• Centenas de linhas de testes de regressão testando false-positives específicos

No final, nem precisei tentar fazer fine tuning próprio. O modelo que já existe resolvia mais de 99% dos casos, o que pra mim já era excelente.

Quem não entende estatística tem dificuldade de entender isso. Com meu procedimento “manual” de opencv eu já conseguia pegar 80%, talvez mais. Mas isso é muito pouco. Se em toda página um rosto fica com um balão em cima, isso é péssimo.

Mesmo se com muito esforço (mais quinhentos “ifs” diferentes) conseguisse chegar em 95%, ainda assim não é suficiente. Chegar em 80% é fácil. os últimos 20% custam exponencialmente mais, e o último 1% pode ser impossível em muitos casos. É assim que as coisas funcionam. Todo mundo pára nos 80%.

As Outras Dores: Flutter no Linux

Enquanto o backend em Python e Go foi relativamente estável, o cliente Flutter no Linux foi um capítulo à parte de sofrimento.

O Flutter usa WebKitGTK pro WebView no Linux, e esse componente tem particularidades dolorosas. Commit 8e5d168 (28/fev) conta a história: WebKitGTK não consegue resolver Promise return values de JavaScript assíncrono, gerando PlatformException. Tive que reescrever todos os overlays como IIFEs síncronas com decode().then() e um nudge de opacity: 0.999 pra forçar refresh da textura no compositor GPU.

No meu setup com NVIDIA + Wayland, o WebView era inutilizável em resolução full. Commit a36e1eb (27/fev) tentou resolver forçando CPU rendering com WEBKIT_SKIA_ENABLE_CPU_RENDERING=1 e desabilitando compositing acelerado. Depois tive que reverter isso (commit 8e5d168) e forçar o Mesa da iGPU AMD via __EGL_VENDOR_LIBRARY_FILENAMES pra impedir que o WebKitGTK pegasse a dGPU NVIDIA.

Cada uma dessas descobertas custou horas de debugging de coisas que simplesmente não tinham documentação. No final consegui deixar a versão Linux razoável, mas não é nada espetacular. Não sei se estou perdendo alguma coisa óbvia, mas Flutter no Linux eu achei uma droga, especialmente tendo acabado de fazer um app nativo com Rust/Tauri (muito melhor). Mas como eu queria um app que funcionasse em Linux e Android, não tinha tanta opção.

O Prefetch do Kindle que Morreu

Uma ideia que parecia genial e que deu errado: criar um segundo WebView escondido no Flutter que compartilhava cookies/sessão com o WebView principal e ficava navegando páginas à frente pra pré-processar.

Isso porque o website do Kindle só carrega uma página de cada vez. Ele não carrega tudo de uma vez ou partes, só uma página. Então não dá pra processar páginas pra frente ou pra trás. Quando o servidor ainda era lento pra processar páginas, eu queria deixar tudo já pré-cacheado, pra quem virar a página já tivesse a tradução.

Commit a36e1eb (27/fev) implementou o KindlePrefetchManager inteiro: 406 linhas de Dart, com batched prefetch (3 páginas à frente), eventos GDK confiáveis pra virar página (isTrusted=true), rate limiting com pacing humano, janela com sensitive=FALSE pra não roubar foco.

Nos dias seguintes, vieram os consertos:

• cfe08eb: melhorar confiabilidade do prefetch e matching de overlay
• 4461b5f: harden na seleção de overlay e recovery do Kindle
• f141b2e: parar de destruir o background webview a cada virada de página

E no final (commit 2b93e99, 4/mar), deletei tudo. 657 linhas removidas, substituídas por um spinner simples na toolbar.

Com a mudança pro modelo RT-DETR, e paralelizando a tradução dos balões, a tradução ficou “quase real-time”, em menos de 10 segundos já carregava a tradução, então não é mais um dor tão grande esperar vir a página, e dá pra pedir um de cada vez. O prefetch adicionava complexidade demais pra um ganho marginal, e o modo certo de resolver era simplesmente processar a página sob demanda com feedback visual adequado.

Os Números

No total, o projeto Frank Yomik tem hoje:

• 111 commits em 9 dias de desenvolvimento (com 2 dias de intervalo no meio)
• 29.428 linhas de código em 181 arquivos
• ~13K linhas de Python (pipeline de processamento + worker)
• ~6K linhas de Dart (cliente Flutter)
• ~3.4K linhas de Go (API server)
• 345 testes unitários + 34 testes de integração
• Suporte a manga japonês (Kindle) e webtoons coreanos (Naver/Webtoons)

O pipeline hoje funciona assim:

1. O cliente Flutter (Android ou Linux desktop) abre o site do Kindle ou Webtoons num WebView
2. Captura a imagem da página (captura do blob de imagem na página do Kindle, fetch do <img> pra webtoons)
3. Envia pra API Go que enfileira no Redis Streams com dedup por SHA256
4. Worker Python processa: RT-DETR-v2 detecta balões → manga-ocr ou EasyOCR extrai texto → Ollama qwen3:14b traduz → text_renderer renderiza de volta na imagem
5. Resultado volta via WebSocket, overlay substitui a imagem original

Pra furigana: fugashi (wrapper do MeCab) faz análise morfológica e gera a leitura em hiragana de cada kanji. Troquei de pykakasi pro fugashi porque o pykakasi não considera contexto da frase (「人」 virava にん em vez de ひと).

Se eu soubesse o que sei agora — que o modelo RT-DETR-v2 já existia e resolvia o problema de detecção com um threshold de confiança — teria eliminado a fase inteira de OpenCV. A parte de OCR, tradução, rendering e Flutter já estava razoavelmente estabilizada. A detecção era o gargalo, e era exatamente a parte que eu poderia ter economizado, se tivesse desistido antes.

O que eu aprendi errando

Eu gastei 5 dias polindo um detector de balões em OpenCV que teve 20+ commits de ajuste fino, 7 camadas de filtro, 3 passes de detecção, e que no final foi substituído por um wrapper de 50 linhas ao redor de um modelo pré-treinado.

Foram 1.112 linhas deletadas num único commit. Mas não foi tempo perdido. Aqueles 5 dias me ensinaram exatamente porque heurísticas falham em visão computacional. Eu entendi o problema, a cascata onde mexer num threshold quebra outro, e foi esse entendimento que me fez reconhecer a hora de parar e pesquisar alternativas.

E aqui entra o papel real do vibe coding nessa história.

Prompting não substitui pensar.

Eu gerei código muito rápido com Claude, mas o problema não era velocidade de escrita, era a abordagem. Nenhum prompt do mundo transforma 7 camadas de filtro heurístico numa solução robusta. A solução certa era mudar de abordagem completamente.

Mas o vibe coding tornou o fracasso barato. Nos tempos pré-AI, aqueles 5 dias de OpenCV teriam talvez sido 2-3 semanas. O custo de errar seria alto o suficiente pra dificultar a decisão de jogar fora. Com vibe coding, 5 dias foram descartados sem dor porque eu sabia que podia reconstruir rápido. E de fato, a integração do RT-DETR-v2 e reestruturação do projeto inteiro foram feitos em um único dia (4/mar, 15 commits).

A pergunta que fica: se eu tivesse feito a pesquisa do yolo_bubble_detection_plan.md no dia 1 em vez do dia 5, provavelmente teria chegado no estado atual em 2 dias. A diferença entre semanas de trabalho e um fim de semana era uma busca no HuggingFace. Pesquisar antes de implementar parece óbvio quando você olha pra trás, mas no calor do momento a tentação de resolver na mão é forte.

O projeto agora é open source. Eu inicialmente não sabia se queria abrir o código, tinha muita gambiarra e aquele detector de 551 linhas que eu tinha vergonha. Mas depois da refatoração, o código ficou limpo o suficiente pra compartilhar. É a versão que eu gostaria de ter construído desde o início, mas que só consegui construir porque errei primeiro.

A dor de cabeça maior foi o modelo de detecção e substituição de balões, mas ainda tem vários outros pontos que não detalhei: notaram que Webtoons são coloridos e os próprios balões tem arte? Precisei usar um modelo de imagem pra fazer in-painting e mandar a IA redesenhar o balão antes de colocar o texto em cima.

Outra dor de cabeça que acho que não vou resolver: coerência da tradução. Hoje ele traduz cada balão isolado, sem contexto da história antes ou depois. Em japonês, não existe diferença de gênero em palavras. Então o capitão estava falando da Nami mas o balão fala “Ele” em vez de “Ela”. Não tem como saber se não ler o texto anterior. Pra isso funcionar melhor, assim como num chat de GPT, precisa adicionar parte do texto anterior, pra saber quando usar o gênero correto ou, pior, quando tem trocadilhos que apareceram volumes atrás e é referenciado no futuro (coisa que um Oda adora fazer). Essas sutilezas todas se perdem se traduzir só um balão de cada vez.

Imagino que é por isso que ainda ninguém fez algo parecido com o que eu fiz, de traduzir em tempo quase real, porque pra realmente ficar bom, o trabalho de tradução seria exponencial pra cada capítulo mais pra frente na história.

Enfim, o nome Frank Yomik vem de “yomi” (読み, leitura em japonês) e “ik-da” (읽다, ler em coreano). Frank é referência à tradução franca, direta. O app lê nas duas línguas.

Pra quem quiser experimentar: o repositório está no GitHub. O server precisa de uma GPU com pelo menos 8GB VRAM pro modelo de detecção + OCR + tradução. O cliente Flutter roda em Android e Linux desktop. E se você, como eu, tem uma pilha de mangás japoneses que gostaria de ler mais fluentemente — agora pode.

–

Publiquei o “post final” da série Bastidores do The M.Akita Chronicles há 10 dias. 274 commits, 1.323 testes, deploy em produção. Escrevi as lições, fiz a conclusão, coloquei a citação no final. Done.

125 commits de pós-produção depois, posso confirmar: software “done” não existe.

Hoje o repositório do M.Akita Chronicles tem 335 commits e 1.422 testes. Amanhã, segunda-feira, os assinantes recebem a 3ª newsletter consecutiva — gerada, revisada, e enviada por um sistema que não para de evoluir. Enquanto isso, o Frank Sherlock saiu de 50 commits e v0.1 pra 103 commits e v0.7 com face detection. O FrankMD recebeu 3 contribuidores externos e lançou a v0.2.0. E até o FrankMega — um projeto construído em 1 dia — precisou de correções quando usuários reais apareceram.

Ao longo de fevereiro, publiquei mais de uma dezena de posts detalhando a construção de cada projeto. Este post é diferente. Não é sobre construir do zero, já cobri isso. É sobre o que acontece depois. E o que acontece depois destrói a narrativa do one-shot prompt. Software precisa de um humano experiente no volante. Desenvolvimento iterativo é a única forma que funciona. Quem discorda não botou sistema em produção ainda.

Vou provar com git log.

A Vida Depois do Deploy

Vamos aos detalhes.

The M.Akita Chronicles: 3 Semanas em Produção

O sistema de newsletter está no ar desde 16 de fevereiro. Já enviou 2 newsletters e amanhã envia a terceira. 56 commits aconteceram desde o “post final”:

Features que Ninguém Previu

Steam Gaming. Não existia no plano original. Nasceu porque a seção de entretenimento só tinha anime — e leitores gamers ficaram de fora. Resultado: 6 commits só no dia de lançamento. O primeiro commit (bf41e25) adicionou a seção completa — serviço de API Steam, job de geração, testes, shortcode Hugo. Os 5 seguintes corrigiram: parsing de datas em português, offset pro ranking não repetir o top 10, filtro de wishlist pra releases, dark theme. Nenhum spec do mundo prevê que a API do Steam retorna datas com abreviações em português ("fev", "mar", "abr") quando você pede l=brazilian. Isso você descobre quando o parser quebra em produção.

Sistema de preview. O /preview nasceu porque eu precisava ver como o conteúdo auto-gerado ficava antes de publicar a newsletter inteira. Parece óbvio em retrospecto, mas na v1 a única forma de validar era gerar tudo e olhar o resultado final. 5 commits pra construir um sistema de preview com 9 seções, aliases (hn pra hacker_news, steam pra steam_gaming), modo de preview de comentários separado, e rescue quando uma seção falha sem derrubar as outras (d23c725 — porque uma seção com erro estava matando o preview inteiro).

Moods do Marvin. O Marvin (a persona sarcástica do bot) sofre de um problema crônico de LLMs: suavização. Sem intervenção, todo comentário vira o mesmo tom morno. A solução iterativa foi um sistema de moods — 9 modos que o operador escolhe por story:

MARVIN_MOODS = {
  "sarcastic"   => "Be extra sarcastic and biting in your commentary.",
  "ironic"      => "Use irony and dark humor to make your point.",
  "grounded"    => "Be more neutral and journalist-like, factual and measured.",
  "provocative" => "Be provocative and controversial, challenge assumptions.",
  "counter"     => "Take the opposite position from Akita's comment.",
  "insightful"  => "Find a non-obvious angle -- a historical parallel, a second-order consequence.",
  "positive"    => "Find the genuinely positive angle.",
  "hopeful"     => "Be cautiously optimistic. Acknowledge the good potential.",
  "negative"    => "Be extra pessimistic and bleak."
}.freeze

Nada disso surgiu de uma spec. Surgiu de 3 semanas lendo comentários genéricos e pensando “isso não tá bom”. São 7 commits só de prompt tuning ao longo de 10 dias. Bani padrões formulaicos (d4bd3a6). Eliminei o “Ah,” como abertura (4171628). Removi o Marvin de seções inteiras do podcast porque ele tava contaminando o tom (246cc60). Forcei substância ao invés de trocadilhos (8bc47c4). Cada commit de prompt é uma micro-correção que só faz sentido depois de ler o output anterior.

Bugs que Só Existem em Produção

Dos 56 commits, 13 são bug fixes. Alguns favoritos:

• Gmail clipping (3258f5b): Gmail silenciosamente corta emails maiores que 102KB. Descobri quando a 2ª newsletter saiu mais longa e leitores no Gmail não viram o final. Resultado: um check de tamanho no content preflight que avisa antes de publicar. Reduzi as seções de história de 10 pra 5 itens (51ce528) pra caber no limite.

• False paywall detection (1fd8739): o scraper marcava sites como paywall quando encontrava texto de bloqueio acidental num rodapé genérico. Só apareceu quando a lista de stories cresceu pra dezenas de fontes reais.

• t.co link mangling (6bd056f): o Twitter encurta URLs com t.co, mas também auto-linka nomes de arquivo que parecem domínios. config.yml vira um link pro domínio config.yml. 158 linhas de fix pra tratar corretamente textos de tweet.

• TTS language revert (7803ad9 -> c1dd668): tentei trocar o idioma do TTS de “Portuguese” pra “Auto”. O modelo gerou sotaque misturado. Revertido no mesmo dia.

• Podcast section ordering (5bef18c): seções do podcast saíram fora de ordem. Fix de 3 linhas + untrack de 1.504 linhas de conteúdo gerado que foi commitado por acidente.

• Elementor sites com múltiplos <article> (e70b756): sites construídos com Elementor usam a tag <article> de forma não-semântica. O extrator de conteúdo pegava o bloco errado. 171 linhas de fix + testes.

Nenhum desses bugs poderia ter sido previsto numa spec. Eles só existem porque o sistema tá no ar, processando dados reais, batendo em APIs reais, sendo lido por gente real.

De 1.323 pra 1.422 Testes

A suíte de testes continuou crescendo junto:

Feature nova? Vem com teste. Bug fix? Vem com teste de regressão. Sem isso, os 56 commits de pós-produção seriam 56 oportunidades de quebrar algo que funcionava ontem. TDD não é fase, é hábito.

O Modelo Mudou: De Claude pra Grok-4

Commit 8f9d11c: Switch default model to x-ai/grok-4. A arquitetura isolou o modelo LLM numa variável de ambiente desde o início. Mas o nome do modelo ainda estava referenciado em código por 24 arquivos. Resultado: commit c8c688e — Centralize LLM model config — 24 arquivos tocados pra garantir que trocar de modelo seja uma mudança de 1 linha de config.

Esse tipo de refactoring só surge na operação. Quando você começa o projeto, não sabe que vai trocar de modelo. Quando troca, quer que seja trivial. E a limpeza pra tornar trivial? Só acontece quando a dor aparece.

Frank Sherlock: De v0.1 a v0.7 em 4 Dias

O post sobre o Frank Sherlock cobriu os primeiros 2 dias e ~50 commits: a pesquisa de benchmarks, o scaffold do app Tauri (Rust + React), a pipeline de classificação com Ollama, e o lançamento da v0.1.0 com binários pra Linux, macOS e Windows.

O que o post não cobriu: os 53 commits seguintes, em 4 dias, que levaram o projeto da v0.3 pra v0.7:

Face Detection: A Feature que Nasceu da Iteração

A v0.1 era um indexador de imagens com classificação por LLM. A v0.7 tem detecção de rostos com embeddings de 512 dimensões, clustering por similaridade de cosseno, e busca por pessoa (face:alice). Nada disso tava no plano original. Surgiu porque comecei a usar o app com fotos de verdade e pensei “quero encontrar todas as fotos de fulano” A feature nasceu do uso, não da spec.

O caminho até lá foi metódico:

1. f34132f: A/B testing framework pra face detection — benchmarkear antes de implementar, não depois
2. ef3be82: Resultados do A/B (SCRFD + ArcFace venceu)
3. 6d9174a: Implementação nativa com ONNX Runtime — sem Python, sem dependência externa
4. 3b25eaf: Clustering, person management, FacesView completa
5. a02d67f: Refactoring — extrair helpers, deletar código morto, compartilhar CSS

Benchmark -> implementar -> refatorar. O mesmo ciclo de sempre. E algo que nenhum one-shot prompt produz.

Video Support: Outro Emergente

O app foi pensado pra imagens. Mas pastas reais de mídia têm vídeos. Commit a67a2f9 adicionou suporte completo: scanning de 11 formatos (MP4, MKV, AVI, MOV, WebM…), extração de keyframe pra classificação pelo LLM, skip de frames pretos, parsing de legendas .srt pro índice full-text, e preview inline com streaming HTTP Range.

1.626 linhas adicionadas num commit. Uma feature inteira que nasceu do uso real, não de uma especificação.

7 Releases, 3 Plataformas, AUR Automático

Em 7 dias, o Frank Sherlock teve 7 releases. Cada um com binários compilados pra Linux (AppImage), macOS (DMG com notarização e code signing), e Windows (MSI). A pipeline de CI/CD (release.yml) faz tudo automaticamente. A partir da v0.5.0, um workflow adicional (aur-publish.yml) publica automaticamente no AUR — o repositório de pacotes do Arch Linux.

No final: 17.210 linhas de Rust, 10.863 linhas de TypeScript, 621 testes (322 Rust + 299 frontend). Cross-platform. Releases publicados e instaláveis por qualquer usuário. Uma semana, um dev, um agente de IA.

A parte de CI/CD pra cross-platform é onde a fantasia do “funciona na minha máquina” morre. Foram 17 commits só de build: Windows UNC paths, macOS signing com notarização, Linux AppImage, permissões de release workflow, macOS Intel target removido. Nenhum LLM do mundo sabe que o macOS exige entitlements específicos pra hardened runtime ou que paths no Windows começam com \\?\. Esse tipo de trabalho de deploy exige alguém que já passou por essa dor antes.

FrankMD: Open Source de Verdade

O FrankMD foi o primeiro projeto desta saga, um editor Markdown self-hosted com Rails 8. Os posts de fevereiro cobriram a construção. O que aconteceu depois é mais interessante: outras pessoas começaram a contribuir.

14 commits desde 20 de fevereiro. 3 contribuidores externos. 4 PRs merged. Release v0.2.0 no dia 28:

O Padrão do Maintainer

O mais revelador não são as contribuições em si, mas o que eu fiz depois de cada merge.

Quando o @LuccaRomanelli submeteu o PR do Omarchy theme sync (+308 linhas), eu mergeei e imediatamente commitei fix: harden Omarchy theme integration and fix broken tests — +163 linhas de fixes e testes no commit seguinte. O contribuidor implementou a feature. O maintainer endureceu.

Quando o @rafaself submeteu o fix de table hints, foram 3 commits iterativos no mesmo dia — enhance, improve, streamline — mostrando o mesmo padrão de refinamento progressivo que eu faço com o agente de IA. No dia seguinte, ele mandou um commit separado atualizando faraday, nokogiri e rack por security advisories.

No dia 28, sentei e fiz tudo de uma vez: mergeei as 4 PRs, commitei o hardening, atualizei 5 gems (brakeman, bootsnap, selenium-webdriver, web-console, mocha), e publiquei as release notes da v0.2.0. Um “release day” clássico.

O FrankMD hoje tem 226 commits, 1.804 testes (425 Ruby + 1.379 JavaScript), e contribuidores ativos. Não é mais “meu projetinho pessoal”. Virou software com comunidade. E comunidade não aparece pra protótipo sem testes que “funciona na minha máquina”. Aparece pra projeto com CI verde, documentação, releases versionados, e código que dá pra ler.

FrankMega: Até o Menor Projeto Precisa de Pós-Produção

O FrankMega foi construído em 1 dia. 26 commits, file sharing seguro com Rails 8, 210 testes, deploy via Docker + Cloudflare Tunnel. Post publicado no mesmo dia. Pronto, certo?

Três dias depois, 2 commits:

• db4bb705 — Add macOS, Linux, and Windows package MIME types to seed defaults
• b0c4829a — Fix MIME types to match Marcel detection, add normalizes strip

Usuários tentaram compartilhar arquivos .dmg, .deb, e .msi. O MIME type detection (via gem Marcel) não reconhecia esses formatos porque não estavam nos defaults do seed. Dois commits. 22 linhas. 15 minutos.

Mas sem eles, o FrankMega não servia pra compartilhar pacotes de instalação — que é exatamente o caso de uso mais comum num home server de devs.

Nenhum prompt no mundo prevê que seus usuários vão querer compartilhar .deb no primeiro dia.

O projeto mais simples de todos, com a pós-produção mais curta. E mesmo assim, precisou de iteração.

Os Números Consolidados

692 commits. 4.057 testes. 4 projetos em produção. Fevereiro de 2026. Eu e um agente de IA.

Por Que One-Shot Prompt É Mito

Olha os 125 commits de pós-produção e me diz qual deles poderia ter sido previsto por uma especificação.

Gmail corta emails maiores que 102KB, e você só descobre quando manda o primeiro email longo. A Steam API retorna datas com abreviações em português ("fev", "abr"), e você só descobre quando o parser quebra no domingo de geração. Usuários de macOS tentam compartilhar .dmg e não conseguem porque o MIME type não tá no seed. O Marvin abre todo comentário com “Ah,” e você só percebe quando lê 30 seguidos e quer arrancar os olhos. O modelo LLM precisa ser trocável com 1 linha de config, mas tá espalhado em 24 arquivos. Windows usa UNC paths que começam com \\?\, e o CI explode na sua cara. E o TTS em modo “Auto”? Gera um sotaque que parece português de Lisboa tentando ser carioca.

Nada disso é “debugar” no sentido tradicional. É navegar um espaço de problemas que só se revela quando o software encontra a realidade. Cada um desses foi uma decisão tomada em tempo real por alguém com contexto.

A fantasia do one-shot prompt é que, se você escrever uma especificação suficientemente detalhada, a IA produz o software perfeito. Mas a especificação perfeita exigiria que você soubesse de antemão tudo que vai dar errado. E se você soubesse de antemão tudo que vai dar errado, você não precisaria da especificação — já teria o software pronto na cabeça.

Software bom é o resultado de centenas de micro-decisões tomadas com o sistema rodando. Não de uma macro-decisão tomada antes de escrever a primeira linha.

O Papel do Desenvolvedor Experiente

A IA acelerou tudo isso. Sem ela, 692 commits em um mês seria impossível pra uma pessoa só. Mas aceleração sem direção é só entropia mais rápida.

Em cada projeto houve decisões que a IA não teria como tomar sozinha. Trocar de Claude pra Grok-4 porque o modelo anterior tava fraco num domínio específico. Benchmark de SCRFD vs alternativas antes de implementar face detection, porque a escolha errada ia custar dias. O hardening de +163 linhas que eu commitei imediatamente depois de mergear o PR do Omarchy, porque eu vi onde ia quebrar. O revert do TTS em modo Auto no mesmo dia, porque eu sei que “Auto” num modelo de TTS pra português brasileiro vai produzir sotaque misturado.

O caso do circuit breaker é o mais ilustrativo. Quando adicionei rate limiting, a Brave Search API começou a retornar 429 de vez em quando. Se eu pedisse, o agente implementaria um retry com backoff exponencial. Mas eu não pedi retry. Pedi circuit breaker:

class WebSearcher
  CIRCUIT_BREAKER_SECONDS = 120

  def self.search(query, max_results: 5)
    return [] if circuit_open?

    response = brave_search(query, max_results)

    if response.code == 429
      trip_circuit!
      Rails.logger.warn("WebSearcher rate limited (429)")
      return []
    end
  rescue Net::OpenTimeout, Net::ReadTimeout => e
    trip_circuit!
    []
  end
end

Se a API retorna 429 ou timeout, para de tentar por 120 segundos. Sem retry, sem backoff, sem fila. Por quê? Porque eu sei que o cron roda todo dia às 8h e que nos domingos de geração de newsletter o volume de queries triplica. Uma manada de retries atrasando tudo é pior que resultados vazios numa seção.

A IA implementa um circuit breaker quando você pede. Mas ela não vai pedir pra implementar um circuit breaker. Ela não tem o contexto operacional. Isso é conhecimento que vem de rodar sistemas em produção por décadas.

O agente escreve o código. Eu decido qual código escrever. E essa decisão exige experiência que nenhum prompt substitui.

As Lições

1. Software em produção diverge da spec em horas, não em meses. Os primeiros bugs do M.Akita Chronicles surgiram na primeira newsletter real. Os MIME types do FrankMega quebraram nos primeiros uploads. Quem acha que deploya e acabou tá vivendo num mundo que não existe.

2. Pós-produção não é “manutenção”. 56 commits em 10 dias no M.Akita Chronicles não são patches. São features novas (Steam Gaming, preview, moods), refactoring de arquitetura (centralização de config do LLM), hardening de segurança (rate limiting). Isso é desenvolvimento. O software não parou de evoluir só porque eu disse “done” num blog post.

3. TDD protege a evolução. 99 novos testes em 10 dias. Os 1.804 testes do FrankMD permitiram mergear 4 PRs de contribuidores externos sem medo. Sem testes, cada merge é roleta russa.

4. Small releases mantêm a sanidade. 7 releases do Frank Sherlock em 7 dias. CI verde, binários compilados, release notes. Deu problema? Reverte uma versão. Compara com “6 meses + big bang release” e me conta qual funciona melhor.

5. Comunidade aparece pra projetos reais. Ninguém manda PR pra protótipo sem testes que “funciona na minha máquina”. O FrankMD recebeu 3 contribuidores porque tem CI verde, documentação, e releases versionados.

6. A experiência do desenvolvedor é o gargalo, não a velocidade da IA. 692 commits em um mês. Mas cada commit que importa exigiu décadas de experiência pra saber que era necessário. A IA digita rápido. Eu sei o que digitar.

7. One-shot é pra demo. Iteração é pra produção. Se o objetivo é um vídeo de 10 minutos mostrando um “SaaS pronto”, one-shot serve. Se o objetivo é software que sobrevive ao contato com usuários reais, só iteração funciona. E iteração sustentável exige disciplina: TDD, CI, small releases, refactoring contínuo. Sem atalho.

Pro Sênior que Ainda Tá de Braços Cruzados

Até aqui eu bati nos amadores que acham que podem mandar um prompt e a IA cospe um sistema pronto. Justo. Mas tem um outro grupo que me preocupa tanto quanto: o desenvolvedor sênior que viu a IA errar três vezes, declarou que “isso não serve pra nada”, e voltou a fazer tudo na mão.

Eu entendo o raciocínio. A IA alucina, gera código com bugs sutis, sugere soluções over-engineered. Tudo verdade, e eu documentei cada um desses problemas nos posts anteriores. Mas me diz uma coisa: você nunca fez exatamente a mesma coisa? Você nunca passou 2 horas lendo documentação pra descobrir que era um typo na config? A diferença é que quando a IA erra, você pega nos testes e corrige em minutos. Quando você erra sozinho, leva o mesmo tempo pra cometer o erro e mais tempo ainda pra achar, porque você confia no próprio código.

Vamos olhar pros números concretos do que eu entreguei em fevereiro, uma pessoa e um agente de IA:

Agora faz a conta de cabeça. Quanto tempo você levaria pra fazer o Frank Sherlock sozinho? Um app Tauri do zero, com pipeline de classificação por LLM em Rust, OCR via Python, full-text search com FTS5, detecção de duplicatas por perceptual hash, face detection com ONNX nativo, suporte a vídeo com extração de keyframe, CI pra 3 plataformas com code signing e notarização no macOS, auto-update, e publicação automática no AUR. Com 621 testes. Em Rust, que não perdoa.

Sendo honesto: sem IA, um dev sênior bom levaria no mínimo 3-4 semanas nisso, provavelmente mais. Eu fiz em 7 dias, sozinho, e cada release tá publicado com binários que qualquer pessoa pode baixar e instalar.

O M.Akita Chronicles eu já estimei no post anterior: ~200 user stories. Em Scrum com equipe sênior de 2-3 devs, sem impedimentos, seriam 10-15 semanas. Fiz em 8 dias. Hoje, 3 semanas depois, o sistema continua rodando, evoluindo, com 99 testes a mais do que quando “acabou”.

O FrankMega é mais modesto, mas file sharing seguro com Rails 8, I18n em 2 idiomas, 22 issues de segurança corrigidos, deploy via Docker, 210 testes. Fiz em 1 dia. Um sênior bom, sem IA, faria em 1-2 semanas na melhor das hipóteses.

E não estou falando de protótipos descartáveis. Gente de fora manda PR pro FrankMD. Assinantes reais recebem a newsletter do M.Akita Chronicles toda segunda-feira. Qualquer pessoa pode baixar o Frank Sherlock no GitHub Releases ou no AUR. CI verde, Brakeman zerado, testes reais, deploys automatizados. Isso é software de produção, não demo de conferência.

“Ah, mas eu faço código melhor sem IA.” Talvez. Mas em quanto tempo? O que eu mostrei aqui não é que a IA faz código perfeito. Longe disso. É que com TDD, CI, pair programming com agente, e refactoring contínuo, o resultado final é código de produção com qualidade. 4.057 testes estão lá pra provar. Brakeman zerado. 125 commits de pós-produção mostram que o código aguenta evolução sem virar uma bola de lama.

E usar IA de vez em quando pra gerar um trecho de código aqui e ali, tipo autocomplete glorificado, também não é a resposta. Você tá deixando 90% do ganho na mesa. O que eu fiz em fevereiro foi pair programming full-time com um agente. Do primeiro commit ao deploy em produção. Com a mesma disciplina que eu usaria com um par humano. Resultado: 4 projetos em produção em 1 mês, com qualidade que eu coloco meu nome. Porque eu coloquei.

Se você é sênior e ainda tá esperando a IA “melhorar” pra começar a usar de verdade, eu digo o seguinte: ela já tá boa o suficiente. Os 692 commits estão aí pra provar. O gargalo agora é você aprender a trabalhar com ela.

Conclusão

Em fevereiro de 2026, eu construí 4 projetos do zero à produção com IA. Mas a construção é a parte fácil. O que separa software de verdade de demo são os 125 commits que vieram depois, quando os bugs que ninguém previu apareceram, quando contribuidores externos mandaram PRs que precisaram de hardening, quando features novas surgiram do uso real e não de uma planilha de requisitos.

A IA me tornou absurdamente mais produtivo. Sem ela, o Frank Sherlock não teria face detection em 7 dias. Sem ela, o M.Akita Chronicles não estaria na 3ª semana de operação com 1.422 testes. A velocidade é real.

Mas nenhuma das decisões que importam veio da IA. Trocar de modelo, revertar o TTS no mesmo dia, olhar pro PR do contribuidor e ver que ia quebrar, pedir circuit breaker ao invés de retry. Tudo isso fui eu. A IA executou. As decisões foram minhas.

A IA é o acelerador. As técnicas de Extreme Programming (TDD, small releases, pair programming, refactoring contínuo) são o freio e a direção. Sem disciplina, IA produz código rápido que acumula dívida técnica mais rápido ainda. Com disciplina, IA produz software que evolui de verdade, semana após semana.

692 commits. 4.057 testes. 4 projetos em produção. E amanhã, segunda-feira, às 7h, os assinantes do The M.Akita Chronicles recebem a 3ª newsletter. Gerada, revisada, e enviada por um sistema que nunca vai estar “pronto”. Porque software pronto é software morto.

“Software pronto é software morto. Software vivo itera.”

O nome é Frank Sherlock — um sistema local de catalogação e busca de imagens usando IA. Você aponta pra uma pasta (pode ser um NAS com terabytes), ele escaneia tudo, classifica cada arquivo usando um LLM de visão rodando localmente na sua GPU, e te dá busca full-text sobre o conteúdo. Não é cloud, não manda nada pra fora, roda 100% na sua máquina.

Eis alguns exemplos de textos que ele extraiu de algumas das minhas imagens:

E olha os detalhes do Surya OCR: ele leu direitinho o texto na tela do Game Boy:

Mais do que isso, eu tenho diretórios de screenshots de comprovantes de pagamento. Nunca mais ia achar nada ali, mas agora:

Embora ele faça alguns erros, claro, animes obscuros (ele fica achando que tudo que ele não reconhece é Evangelion 😂). Mas muitos ele surpreendentemente acerta também. Mas as descrições em si já ajudam muito.

Vai precisar de um mínimo de GPU (eu só testei na minha 5090, mas é pra baixar modelos menores pra GPUs menores, e teoricamente suporta AMD e Mac também, mas ainda não testei - aceito Issues e Pull Requests pra quem quiser fazer beta-testing em Mac e Windows). Basta ter o Ollama instalado e rodando; opcionalmente, Python (pra ter o Surya OCR, que é opcional, mas é o melhor).

Vou colocar como “1.0” quando tiver mais gente testado em Windows/macOS e eu tiver os certificados pra assinar os executáveis direitinho. Esta é uma versão “beta” ainda! Compilem e rodem vocês mesmos em suas máquinas, tá tudo explicado no README.

E eu fiz isso com meu “Agile Vibe Coding” — basicamente, programar em parceria com um LLM (no caso, Claude Code).

Agile Vibe Coding funciona. E funciona muito bem. Mas a ideia é só 10% do trabalho. Os outros 90% são engenharia.

Engenharia requer experiência, julgamento, e saber fazer as perguntas certas. O LLM é um executor excelente. Mas quem decide o que executar, em que ordem, e por quê, esse continua sendo o trabalho do desenvolvedor.

Tem um discurso crescente de que qualquer pessoa com uma boa ideia pode construir software agora. Num certo sentido, sim, você pode colocar um protótipo no ar rápido. Mas a distância entre “roda na minha máquina” e “software que funciona em 3 sistemas operacionais, sobrevive a cancelamentos no meio do processamento, não corrompe dados, e escala de 94 arquivos de teste pra 500 mil em produção” continua sendo enorme. Esse gap é engenharia, e engenharia ainda exige alguém que saiba o que está fazendo.

Vou contar a história completa: da pesquisa inicial ao release, passando por benchmarks, prova de conceito, decisões de arquitetura, CI/CD multi-plataforma, e tudo que ficou entre “eu tenho uma ideia” e “aqui está o AppImage, o DMG e o MSI”.

A Ideia Original

Tudo começou com uma pergunta simples: será que LLMs open-source de visão conseguem classificar conteúdo de verdade? Não estou falando de “mulher na praia” — isso qualquer modelo faz. Estou falando de olhar pra uma imagem e dizer “isso é a Ranma, do anime Ranma 1/2 da Rumiko Takahashi, numa cena do OVA The Battle for Miss Beachside”. Será que chegamos nesse nível? (TL;DR não, mas o suficiente)

E se chegamos, dá pra fazer um catálogo inteligente de arquivos? Algo que eu aponte pro meu NAS com terabytes de mídia acumulada ao longo de décadas e consiga buscar por conteúdo, não por nome de arquivo? Quem tem um NAS em casa sabe: depois de alguns anos, os arquivos acumulam e a organização de diretórios simplesmente para de escalar. Você sabe que tem aquele comprovante de pagamento de 2019 em algum lugar, mas o arquivo se chama IMG_20190315_142301.jpg e está num diretório com mais 3 mil fotos.

Meu hardware: AMD 7850X3D, RTX 5090, Arch Linux. Restrição absoluta: nada de APIs remotas, nada de OpenAI, nada de cloud. Tudo open-source, tudo local. Se eu vou processar terabytes de arquivos pessoais, incluindo documentos financeiros e fotos privadas, não quero mandar nada pra servidor de terceiros. Fora que o custo de API cloud pra esse volume seria proibitivo.

Mas primeiro: pesquisa. Sem saber se a tecnologia entrega o que eu preciso, não faz sentido construir nada. Scripts pequenos, protótipos rápidos, modelos diferentes. Ver o que funciona antes de escrever a primeira linha de código do app de verdade. Esse é um padrão que eu sigo há anos: valide a suposição mais arriscada primeiro. Se o LLM de visão não conseguir classificar decentemente, todo o resto é desperdício.

Pesquisa A/B: Benchmark Driven Development

Essa é a parte que a maioria das pessoas pula, e é exatamente onde a experiência faz diferença. A tentação de pular direto pra implementação é enorme. “Vou usar o modelo X porque li num blog que é bom.” Não. Antes de escolher modelo, framework, ou arquitetura, eu montei um benchmark formal.

Montei um corpus de teste com 94 arquivos: 60 imagens (fotos, screenshots, anime, documentos, receipts), 9 áudios, 13 vídeos e 12 documentos. Pra cada arquivo, criei um ground truth em JSON com a classificação correta — tipo, descrição, série (quando aplicável). Esse ground truth é o que permite medir accuracy de verdade, não “olhei o resultado e pareceu OK”.

O benchmark tem 6 fases, cada uma respondendo a uma pergunta específica:

1. Metadata: quanto custa extrair metadata básica? (resposta: barato, 0.07s/arquivo)
2. Imagens: qual modelo de visão é melhor? Qual OCR?
3. Áudio: Whisper funciona? Qual tamanho de modelo?
4. Vídeo: classificação por frames funciona?
5. Catálogo unificado: o pipeline completo integrado funciona?
6. Projeção de custo: quanto tempo e dinheiro pra processar um NAS real?

Fase 2: Visão — O Resultado Que Ninguém Esperava

Testei qwen2.5vl:7b, llava:13b e minicpm-v:8b em 30 imagens rotuladas. O resultado:

O modelo de 7B parâmetros ganhou de lavada dos maiores. Não é typo. O qwen2.5vl:7b bateu o llava:13b (quase o dobro do tamanho) em todas as métricas, e ainda foi 3x mais rápido. Isso contradiz a intuição de “modelo maior = modelo melhor”. Na prática, depende do task e do prompt.

Naturalmente, a próxima pergunta é: e o 32B? Mesmo modelo, versão gigante. A gente deve conseguir bem mais, certo? Errado:

O 32B deu +0.06 em series accuracy (literalmente 1 acerto a mais em 16 itens rotulados) e custou 29x mais tempo. Pra quem vai processar centenas de milhares de arquivos, essa troca não fecha. 29x mais lento significa que um job de 6 horas vira um job de uma semana.

Aqui faço um comentário sobre ferramenta: fiz a primeira rodada com Claude Code e tinha pedido pra ele escolher os modelos que achava melhores. Mas depois decidi ir pro GPT Codex e ele fez outras sugestões que achei interessante testar. Em resumo: tenho achado Codex muito melhor pra experimentação e código exploratório, pra pesquisa mesmo. Claude eu acho melhor quando já sabemos melhor exatamente o que queremos.

Com o Codex, testei os novos candidatos qwen3-vl:8b e qwen3-vl:30b-a3b com 3 repetições para fins de significância estatística. Resultado? Ambos piores que o qwen2.5vl:7b — type_accuracy de 0.55 contra 0.89 do incumbent, com intervalo de confiança de 95% que nem se aproxima. E ainda mais lentos: 2x e 2.2x respectivamente. Modelo mais novo nem sempre é modelo melhor pro seu caso de uso. O qwen3-vl frequentemente retornava JSON truncado ou mal-formado — uma regressão real em robustez.

OCR: Surya vs Ollama Vision

Para extração de texto (documentos escaneados, receipts, screenshots com texto), testei dois engines:

Surya encontra texto em muito mais arquivos (83% vs 58%), mas é 5x mais lento. Quando encontra texto, a qualidade é praticamente igual (similarity > 0.94 nos dois). Solução óbvia: abordagem híbrida. Usa Surya quando precisa de cobertura máxima, Ollama Vision como fallback rápido. O design do pipeline ficou: tenta Surya → se falhar ou não encontrar texto → fallback pra Ollama Vision. Por isso falei no começo que Surya é opcional, se não quiser instalar.

Projeção de Custo

A fase 6 fez algo que raramente vejo em projetos open-source: projeção de custo pra uso real. Com os timings medidos por tipo de arquivo, extrapolamos pra cenários de NAS:

Leve esses números com algum ceticismo porque é conta em papel de pão. $34 de eletricidade pra classificar 500 mil arquivos com GPU local. Tenta fazer isso com API do GPT-4 Vision — a $0.01 por imagem (conservador), são $5.000. O preço do meu setup (GPU + eletricidade) se paga no primeiro uso grande.

A lição: faça benchmark, não adivinhe. Eu poderia ter assumido que o modelo maior seria melhor, ou que o mais novo superaria o antigo. Os dados mostraram o contrário. ~2 horas de benchmarks me pouparam de escolhas erradas que custariam dias de retrabalho (antigamente eu diria “semanas”).

Prova de Conceito em Python

Com os benchmarks em mãos, o próximo passo foi validar o pipeline completo antes de partir pro Rust. Não o pipeline de benchmark (que testa cada modelo isoladamente), mas o pipeline de classificação real — a sequência exata de chamadas que o app final vai fazer pra cada arquivo.

Criei um protótipo em Python — 754 linhas em um único arquivo (classification/run_classification.py) — que implementava a estratégia vencedora dos benchmarks.

O pipeline tem 4 estágios de enriquecimento:

1. Classificação primária: manda a imagem pro qwen2.5vl:7b com prompt estruturado, pede JSON com tipo, descrição, tags, confidence
2. Enriquecimento anime: se o tipo primário for anime/manga/cartoon, faz uma segunda passada com prompt especializado pedindo série, personagem, cena, artista
3. Documento/OCR: se for documento ou receipt, extrai texto com Surya e/ou Ollama Vision, depois pede dados estruturados (datas, valores, IDs de transação)
4. Output: grava resultado em YAML espelhando a estrutura de diretórios de origem

A parte mais crítica é o parsing de JSON do LLM. Quem já trabalhou com output de LLMs sabe que eles são… criativos com formatação. Às vezes vem com markdown fences (json ... ). Às vezes tem texto antes e depois do JSON. Às vezes o JSON está quase certo mas falta fechar uma chave. O protótipo implementou uma cascata de 3 tentativas que depois virou a regra do projeto inteiro:

1. Parse direto: json.loads(response) — funciona em ~70% dos casos
2. Extração por balanceamento de chaves: encontra o primeiro {, conta chaves abertas e fechadas, extrai o substring — pega mais ~20%
3. Regex field salvage: se tudo mais falhar, usa regex pra extrair campos individuais (“type”: “…”, “description”: “…”) — salva os últimos ~10%

Essa cascata ficou no código Rust praticamente idêntica. PoC bem feito encurta o caminho pra produção.

Resultado: 60 imagens processadas, zero erros, 6.29s/imagem de média. O pipeline funcionava de ponta a ponta. Hora de construir o app de verdade.

Construindo o App Tauri

Nesse ponto, tentei continuar com o Codex, mas aí ele se engasgou em tentar converter o Poc em Python pra Tauri. Mas como agora as escolhas já foram feita, voltei pro Claude Code, e ele não teve problemas em mapear do Python pra Rust.

Aqui é onde o vibe coding mostra a que veio. Vou contar a timeline real, commit por commit, pra você ter noção do ritmo. Os timestamps são do git log, então são precisos.

Sábado 21/02 (19:29 → 21:08) — 6 commits, 1h39

Tudo começou com research. Seis commits de setup, scripts de benchmark, análise de resultados:

f57221c 19:29 Phase 0: Project setup with uv, environment verification
4977497 19:45 Implement all phases: metadata, image/audio/video classification
af6e3aa 19:49 Add research results report
41d6c2a 20:12 Add per-file timing, OCR phase, cost estimation
0cd1b10 21:02 Fix Surya OCR, re-run on 94-file corpus
25b3ace 21:08 Add conclusions, cost analysis, recommended pipeline

Sábado à noite, só pesquisa pura. Nenhuma linha de código do app. Mas quando fui dormir, sabia qual modelo usar, qual abordagem de OCR, e quanto ia custar em tempo e eletricidade.

Domingo 22/02 (13:05 → 23:30) — 14 commits, ~10h25

O domingo foi o dia de construção pesada. Acordei, almocei, e sentei pra trabalhar.

13:05 — Primeiro commit do dia: o protótipo Python de classificação. 749 linhas validando o pipeline completo de classificação, a cascata de JSON parsing, e o enriquecimento condicional. Esse protótipo não era throwaway — ele era o design document executável do pipeline Rust que viria depois.

Dei uma pausa pra pra dar uma saída, passear, tomar um vinho, depois voltei e continuei:

17:31 — Benchmarks atualizados com os novos candidatos (qwen3-vl:8b e qwen3-vl:30b-a3b). Três repetições cada, intervalos de confiança. Confirmaram que o qwen2.5vl:7b era a escolha certa — não por pouco, mas por uma margem enorme.

17:56 — O “big bang”: scaffold do app Tauri. 9.631 linhas inseridas num único commit. A estrutura inteira do app: Rust backend com SQLite + FTS5, React frontend, config system, scanner de arquivos, modelos de dados, query parser pra busca natural. Nesse ponto o app já buscava no banco. Não tinha classificação ainda, mas a fundação estava sólida — e é exatamente o ponto. O scaffold veio com testes, tipos TypeScript, e a arquitetura de diretórios que eu defini. O Claude gerou o código, mas a estrutura de módulos (config, db, scan, models, query_parser) veio de como eu queria organizar as responsabilidades.

19:04 — O commit mais pesado do projeto: 4.186 linhas. Classification pipeline em Rust (1.069 linhas de classify.rs — praticamente a tradução do PoC Python), geração de thumbnails (Lanczos3, 300px, JPEG 80%), scanning incremental com fingerprint, o script Surya OCR em Python, runtime detection pra Ollama, e a expansão brutal do banco de dados com upsert, touch, delete e FTS indexing. Num commit. Com 47 testes. Eu tive que tomar as decisões de arquitetura (como o cache espelha o rel_path, como o scan é dividido em duas fases, como os erros propagam), mas o Claude escreveu o grosso do código e os testes que vieram junto.

19:55 — Redesign de UI, cancellation de scan, auto-cleanup de classificações órfãs, reorganização do repo inteiro (movi tudo de research pra _research_ab_test/). CI e release workflow já configurados nesse commit — eu sabia que ia precisar deles no dia seguinte.

21:02 — DB resilience (WAL mode, backup, health check), gerenciamento de roots (adicionar, remover, listar diretórios monitorados), zoom, redesign do sidebar com tree view, fix de thumbnails. Quatro features num commit. Num workflow manual, cada uma dessas seria um PR separado com review de dias.

21:14 → 21:39 — Read-only database mode pra filesystems sandbox, resume de scans interrompidos no startup, redesign de grid tiles com hover overlay, modelo de seleção, infinite scroll. Três commits em 25 minutos. O Claude estava num ritmo absurdo.

22:41 — Multi-select com Ctrl/Shift click, preview de collage com os itens selecionados, Ctrl+C copia pro clipboard do OS.

23:30 — O grande refactor: frontend monolítico (tudo no App.tsx - se não explicar, Claude sempre faz isso) desmembrado em 15 componentes + 10 hooks + 84 testes frontend. Esse é o tipo de coisa que normalmente leva um dia inteiro de trabalho tedioso. Com vibe coding, foi um commit de uma hora. O Claude extraiu cada componente, criou os hooks, montou os testes com mocks adequados, e manteve tudo funcionando. Eu só precisei dizer “refatora esse monolito em componentes e hooks, e escreve testes pra cada um”.

Segunda-feira 23/02 (00:09 → 14:33) — 30 commits, ~14h

A segunda foi de polimento, robustez e a maratona de cross-platform.

00:09 — Abstração multi-OS: todo código específico de plataforma isolado no módulo platform/. Essa decisão, tomada cedo, salvou horas de dor no CI. Quando o Windows precisou de tratamento especial pra paths UNC, a mudança ficou contida em platform/process.rs em vez de espalhada em 8 arquivos.

00:12 → 01:18 — Sequência rápida: cargo audit no CI, remoção de duplicações, licença GPL-3.0, help dialog (F1) com exemplos de query syntax, sort controls pra resultados, sistema de migração SQLite formal, context menu (copy, delete, rename). Seis commits em pouco mais de uma hora.

09:38 — Após dormir umas 8 horas, o primeiro commit da manhã: extração do módulo LLM. O monolito de chamadas ao Ollama que vivia dentro de classify.rs foi separado em llm/client.rs (chamadas HTTP, parsing JSON), llm/management.rs (download, listagem, cleanup de modelos) e llm/model_selection.rs (seleção hardware-aware por tier). Atomic file ops pra não corromper cache se o processo morrer no meio de uma escrita.

10:54 — Extração de localização EXIF (GPS coordinates → endereço legível), modal de edição de metadata, setup instructions por OS (cada OS tem dependências diferentes pro Ollama e Python).

11:34 — Suporte a PDF: scanning, indexing e preview usando PDFium. Não é trivial — PDFium precisa de binário nativo por plataforma, renderização de páginas em imagem, detecção de páginas em branco (pra não gerar thumbnail de uma capa vazia), montagem de thumbnail com as 2 primeiras páginas com conteúdo, e extração de texto nativo como alternativa mais rápida ao OCR.

12:08 — Albums e Smart Folders. Albums são coleções manuais (o usuário arrasta arquivos pra dentro), Smart Folders são queries salvas que aparecem no sidebar e atualizam automaticamente. Duas migrações de banco, novo componente de sidebar, drag-and-drop. Em 34 minutos.

12:11 → 12:52 — Ícones SVG macOS-inspired no sidebar, suporte a argumento CLI (sherlock /path/to/folder), copy description/OCR text no context menu, fix de path do PDFium em produção, ícones e screenshots no README, script tauri no npm, sidebar toggle, titlebar dinâmico, fix de compilação Windows (imports Unix-only). Dez commits em 41 minutos. A maioria desses foram issues que apareceram no CI ou durante teste manual.

13:14 → 13:54 — A maratona de CI fixes. Auto-provision do venv Surya OCR com barra de progresso no SetupModal, regeneração de ícones com alpha channel, cargo fmt + clippy + fix de UNC paths no Windows, testes pros exemplos do help dialog, rescan de pasta individual, fix de assertions Windows, fix de permissions do release workflow. Sete commits de hardening. Cada um resolvendo um bug real que aparecia no CI matrix ou em teste.

14:26 — Drag-and-drop pra reordenar roots no sidebar, cancelamento de scan antes de deletar um root (pra não deixar o scan rodando em background num diretório que o usuário removeu — edge case sutil que poderia causar crash).

14:33 — Último commit: fix de responsividade no cancelamento de scan. Check do cancel flag após cada classificação, poll imediato em vez de esperar o próximo tick. Detalhe pequeno, impacto grande na UX.

Decisões de Arquitetura

Aqui é o que separa “deixar o LLM escrever código” de “construir software de verdade”. Nenhuma dessas decisões veio de prompt. O Claude não sugeriu nenhuma espontaneamente. Eu tive que pedir cada uma.

Princípio Read-Only

O app nunca escreve nos diretórios escaneados. Tudo — thumbnails, cache de classificação, banco de dados — fica em ~/.local/share/frank_sherlock/. Isso não é só boa prática, é respeito pelo dado do usuário. Se alguém aponta pro NAS da empresa, o app não pode sair criando .sherlock/ em cada subdiretório. Se o diretório é montado como read-only via NFS, o app precisa funcionar normalmente. Parece óbvio, mas muitos apps de catalogação que você conhece criam caches e thumbnails dentro dos diretórios de origem. (cof Synology @eaDir cof)

Scanning Incremental

Escanear terabytes de dados toda vez que o app abre seria insano. O scan é incremental em dois sentidos:

1. Fase de descoberta (rápida): caminha o filesystem comparando mtime + tamanho de cada arquivo. Se nada mudou desde o último scan, nem lê o conteúdo — apenas atualiza o marcador de “visto neste scan”. Pra um NAS com 500K arquivos onde 99% não mudou, essa fase leva segundos, não horas.
2. Fase de processamento (pesada): só pra arquivos novos ou modificados. Calcula fingerprint (SHA-256 dos primeiros 64KB), gera thumbnail, classifica com o LLM. E aqui entra a detecção de movidos: se um arquivo mudou de path mas o fingerprint é o mesmo, o app preserva toda a classificação já feita e apenas atualiza o path. Você reorganizou 10 mil fotos em pastas novas? O app detecta e não reclassifica nenhuma.

O checkpoint é por arquivo. Se o scan for interrompido (o app crashou, o usuário fechou, acabou a luz), na próxima vez ele retoma do último arquivo processado, não do zero. Isso é implementado via scan job persistence no banco: o cursor do scan fica salvo em scan_jobs.

Cancelamento Cooperativo

O scan roda numa thread separada via tokio::spawn_blocking. Para cancelar, uso AtomicBool compartilhado entre a thread de scan e o frontend. O flag é checado:

• Antes de cada arquivo na fase de descoberta
• Antes de cada classificação na fase de processamento
• Após cada classificação (pro caso de a chamada ao Ollama demorar)

Isso garante que o cancelamento responde em no máximo o tempo de uma classificação (~1 segundo), não no tempo do scan inteiro. Sem esse design, cancelar um scan de 500K arquivos poderia levar minutos — ou simplesmente não funcionar.

Resiliência do Banco

SQLite com WAL mode (permite leituras concorrentes durante escrita), health check no startup, backup automático antes de migrações, sistema de migração formal via rusqlite_migration. Cinco migrações no total:

0. Schema inicial (tabelas de arquivos, roots, scan_jobs, e a virtual table FTS5 pra busca)
1. Coluna location_text pra endereço EXIF
2. Rebuild do índice FTS (necessário após mudar a tokenização)
3. Tabelas albums e album_files pra coleções manuais
4. Tabela smart_folders pra queries salvas

As migrações são identificadas por posição e nunca podem ser editadas ou reordenadas depois de publicadas. Isso é o tipo de regra que você aprende depois de corromper o banco de produção de alguém uma vez. A regra está codificada no CLAUDE.md do projeto pra que futuras sessões de vibe coding não a violem.

Seleção de Modelo Hardware-Aware

Nem todo mundo tem uma RTX 5090. O app detecta a GPU no startup e escolhe o modelo adequado:

• GPU fraca ou sem GPU: qwen2.5vl:3b (tier small — roda em qualquer coisa)
• GPU com >= 6GB VRAM: qwen2.5vl:7b (tier medium, o default dos benchmarks)
• Apple Silicon com >= 48GB unificados: qwen2.5vl:32b (tier large, só onde a memória unificada permite sem swap)

A detecção usa nvidia-smi no Linux/Windows, system_profiler no macOS, e sysinfo como fallback pra RAM do sistema. O resultado é cacheado no AppState do Tauri pra não ficar executando subprocesso toda hora.

Multi-OS e CI/CD

Se tem uma parte do projeto que justifica ter experiência, é essa. Fazer software que compila é fácil. Fazer software que compila e passa todos os testes em Linux, macOS e Windows ao mesmo tempo te ensina humildade.

Módulo Platform

Todo código específico de OS vive em src-tauri/src/platform/:

• gpu.rs: detecção de GPU (NVIDIA via nvidia-smi, AMD via sysfs/rocm-smi, Apple via system_profiler)
• clipboard.rs: cópia de imagem pro clipboard (xclip no Linux, pbcopy no macOS, PowerShell no Windows)
• python.rs: localização de Python (python3 vs python no PATH), caminhos de venv por OS
• process.rs: abstração de execução de subprocesso com tratamento de output

Isso significa que classify.rs, scan.rs, thumbnail.rs — nenhum deles sabe em qual OS está rodando. Eles pedem pra plataforma e a plataforma resolve. Quando o Windows precisou de tratamento especial pra paths UNC (aqueles que começam com \\?\), a mudança ficou contida em platform/. Quando o macOS precisou de um import condicional, idem. O resto do codebase não foi tocado.

GitHub Actions Matrix

Dois workflows:

• CI (push + PR): build e teste em Linux, macOS e Windows. Cada push roda cargo test + npm test nos 3 OS. Inclui cargo fmt --check, cargo clippy -- -D warnings e cargo audit. Se qualquer plataforma falhar, o PR não passa.
• Release (tags v*): build via tauri-action, gera AppImage (Linux), DMG (macOS arm64), MSI (Windows), e cria um Draft Release no GitHub com os binários anexados.

Os 10+ commits de CI fix na segunda de manhã, foram a parte menos glamorosa do projeto. Coisas como:

• #[cfg(not(target_os = "windows"))] em imports que usam std::os::unix::fs::PermissionsExt
• dunce::canonicalize no lugar de std::fs::canonicalize porque o Windows gera paths com prefixo \\?\ que quebram comparações de string
• Instalar rustfmt e clippy explicitamente no runner porque nem sempre vêm no toolchain default da GitHub Actions
• Remover o target macOS Intel do release workflow (Apple Silicon only — não vale o custo de manter dois targets Mac)

Ninguém posta essas coisas no X. Mas sem elas, seu app não builda em 2 dos 3 targets.

Integrações Externas

O app depende de 3 sistemas externos. Cada um trouxe seus próprios problemas.

Ollama

O Ollama serve os modelos de visão via API REST local (porta 11434). O app faz:

• Verificação de status: checa se o Ollama está rodando e lista modelos instalados/carregados
• Download de modelo: se o modelo recomendado não está instalado, oferece download com barra de progresso via streaming da API
• Geração: manda imagem em base64 + prompt, recebe JSON (com a cascata de parsing de 3 níveis)
• Cleanup: descarrega modelos da VRAM quando não está classificando, pra não ficar monopolizando a GPU pras outras aplicações do usuário

O Ollama é o único hard requirement. Sem ele, a classificação não funciona. O SetupModal guia o usuário pela instalação e download do modelo.

Surya OCR

Surya é um engine de OCR em Python que roda localmente. O problema: o app é Rust e não pode depender de uma instalação Python do sistema. A solução:

• O app mantém um Python venv isolado em ~/.local/share/frank_sherlock/surya_venv/
• O script surya_ocr.py é bundled como resource do Tauri (empacotado no binário)
• No primeiro uso, o SetupModal oferece provisionar o venv automaticamente (encontra Python, cria venv, pip install surya-ocr + dependências)
• A classificação chama o script via subprocess, passa a imagem como argumento, lê o texto extraído do stdout

O Surya é um soft requirement: se não estiver instalado, o app funciona normalmente — só não vai ter OCR dedicado. O pipeline degrada gracefully pra usar Ollama Vision como fallback, que é pior em cobertura mas funciona. O usuário vê um aviso no setup, não um erro que bloqueia o uso.

PDFium

Pra PDFs, eu precisava de extração de texto nativo e renderização de páginas pra thumbnail. PDFium é o engine do Chrome pra PDFs, e tem bindings Rust via pdfium-render.

O binário do PDFium é baixado por um script (scripts/download-pdfium.sh) e bundled via lib/ nos resources do Tauri. Cada plataforma recebe o binário correto (.so, .dylib, .dll). O lib/ é gitignored — os binários são baixados no build, não versionados.

O pipeline de PDF:

1. Tenta extrair texto nativo (sem OCR) — muitos PDFs já têm text layer
2. Se tiver texto suficiente, usa direto pra indexação (mais rápido e mais preciso que OCR)
3. Se não, renderiza a página e manda pro pipeline de imagem (Ollama Vision)
4. Detecta páginas em branco, encontra a primeira página com conteúdo real
5. Gera thumbnail como montagem das 2 primeiras páginas com conteúdo (dá uma noção melhor do documento do que só a capa)

O que Agile Vibe Coding Realmente É

OK, agora o ponto que realmente importa. O motivo de eu estar escrevendo isso.

O Que o Claude Fez

• Escreveu a maior parte do código Rust e TypeScript
• Gerou 166 testes Rust e 172 testes frontend
• Implementou o parsing de JSON com 3 níveis de fallback
• Configurou CI/CD com matrix de 3 OS
• Fez refactors massivos (monolito → 15 componentes + 10 hooks)
• Lidou com edge cases de encoding, paths Unicode, e formatos de arquivo exóticos
• Escreveu queries SQL, migrações, índices FTS5
• Implementou detecção de GPU, clipboard por OS, resolução de Python
• Criou o setup flow com barra de progresso e download de modelo
• Debugou e fixou dezenas de issues de compilação cross-platform

A velocidade é difícil de descrever sem parecer exagero. O commit das 19:04 de sábado, aquele de 4.186 linhas com 47 testes, levou cerca de uma hora incluindo minha revisão. Um dev humano, mesmo bom, levaria um dia inteiro pra escrever isso com a mesma cobertura de testes.

O Que Eu Fiz

• Decidi fazer benchmarks antes de escrever qualquer código de app
• Escolhi Tauri em vez de Electron (menor footprint, Rust nativo, sem Node runtime em prod)
• Defini o princípio read-only como regra inviolável
• Projetei o scan incremental com detecção de move por fingerprint
• Decidi por cooperative cancellation com AtomicBool
• Exigi migração formal de schema (nada de ALTER TABLE ad-hoc em scripts soltos)
• Insisti em abstração de plataforma desde o primeiro commit multi-OS

E principalmente: fiz as perguntas chatas. “E se o scan for cancelado no meio?” virou o sistema de checkpoint. “E se o banco corromper?” virou WAL + backup + health check. “E se a pessoa não tiver GPU boa?” virou model selection por tier. “E se o Surya não estiver instalado?” virou soft requirement com fallback. “E se o usuário deletar um root que está no meio de um scan?” virou cancel-before-delete. “E se o arquivo mudar de lugar mas o conteúdo for o mesmo?” virou detecção de move.

Ah, e decidi a hora de parar de adicionar features e publicar.

Essa última é subestimada. A tentação de ficar adicionando “só mais uma coisa” é enorme quando o custo marginal de implementar é baixo. O Claude implementa qualquer feature que eu pedir em minutos. Mas software que nunca é publicado não serve pra ninguém. Saber a hora de parar é uma skill que nenhum LLM vai te dar.

O Padrão Real

Agile Vibe coding não é “pedir pro LLM fazer um app”. É pair programming com um parceiro que é rápido pra caramba, tem memória perfeita, e nunca reclama de refactor. Você diz o que quer, ele implementa, você revisa e ajusta a direção. Mas se você não sabe pra onde ir, velocidade não ajuda — você só chega mais rápido no lugar errado.

As perguntas que eu fiz — sobre resiliência, cancelamento, multi-OS, degradação graceful, detecção de edge cases — nenhuma delas veio do LLM. Vieram de anos construindo software que precisa funcionar em ambientes reais, com usuários reais, em hardware diverso. O Claude não vai te perguntar “e se o usuário puxar o cabo de rede no meio do download do modelo?”. Mas se você perguntar, ele implementa o tratamento em minutos.

É tentador olhar pra esse projeto e concluir que qualquer pessoa com uma boa ideia poderia ter feito o mesmo. Mas tente imaginar: sem a decisão de fazer benchmarks, eu teria escolhido o modelo errado. Sem o PoC em Python, teria descoberto os problemas de JSON parsing em produção. Sem a abstração de plataforma, estaria debugando issues de Windows espalhadas por 15 arquivos. Sem o checkpoint de scan, usuários perderiam horas de processamento a cada crash. Sem a migração formal de schema, a primeira atualização quebraria o banco de todo mundo.

Pense num arquiteto com uma equipe de construção absurdamente eficiente. O arquiteto não precisa levantar cada parede, mas precisa saber onde elas vão e o que acontece se você tirar uma. A equipe executa rápido, trabalha de noite, não reclama. Mas alguém precisa ter desenhado a planta. Sem planta, é só um monte de tijolos empilhados rápido.

Números Finais

Pra quem gosta de números concretos:

O primeiro commit foi sexta-feira 21/02 às 19:29. O último foi segunda-feira 23/02 às 14:33. Descontando sono (~8h na noite de sábado/domingo, ~8h na madrugada de domingo/segunda) e pausas, são ~26 horas de trabalho distribuídas em um fim de semana.

De zero — sem um único arquivo no repositório — a binários publicados para 3 sistemas operacionais, com testes automatizados rodando no CI a cada push. Incluindo a fase de pesquisa, que sozinha justificaria um sprint.

Conclusão

Agile Vibe coding funciona. Mas funciona como qualquer ferramenta poderosa: nas mãos de quem sabe o que está fazendo.

A ideia do Frank Sherlock caberia num tweet: “classificar imagens com LLM local”. Mas transformar isso em software real exigiu: pesquisa benchmarked com ground truth formal, prova de conceito validando o pipeline completo, arquitetura incremental, tratamento de erros em 3 níveis, cancelamento cooperativo, migração formal de schema, abstração de plataforma, CI/CD com matrix de 3 OS, integração com 3 sistemas externos com graceful degradation, e 338 testes pra garantir que nada disso quebra quando alguém fizer cargo update.

O LLM acelerou tudo isso absurdamente. Mas não substituiu a necessidade de saber o que fazer. Se eu tivesse pedido “faz um app que classifica imagens” sem as 2 horas de benchmark, sem a prova de conceito, sem as decisões de arquitetura, sem as perguntas chatas sobre edge cases, o resultado seria um protótipo que funciona na minha máquina e quebra em qualquer outro lugar. E provavelmente eu nem perceberia até alguém reclamar.

O vibe precisa de um condutor experiente. Por enquanto, esse condutor ainda é humano.

Código em github.com/akitaonrails/FrankSherlock. GPL-3.0, local-only, open source.

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

O TL;DR é o seguinte: antigamente, se eu fosse fazer este web app do zero, teria me custado aproximadamente 200 horas, ao longo de 1 ou 2 meses, bem devagar, indo e voltando. E talvez não tivesse ficado tão completo quanto este.

Com Claude, fiz tudo em pouco mais de 30 horas, distribuído em 3 dias de super hiper foco (não recomendo; praticamente fiquei doente fazendo isso). No final, isso gerou um projeto com aproximadamente 130 pull requests. Um total de 18 mil linhas de código (cobertura de testes de cerca de 70%). Foi tudo feito em Ruby on Rails 8 e Javascript (HotWire/Stimulus).

Existem várias vantagens neste aplicativo em particular: é um escopo muito bem conhecido e bem documentado. Existem centenas de editores de texto de todos os tipos e de complexidades. Certamente todos os LLMs foram treinados com toneladas de material sobre isso. Então, quando eu peço pra fazer uma pesquisa por nome de arquivo, ele já sabe buscar algo como o algoritmo de Levenshtein, pra fuzzy matching, por exemplo.

Buscar e listar imagens em um grid, fazer upload pra S3, procurar e substituir texto, preview em HTML, etc. Tudo isso é super bem documentado e trivial de fazer. Mesmo sem LLMs, qualquer estagiário encontraria no primeiro link no Google e no Stack Overflow. Portanto, eu diria que mais de 90% do escopo foi fácil. Um aplicativo com um escopo mais desconhecido — digamos, um aplicativo de uso científico — teria sido bem mais difícil. Então este meu exemplo é só um pouco acima de um Hello World: repetir um escopo bem conhecido, que já existe.

Diferente do que fiz no meu artigo do primeiro exemplo de Vibe Coding, desta vez eu não vou comentar commit a commit; são mais de 130! Ficaríamos aqui a semana inteira. Em vez disso, vou comentar alguns temas que me chamam mais a atenção e que podem ser relevantes pra outros projetos.

Escolha bem seus planos de LLM

Durante os 3 dias, eu fui interrompido pelo Claude Code umas 2 ou 3 vezes e tive que usar outra coisa por 2 ou 3 horas. Isso porque ele tem algum limite diário de tokens e me manda parar depois que eu uso tokens demais.

Estou usando o Plano Max (5x Pro), que acho que custa uns USD 100, ou seja, cerca de USD 6 por dia. Nesse caso, foi barato porque 3 dias custariam só USD 18.

Mas num desses intervalos, mudei pra usar Claude Opus via OpenRouter, e isso foi BEM mais caro. Fora do plano Max exclusivo do Claude Code, o custo por token é absurdamente maior. Em umas 2 ou 3 horas, já consumiu mais de USD 100 (o equivalente à mensalidade toda!)

Ou seja, no total, por usar o plano Max fora, acabei gastando mais de USD 120. Mas se tivesse só parado pra descansar entre os limites diários, teria gasto um dia a mais (não teria ficado doente 😅) e não teria ficado muito além de USD 20. Portanto, precisa pesquisar bem os planos de cada plataforma antes de sair usando sem pensar, como eu nem. 😂

Como já cansei de falar: na dúvida, use o Claude Code com o plano Max.

Escolha bem sua arquitetura

Quando comecei a codificar (sempre que falar “eu codifiquei”, leiam como “eu vibe codei”, claro), o início foi bem rápido. Eu decidi poucas coisas técnicas: queria que fosse Ruby on Rails 8, queria que usasse Tailwind CSS, queria que não usasse nenhum banco de dados e implementasse tudo com base em sistemas de arquivos, queria que não tivesse autenticação, já que seria self-hosted pra uso somente meu.

Os primeiros 10 commits levaram pouco mais de 1 hora e meia. Fui adicionando funcionalidades pouco a pouco pra dar “forma” ao editor e, nesse ponto, eu já tinha um editor mínimo, bonito, com tema dark, que editava e exibia uma preview em html. Nada mal pra um protótipo.

Como falei no outro artigo, esse seria um dos pontos de “já funciona”.

Mas claro, ainda faltam mais de 120 commits pra realmente funcionar e quase 30 horas pra chegar no “funciona de verdade”.

Fui adicionando várias pequenas funcionalidades, nesta ordem:

• Adicionar um cheat-sheet de Markdown (help)
• Dialog box pra adicionar fenced code blocks com autocomplete de linguagem
• Sistema de temas, já adicionando uns 10 temas (mas ainda não ajustado pro Omarchy)
• Dialog box pra customizar fontes
• Controle de zoom no Preview
• Primeira tentativa de “typewriter mode” (isso vai dar muita dor de cabeça ainda)
• Dialog box de pesquisar arquivos por path com fuzzy finder
• Primeira tentativa de sincronizar o scroll do editor e preview (isso também ainda vai dar muita dor de cabeça)
• Dialog box de pesquisar arquivos por conteúdo com suporte a regex
• Dialog box de pesquisar e embedar videos de YouTube
• Dialog box de pesquisar imagens, upload e inserir
• Suporte inicial a Docker

Isso completa os primeiros 34 commits e cerca de 4 horas de trabalho. Novamente, muito próximo do “já funciona”.

Mas a diversão começa no commit 7bbf03a, intitulado: “Refactor to Restful Architecture”.

Isto é uma coisa específica de Rails e de arquitetura em geral. O Claude, sem eu ter instruído, fez exatamente o que eu esperaria que um estagiário em Rails fizesse: embutiu toda a lógica de gerenciar diretórios e arquivos, upload de imagens e tudo mais em 2 ou 3 módulos de serviço.

Também fez todas as rotas manualmente. Ou seja, não usou a coisa mais básica de Rails: o conceito de Restful Resources. Leiam o guia no link; não vou explicar o que é isso aqui, só que qualquer pessoa experiente em Rails sabe disso de olhos fechados.

Portanto, ele criou rotas como “http://localhost:3000/notes” mas não habilitou ter coisas como “http://localhost:3000/notes/hello” automaticamente abrir o “hello.md” e que verbos de HTTP como PATCH pra atualizar o arquivo ou DELETE pra apagar o arquivo. E também, sem a opção de GET, eu não teria a opção de fazer um bookmark direto de um arquivo. Tudo isso sai de graça se usar o RESTful. Então esse commit foi o refactoring em que eu o instruí a refazer tudo nessa arquitetura. Só isso foi quase 1000 linhas adicionadas.

O “correto” seria ter, logo no começo, configurado um arquivo CLAUDE.MD ou CONTRIBUTING.MD ou similar com as regras específicas de arquitetura e convenções de código - mas eu não fiz, então fica aqui o lembrete pra vocês. 😅

Refactoring e Fixes

Depois desse primeiro grande refactor, voltei a fazer ajustes (fixes ou consertos) e continuar adicionando novas funcionalidades:

Neste ponto já cruzamos 47 commits e mais de 8 horas non-stop. E sim, eu não tirei o olho do monitor. Não dá pra ler 100% de tudo o que o Claude fica pensando e fazendo; é muita coisa, mas, no geral, já notei que precisa ficar batendo o olho e, principalmente, prestando muita atenção!

O tempo de processamento de múltiplos agentes em paralelo, muitos em modo de reasoning/thinking é muito demorado mesmo. O Claude é um dos mais rápidos entre os outros, mas, na prática, eu acho sofridamente demorado.

Depois do almoço, resolvi abrir um YouTube do lado enquanto esperava o Claude terminar as tarefas. Significa que eu não prestei atenção e só batia o olho se ele terminava com “sucesso” ou se me pedia alguma permissão pra executar alguma coisa.

Não lembro se foi neste ponto, mas aí fui dar uma olhada no que ele tinha gerado e, claro, a essa altura já tinha um application.css de mais de 1000 linhas, que mandei consertar neste commit e ele quebrou um único arquivão em todos estes aqui:

Até os temas: estava tudo num único arquivo!! Esse é o nível que eu chamaria de “estagiário”. Como tudo “funciona”, vai só acumulando código, tudo no mesmo lugar, e deixa pra se preocupar com isso depois. Todo estagiário faz isso no começo se ninguém ensinar, e a LLM, pelo visto, faz do mesmo jeito. Ele não tenta fazer nada proativamente que você não pediu explicitamente. De fato, eu nunca disse no prompt “lembre-se de ir quebrando em pequenos arquivos”, mas deveria.

Mas esse não foi o pior. Não, senhor, neste commit está todo o Javascript, NUM ÚNICO ARQUIVO. Eu acho que já tinha passado de 4 mil ou 5 mil linhas. Olha só em quantos arquivos ele quebrou, nem cabe tudo nesta foto:

O problema é que eu mesmo caí no que estou criticando aqui. Eu pedia pra adicionar uma nova funcionalidade, dava “reload” no navegador e voilá lá estava a funcionalidade nova! “FUNCIONANDO”!! (Ruby on Rails é muito produtivo!)

E assim fui, adicionando “funciona já”, adicionando, “funciona já”, quando fui ver, show de horror!!

No último refactoring estávamos na marca de umas 9 horas de trabalho. Aqui já terminamos o dia; estamos no dia seguinte e, tirando o tempo que eu dormi, já estamos em 17 horas, 70 commits. Mais ou menos na METADE do projeto.

Tudo isso pra dizer o seguinte: a MAIOR parte de Vibe Coding, sempre vai ser REFATORAÇÃO e consertos de bugs e adicionar TESTES!

I18n - Internacionalização

Eu me adiantei um pouco; antes do mega-refactoring de Javascript, ainda tinha feito outro mega-refactoring antes: pedi pra ele extrair todas as strings em inglês e já me traduzir uma opção em português do Brasil. Mais um commit gigante de mais de 1600 linhas modificadas.

Quis fazer uma seção separada só pra comentar isso porque este é um dos pontos em que eu acho que LLMs brilham. Eles foram inicialmente feitos justamente pra lidar com linguagem natural e traduções. LLMs são muito bons em línguas. Antigamente eu precisaria passar pelo Google Tradutor, que sempre foi bem ruim, e depois achar alguém nativo da língua pra ajustar termos que o Google traduziu errado.

Como esperado, depois de extrair tudo, mandar ajustar os testes pra levar i18n em consideração e ver que o português estava funcionando, saí adicionando outras de brincadeira e fiquei muito satisfeito com o resultado. I18n é definitivamente algo que não faz sentido fazer sem LLM hoje em dia. É de ordens de grandeza melhor do que o jeito antigo.

A Última METADE

Do último grande refactoring até o fim, são mais uns 70 commits e aproximadamente 14 horas, o fim do segundo e do 3º dia, com intervalo de umas 15 horas no meio onde eu fiquei com febre e tive que me jogar na cama e me entupir de remédios… mas tudo bem, na manhã seguinte melhorei um pouco e aí terminei!

Daqui em diante, fui adicionando o resto das features, como emoji, emoticons, find and replace dialog, jump to line dialog, ajustes no sistema de configuração (via envs, via .fed) e Docker.

Uma coisa que não falei antes, mas que veio antes do esforço de I18n, foi um REBRANDING. Isso é outra coisa em que LLMs são muito boas pra resolver: substituição de texto, sabendo diferenciar textos, variáveis e código em geral. Eu não tava muito inspirado e, no começo, ia fazer um editorzinho web MUITO mais simples do que o que acabou ficando, e ia chamar só de “WebNotes” mesmo.

Mas quando cresceu e decidi que valia a pena compartilhar publicamente, resolvi dar um nome de verdade pra ele. Daí nasceu “FrankMD”. Só que não basta só dar nome; agora tem que sair renomeando TUDO dentro do código, strings, documentação, etc. Foi neste commit: umas boas 700 linhas de modificações.

Agora “funciona??”

Estou escrevendo este artigo às 17h de domingo. Às 19:25 de sábado, mandei no Discord pra uns amigos testarem, inocentemente achando que já tinha chegado à versão 1.0.

E lá vou eu, com febre precisando deitar, mas querendo chegar no 1.0!!

As issues em si matei rápido, mas Syntax Highlight eu não sabia que ia virar um inferno na minha vida. A primeira versão saiu rapidinho, neste commit

Não Reinvente a Roda (duh)

Sim, é o clichê mais óbvio de todos, mas até eu cometo esse erro. Como falei no começo, minha expectativa com esse projeto era ser pouco mais do que um “Notepad” Web pras minhas anotações, e acabou virando o editor principal pro meu blog.

A parte do editor de textos começou com a primeira coisa que funciona primeiro: um mesmo textarea mesmo.

Mas no sábado eu queria colocar uma coluna de contador de linhas, que leva em consideração o wrapping das linhas, controle desse wrapping, modo typewriter sempre centralizado no meio da tela e sincronização do scroll do editor de texto com o preview.

Sem contar todos os dialog-boxes que adicionam coisas ao texto, como imagens, vídeos, código e tabelas. Sem contar os shortcuts pra coisas como bold, italic. Sem contar rotinas de auto-save, estatísticas de contagem de linha, linha atual, etc.

Pra quem não sabe, o problema de syntax highlight é que não dá pra editar direto no texto colorido (porque ele tem tags escondidas que formatam o texto). Uma das formas de resolver isso é duplicar o bloco de texto: um no background, que é o texto cru e você pode editar como quiser, e outro bloco formatado e colorido com html exatamente em cima, que você não mexe, mas ele atualiza com o que for editado. Foi assim que o Claude fez.

Mas tem UM MONTE de “edge cases”: problemas de alinhamento por conta de wrapping, problemas com tamanho e posição pra ajustar o sync do auto-scroll. Levei horas e horas brigando com isso. Olha o tipo de problema que eu estava lidando:

Tudo se resolveu quando decidi: chega. Estou reinventando a roda. Obviamente esse problema já foi resolvido. Então pedi ao Claude pra remover toda a lógica ligada ao textarea customizado e substituir por Code Mirror, que é um componente open source pra editor de código, com suporte a contagem de linha, syntax highlight e muito mais!

Não foram só esses 5 commits; foram os principais. Levaram umas boas 3 horas ou mais pra estabilizar esse código e múltiplos ajustes pequenos ao longo de mais commits. Umas boas 6.000 linhas de código modificadas. É o tipo de refactoring que, num projeto real, teria levado a semana inteira e, ainda assim, teria saído com vários bugs e efeitos colaterais. Mas, pra isso, a LLM também é muito boa. Grandes refactorings, especialmente se você preparou uma boa suite de testes automatizados, vão bastante bem com LLMs.

Isso é o tipo de coisa que acontece em projetos de verdade. Não posso culpar a LLM, é totalmente culpa de eu ter mudado os requerimentos do projeto: originalmente não ia ter syntax highlight!

Testes, testes, testes

As principais recomendações de como fazer vibe coding são as mesmas de como programar do jeito antigo:

• Cuidado com a escolha de arquitetura (sim, exige experiência)
• Faça pequenas funcionalidades de cada vez, cada uma com abstrações corretas e imediatamente com testes
• Refatore de tempos em tempos pra consolidar ou abstrair código nos domínios corretos, ajustando e criando mais testes

Se seguir esses 3 itens, já ajuda muito. Não é mágica: tudo isso são ferramentas que dão feedback à LLM pra ela saber o que fazer.

Se você é aquele tipo de cliente anta que só fala “ah, parou de funcionar” - você não serve pra falar com um programador, e sinto dizer que LLMs não vão te ajudar também:

• O “QUE” parou de funcionar?
• Tudo parou de abrir?
• Somente um elemento desapareceu?
• O elemento aparece, mas ao clicar não acontece nada?
• Dá pra clicar, mas aparece uma mensagem de erro?
• Que mensagem exatamente?
• O que você fez antes disso?
• Mudou alguma coisa do teste anterior pra este?
• etc

TUDO ISSO e mais tem que estar no próximo prompt pra correções. Incluindo logs do servidor, linhas de comando pra reproduzir o erro e toda a evidência que puder ser produzida, pra facilitar o entendimento do erro.

Não existe “parou de funcionar” — sua cabeça que nunca funcionou.

Uma coisa de que gostei muito do Claude foi quando apareceu um bug que antes não existia, mas não sabia se tinha sido no último commit ou em uns 3 commits pra trás. E em vez de chutar coisas aleatórias, o próprio Claude ofereceu pra fazer, manualmente, o equivalente a um git bisect e foi me oferecendo um commit de cada vez pra testar e continuar até acharmos em qual o erro foi introduzido:

Otimizações e Checagens

Ao longo do projeto, umas 2 ou 3 vezes eu parei especificamente pra checar coisas como leaks de memória e buracos de segurança. Mesmo sendo um projeto pessoal, eu não queria buracos muito óbvios.

Já fiquem avisados de que Claude é campeão em fazer um monte de setTimeout em Javascript e não dar clearTimeout em nada!

Não é muita coisa, mas eu tive mais de um commit pra apagar “Dead Code”, que é código morto: código que, numa refatoração, foi movido pra outro módulo, mas se esqueceu de apagar da origem. As LLMs sempre vão deixar sobrando dead code, porque não têm como olhar 100% de todos os arquivos 100% do tempo. Eventualmente ele perde uma coisa ou outra. E não vai causar nenhum bug óbvio. Tem que ir tirando aos poucos, depois de cada refatoração.

Quando comecei a testar de verdade, com textos longos, notei que a interface estava com “lag”, meio devagar. Duas coisas pareciam estar afetando: a contagem estatística de quantas palavras e caracteres o texto tem estava muito agressiva.

Novamente “Funciona já” … mas devagar …

Pior, quando mandei criar o editor de texto pela primeira vez, não disse exatamente como queria que fosse o “auto-save”. Então ele fez do jeito mais conservador, agressivo e lento de todos: pra mandar salvar tudo a cada tecla digitada!!!

Tinha várias outras coisas como não atualizar o Preview HTML se não estiver aberto e coisas assim.

LLMs não vão fazer o código mais performático logo de cara; você precisa pedir como!

Performance é sempre um trade-off. Por exemplo, se eu deixar o mais rápido possível, o resto pode acabar super inseguro. Se eu aumentar a segurança demais, derruba a usabilidade. Se aumentar demais a otimização, derruba a manutenibilidade do código. Não existe como fazer tudo perfeito: um sempre vai afetar negativamente o outro e só um programador experiente sabe como escolher (ou ir na tentativa e erro até acertar, pro caso específico).

De novo, não é “culpa” da LLM; isso é normal em qualquer projeto e temos que ficar o tempo todo ajustando essas coisas.

Agora sim, chegando ao fim

Ainda sobrou muito débito técnico. O arquivo app_controller.js ainda tem mais de 2.000 linhas. Isso já é DEPOIS que eu gastei umas boas 3 horas refatorando só ele. Agora tem aproximadamente 28 controllers em JavaScript, mas antes tinha somente um arquivo.

Além disso, as LLMs não conseguem ser consistentes o tempo todo, especialmente quando o código do projeto aumenta muito. Teve um tipo de funcionalidade que ele sempre fazia server-side, mas depois resolveu fazer client-side. Eu tive que interromper e falar: “ow, por que?”, daí ele refez do jeito certo:

Todo código feito sem assistência humana nenhuma SEMPRE sai na pior qualidade de código possível. Com minha assistência, acho que o código está minimamente apresentável. Vocês mesmos podem checar no meu repositório no GitHub.

Recomendo que fucem os commits: pelo menos uma coisa que as LLMs fazem bem é documentar o histórico do que foi modificado naquele commit, o que facilita muito pra pesquisar depois.

Teve um bug em que o Claude ficou em loop, fazendo tentativa e erro, pra descobrir quando meu CSS quebrou do nada. Ele mudava alguma coisa e me mandava testar; eu reiniciava o server, dava force reload e nada: quebrado.

Era sábado à noite; eu estava cansado e meio febril, mas aí que me caiu a ficha. Eu tinha feito uma besteira antes. Coloquei “notes/” no .gitignore, que era o diretório onde estava criando arquivos Markdown de teste no editor e não queria que commitasse.

Porém, isso também passou a ignorar diretórios como app/views/notes/..., por exemplo. E nem eu nem o Claude sabíamos disso, mas quando mandei ele pesquisar, voilá:

Tailwind build obedece ao .gitignore então tava cagando a compilação de CSS. 🤬

Quando consertamos isso, passou a funcionar, mas aí já passaram 2 horas!

Como falei, você precisa estar esperto nos erros, ver por que a LLM tá fazendo tanta tentativa e erro, fazendo e desfazendo no mesmo lugar e não chegando a lugar algum. Isso não é incomum e pode passar metade do seu dia nisso, se não prestar atenção.

Conclusão

Quando comecei a fazer isso sexta de manhã, imaginei:

“Ah, um dia inteiro de trabalho deve ser suficiente.”

E como sempre, toda estimativa é subestimada. Agora já é domingo, fim do dia, e só agora eu acho que cheguei perto da versão 1.0. Ainda não está perfeito, mas acho que está minimamente apresentável.

Lembrando que eu fiz isso no meu ritmo de extremo hiperfoco, quando eu quase nem pisco, meus olhos ressecam e começo a enxergar tudo embaçado, até a cabeça começa a doer um pouco de tanto ficar tenso, concentrado numa coisa só. Não é um estado que eu recomendo.

Mesmo essas 30 horas em 3 dias, o correto seria 30 horas ao longo de, pelo menos, 5 dias.

Se eu tivesse deixado o Claude fazer tudo sozinho, sem checar nada, teria levado metade do tempo e, no final, teria um código “que funciona”, mas inusitado, com um único arquivo css de umas 2000 linhas, um único arquivo JS de umas 8 mil linhas, tudo com ZERO testes e tudo parecendo um castelo de cartas onde se mexe numa coisa pequena e quebra 10 outras coisas sem saber por quê.

No geral, foi um bom experimento. Sabendo como e onde usar, LLMs são excepcionais. Como disse no começo, sem a LLM eu teria levado mais de 200 horas pra fazer sozinho. Mesmo sofrendo vários perrengues no meio do caminho, levei só 30 horas. Então a LLM realmente me fez trabalhar pelo menos 6 a 7 vezes mais rápido, talvez mais.

Finalmente eu sinto que chegamos ao elusivo “Developer 10x”. Basta que você seja sênior primeiro.

Pra acabar, um mini-relatório do Tokei:

Breakdown by language:
┌─────────────────┬───────┬────────┬────────┐
│    Language     │ Files │ Lines  │  Code  │
├─────────────────┼───────┼────────┼────────┤
│ JavaScript      │ 137   │ 26,621 │ 19,922 │
├─────────────────┼───────┼────────┼────────┤
│ Ruby            │ 60    │ 8,449  │ 5,883  │
├─────────────────┼───────┼────────┼────────┤
│ YAML            │ 10    │ 3,477  │ 2,867  │
├─────────────────┼───────┼────────┼────────┤
│ Ruby HTML (ERB) │ 33    │ 2,927  │ 2,634  │
├─────────────────┼───────┼────────┼────────┤
│ CSS             │ 29    │ 1,619  │ 1,297  │
├─────────────────┼───────┼────────┼────────┤
│ Markdown        │ 1     │ 716    │ -      │
├─────────────────┼───────┼────────┼────────┤
│ HTML            │ 5     │ 369    │ 329    │
├─────────────────┼───────┼────────┼────────┤
│ Dockerfile      │ 1     │ 88     │ 46     │
├─────────────────┼───────┼────────┼────────┤
│ Other           │ 6     │ 145    │ 76     │
└─────────────────┴───────┴────────┴────────┘
The codebase is primarily JavaScript (60%) and Ruby (17%) by code volume.

Portanto, aproximadamente 33 mil linhas de código. Isto é um projeto PEQUENO! Projetos grandes são 10 vezes maiores, com mais de 300 mil linhas de código. Eu chutaria que num iFood ou Mercado Livre da vida, com todos os subsistemas, é mais de 1 milhão de linhas de código. Arrumem suas expectativas!

Eu falo isso faz anos: eu GOSTO das LLMs, uso bastante desde que foram lançadas e nunca tive problemas com elas. Meu problema é só balizar as expectativas IRREAIS dos “normies”, não-programadores: nunca vai sair um app como este com poucos prompts e sem saber exatamente os componentes e técnicas pra usar por baixo.

Desta vez, decidi resolver outro probleminha que tava no meu todo-list faz tempo: ter um web app de anotações self-hosted (pra colocar no meu home-server. Ao longo dos anos, já usei de tudo: Evernote, Notion, Obsidian, entre outros, mas nenhum deles realmente me agrada. Então, por que não fazer o meu próprio exatamente como eu quero?

Vou dividir este tema em 2 artigos: neste primeiro, vou falar exclusivamente sobre o meu aplicativo; no segundo, vou falar sobre o processo de vibe codar com o Claude. Spoilers: levou 3 dias inteiros (aproximadamente 30 horas). 137 pull requests! Aguardem o post-mortem.

O Problema

No geral, é só frescura minha mesmo. Guardar anotações não é pra ser complicado: cria um diretório aí na sua máquina, abre o LazyVim, o VSCode ou qualquer outro, e acabou: edita os Markdown em código puro e seja feliz.

Enfim, recentemente estava usando apenas o Obsidian num diretório compartilhado no meu Dropbox. Assim, eu poderia acessar do meu celular, se precisasse. Mas é um saco porque se eu estiver em outro PC, preciso ter o Obsidian ou outro editor instalado. Se tiver plugins, também preciso instalar.

Na prática, qualquer outro editor de textos serviria: são só arquivos de texto, mas a inconsistência de ter algo diferente em cada lugar e desconfigurado me desmotiva a escrever.

Em particular, estava usando Obsidian e, depois, LazyVim pra editar os posts do meu blog, que também são em Markdown. E aqui tenho um conjunto maior de problemas:

• tem path específico e frontMatter do Hugo; tomar cuidado com o título pra gerar o slug correto, etc.
• tem imagens/screenshots que fico manualmente subindo no S3, pegando a URL e colando no post
• evito usar tabelas porque é um saco “desenhar” tabelas direto em Markdown
• fico com abas de Google Images, youtube, etc aberta pra poder ficar pegando links, alt-tab, e colando
• não tem um bom preview, então eu deixo passar muito errinho (url de imagem duplicada, por exemplo)
• não tem um bom corretor ortográfico, então passa muito errinho que depois tenho que ficar corrigindo

Eu queria resolver esses problemas tudo num lugar só: um editor bonito como o Obsidian, que resolvesse todos esses inconvenientes e me deixasse só focar no meu texto.

FrankMD

Frank Rosenblatt foi o criador do Perceptron em 1957, o que deu origem às redes neurais modernas. Como eu fiz este editor totalmente com IA, resolvi homenagear o Frank.

Por isso, nomeei de Frank Markdown ou Frank Editor (fed). Este editor tem todo o básico que você esperaria em qualquer editor:

• syntax highlighting
• HTML preview
• facilitadores pra formatar markdown (Ctrl-B pra bold, por exemplo)
• customizar família e tamanho de fontes

Mas aí eu fui adicionando algumas coisas específicas do meu gosto pessoal e/ou que facilitariam minha vida pra editar os posts do meu blog. Vamos lá.

Inserção de Imagens

Esta é uma parte importante pra mim. Quando faço posts sobre código, sempre fico tirando fotos de tela do meu terminal ou do editor pra ilustrar. O processo é um print screen que manda pra ~/Pictures/Screenhots. Eu abro o Nautilus (estou no Linux) e executo um scriptzinho que fiz pra subir essa imagem num bucket no meu AWS S3. Copio o link gerado e adiciono ao meu post.

É “chatinho” toda vez fazer assim. Além do mais, às vezes eu gostaria de redimensionar a imagem pra ficar mais otimizada. Mas isso significa ir ao terminal e rodar magick screenshot.png -resize 50%, o que é mais um passo manual.

Então decidi fazer um dialog-box com várias opções pra isso.

Por padrão, posso configurar um diretório principal de imagens no meu PC e ele vai exibir um grid limitado a 10 dos mais recentes. Ou posso filtrar por nome. Tem opção pra linkar diretamente (caso eu queira subir a imagem junto com o html) ou servir do S3 e ele vai copiar o link gerado automaticamente (que é o que prefiro).

Mesma coisa pra imagens na Web (Google, Pinterest), onde posso escolher fazer download, redimensionar e subir no S3:

E o link vai ser no formato esperado ...amazonaws.com/frankmd/...jpg. Tudo bonito, fácil e prático! Pra mim, isso ajuda muito!

É um extra, já que não poderia deixar de integrar uma IA; a última aba é pro Nano Banana:

Nano Banana é bem impressionante mesmo. olha o que esse prompt gerou:

Mais importante ainda: posso ver o preview imediatamente (ctrl-shift-v) pra saber se inseri a imagem correta (coisa que eu errava muito editando pelo NeoVim, sem ver):

Pra mim, estes assistentes de inserção de imagem são os que vão me ajudar mais pra editar meus posts no blog.

Facilitadores de Markdown

Mais simples que uma imagem é embedar um player de vídeo. Posso ou passar um link qualquer com um arquivo .mp4 da vida, ou posso diretamente pesquisar no YouTube e embedar corretamente:

Ele vai inserir o HTML correto, <embed ..., com a URL e o título corretos.

Também fiz um jeito fácil de adicionar e editar tabelas:

E vai gerar o Markdown direitinho. Nunca mais preciso ficar editando essa porcaria na mão pra reajustar colunas ou linhas.

| Cabeçalho 1 | Cabeçalho 2 |
| ----------- | ----------- |
| Linguagem   | Nota        |
| Ruby        | 10          |
| JS          | 5           |
| Rust        | 6 😂        |

Mas se quiser fazer manualmente, também tem como:

Isso eu coloquei mais porque ficaria estranho omitir, mas, em geral, prefiro escrever blocos de código manualmente mesmo. Mas tá aí pra quem quiser um modo visual.

Daí, claro, tinha que ter um jeito fácil de editar Emojis 😆 (ctrl-shift-e):

Mas o que ninguém esperaria é que eu também oferecesse suporte a Emoticons!! ☆:.｡.o(≧▽≦)o.｡.:*☆

Customização

Falando em Emoticons, me lembra que eu quis fazer este editor ser infinitamente customizável. Por exemplo, claro que adicionei internacionalização e tem japonês!!

E mais outras línguas também; deem uma fuçada depois. Tem português também!

“Qual a melhor fonte pra programação?”

Sei lá! Por isso adicionei várias pra escolher:

Como uso Omarchy então também queria que meu editor tivesse suporte a exatamente os mesmos temas:

No README tem documentado tudo o que dá pra customizar. Dá pra customizar várias coisas via variável e ambiente e também via um arquivo .fed, criado automaticamente no diretório onde se abre este editor. Tem bastante coisa, então recomendo fuçar.

Foco no Texto

Obviamente eu incluí um “Typewriter Mode” que mantém meu cursor mais perto do meio da tela e centraliza o editor e, ao mesmo tempo, esconde todas as distrações.

Eu normalmente prefiro TUIs, mas tenho que admitir que usar um navegador tem a vantagem de me dar acesso a extensões. A mais útil sem dúvida é Grammarly, pra qualquer língua:

Mas, além disso, eu adicionei um botão de “IA” no toolbar (que é configurável via ENVs e um arquivo de configuração — leia o README). E ele faz isto:

Manda pro seu LLM de preferência (Ollama local, OpenAI, Anthropic, OpenRouter, etc.) com um prompt pra não reescrever seu texto, somente checar gramática, ortografia e erros desse tipo. Daí eu devolvo uma interface de “diff” pra comparar e aceitar, editar ou cancelar.

Eu acho que o Grammarly sozinho já é suficiente, mas não custava nada fazer esse, então fiz.

Hugo Blogging

Este blog é feito com Hextra/Hugo. Por isso, queria já embutir um jeito fácil de criar novos artigos no Hugo. Isso começa já na opção de criar um novo documento:

E ele já cria com o frontMatter, geração automática de slugs, subdiretórios timestamped e tudo mais:

Como falei, este editor foi feito principalmente pra facilitar o meu workflow.

Self-deploy vs CLI

Originalmente pensei neste projeto pra ser um Notion-light ou algo assim. Um editor web que fizesse deploy no meu home server e servisse apenas como organizador, um lugar pra colocar anotações maiores do que um post-it (tipo histórico de configurações do meu Linux, passo a passo de comandos, etc.).

Mas enquanto ia construindo o app, mais e mais ele foi ficando maior e mais parecido mesmo com um desktop app. Mas aí já era tarde demais. Eu queria usar Ruby on Rails 8 (pra me desenferrujar e porque eu gosto). Mas só na metade pensei que deveria ter feito em Node, porque agora não posso mais embutir num app do Electron.

Tudo bem, a ideia é ser um editor de Markdown pra programadores. Todo programador tem Docker. Então encapsulei numa funçãozinho de shell e posso só chegar em qualquer diretório no meu Linux digitar:

cd ~/Projects/akitaonrails-hugo
fed .

Leia o README do projeto para saber como adicionar ao seu .bashrc. E fazendo assim, vai funcionar no meu Omarchy igualzinho a qualquer outro app nativo:

Na realidade, vou usar ambos os jeitos: como se fosse um app nativo. E como self-hosted, pra organizar um lugar central com minhas anotações — que vai ser diferente de onde organizo meus posts de blog. Então tem múltiplas utilidades mesmo.

Conclusão

Eu resumi as funcionalidades; há várias pequenas coisinhas que vocês vão descobrir à medida que começarem a usá-las. Tudo é clicável; se clicar no título do app, tem um About:

Botão direito em cima do texto selecionado tem um sub-menu de formatação; Ctrl-I funciona pra itálico; Ctrl-H tem “find and replace” básico; tem um monte de combinações de teclado pra acessar as coisas.

Ah é, nem falei que tem como pesquisar rapidamente arquivos por nome ou por conteúdo usando Ctrl-P e Ctrl-Shift-F:

Pra garantir que tudo está funcionando, este artigo aqui já foi escrito inteiramente com o meu novo editor. E diria que, se não está perfeito (pra mim), está nos 99%. Fiquem à vontade pra abrir Issues com bugs ou features que fariam sentido — lembrando: a ideia não é substituir o VSCode e ter TUDO. Eu preciso que tenha só o SUFICIENTE.

Considerando que me custou 3 dias de trabalho e que não escrevi nenhuma linha de código, o resultado é impressionante. Sim, editores de texto são aplicativos muito bem documentados e com vasto material de treinamento — por isso, o Claude conseguiu fazer sem problemas. Não se impressionem demais. Mas isso dito, sim, eu queria um editor customizado pro meu uso pessoal, que fosse bonito de usar, e ele conseguiu entregar, então estou satisfeito.

Não deixem de ver a PARTE 2 pros detalhes de como foi fazer isso.