Entre setembro de 2020 e dezembro de 2022 eu rodei mês a mês a série histórica de uma métrica de reputação que não existia antes da gente escrever. Não tinha fornecedor, não tinha paper pronto pra aplicar, não tinha campo na API do Google esperando pela resposta. Tinha uma necessidade de produto clara, um banco com milhões de avaliações e uma pergunta que a média aritmética não respondia.

O RRi morreu. E eu voltaria a fazer tudo de novo, porque o que ficou na empresa não foi o número, foi a capacidade de pegar uma necessidade de produto e atacar com matemática própria, do zero, sem esperar que alguém publicasse a solução primeiro.

A necessidade chegou sem métrica

Cliente enterprise de varejo físico não pergunta qual é a nota dele. Ele já sabe a nota. Ele pergunta onde agir na segunda-feira, em qual das centenas de lojas, e por quê.

Média de estrelas não responde isso, por dois motivos. O primeiro é tempo. Uma loja com 4,7 formada por avaliações de 2018 e uma loja com 4,7 formada por avaliações do mês passado são a mesma linha na planilha e não são a mesma loja. A primeira tem um estoque antigo que ninguém confere mais. A segunda tem gente entrando hoje. Quem opera loja sabe a diferença, e a média não sabe.

O segundo é volume. Loja com 12 avaliações e loja com 30 mil aparecem com a mesma autoridade numa tabela ordenada por nota. A lei dos pequenos números faz a nota de quem tem pouco volume chicotear: uma avaliação de 1 estrela num universo de 12 derruba a média em quase meio ponto, e no universo de 30 mil não move o terceiro decimal. Ordenar lojas por média é, em boa parte, ordenar lojas por tamanho de amostra.

A conclusão foi que a gente precisava de uma medida diferente, e que essa medida não existia pronta. Reputação não é média, é estoque. Um acumulado de tudo que já foi dito sobre a loja, com cada avaliação valendo menos conforme envelhece. Isso é uma frase de produto. Virar número é outra história.

Antes da fórmula, as propriedades

A parte da jornada que eu recomendo pra qualquer time que vá construir métrica própria é essa, e ela vem antes de qualquer símbolo: escrever o que a métrica precisa fazer, e escrever também o que vai atrapalhar.

O que a gente exigiu: refletir o estoque de reputação e não a média; decair a importância de cada avaliação no tempo; ter frequência diária, pra dar leitura acionável e não relatório trimestral; permitir agregação temporal e setorial, pra comparar loja com loja, setor com setor, e loja com o próprio setor; e considerar se a avaliação tem texto, porque avaliação escrita carrega informação que estrela sozinha não carrega.

E o que a gente sabia que ia atrapalhar: valor faltante em volume alto; heterogeneidade entre estabelecimentos; heterogeneidade entre setores, porque a régua de nota de restaurante não é a régua de nota de hotel; sazonalidade semanal, porque fim de semana avalia diferente de terça-feira; e interpretabilidade. Guarde esse último item, ele decide o final da história.

Essa lista de dez linhas fez mais pela métrica do que qualquer decisão técnica que veio depois. É ela que transforma “queremos medir reputação de verdade” em critério de aceite.

Com o tempo essa etapa virou uma ordem fixa, e é ela que eu sigo hoje em qualquer indicador novo. Escrever as propriedades desejáveis e os problemas esperados antes de qualquer símbolo. Montar a notação antes de abrir o editor de código, porque é na álgebra que erro de raciocínio aparece. Revisar a fórmula, e não o programa, até ela responder às propriedades uma por uma. Trocar todo chute de parâmetro por critério declarado, que pode ser discutido e reajustado quando a preferência da empresa mudar. E, no fim, sentar com quem vai receber o número e perguntar o que ele faz na segunda-feira com aquilo. Os cinco passos estão nas seções que vêm, na ordem em que eu aprendi cada um, quase sempre errando antes.

O primeiro rascunho, escrito à mão

Com as propriedades na mesa, escrevi a primeira versão. O peso de cada avaliação e o índice final ficaram assim, com $s_i$ o escore da avaliação, $\Delta t_i$ o tempo decorrido em dias até a data de referência, $N$ o total de avaliações do conjunto e $\tau_i$ valendo 1 quando a avaliação tem texto:

Cada pedaço responde a um item da lista. Média ponderada porque o acumulado tem que somar tudo. Peso caindo com o tempo porque avaliação velha importa menos. Logaritmo pra achatar escala. Bônus pra quem escreveu texto. E um dois no fim pra jogar o resultado numa faixa de 0 a 10, que é uma escala que soa mais natural pra quem lê dashboard.

Virou um microserviço em Go que, por motivos que a minha vaidade da época explica melhor que eu, se chamava Wolfram-Alpha. Ele expunha o índice em três níveis de agregação, estabelecimento, grupo e cliente, e passou a rodar em produção.

Esse é o ponto da jornada que eu quero destacar antes de contar o que deu errado: em poucas semanas a gente saiu de uma insatisfação com a média de estrelas pra um índice diário calculado sobre a base inteira, servido por HTTP, consumido por relatório. Sem contratar ninguém, sem esperar seis meses e sem comprar nada. Métrica própria é acessível. O caro não é começar.

O que a álgebra devolveu quando olhei de novo

O caro é revisar. E revisando aquela fórmula com calma, anos depois, dá pra ver três coisas que a intuição não pegou. Vale escrever porque são erros que qualquer um comete na primeira métrica.

O escore aparece dentro do próprio peso. Logaritmo é monotônico crescente, então avaliação de 5 estrelas pesa mais que avaliação de 1 estrela pelo fato de ser 5 estrelas. Numa loja com 5 avaliações, todas com texto, o peso de uma nota 5 fica 23,2% acima do peso de uma nota 1. A regra que eu levo daí é curta: a grandeza que você mede não pode aparecer no peso com que você a mede.

O $N$, que é o total de avaliações do conjunto, é a mesma constante pra todas as avaliações do cálculo. Somar constante de conjunto dentro de um logaritmo que deveria diferenciar itens individuais faz o escore sumir do peso conforme a base cresce: aquela diferença de 23,2% com 5 avaliações cai pra 0,83% com 100, 0,058% com mil e 0,0013% com 30 mil. O esquema de ponderação atua com força máxima onde a amostra é frágil e se dissolve onde ela é robusta, que é o inverso do desejável. Quantidade de conjunto e valor de item não se misturam na mesma expressão.

E o decaimento é $1/\Delta t$, hiperbólico. Avaliação de ontem pesa 365 vezes mais que avaliação de um ano atrás. Como o $\Delta t$ é float de dias, avaliação de seis horas atrás pesa quatro vezes mais que a de ontem, e o peso tende ao infinito quando o tempo tende a zero. Na prática o índice não media estoque, media as últimas 48 horas com uma cauda decorativa, o que contraria a primeira propriedade da lista que eu mesmo escrevi.

Nenhum desses três é erro de programação. Todos os três são visíveis na notação e invisíveis no código, e é por isso que hoje eu escrevo a fórmula antes de escrever a função.

Teve um quarto problema, e esse não estava na álgebra: uma linha de parsing de data em Go descartava o erro, o cálculo seguia com o instante zero e o decaimento desligava em silêncio, o que virava a média ponderada em média simples e continuava exportando número plausível. Não desenvolvo aqui porque não é matemática, é execução, e por isso virou post próprio. Do assunto deste texto ele leva uma frase só: métrica não tem teste de sanidade natural, então número errado não vira alerta, vira gráfico.

Quando a matemática de artesão virou econometria

O passo seguinte da jornada foi o mais valioso, e foi uma decisão de humildade: a Harmo encomendou um estudo formal pra reescrever o índice, com gente de econometria de verdade. O documento é proprietário e eu não vou reproduzir as equações, mas as correções de rumo são o que importa aqui, e elas mapeiam nos meus três pontos.

O peso passou a depender só do tempo. O escore aparece uma única vez, no numerador, onde ele é objeto da medição e não juiz dela.

O decaimento deixou de ser hiperbólico e virou logarítmico, na forma de um sobre o log do tempo. A diferença é grande na prática: no meu esquema, avaliação de um ano atrás carrega 0,0027 de peso relativo, praticamente nada; no esquema deles, 0,169, sessenta e duas vezes mais. Avaliação velha continua contando, cada vez menos, sem nunca zerar, que é exatamente o que a palavra estoque significa.

E o problema do volume foi atacado onde ele mora, na amostra e não no peso. Em vez de enfiar o $N$ dentro do logaritmo, o estudo define um número mínimo de avaliações pra loja entrar no índice, e escolhe esse número com critério explícito: padroniza desvio-padrão e perda de amostra na mesma escala, traça uma reta de indiferença cuja inclinação é um parâmetro de preferência declarado antes, e toma o ponto mais distante dela. Com preferência neutra, o corte cai em 29 avaliações acumuladas, custa 26,3% da amostra e leva o desvio-padrão mediano de 0,141 pra 0,055.

Essa última parte é a que eu mais admiro no trabalho deles, e é o tipo de coisa que dificilmente sai de dentro da engenharia. Eu tinha resolvido a questão do volume com um logaritmo. Eles resolveram com um critério de decisão declarado, que pode ser discutido, auditado e reajustado quando a preferência da empresa mudar. A diferença entre as duas abordagens não é sofisticação, é rastreabilidade da escolha.

O estudo ainda acrescentou um andar que eu não tinha imaginado: um índice de difusão, que compara cada loja com a média do próprio setor e responde qual porcentagem das lojas está acima dela, numa escala de 0 a 100 com 50 como neutro. Isso resolve de fato a heterogeneidade setorial que estava na minha lista de problemas, e permite comparar restaurante com hotel sem comparar nota com nota.

O produto morreu de interpretabilidade

E aí a métrica ficou correta e morreu de qualquer jeito, pelo item que estava na lista desde o começo.

Pense no operador do shopping recebendo a leitura. O RRi da loja dele é 4,42 e a difusão do setor está em 57. O que ele faz na segunda-feira com isso? A escala é nova, não tem faixa de alarme, não tem ação atrelada, e na série real a difusão vive num corredor entre 54 e 59 com ruído diário grande, então a variação que ele vê é indistinguível de barulho.

Compare com a frase que a gente usa hoje: a cada 0,1 estrela adicional, aparece em média uma diferença de 8,8% nos pedidos de rota. É a mesma família de estatística descritiva que eu já mapeei no post sobre as oito famílias de matemática, amarrada num número que o lojista já entende, a estrela, e num resultado que ele quer, gente entrando na porta. Nota é comparável com o concorrente da esquina, é auditável no Google, e todo mundo já sabe se 4,3 é bom ou ruim.

Métrica proprietária cobra um pedágio de aprendizado do cliente, e ela só se paga se, depois de aprender, ele souber o que fazer. O RRi cobrava o pedágio e não entregava a ação. Foi por isso que ele saiu, e não por erro de conta.

Uma ressalva de honestidade, porque ela importa num texto que fala de rigor: essa é a minha leitura, não ata de reunião. Não existe no estudo nenhuma linha dizendo que o índice saiu por interpretabilidade, e o desligamento não teve um dia com data marcada. O que eu afirmo aqui é o que eu vi de dentro. Se quem decidiu lembrar diferente, eu corrijo o post.

O que ficou depois que o produto saiu

Quatro coisas que sobreviveram ao RRi, e nenhuma delas é o número.

• O vocabulário. Reputação como estoque, e não como média, é uma ideia que continua orientando produto aqui. A frase sobrevive à fórmula que a originou.
• O critério antes do símbolo. Escrever as propriedades desejáveis e os problemas esperados, dez linhas, antes de qualquer notação. É o artefato mais reaproveitável da jornada inteira e serve pra qualquer métrica nova.
• A régua da notação. Os três problemas da minha fórmula eram todos visíveis na álgebra e nenhum era visível no código. Notação é onde erro de raciocínio aparece; código é onde ele fica escondido, rodando e exportando série histórica.
• A descoberta de que interpretabilidade era a restrição dominante, e não precisão. Isso custou uma métrica pra aprender e hoje é o filtro que aplico em toda proposta de indicador novo: se não vem com uma ação atrelada, é decoração.

Se o critério de sucesso fosse o produto continuar de pé, o RRi foi um fracasso. Mas a empresa saiu da jornada sabendo formular uma métrica própria, sabendo quando escalar isso pra econometria formal, e sabendo que sofisticação estatística não compra interpretabilidade. Isso não estava disponível pra compra, e não teria vindo de outro jeito que não tentando. Necessidade de produto que ninguém no mercado resolve é convite pra escrever a matemática você mesmo, e a conta fecha mesmo quando o resultado é desligado depois.

A conta dava 6,885. O valor certo era 11,385. A diferença, 4,5 exatos, não era erro de arredondamento nem de quadratura: era um termo inteiro que eu tinha deixado de escrever. Quase 40% da resposta desaparecida porque a derivada de uma integral tem três pedaços e eu só tinha somado dois.

Derivar integral de limites fixos é entediante: $\int_0^1 g(\tau) d\tau$ é um número, e derivada de número é zero. Fica interessante quando o $t$ que você está derivando aparece em mais de um lugar dentro da integral. O Teorema Fundamental do Cálculo cobre o caso em que ele aparece só no limite. A regra de Leibniz cobre também o caso em que ele aparece dentro do integrando, e os dois ao mesmo tempo, que é o que acontece de verdade quando você modela acumulação com memória.

Na forma geral:

Os dois primeiros termos são fronteira: eles medem o efeito de mexer a região de integração. O terceiro é interior: mede o efeito de a curva inteira mudar de altura.

Não vale decorar isso. Vale ver de onde sai, porque de onde sai é regra da cadeia, e aí os três termos param de ser arbitrários.

Parte I: os três termos são a regra da cadeia disfarçada

O truque é parar de ver a integral como função de $t$ e ver ela como função de três argumentos independentes. Define

e repara que o que você quer é a derivada de $H(t, a(t), b(t))$, uma composição. A cadeia entrega direto:

Agora os três pedaços, um por um. $\partial H/\partial v = g(t,v)$ é Teorema Fundamental do Cálculo puro: mexer o limite de cima acrescenta área na borda direita, e a taxa com que ela entra é a altura da curva ali. $\partial H/\partial u = -g(t,u)$ é o mesmo TFC com o sinal trocado, porque subir o limite de baixo tira área. Nenhum dos dois é novidade: você já sabia os dois antes de ouvir falar em Leibniz.

O único pedaço que é teorema de fato é o terceiro, $\partial H/\partial t = \int_u^v \partial_t g(t,\tau) d\tau$. Ele diz que dá pra trocar a ordem de duas operações de limite, derivar e integrar, e essa troca é justamente o que precisa de hipótese pra valer. É esse pedaço que se chama derivar sob o sinal da integral. A regra de Leibniz é ele mais dois termos de fronteira que já vinham de graça. E isso não é atalho didático meu: é assim que a prova é montada nas notas de Keith Conrad, com a versão de limites variáveis saindo como corolário da versão de limites fixos, aplicando a regra da cadeia exatamente a essa função de três argumentos.

A intuição geométrica fecha o assunto. Entre $t$ e $t+dt$ a integral muda por dois motivos independentes. A região de integração cresce, e nasce uma tira fina de área na borda, de largura $dt$ e altura igual ao integrando naquele ponto. E a curva inteira sobe ou desce, em todo ponto do interior, porque o integrando também depende de $t$. Pensa numa piscina que fica ao mesmo tempo mais comprida e mais funda: o volume novo é a fatia que entrou na ponta mais o que subiu no resto do fundo. Somar os dois efeitos é a regra.

As hipóteses, e onde continuidade deixa de bastar

A versão suficiente pra quase tudo é curta: se $g$ e $\partial g/\partial t$ forem contínuas num retângulo que contenha a região de integração, e $a$ e $b$ forem diferenciáveis, a fórmula vale. Num retângulo fechado a continuidade já dá limitação de graça, e é isso que faz a demonstração andar.

Em domínio infinito, continuidade não basta, e o contraexemplo é curto o suficiente pra caber numa linha:

Para todo $t > 0$ isso vale exatamente 1, e você confere na mão: a primitiva é $-e^{-tx}$, avaliada de 0 a infinito dá 1, e o $t$ cancela. Em $t = 0$ o integrando é identicamente zero, então $I(0) = 0$. O integrando é suave em $t$ para cada $x$ fixo, e mesmo assim $I$ é descontínua na origem. Derivar sob o sinal ali não produz erro pequeno, produz besteira: a função nem é contínua no ponto.

A massa fugiu. Conforme $t$ diminui, a exponencial se espalha e fica baixinha, mas a área não muda, só migra pra longe. Nenhuma função integrável fixa segura a família toda por cima, e é exatamente isso que a dominação pede. No enunciado que o Conrad usa, pra derivar num ponto $t_0$: $g$ e $\partial_t g$ contínuas, e cotas $|g(t,\tau)| \le A(\tau)$ e $|\partial_t g(t,\tau)| \le B(\tau)$ independentes de $t$, com $A$ e $B$ integráveis. Repara no detalhe que muda tudo na prática: essas cotas são pedidas só para $t$ num intervalo em volta de $t_0$. A dominação é local no parâmetro, não é um contrato que você assina para todo $t$ do universo.

E é condição suficiente, não necessária. A versão de Lebesgue, que sai da convergência dominada, cobra menos: basta $g(\cdot,t)$ integrável para um $t$ e a cota integrável em cima da derivada, $|\partial_t g(t,\tau)| \le B(\tau)$, numa vizinhança de $t_0$. A cota em $g$ você não precisa trazer, ela cai do teorema do valor médio aplicado à própria derivada. Fica a regra de bolso: em retângulo compacto a continuidade compra a dominação; em domínio infinito você traz a dominação de casa, e traz menos do que parece.

Um caso inteiro, com o erro medido

Pega um acumulador com memória logarítmica, que é a forma que aparece quando o passado pesa cada vez menos mas nunca zera:

O parâmetro \(t\) aparece nos dois lugares que interessam: no limite de cima e dentro do núcleo. É o caso completo da regra, com um dos termos de fronteira ativo.

Identificando as peças: $a(t) = 0$ com $a^{\prime} = 0$, o que mata o termo de fronteira de baixo; $b(t) = t$ com $b^{\prime} = 1$; e $g(t,\tau) = F(\tau)\log_2(2+t-\tau)$.

O termo de fronteira de cima é $g(t,t) \cdot 1 = F(t)\log_2 2 = F(t)$. Ele saiu redondo por construção: o núcleo vale exatamente 1 na diagonal. A derivada parcial do núcleo é $\partial_t \log_2(2+t-\tau) = 1/((2+t-\tau)\ln 2)$, e escrevendo $c = 1/\ln 2$:

A regularidade aqui é confortável: $g$ e $\partial_t g$ são contínuas no triângulo compacto $\lbrace 0 \le \tau \le t \le T\rbrace $ e o denominador nunca desce abaixo de 2. Nada perto de explodir, nenhuma dominação pra negociar.

Sobrou uma integral do mesmo formato, então aplica Leibniz de novo. O novo termo de fronteira é o núcleo na diagonal, $F(t)/2$, e a parcial do novo núcleo ganha um sinal negativo:

Agora a parte que interessa: conferir. Com $F(\tau) = 1 + \tau/2$ e $t = 7$, comparando a expressão de Leibniz contra a derivada numérica da integral obtida por quadratura de Simpson e diferença finita central:

Os dois erros são do método, não da fórmula. A coluna de Leibniz bate com a forma fechada da integral na décima quinta casa, então o que a tabela mostra é erro da derivada numérica, e ele erra pelo motivo esperado. Variando o passo, aparece o desenho de sempre: o erro da diferença central cai como $h^2$ até perto de $h = 10^{-4}$ e depois volta a subir como $1/h$, quando subtrair dois números quase iguais passa a custar mais do que a aproximação ganha. A diferença segunda faz a mesma curva, só que o ramo de arredondamento sobe como $1/h^2$. É por isso que os dois passos da tabela são diferentes, cada um perto do fundo da curva do seu método, e por isso a segunda linha erra mais mesmo usando passo cem vezes maior.

Todas as contas deste post estão num script de verificação em Python, só biblioteca padrão, que imprime método, discretização, valor esperado, valor obtido, erro absoluto e tolerância, e sai com código diferente de zero se qualquer verificação passar da tolerância justificada pro método dela: verificacao.py. São 23 verificações e roda em um segundo e meio.

E o número que abriu o post: esquecendo o termo de fronteira, $A^{\prime}(7)$ daria 6,885154864821 em vez de 11,385154864821. A diferença é 4,5 exatos, que é exatamente $F(7)$, o termo que ficou de fora. Não é erro pequeno, é 39,5% da resposta. E não podia ser pequeno: o termo de fronteira vale $g(t,b(t))b^{\prime}(t)$, uma quantidade da ordem do próprio integrando. Quem esquece ele não perde precisão, perde o resultado.

A segunda armadilha é mais boba e mais comum: usar a mesma letra para a variável de integração e para o parâmetro. Escrever $\int_0^t F(t) dt$ não é notação relaxada, é expressão sem sentido, e o efeito colateral pior é apagar a possibilidade de aplicar a regra. Se as duas coisas têm o mesmo nome, você não consegue nem perguntar qual está variando.

Onde isso aparece em computação

Nada disso é exclusividade de integral com primitiva fechada. A regra aparece em lugares que qualquer pessoa que escreve código encontra, e em dois dos três casos abaixo o termo de fronteira não é detalhe: é a resposta inteira.

O primeiro é a janela deslizante, que é o agregado mais comum de qualquer sistema de observabilidade. Soma dos últimos $W$ minutos é uma integral com os dois limites andando junto com o tempo:

O integrando não depende de $t$, então o termo interior é zero e sobra fronteira pura: o que entra na janela menos o que sai dela.

Conferi numericamente e bate na décima primeira casa. A consequência é conhecida de quem já pôs alarme em cima da variação de uma métrica de janela: cada pico produz dois eventos, um quando entra e outro, exatamente $W$ depois, quando sai. A queda que aparece uma janela inteira depois do incidente não é o sistema melhorando, é o segundo termo de fronteira entrando na conta com sinal trocado. O gráfico está certo e a leitura é que erra, porque a intuição trata a curva como se fosse o sistema quando ela é o sistema convolvido com a janela.

O segundo é o gradiente de uma esperança, que é o que treina boa parte de machine learning moderno. Otimizar a esperança de $f(X)$ sob uma densidade $p_\theta$, em relação a $\theta$, é derivar uma integral cujo parâmetro está na densidade, e a pergunta de sempre é se dá pra empurrar a derivada pra dentro. Quando o suporte não depende de $\theta$, dá, e o que sobra é a identidade que sustenta os estimadores de gradiente por amostragem, o mesmo movimento que aparece em policy gradient:

Essa identidade não é universal, e vale saber o que ela está cobrando: suporte independente de \(\theta\), regularidade suficiente pra trocar derivada com integral, e \(f\) sem dependência direta do parâmetro. Se o custo também depender, \(f_\theta\), aparece um segundo termo, \(\mathbb{E}[\nabla_\theta f_\theta(X)]\). A primeira das três hipóteses é a que quebra no exemplo seguinte.

Conferi com $X \sim N(\mu,1)$, $f(x)=x^3$ e $\mu = 1{,}7$: a identidade e a derivada numérica dão as duas 11,67, que é o valor fechado $3(\mu^2+1)$, com erro de $5{,}3 \times 10^{-15}$ e $2{,}2 \times 10^{-10}$.

Agora o caso em que o suporte depende do parâmetro, que é onde a coisa fica interessante. Tome $X \sim \mathrm{Uniforme}(0,\theta)$ e $f(x) = x^2$. A esperança sai na mão, e a derivada dela também:

Em $\theta = 3$ isso vale 2, e esse é o número a bater. Agora aplique a identidade de cima do jeito ingênuo: derive só a densidade, com $x$ fixo, esquecendo que o suporte também é função de $\theta$. No interior a densidade é $1/\theta$, então $\partial_\theta(1/\theta) = -1/\theta^2$, e a conta fecha em outro lugar:

O interior sozinho dá \(-1\) em \(\theta = 3\): não é imprecisão, é sinal trocado. Os 3 que faltam são o termo de fronteira, o limite de cima andando junto com o parâmetro. Somados, os dois devolvem o gradiente certo.

Vale desfazer uma confusão que eu mesmo já fiz aqui. É tentador culpar “autodiff ingênuo”, mas o autodiff não tem opinião: ele deriva o que você entregou. Se o que você entregou foi a densidade, e você derivou ela ignorando que o domínio se move, erra. Se o que você entregou foi o programa de amostragem, $X = \theta U$ com $U \sim \mathrm{Uniforme}(0,1)$, acerta, e acerta por um motivo que é o assunto deste post: a mudança de variável $x = \theta u$ tira o parâmetro da fronteira e coloca no integrando.

Com os limites presos em 0 e 1, não sobra fronteira nenhuma pra esquecer, o termo interior dá conta de tudo sozinho, e derivar $f(\theta u)$ é regra da cadeia de primeiro semestre. Esse é o gradiente pathwise, o truque de reparametrização. A diferença entre ele e o score function não é esperteza de implementação: é onde cada um deixa o parâmetro. O score function deixa $\theta$ na medida, e aí a fronteira móvel vira problema dele. O pathwise empurra $\theta$ pro integrando, e o problema deixa de existir.

Esse caso é o exemplo padrão da falha na literatura. Mohamed, Rosca, Figurnov e Mnih usam a mesma $\mathrm{Uniforme}(0,\theta)$, com $f(x)=x$, no survey de estimação de gradiente por Monte Carlo, e o diagnóstico deles é mais preciso do que “esqueceu um termo”: o score function assume continuidade absoluta, que $p_{\theta+h}$ seja positiva onde $p_\theta$ é, e essa hipótese quebra na borda exatamente quando o parâmetro define o suporte. Na conta deles o gradiente verdadeiro é $1/2$ e o estimador devolve $-1/2$. E quando eles refazem a mesma esperança por derivada de medida, a separação que aparece é literalmente a regra de Leibniz: $f(\theta)/\theta$ na fronteira, menos $(1/\theta^2)\int_0^\theta f$ no interior.

O terceiro é rendering diferenciável, e é o exemplo mais bonito porque a fronteira ali é literalmente uma silhueta. A cor de um pixel é uma integral, e o termo de visibilidade torna o integrando descontínuo: um ponto está atrás do objeto ou não está. A posição dessa descontinuidade depende dos parâmetros da cena, então derivar em relação à geometria produz uma contribuição concentrada na borda. Quem ignora essa contribuição consegue treinar cor e material, e não consegue mover geometria, porque o gradiente que empurraria a silhueta é justamente o que ficou de fora. O trabalho que virou referência na área ataca isso de frente, com um algoritmo de amostragem de arestas que, nas palavras dos autores em tradução minha, “diretamente amostra as funções delta de Dirac introduzidas pelas derivadas do integrando descontínuo”.

Some os três e o padrão fica claro. Na integral fechada da seção anterior, esquecer a fronteira custou um pedaço da ordem do próprio integrando. No suporte móvel, custa o sinal. No rendering, custa a capacidade de otimizar geometria. O termo que ninguém precisa provar continua sendo o que mais cobra.

O parâmetro que você inventa

A mesma regra sustenta um truque que parece mágica na primeira vez: introduzir um parâmetro que não existia no problema, só pra derivar em relação a ele. O exemplo clássico cabe em três linhas.

Essa integral não tem primitiva elementar. A derivada dela tem, e é trivial: derivar sob o sinal mata o logaritmo do denominador, porque $\partial_a x^a = x^a \ln x$. Sobra $I^{\prime}(a) = \int_0^1 x^a dx = 1/(a+1)$, e como $I(0) = 0$, integrando de volta vem $I(a) = \ln(a+1)$, válido para $a > -1$.

E aqui eu escorreguei escrevendo este post, então conto o escorregão. A tabela-resumo do Conrad traz as dominantes prontas para exatamente esta integral, com $|\partial_a f| = x^a \le 1$. Peguei a cota e segui em frente. Só que aquela linha da tabela vale para $0 < a < c$, e eu tinha acabado de afirmar o resultado para todo $a > -1$. Com $a$ negativo a cota é falsa: em $x = 0{,}01$ e $a = -1/2$, $x^a$ já vale 10. Cota tabelada vale no intervalo em que foi tabelada.

A conta que cobre o domínio inteiro é local, que é como a dominação tinha que ser desde o começo. Fixe $a_0 > -1$ e um intervalo $[c,C]$ em volta dele que contenha o zero, com $c > -1$. Em $(0,1)$ a função $x^s$ decresce em $s$, então para todo $a$ nesse intervalo:

A cota do meio sai de enxergar o próprio integrando como uma integral, \(\int_0^a x^s\,ds = (x^a-1)/\ln x\), e é ela que resolve as duas pontas de uma vez: limitar numerador e denominador em separado não funciona perto de \(x=1\), onde \(1/\lvert\ln x\rvert\) explode e é só o numerador indo a zero que segura o quociente.

Nenhuma das duas depende de $a$, as duas são integráveis porque $c > -1$, e as duas valem numa vizinhança de $a_0$, não no domínio inteiro de uma vez. É a mesma dominação local da seção das hipóteses, agora numa integral concreta.

Conferi em cinco valores de $a$, quatro positivos e um negativo. Nos positivos o erro fica em $1{,}1 \times 10^{-7}$, todo ele de quadratura junto às pontas, onde o integrando vale $-1/\ln x$ e tem derivadas de ordem alta ilimitadas, e o Simpson deixa de valer $O(h^4)$. Com $a$ negativo o integrando é ilimitado em zero e a integral é imprópria, então o script troca de variável, $x = u^p$ com $p(a+1) > 1$, e o erro cai para $10^{-14}$.

É esse movimento que ficou conhecido como truque de Feynman. E é aqui que o post vira outro post, de propósito. Até agora eu tratei a regra como ferramenta, e ferramenta se julga por funcionar. Daqui pra frente eu trato ela como atribuição, e atribuição se julga por ser verdadeira. A segunda pergunta tem uma resposta bem pior do que eu esperava quando comecei a procurar.

Parte II: o que Leibniz de fato escreveu

Gottfried Wilhelm Leibniz nasceu em 1 de julho de 1646 em Leipzig e morreu em 14 de novembro de 1716 em Hannover. Ele não era matemático de formação: doutorou-se em direito em Altdorf, em fevereiro de 1667, e ganhou a vida como secretário, advogado, bibliotecário e conselheiro de corte. A matemática entrou por via diplomática. Foi a Paris em 1672 numa missão política, ficou até 1676, estudou com Christiaan Huygens no outono de 1672 e, por indicação dele, foi ler Saint-Vincent sobre soma de séries.

A notação é a parte da herança que ninguém disputa. Em 29 de outubro de 1675, num manuscrito não publicado chamado Analyseos tetragonisticae pars secunda, ele escreveu a frase que vale a pena ler no original: “Utile erit scribi ∫ pro omnia, ut ∫l = omn. l, id est summa ipsorum l”. Será útil escrever ∫ em vez de omnia, isto é, a soma dos próprios $l$. O símbolo é um S alongado de summa, e ele nasceu como abreviação de uma palavra que Leibniz estava cansado de escrever. Duas semanas depois, em 11 de novembro de 1675, no manuscrito Methodi tangentium inversae exempla, aparecem $dx$, $dy$ e $dy/dx$. E um detalhe de rodapé sobre como as datas escorregam: a biografia de Leibniz no MacTutor dá 21 de novembro de 1675 para a primeira aparição de $\int f(x)dx$, enquanto a página de primeiras ocorrências de símbolos, no mesmo arquivo, data de 11 de novembro o manuscrito em que ele pela primeira vez pôs $dx$ depois do símbolo de integral, que é o mesmo evento descrito com outras palavras. As duas páginas não batem. O que dá pra dizer é que elas não têm o mesmo lastro: a segunda cita Cajori, volume 2, página 204, e a primeira não cita fonte. Isso não resolve, mas diz onde se resolve, e eu deixo o endereço: os dois manuscritos estão na edição crítica da Academia, série VII, volume 5, páginas 288 a 295 e 321 a 331.

O artigo de 1684 na Acta Eruditorum, o Nova methodus pro maximis et minimis, é a primeira publicação do cálculo diferencial. Ele traz a notação $d$ e as regras de derivada de potência, produto e quociente, e não traz demonstração nenhuma. Os resultados de cálculo integral saíram em 1684 e 1686 com o nome de calculus summatorius; a expressão cálculo integral foi sugestão de Jacob Bernoulli, em 1690. E o símbolo $\int$, inventado em 1675, só apareceu impresso em 1686.

A disputa de prioridade com Newton rende um parágrafo, e ele é bom. Em 1711 Leibniz leu um artigo de Keill acusando ele de plágio e recorreu à Royal Society. Newton, que era presidente da Royal Society, nomeou um comitê “imparcial” para decidir se o inventor do cálculo era ele ou Leibniz, escreveu ele mesmo o relatório oficial do comitê, sem assinar, e depois publicou uma resenha anônima do próprio relatório nas Philosophical Transactions. O relatório saiu como Commercium Epistolicum no começo de 1713, e Leibniz só viu o documento no outono de 1714.

Aqui começa a parte em que eu preciso ser chato. A continuação dessa história, do jeito que circula, é que o rancor da disputa isolou a matemática britânica por um século, e que a culpa foi de os ingleses se agarrarem aos pontinhos de Newton em vez do $d$ de Leibniz. Quem estudou o período de perto contesta. Niccolò Guicciardini, no livro que dedicou ao cálculo de fluxões na Grã-Bretanha entre 1700 e 1800, sustenta que a diferença entre a notação de Newton e a de Leibniz recebeu importância demais: as duas escolas compartilhavam um método matemático comum, com dois algoritmos que se traduziam um no outro, e passar de uma notação pra outra era trivialidade. E rastreia a imagem deprimente do cálculo newtoniano até os escritos da Analytical Society de Cambridge, no começo do século XIX, reformadores com interesse direto em pintar o passado como atrasado. A disputa não foi inofensiva. Mas a versão forte da lenda tem origem identificável e autor interessado, e a lista de matemáticos britânicos do século XVIII, com Taylor, Stirling, Bayes, Maclaurin e Simpson dentro, não parece lista de terra arrasada.

O que se afirma com tranquilidade sobre notação é mais modesto e mais interessante que a lenda: Leibniz sabia que achar boa notação era problema de primeira ordem e pensava muito nisso, enquanto Newton escrevia mais para si mesmo e usava a notação que lhe ocorria no dia. O $d$ e o $\int$ deixam explícito o aspecto de operador, e foi esse aspecto que os desenvolvimentos posteriores foram cobrar.

Agora a pergunta que me interessava, e que é a razão de este post existir: Leibniz enunciou a regra que leva o nome dele?

A resposta honesta é não, não nessa forma. O que a literatura documenta é mais estreito, e antes de eu contar o que é, o grau de certeza: eu li isso no resumo do capítulo 2 da monografia, o que o editor publica na página do livro, e não no volume impresso. Com a ressalva na mesa. Steven Engelsman, na monografia sobre a origem da diferenciação parcial a partir de problemas de famílias de curvas, situa em 1697 a descoberta e o uso, por Leibniz e Johann Bernoulli, do que ele chama teorema da permutabilidade entre derivação e integração, na forma $d_x\int \varphi(x,a) da = \int d_x \varphi(x,a) da$, com Jakob Bernoulli usando a mesma propriedade em 1698. O contexto era o problema das trajetórias ortogonais, e os dois estavam conscientes da novidade conceitual: chamaram a operação de diferenciação de curva em curva, em contraste com a derivação ordinária ao longo de uma única curva.

Olha bem o que está e o que não está nessa fórmula. Está o terceiro termo, a troca de ordem, o pedaço que é teorema de fato. Não estão os limites variáveis, não estão os dois termos de fronteira, não está hipótese nenhuma. O que Leibniz teve em 1697, pelo que a documentação sustenta, foi a permutação com limites fixos, escrita na linguagem de famílias de curvas, e usada como ferramenta para resolver um problema geométrico concreto. A regra completa que hoje leva o nome dele, com os três termos e com o retângulo de continuidade, é construção posterior de outras pessoas.

E aqui tem uma ironia de bibliografia que vale contar. As notas de Keith Conrad sobre derivação sob o sinal da integral, que são hoje a referência que todo mundo manda para quem pergunta, abrem dizendo que o método é “devido a Leibniz em 1697”, e a nota de rodapé dessa afirmação aponta para uma resposta no History of Science and Mathematics Stack Exchange. Não é crítica ao Conrad, o texto dele é de matemática e é excelente. É um retrato de como funciona a atribuição em matemática: a data circula com precisão de ano, a cadeia de citação termina num fórum, e ninguém checa porque o crédito não muda a fórmula.

O rigor que hoje se exige veio depois, e veio de outro projeto. Leibniz operava com infinitesimais, quantidades menores que qualquer grandeza dada e ainda assim não nulas, e nem ele tinha certeza do estatuto delas. Numa carta a Johann Bernoulli de junho de 1698 escreve, em tradução livre minha do inglês, que talvez o infinito e o infinitamente pequeno que concebemos sejam imaginários, mas adequados para determinar coisas reais, assim como as raízes também costumam ser consideradas imaginárias. É o autor do cálculo dizendo, com elegância, que não sabe se os objetos dele existem.

A formulação moderna abandonou o infinitesimal como objeto e reconstruiu tudo em cima de limite, com Bolzano, Cauchy e Weierstrass, e foi essa reconstrução que trouxe as hipóteses. A troca de derivada com integral deixou de ser propriedade evidente e passou a exigir continuidade, convergência uniforme e, com a integral de Lebesgue, convergência dominada, que é a hipótese que dá conta do contraexemplo da seção anterior sem pedir nada além de uma cota integrável.

Fecha o círculo o Feynman, responsável pela regra ter fama de arma secreta. Em Surely You’re Joking, Mr. Feynman!, no capítulo “A Different Box of Tools”, ele conta que o professor de física do colégio, o Mr. Bader, mandou ele ficar depois da aula e deu de presente um livro, o Advanced Calculus do Woods, porque ele falava demais e fazia barulho por tédio. E conta o efeito: “aquele livro também mostrava como derivar parâmetros sob o sinal da integral, é uma certa operação. Acontece que isso não é muito ensinado nas universidades, elas não dão ênfase nisso”. Foi com essa peça que ele construiu a fama de resolver integrais em Princeton, não por ser mais rápido, mas porque a caixa de ferramentas dele tinha algo que as outras não tinham. A regra é de 1697, o rigor é do século XIX, e a fama é de um físico que ganhou um livro de presente por ser aluno inconveniente.

O termo de fronteira é o resumo do post. É a parte da regra que ninguém precisa provar, que qualquer um deduz do TFC, e é justamente a parte que todo mundo esquece de escrever. Vale 40% da resposta no caso que eu conferi. A parte difícil você respeita, porque ela impõe hipótese e te obriga a pensar. A parte fácil você atropela, e é ela que te cobra a conta.

Fontes

• Biografia de Leibniz, arquivo MacTutor, St Andrews: datas de nascimento e morte, doutorado em direito em Altdorf, os anos de Paris e o contato com Huygens, conteúdo do Nova methodus de 1684, primeira aparição impressa do ∫ em 1686, cronologia da disputa e do Commercium Epistolicum. mathshistory.st-andrews.ac.uk/Biographies/Leibniz
• Biografia de Newton, arquivo MacTutor: comitê “imparcial” da Royal Society, relatório escrito por Newton sem assinatura e resenha anônima do próprio relatório. mathshistory.st-andrews.ac.uk/Biographies/Newton
• Earliest Uses of Symbols of Calculus, compilação de Jeff Miller hospedada no MacTutor, citando Cajori vol. 2 p. 204: manuscrito de 29 de outubro de 1675 com a frase sobre o ∫, manuscrito de 11 de novembro de 1675 com $dx$, $dy$ e $dy/dx$, e a informação de que os dois foram publicados primeiro por Gerhardt e hoje estão na edição crítica da Academia, Sämtliche Schriften und Briefe, Reihe VII vol. 5, Infinitesimalmathematik 1674-1676, Akademie Verlag, 2008, pp. 288-295 e 321-331. mathshistory.st-andrews.ac.uk/Miller/mathsym/calculus
• The rise of calculus, MacTutor: postura de Leibniz e de Newton em relação a notação, calculus summatorius, e a sugestão do nome cálculo integral por Jacob Bernoulli em 1690. mathshistory.st-andrews.ac.uk/HistTopics/The_rise_of_calculus
• Niccolò Guicciardini, The Development of Newtonian Calculus in Britain, 1700-1800, Cambridge University Press, 1989: crítica à tese do declínio britânico, origem da imagem na Analytical Society de Cambridge, e a posição de que as duas escolas compartilhavam um método comum com notações traduzíveis uma na outra. Parafraseado, não citado; ver a seção seguinte.
• Steven B. Engelsman, Families of Curves and the Origins of Partial Differentiation, North-Holland Mathematics Studies 93, 1984: 1697 como data da descoberta e uso do teorema de permutabilidade por Leibniz e Johann Bernoulli, 1698 para Jakob Bernoulli, e o termo diferenciação de curva em curva. Conferido no resumo do capítulo 2, Families of Curves in the 1690s, publicado pela editora, e não no volume impresso. sciencedirect.com/bookseries/north-holland-mathematics-studies/vol/93
• Carta de Leibniz a Johann Bernoulli de 7/17 de junho de 1698, edição da Academia A III 7, 796-97, em tradução inglesa publicada pela Technion: os infinitos e infinitamente pequenos como possivelmente imaginários. humanities.technion.ac.il
• Keith Conrad, Differentiating under the integral sign: o Teorema 12.3, com a dominação pedida só para $t$ num intervalo em volta do ponto; o Corolário 12.4, que tira a versão de limites variáveis do teorema de limites fixos mais a regra da cadeia sobre $I(t,a,b)$; a seção 8, que é a integral do truque de Feynman deste post, com as dominantes na Tabela 2; a atribuição a “Leibniz em 1697” na primeira frase, cuja nota de rodapé é a referência [4], uma resposta no History of Science and Mathematics Stack Exchange; e a referência [16], a edição de 1934 do Woods pela Ginn and Co. A epígrafe é o trecho do Feynman. kconrad.math.uconn.edu
• Shakir Mohamed, Mihaela Rosca, Michael Figurnov e Andriy Mnih, Monte Carlo Gradient Estimation in Machine Learning, JMLR 21 (2020) 1-62: as condições para a troca de derivada e integral no estimador score function (seção 4.3.1), a hipótese de continuidade absoluta e o exemplo de suporte limitado com $\mathrm{Uniforme}(0,\theta)$ e $f(x)=x$, com gradiente verdadeiro $1/2$ contra $-1/2$ do estimador (seção 4.3.2), a derivação do estimador pathwise empurrando o parâmetro pro custo (seção 5.2), e a separação em termo de fronteira e termo interior na equação (41a). jmlr.org/papers/volume21/19-346
• Tzu-Mao Li, Miika Aittala, Frédo Durand e Jaakko Lehtinen, Differentiable Monte Carlo Ray Tracing through Edge Sampling, ACM Transactions on Graphics 37(6), SIGGRAPH Asia 2018: descontinuidade de visibilidade no integrando e amostragem direta das deltas de Dirac introduzidas pela derivada. A citação do parágrafo de rendering vem do resumo dos autores. people.csail.mit.edu/tzumao/diffrt
• Richard Feynman, Surely You’re Joking, Mr. Feynman!, capítulo “A Different Box of Tools”: o Mr. Bader, o Advanced Calculus do Woods, e o trecho sobre derivar parâmetros sob o sinal da integral.
• Conferência numérica de tudo que este post afirma em número: $A^{\prime}(7)$ e $A^{\prime\prime}(7)$ contra a forma fechada, o termo de fronteira esquecido valendo $F(7)$, a janela deslizante, o gradiente de esperança com suporte fixo, os cinco números da $\mathrm{Uniforme}(0,\theta)$, o contraexemplo $\int_0^\infty t e^{-tx}dx$ e a integral $\int_0^1 (x^a-1)/\ln x,dx = \ln(a+1)$. São 23 verificações, quadratura de Simpson com 200 mil a 400 mil subintervalos somada com math.fsum, diferenças finitas centrais, uma troca de variável para o caso impróprio, e uma tolerância própria por método. Script em Python, só biblioteca padrão. verificacao.py

O que eu não consegui verificar

• Se Leibniz chegou perto da forma com limites variáveis. O que achei documentado é a permutação com limites fixos, em 1697. Nenhuma fonte que eu alcancei diz que ele tratou dos termos de fronteira nesse contexto, e nenhuma diz que ele não tratou. Fica em aberto.
• Quem primeiro enunciou a regra na forma moderna, com hipóteses. Não achei fonte. Sei dizer que a maquinaria veio da rigorização do século XIX e que a versão com convergência dominada é posterior a Lebesgue, mas não atribuo o primeiro enunciado a ninguém porque não sei.
• A monografia do Engelsman e a edição Gerhardt eu não li. A afirmação sobre 1697 vem do resumo do capítulo 2 publicado pela editora, não do volume impresso, e não fui à correspondência original. O exemplar está no Internet Archive, mas em regime de empréstimo, sem busca no texto. Quem quiser fechar essa lacuna precisa do livro na mão.
• A formulação exata do Guicciardini. A posição dele sobre a notação ter recebido importância demais eu confirmei em fonte secundária, e por isso ela aparece aqui como paráfrase, não entre aspas. Não tenho a página, e não vou fingir que tenho.
• A divergência de data entre duas páginas do MacTutor, 11 contra 21 de novembro de 1675, continua sem resolução. O que eu consegui apurar é que as duas não têm o mesmo lastro documental: a página de símbolos cita Cajori, a biografia não cita nada. Quem for atrás dos manuscritos tem o endereço na lista acima, edição da Academia, série VII volume 5.
• Qual edição do Woods o Feynman tinha. A bibliografia do Conrad cita a edição nova, de 1934, da Ginn and Co. O Feynman não dá edição no relato. Não sei qual era.

Da conversa pro board: a skill propõe as tasks pontuadas, eu aprovo, ela escreve.

Numa única conversa com o Claude Code saíram 15 tasks pontuadas, 11 subtasks reestimadas e dois pull requests. Eu não abri o ClickUp em momento nenhum. No fim, a parte que mais me marcou foi banal: a própria ferramenta que eu tinha acabado de construir criou a última task do board, sozinha, fechando o loop.

Esse post é a história de como cheguei nisso e, principalmente, o que eu encontrei quando fui abrir a implementação pra escrever aqui. Não é um tutorial de como criar uma skill do zero. Esse eu já contei no post do /save-session. Aqui o assunto é o que acontece quando você dá a uma skill o poder de escrever num sistema que o time inteiro usa, e o que essa escrita pode quebrar quando ela falha no meio.

Por que o board ficava pra trás

Trabalho de infraestrutura quase sempre acontece antes da burocracia. Você investiga um custo, mexe num cluster, prepara um upgrade de banco, e só depois lembra que aquilo precisa virar registro em algum lugar. O registro fica pra trás. A sprint não reflete o que foi feito. O esforço some.

Abrir task no meio do trabalho dá preguiça porque dá trabalho de verdade: título, escopo, pontos, épico, sprint certa, atribuição. Multiplica por quinze e ninguém faz. Foi exatamente o que aconteceu comigo numa sessão de trabalho de custo: eu tinha um monte de coisa feita e planejada, e zero disso no board.

A virada foi parar de tratar a documentação como uma segunda jornada e passar a tratar como subproduto. Eu conversei com o Claude Code enquanto fazia o trabalho de verdade, e no fim pedi pra ele documentar.

Do curl improvisado pra uma skill

Não comecei com uma skill. Comecei com a coisa mais burra que funcionava: pedi pro Claude descobrir como a gente já falava com o ClickUp. Ele varreu o código, achou uma integração existente que abre task automaticamente quando o robô diário de custo AWS detecta anomalia, entendeu o padrão da API e passou a montar chamadas a partir dali. Em poucos minutos eu tinha tasks sendo criadas via curl improvisado.

Funcionou, e era frágil pelo motivo mais chato: a cada novo pedido o modelo redescobria os mesmos IDs, os mesmos campos, a mesma convenção. Redescoberta é onde mora a variação, e variação em escrita é onde mora o erro. Empacotei numa skill do Claude Code, que é um diretório com um SKILL.md que carrega só quando é usado:

~/.claude/skills/clickup-ops/
├── SKILL.md        # instrucao pro modelo: quando usar, fluxo, regras combinadas
├── reference.md    # ids estaveis do workspace e mapeamento dos custom fields
└── scripts/cu.py   # o que fala com a API, sem modelo no meio do caminho

O SKILL.md tem frontmatter com name e description, e é a description que faz o modelo puxar a skill quando eu falo de sprint, ponto ou task. O corpo dele não é código: é o combinado com o time escrito em português, e cada regra dali vira uma das seções abaixo.

O reference.md guarda o que é estável e caro de descobrir: ids de workspace, space e folder de sprints, o meu user id, e o mapeamento dos custom fields com o UUID de cada opção. Tem uma linha ali que vale mais que o resto do arquivo: as list ids de sprint não são estáveis, mudam a cada quinzena, e por isso são proibidas de virar constante.

O cu.py é o único que toca a rede, e nenhum subcomando dele pede opinião. A regra que eu segui é simples de enunciar e chata de manter: o modelo decide o quê, o script decide como. Escolher o ponto de uma feature é julgamento. Montar payload, resolver UUID de opção e escolher endpoint é determinístico, e determinístico não se delega pra um gerador de texto.

De “documenta isso” até a task criada

O pedido chega em linguagem natural, do tipo “abre essas tasks na sprint”. A primeira coisa que a skill faz é descobrir a sprint corrente, e o método é mais rústico do que eu gostaria: ela lista o folder de sprints, extrai as datas do nome de cada lista com regex e escolhe a que contém hoje. Quando nenhuma cobre o dia, ela não chuta, avisa e manda usar o backlog ou uma lista explícita. Depende de convenção de nomenclatura e quebra se alguém renomear uma sprint. Aceito o acoplamento porque a alternativa, cravar id, quebra a cada quinze dias em silêncio.

Resolvida a lista, o resto sai do reference.md: épico, tipo, responsável e o UUID da opção de ponto. Aí ela monta o plano e me mostra antes de escrever qualquer coisa:

Sprint 25/08 a 05/09  (lista 9011xxxxxx)

  5 pts  Infra     Tecnica  Corrigir alarme que nao dispara em fila parada
  3 pts  Cronjobs  Tecnica  Migrar job diario de custo pro agendador novo
  2 pts  Infra     Debito   Remover credencial de servico do script legado

  3 tasks | 10 pts | status todo

Eu aprovo ou ajusto, e só então ela sobe. Depois da escrita, imprime o id e a URL de cada task, que é o que a resposta da API devolve. Não há releitura pra conferir se o board ficou como o plano dizia.

Os dois campos de ponto, e o que eu errei na primeira implementação

O ClickUp tem dois lugares diferentes pra guardar ponto, e eles não conversam. Tem o custom field que o time configurou no board, um dropdown, e tem o Sprint Points nativo, que é o que alimenta o relatório de velocity. Preencher só um deixa o board mostrando um número e o relatório contando outro.

A skill escreve nos dois, sempre iguais. A parte que eu errei foi como.

Eu implementei a criação em duas etapas: o POST criava a task já com o custom field, e um PUT posterior preenchia o Sprint Points. Ao revisar a implementação pra escrever este texto, descobri que a separação não era necessária na criação. O endpoint de criação aceita points e custom_fields no mesmo payload:

POST /api/v2/list/{list_id}/task
{
  "name": "Corrigir alarme que nao dispara em fila parada",
  "description": "Escopo da task.\n\n---\nPS: task aberta automaticamente pelo Claude Code.",
  "status": "todo",
  "assignees": [<user_id>],
  "points": 5,
  "custom_fields": [
    {"id": "<uuid do campo Pontos>", "value": "<uuid da opcao 5>"},
    {"id": "<uuid do campo Epic>",   "value": "<uuid da opcao Infra>"}
  ]
}

A separação em duas chamadas só é obrigatória em outro caso, o de repontuar uma task que já existe. O endpoint de atualização aceita points, mas não aceita custom_fields, e a documentação é explícita ao dizer que pra atualizar Custom Fields você precisa usar o endpoint específico:

POST /api/v2/task/{task_id}/field/{field_id_pontos}   {"value": "<uuid da opcao 8>"}
PUT  /api/v2/task/{task_id}                           {"points": 8}

São quatro casos, e eu perdi tempo por não ter isso escrito em lugar nenhum. Criar task com ponto é uma chamada só. Atualizar o campo nativo de uma task existente é PUT com points. Atualizar o custom field é POST no endpoint de custom field. E manter os dois em sincronia numa task existente é obrigatoriamente duas chamadas.

Tem uma armadilha a mais no dropdown, e ela vale nos dois sentidos. Ao escrever, o campo não aceita o número 5, aceita o UUID da opção que vale 5. Ao ler, ele devolve orderindex, e a ordem configurada no meu board não é a ordem numérica: o índice 1 é o ponto 3 e o índice 2 é o ponto 2. Quem lê uma task e reescreve confiando no índice troca 3 por 2 sem receber erro nenhum. A única fonte confiável é o mapeamento entre o UUID canônico e o valor semântico, que é exatamente o que o reference.md existe pra guardar.

O default 8

Essa é a parte em que a IA quase me passou a perna sem querer.

Eu tinha um conjunto de subtasks pra pontuar, e o campo já vinha preenchido: todas com 8. Olhei e o número não cheirava bem, porque 8 é o teto da escala do board, que vai de 1 a 8 e não tem 13. Teto em tudo, do item mais trivial da lista, um fallback de valor padrão, até o mais pesado, um fluxo conversacional de várias etapas. Isso não é estimativa. É o padrão clássico de quem aplicou um valor em lote e seguiu a vida.

Se eu tivesse pedido pro Claude só copiar o que já estava lá, ele teria propagado aquilo com a maior cara de competência, e sem cometer erro nenhum de execução. Aqui mora a distinção que eu não sabia formular antes desse dia: transportar uma estimativa e produzir uma estimativa são operações diferentes. Transportar é mecânico e a máquina faz melhor que eu. Produzir exige comparar o item com outros que já foram entregues, e essa é justamente a evidência que falta pro modelo: ele lê o título, o escopo dito na conversa e o que apareceu no código durante a sessão, mas não tem o histórico de quanto doeu a última feature parecida.

Pedi pra reestimar item a item e o resultado saiu variado, de 2 a 8, somando bem menos que o bloco de oito em tudo. A regra que ficou pra skill é declarar contexto insuficiente em vez de arriscar quando o escopo não apareceu na conversa. A que ficou pra mim é mais curta: ferramenta nenhuma substitui o seu julgamento sobre o tamanho das coisas. Ela acelera o registro, não a decisão.

O que pode dar errado no meio da escrita

Volte na criação em duas etapas. O POST cria a task e já grava o custom field de ponto. Se o PUT seguinte falhar, por rede, por 429, por um 500 do outro lado, o script morre ali. E o que fica pra trás é isto: a task existe, o board mostra o ponto no campo do time, e o Sprint Points nativo está vazio. A velocity passa a divergir do número que aparece na tela.

Ou seja, o modo de falha da minha implementação produzia exatamente a inconsistência que ela existia pra evitar. E o pior detalhe é que ela falha em silêncio do ponto de vista do board: ninguém recebe erro, ninguém vê task pela metade, só um número que não bate daqui a uma semana.

A correção de fundo é a chamada única que a API já permitia, porque ela elimina a janela entre os dois estados. Onde a janela é inevitável, no caso de repontuar task existente, o certo é ler de volta e comparar antes de dizer que deu certo.

O fallback que troca a sua identidade

O token nunca esteve no repositório nem no arquivo da skill, e nisso eu não abri mão. Quando o próprio modelo sugeriu, em algum momento, salvar o token num arquivo pra facilitar, eu recusei. Credencial em texto puro versionada é dívida que volta pra te morder, e construir ferramenta nova não é desculpa pra repetir o erro que a gente passa a vida pedindo pros outros não cometerem.

O que eu não tinha percebido é mais sutil, e não é sobre onde o segredo mora. É sobre qual identidade ele carrega.

O script lê $CLICKUP_TOKEN do ambiente e, se não achar, cai num secret no AWS Secrets Manager. Em shell interativo, a variável aponta pro meu token pessoal. Em shell não interativo a coisa muda: o ~/.bashrc tem o guard clássico que retorna cedo quando não há sessão interativa, o export nunca acontece, a variável chega vazia, e o script cai no fallback sem reclamar. O segredo que ele recupera pertence a uma conta de serviço, não a mim. A operação funciona, a task é criada, e a autoria registrada muda.

O problema não é o Secrets Manager, que é exatamente o lugar certo pra guardar isso. O problema é um fallback silencioso trocar o principal da operação. O que eu quero é que a origem da credencial apareça, que a identidade escolhida seja registrada antes da escrita, e que a execução falhe quando a identidade esperada não estiver disponível, em vez de trocar de principal por conta própria.

O engraçado é que a skill já faz isso certo em outro lugar. O comando que cria documento recusa o fallback e exige uma flag explícita pra usar a conta de serviço, porque ali a consequência é visível na hora, o documento nasce com dono errado. Na criação de task a consequência é invisível, e por isso a proteção não foi escrita. Consequência invisível é onde a gente esquece de se proteger.

Quem aprovou, quem executou, quem assina

O passo de confirmação antes de escrever em lote não é cosmético. Não é “você tem certeza?”, que ninguém lê depois da terceira vez. O que aparece na tela é o plano inteiro, com alvo, ponto e épico de cada item, e é a última chance de pegar a lista certa na sprint errada, que é o erro caro e chato de desfazer.

Junto veio a marcação de procedência: toda task aberta pela skill leva no fim da descrição um PS dizendo que foi aberta automaticamente pelo Claude Code. Ela tem dois defeitos que eu já enxergo. É prosa na descrição e não campo estruturado, então não dá pra filtrar nem contar por ela num relatório, e marcador de procedência devia ser campo num board que tem campos. E texto igual repetido em toda task vira ruído, porque o leitor para de enxergar depois da décima.

O que essa marcação registra, no fim, é só uma das três coisas que a gente costuma confundir numa frase só. Quem executou é o que o PS diz. Sob qual identidade é o que o token define, e é o que o fallback silencioso pode mentir. Quem respondeu pela decisão sou eu, sempre, porque fui eu que aprovei o plano. Automação que embaralha as três produz um board onde ninguém sabe a quem perguntar.

O loop que fechou sozinho

No fim daquela sessão, investigando algumas tasks, apareceu uma ação residual que não estava no board. Pedi pra registrar. A skill, agora pronta, criou a task. Foi a primeira vez que ela rodou a partir de uma decisão tomada na própria conversa, em vez de um comando meu explícito de “cria task tal”. Pequeno, mas foi o sinal de que a ferramenta tinha deixado de ser experimento e virado parte do fluxo.

Os controles que eu adicionaria hoje

Nada do que está aqui existe na implementação. Estou escrevendo como dívida, não como recurso.

Não há timeout explícito nas chamadas HTTP, então uma conexão pendurada trava a execução até o sistema operacional desistir. Não há retry nem backoff. O 429 não é tratado, cai no mesmo caminho de erro genérico de qualquer outro status. Não há idempotência nem deduplicação: rodar o mesmo lote duas vezes cria o dobro de tasks, e o único guarda-corpo é a minha atenção na hora de aprovar. Não há dry-run de verdade, e não há verificação depois da escrita.

Sobre o 429, vale fazer a conta em vez de dar de ombros. O limite oficial no plano Business é de 100 requisições por minuto por token, com os headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset na resposta. Aquelas 15 tasks a duas chamadas dão cerca de 30 requisições, bem abaixo do teto. Só que o limite é por token, e esse mesmo token é usado pelo robô de custo que roda toda manhã, então as duas automações competem pela mesma cota. Um lote maior, ou dois ao mesmo tempo, chegam lá sem esforço.

O formato que eu quero é este:

plano aprovado
  -> --dry-run: imprime o payload final de cada task e nao chama a API
  -> escrita: um POST por task, com points e custom_fields no mesmo corpo
  -> 429 ou 5xx: respeita X-RateLimit-Reset, tenta de novo, e desiste com o indice do lote
  -> verificacao: GET /task/{id} e compara points e custom field com o plano
  -> divergiu: reporta a task pelo id e diz qual campo ficou pra tras

O que essa sequência entrega não é robustez genérica. É a capacidade de responder uma pergunta específica depois de uma execução interrompida: quais itens do plano ficaram no board, quais não, e quais ficaram pela metade. Hoje a resposta é abrir o ClickUp e olhar.

O que fica

O ganho de tempo é real. Construir a skill custou menos que documentar uma sprint cheia na mão, e ela paga esse custo toda vez que eu abro um board agora. Mas o que ficou mais valioso não foi ficar mais rápido, foi ficar mais correto: os dois campos de ponto sempre iguais, o épico sempre preenchido, a sprint sempre a corrente. Registro feito na mão às onze da noite erra mais que isso.

O resto é sobre a natureza da revisão. Quando uma IA só lê e responde, um erro dela é um parágrafo errado. Quando ela escreve num sistema que o time usa, um erro vira ruído no board, número torto na velocity e decisão tomada em cima de dado falso. E o erro que eu achei aqui não foi nem do modelo: foi meu, escondido atrás de uma sequência de chamadas que funcionava em todos os dias normais. Ferramenta que escreve no mundo externo merece a mesma revisão que código de produção, e o teste de que ela está pronta não é ela funcionar. É você saber dizer o que sobra quando ela falha no meio.

Introdução

Comecei a tarde de domingo querendo só arrumar uma câmera que estava com a imagem estranha e terminei com um script que lê e escreve a configuração das quatro câmeras do meu DVR direto pela linha de comando. No caminho descobri que o Intelbras MHDX 3004-C expõe uma interface CGI compatível com a família de APIs da Dahua, coisa que quase ninguém documenta em português. Faço a ressalva porque ela importa: eu não abri o firmware nem li strings de build pra saber de quem é o código. O que eu tenho é comportamento observado. A autenticação, os caminhos em /cgi-bin/ e os nomes das tabelas seguem o mesmo padrão da Dahua, o que já é suficiente pra documentação de Dahua servir de mapa aqui. Origem do firmware é outra afirmação, bem mais forte, e essa eu não posso fazer.

A interface web do aparelho é aquela coisa pesada, cheia de combobox, em que você ajusta um parâmetro, troca de canal, espera recarregar, repete. Com quatro câmeras e um punhado de parâmetros pra padronizar, isso é trabalho manual chato e propenso a erro. A pergunta óbvia pra quem vive em terminal: dá pra fazer isso por API? Dá. E o caminho até lá é um bom exercício de engenharia reversa educada, do tipo ler antes de escrever.

Este post documenta o que funcionou de verdade no meu aparelho: MHDX 3004-C, firmware 4.001.00IB000, build de agosto de 2024, com as quatro câmeras analógicas que estão ligadas nele. Fora desse conjunto exato eu não garanto nada. Nome de tabela, índice, faixa de valor, capability anunciada, resposta de erro e teto de FPS mudam entre modelo, revisão de hardware e versão de firmware. É exatamente por isso que a primeira metade do trabalho é descobrir, não chutar, e é por isso que não vale ler isso aqui como receita pra linha Intelbras inteira nem pra qualquer aparelho Dahua.

Achando a porta

Primeiro fato: o DVR estava na mesma rede que a máquina de onde eu trabalho. Peguei o IP local dele na própria tela de rede do aparelho (ele estava em DHCP, o que por si só já é um problema que comento no final). O teste inicial de alcance foi direto:

ping -c2 "$DVR_IP"
curl -s -o /dev/null -w "%{http_code}\n" "http://$DVR_IP"

O ping não recebeu nenhuma resposta, e o curl devolveu http_code=000. Quase desisti achando que não alcançava o aparelho. Estava errado nas duas leituras.

Ping sem resposta em DVR é comum, muito aparelho simplesmente não responde ICMP. E 000 não é um código HTTP: é o curl avisando que não chegou a receber resposta HTTP nenhuma. Pode ser timeout, conexão recusada, falta de rota, protocolo errado, qualquer coisa que aconteça antes do servidor responder. Como diagnóstico, 000 sozinho não vale nada, ele só diz “não deu”.

O que vale é pedir pro curl contar o motivo. Do 7.75 em diante dá pra imprimir o exit code e a mensagem de erro no mesmo -w, e com -sS o erro para de ficar escondido:

curl -sS --connect-timeout 3 \
  -o /dev/null \
  -w 'http=%{http_code} exit=%{exitcode} erro=%{errormsg}\n' \
  "http://$DVR_IP"

Aí o 000 deixa de ser beco sem saída e vira frase: exit 7 é conexão recusada ou sem rota, exit 28 é timeout, exit 6 é DNS. Em curl mais velho que 7.75 esses dois campos não existem, e o equivalente é olhar o $? do shell e deixar o stderr aparecer. Não guardei a saída da tentativa original, então não vou dizer aqui qual exit code apareceu naquele domingo.

A parte que eu descobri em seguida: a interface web não estava na 80. O aparelho usa uma porta HTTP customizada, alta. Com a porta certa:

curl -sS -o /dev/null -w "%{http_code}\n" "http://$DVR_IP:$PORT"
# 200

Lição que sempre esqueço: separe “o host está vivo” de “o serviço está na porta que eu chutei”. Ping testa resposta a ICMP e nada mais, não diz se tem HTTP escutando em algum lugar. São perguntas diferentes, e eu tinha feito a errada duas vezes seguidas.

A autenticação é Digest, não Basic

Com a web respondendo, fui bater na API CGI. O padrão Dahua expõe tudo em /cgi-bin/. O primeiro probe é pedir o tipo do aparelho:

curl -sS -i "http://$DVR_IP:$PORT/cgi-bin/magicBox.cgi?action=getDeviceType"

A resposta foi um 401 Unauthorized com um header revelador:

WWW-Authenticate: Digest realm="Login to ...", qop="auth", nonce="...", opaque=""

Digest, não Basic. Isso muda o curl: tem que usar --digest, senão a credencial nem é negociada direito. O curl faz o desafio-resposta de Digest sozinho, então na prática é só trocar a flag:

curl -sS --digest -u "$DVR_USER:$DVR_PASS" \
  "http://$DVR_IP:$PORT/cgi-bin/magicBox.cgi?action=getDeviceType"
# type=MHDX 3004-C

Funcionou. A partir daqui é tudo configManager.cgi.

Uma ressalva que precisa vir junto: Digest é melhor que Basic porque a senha não viaja em claro, ele faz desafio-resposta com hash em cima do nonce. Mas isso autentica, não cifra. A conexão continua sendo http://, então URL, endpoint, parâmetros que eu escrevo e a config que volta na resposta ficam todos legíveis pra quem estiver na mesma rede olhando o tráfego. Por isso isso aqui é coisa de rede local controlada, de preferência num segmento isolado só pros bichos de câmera, e por isso DVR não fica publicado na internet. Se o firmware do teu oferecer HTTPS de forma confiável, prefira HTTPS.

Mantendo a senha fora do histórico

Antes de seguir, um parêntese que pra mim não é negociável. Senha de DVR é credencial de sistema de segurança física da minha casa. Ela não vai pro histórico do shell, não vai pro corpo de um script versionado, e não vai num post público. O padrão que usei foi um arquivo de credenciais com permissão restrita, que os scripts apenas carregam:

umask 077
cat > ~/.dvr_creds <<'EOF'
DVR_USER='admin'
DVR_PASS='troque aqui'
EOF
chmod 600 ~/.dvr_creds

As aspas simples não são decoração. Esse arquivo vai ser lido com source, ou seja, é shell de verdade: senha com espaço, $, crase ou aspas duplas sem quoting vira expansão ou erro de sintaxe, e você descobre isso na forma de um 401 que não faz sentido. Aspas simples resolvem tudo menos a própria aspa simples; se a tua senha tiver uma, escapa com '\'' ou troca a senha.

E todo script começa com:

source ~/.dvr_creds
AUTH=(--digest -u "${DVR_USER}:${DVR_PASS}")

O array ajuda em organização e quoting, mantém a credencial como um argumento só e evita que ela se espalhe pela linha em cada chamada. Mas vale ser honesto sobre o que ele não faz: no instante em que o curl roda, os argumentos já foram expandidos pro processo, e a senha está na linha de comando visível em ps e em /proc. Array nenhum conserta isso. Pra rede doméstica controlada eu aceito essa troca. Em máquina compartilhada eu não aceitaria, e o caminho seria --netrc ou um cofre de verdade. Fica registrado que eu não validei o --netrc contra esse DVR, então não estou recomendando como testado, e vale saber que a entrada do .netrc casa por host, não por porta, o que importa justamente aqui porque o aparelho não está na 80.

Ler antes de escrever

Aqui está o princípio que separa mexer com confiança de quebrar o sistema às cegas: a primeira coisa que a API faz é leitura, não escrita. Os nomes dos parâmetros variam entre versões de firmware, e eu não ia descobrir o nome certo escrevendo e torcendo. O configManager.cgi lê qualquer tabela com action=getConfig&name=<Tabela>.

A configuração de codificação fica em Encode:

curl -s "${AUTH[@]}" \
  "http://$DVR_IP:$PORT/cgi-bin/configManager.cgi?action=getConfig&name=Encode" \
  | grep -E '^table\.Encode\[0\]'

A saída é um formato chave-valor plano, com índices entre colchetes. O canal 0 da API é o canal 1 do aparelho. Cada canal tem MainFormat[0] (o stream principal, que grava) e ExtraFormat[0] (o stream extra, leve, pra ver remoto):

table.Encode[0].MainFormat[0].Video.Compression=H.265
table.Encode[0].MainFormat[0].Video.resolution=1920x1080
table.Encode[0].MainFormat[0].Video.FPS=15
table.Encode[0].MainFormat[0].Video.BitRateControl=VBR
table.Encode[0].MainFormat[0].Video.BitRate=3072
table.Encode[0].MainFormat[0].Video.Quality=6
table.Encode[0].MainFormat[0].AudioEnable=false
table.Encode[0].ExtraFormat[0].Video.resolution=704x480
table.Encode[0].ExtraFormat[0].Video.FPS=10
table.Encode[0].ExtraFormat[0].Video.BitRate=512

Esse dump é o mapa. A partir dele eu sei exatamente o nome de cada campo que vou querer escrever, sem adivinhação.

As tabelas que importam

Lendo as tabelas relevantes, montei o mapeamento entre o que a interface gráfica chama de uma coisa e o que a API chama de outra. Esse foi o pulo do gato, porque os nomes não batem:

A tabela VideoColor guarda brilho, contraste, saturação, matiz e, surpresa, a nitidez (que a UI chama de “Nitidez” e a API chama de Acutance). Ela é indexada por canal e por período de tempo, VideoColor[canal][periodo]. O período [0] é o perfil ativo (seção de tempo habilitada, 00:00-24:00); o [1] é uma segunda faixa que no meu caso estava desabilitada. Ou seja, eu só escrevo no período [0]:

table.VideoColor[0][0].Brightness=50
table.VideoColor[0][0].Contrast=50
table.VideoColor[0][0].Saturation=50
table.VideoColor[0][0].Hue=50
table.VideoColor[0][0].Acutance=5
table.VideoColor[0][0].TimeSection=1 00:00:00-24:00:00

Ler VideoColor de todos os canais de uma vez também serviu pra confirmar o mapeamento de índice, batendo brilho e contraste com o que eu via na tela canal a canal. Conferir o mapa contra a realidade antes de escrever evitou que eu sobrescrevesse o canal errado.

E aqui um dado me corrigiu. Minha ideia inicial era padronizar tudo em 50, ponto neutro de uma escala 0-100. Funciona pra brilho, contraste e saturação. Mas a leitura mostrou que a Acutance (nitidez) das câmeras estava em 1 a 5, e a câmera que eu achava a melhor de todas rodava em 1. Numa escala 0-100, esses valores são quase nada de realce, e por bom motivo: nitidez alta à noite só amplifica grão do infravermelho. Se eu tivesse cravado 50 no automático, teria deixado as quatro super-realçadas e cheias de ruído. Padronizei em 5. A lição vale além do DVR: “valor neutro” presumido não é “valor bom”, e só a leitura do que o aparelho já usava me mostrou a diferença.

A “Redução de ruído” da interface não está em VideoColor nem no VideoInOptions. Demorei a achar: ela vive em VideoInDenoise, com controle 2D e 3D separados:

table.VideoInDenoise[0][0].2DEnable=true
table.VideoInDenoise[0][0].2DLevel=100
table.VideoInDenoise[0][0].3DAutoType.AutoLevel=40

E tem um campo de ganho de imagem em VideoInOptions[canal].Gain, com uma variante NightOptions.Gain pro modo noturno. Esse eu não decifrei. O valor do Gain na API não bate número a número com o slider “Ganho imagem” da UI, e mais pra frente o getCaps do canal ainda me devolveu caps.Gain=false. Um campo que existe na tabela de config e uma capability negada pelo canal aparentemente não são a mesma coisa, provavelmente camadas diferentes, processamento no gravador de um lado e ganho nativo da câmera do outro, ou um parâmetro legado que ficou na tabela. Não fechei isso com o que o aparelho me devolveu, então fica registrado como não esclarecido em vez de explicado por chute. Na prática, mais um motivo pra testar num canal e conferir no preview antes de replicar.

O que a API NÃO deixa fazer

Aqui vem a parte honesta, e a mais importante de um post de engenharia reversa: nem tudo está exposto. A câmera que eu queria consertar tinha listras horizontais, o clássico flicker de iluminação, em que uma lâmpada LED pulsando bate com o obturador eletrônico da câmera. O ajuste pra isso é o anti-flicker, que vive na exposição. Fui ler a tabela de exposição:

curl -s "${AUTH[@]}" \
  "http://$DVR_IP:$PORT/cgi-bin/configManager.cgi?action=getConfig&name=VideoInExposure"
# Error
# Bad Request!

Bad Request. O que isso me autoriza a dizer é modesto: o firmware não aceitou VideoInExposure por esse endpoint e nesse formato. Bad Request cobre várias coisas, nome de tabela diferente, formato de requisição inválido, permissão do usuário, endpoint que não é esse. Não é prova de que a tabela não existe. Varri os nomes prováveis (VideoInAntiFlicker, VideoInDayNight, VideoInNR) e todos voltaram vazios, o que aumenta a suspeita mas continua sendo ausência de resposta útil, não demonstração de ausência.

Pra não parar no “não achei a tabela”, fui perguntar ao próprio aparelho o que ele suporta naquele canal, com devVideoInput.cgi?action=getCaps:

curl -g -s "${AUTH[@]}" \
  "http://$DVR_IP:$PORT/cgi-bin/devVideoInput.cgi?action=getCaps&channel=2"
# caps.Gain=false
# caps.VideoInDenoise.2D.Support=true
# caps.ImageEnhancement.Support=true
# ... nenhuma linha de shutter, exposure, antiflicker ou WDR

Isso é mais forte que o Bad Request, mas ainda não é onisciência. O que os dois juntos sustentam: as tabelas que eu procurei não foram aceitas, e o canal não anunciou capability de shutter, exposição, antiflicker ou WDR nos endpoints que eu testei. Ou seja, com os endpoints e as capabilities expostos por esse conjunto de DVR, firmware e câmera, eu não encontrei um caminho suportado pra controlar o anti-flicker. Isso não é a mesma coisa que dizer que o controle não existe em nenhum canto da API, nem que a câmera não tem esse ajuste por outro caminho, nem que outro firmware não exporia. Não testei tudo, e não tenho como testar tudo.

O palpite informado, e eu marco que é palpite, é que são câmeras analógicas HDCVI simples, de exposição automática. Nessa família, quando o ajuste existe, costuma morar no menu OSD da câmera, navegado por sinal coaxial, e não na config do gravador. O coaxialControlIO.cgi respondeu (consegui ler status de speaker e luz branca), então o canal de controle pra câmera existe. Só não achei do outro lado dele o botão que eu queria.

Saber o limite da ferramenta é tão valioso quanto saber o que ela faz. Eu poderia ter perdido uma hora montando um setConfig de anti-flicker que o aparelho ia ignorar em silêncio, ou pior, subido numa escada pra caçar um menu OSD que talvez não esteja lá. Duas leituras de API me pouparam as duas coisas em segundos.

Backup antes da primeira escrita

Regra que eu não quebro nem em casa: antes do primeiro setConfig, tira um retrato do que está lá. Não porque eu espero errar, mas porque a config atual é a única referência do que era o estado bom, e esse aparelho não tem desfazer.

Aqui também muda a natureza dos comandos. Até agora eu estava explorando na mão, e podia ler a saída de cada um. Daqui pra frente é automação, e automação precisa de timeout e de erro visível:

source ~/.dvr_creds
CURL=(-sS -g --digest -u "${DVR_USER}:${DVR_PASS}"
      --connect-timeout 3 --max-time 15)
BASE="http://$DVR_IP:$PORT/cgi-bin"

O -sS cala a barra de progresso mas deixa o erro aparecer, o --connect-timeout e o --max-time evitam que um script fique pendurado a madrugada inteira num aparelho que travou. Do curl 7.76 em diante existe também o --fail-with-body, que faz o exit code refletir status HTTP de erro sem jogar o corpo da resposta fora. Só não bota ele no probe de descoberta que espera justamente um 401 pra revelar o esquema Digest, senão você transforma o resultado desejado em falha.

Com isso, o backup:

BKP="$HOME/dvr-backup-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BKP" && chmod 700 "$BKP"

for t in VideoColor VideoInDenoise VideoInOptions Encode; do
  curl "${CURL[@]}" "$BASE/configManager.cgi?action=getConfig&name=$t" \
    > "$BKP/$t.txt" || echo "FALHOU: $t" >&2
done

{
  date -Iseconds
  curl "${CURL[@]}" "$BASE/magicBox.cgi?action=getDeviceType"
  curl "${CURL[@]}" "$BASE/magicBox.cgi?action=getSoftwareVersion"
} > "$BKP/contexto.txt"

chmod 600 "$BKP"/*

Modelo, versão de firmware e data no mesmo diretório das tabelas, porque dump de config sem saber de que firmware ele veio é quase inútil daqui a um ano. E não existe, pelo menos não que eu tenha achado nesse firmware, endpoint de restore em massa que engula esse arquivo de volta. Então trata o dump pelo que ele é: referência recuperável pra reaplicar valor por valor com setConfig se algo sair errado. Ele também é a configuração do sistema de segurança da tua casa, então mora com a mesma disciplina do arquivo de credencial, permissão fechada e longe de qualquer repositório.

Escrevendo a configuração (e a pegadinha do glob)

Com o mapa na mão, escrever deveria ser trivial. O setConfig aceita múltiplos campos numa chamada, separados por &. Montei a primeira escrita, mandei, e o servidor respondeu com uma linha em branco. Sem OK, sem erro. E a leitura de volta mostrava os valores antigos, intocados.

O motivo me custou alguns minutos: o curl interpreta [ e ] como globbing de URL (aquele recurso que expande http://site/arq[1-10].jpg). Os índices [0][0] dos nomes de parâmetro caíam direto nessa armadilha e a requisição saía mangled. A correção é uma flag, -g (ou --globoff):

curl -g -s "${AUTH[@]}" \
  "http://$DVR_IP:$PORT/cgi-bin/configManager.cgi?action=setConfig\
&VideoColor[0][0].Brightness=50\
&VideoColor[0][0].Contrast=50\
&VideoColor[0][0].Saturation=50\
&VideoColor[0][0].Acutance=5"

Com o -g, a resposta vira OK e os valores pegam.

Antes de seguir, o aviso que falta nessa linha: -g resolve o colchete, não resolve encoding. Os valores que eu escrevo aqui são números, então passam limpos. No dia em que o valor tiver espaço ou caractere reservado, e tem, o TimeSection é literalmente 1 00:00:00-24:00:00, ele precisa ir codificado. Pensei em montar tudo com --get --data-urlencode, que seria o jeito canônico, e não fui: nessa forma o curl codifica também o nome do parâmetro, e VideoColor%5B0%5D%5B0%5D.Brightness pode ou não ser aceito por esse CGI. Como eu não testei, fico com o -g que eu vi funcionando e digo o que não sei, em vez de recomendar por elegância. Mesma coisa pra POST: não confirmei que esse CGI aceita, então não converti.

Detalhe que vale ouro: foi a leitura de volta que denunciou a falha silenciosa. Se eu tivesse confiado no OK ausente sem reler, teria saído achando que apliquei quando não apliquei nada. O método pra padronizar as quatro câmeras vira um laço sobre os índices de canal, aplicando o mesmo conjunto de valores. Mas a disciplina aqui é a mesma de qualquer mudança em produção: aplica em um canal, confere no preview ao vivo, e só então replica pros outros. Num sistema de segurança eu não faço fan-out de uma mudança não verificada.

E o aparelho me deu mais um motivo pra reler tudo: ao padronizar o stream extra em 10fps, o setConfig respondeu OK nos quatro canais, mas a leitura de volta mostrou três deles travados em 7fps. O DVR aceitou o comando e clampou o valor em silêncio num teto de hardware do stream secundário. Nesse firmware, OK confirma que a requisição foi aceita, não que cada valor foi persistido exatamente como pedido. A única fonte de verdade é reler a config depois de escrever e comparar campo a campo. O que é uma coisa boba de automatizar, e que eu devia ter feito desde o começo:

check() { # check <tabela> <chave> <esperado>
  local got
  got=$(curl "${CURL[@]}" "$BASE/configManager.cgi?action=getConfig&name=$1" \
        | grep -F "table.$2=" | cut -d= -f2-)
  if [ "$got" = "$3" ]; then
    echo "ok        $2=$got"
  else
    echo "DIVERGIU  $2: pedi $3, gravou ${got:-<vazio>}" >&2
    return 1
  fi
}

check Encode 'Encode[0].ExtraFormat[0].Video.FPS' 10

Com isso o 7fps aparece como divergência na cara, não como um OK que eu li rápido. O ciclo que eu sigo agora é sempre esse: escreve, relê, compara pedido com persistido, e só então replica pros outros canais. É o tipo de detalhe que separa “achei que configurei” de “configurei”.

O que levo desse domingo

Três coisas ficam.

A primeira é que muito equipamento doméstico de prateleira tem uma API perfeitamente utilizável, e não documentada, atrás de uma interface ruim. Não que o fabricante esteja escondendo: é o mesmo endpoint que a interface web dele consome, só sem manual em português. DVR, roteador, nobreak, impressora. Vale o probe.

A segunda é o método: alcance, autenticação, leitura, mapeamento, e só no fim a escrita. A leitura não é só reconhecimento, é o que transforma chute em certeza e revela o que o aparelho não expõe.

A terceira é uma pendência que esse exercício escancarou: o DVR está em DHCP. Toda essa automação aponta pra um IP que pode mudar quando o roteador resolver. Próximo passo é reservar um IP fixo pra ele no DHCP do roteador, pra que o script não quebre sozinho numa madrugada qualquer. Endereço de infraestrutura que você automatiza não pode ser volátil, e isso vale tanto pra um DVR de casa quanto pra qualquer serviço que a gente opera em produção.

No fim das contas, a câmera com listra não tem conserto por API, pelo menos não por um caminho que eu tenha achado. A luz que causa o flicker é de um poste da rua, apagar não é opção. O conserto de software seria o anti-flicker, que sincroniza o tempo de exposição com a frequência da rede ou com a pulsação efetiva da iluminação. Numa rede de 60Hz o LED pode piscar em 60 ou em 120Hz dependendo do driver dele, e é por isso que não dá pra recomendar número mágico de shutter sem conhecer a câmera, a luz e os modos que o firmware oferece. De todo jeito é conversa teórica aqui: nem o getConfig das tabelas de exposição nem o getCaps do canal me deram um caminho suportado pra chegar nesse ajuste. Então sobra o físico: tirar o poste do enquadramento direto e pôr um capuz na lente pra cortar a luz que entra reta no sensor. Anticlimático, mas é a verdade que a investigação entregou, e descobri isso sem subir escada nenhuma. Saí com as quatro câmeras padronizadas em segundos em vez de meia hora de clique, e com um mapa da API que vou reusar toda vez que precisar mexer nelas.

As oito famílias do cheatsheet não param na lousa: descem até a loja física e viram fluxo de gente na porta.

Introdução

Existe um cheatsheet clássico circulando pela internet com oito famílias de fórmulas essenciais de data science: estatística descritiva, probabilidade, álgebra linear, cálculo, machine learning, information theory, data science essentials e séries temporais. Na imagem, cada caixa traz três ou quatro fórmulas em notação acadêmica limpa. A reação mais comum de quem bate os olhos é “isso é coisa de pesquisador, eu só faço CRUD”.

Esse post amplia o que comecei a contar no post do alpinista no nevoeiro. Lá mostrei que uma única ferramenta de Cálculo II, o gradiente descendente, sustenta o treinamento de grande parte da IA moderna. Aqui o quadro é maior. Cada uma das oito famílias do cheatsheet tem aplicação direta na operação da Plataforma Harmo, em volume que dá pra dimensionar: processamos 10 milhões de pesquisas e 300 mil avaliações públicas por mês, em mais de 60 mil lojas físicas. Nada disso roda sem matemática trabalhando no background, mesmo quando o time que opera não chama as coisas por esses nomes.

O objetivo aqui é mapeamento, não tutorial. Por onde cada família anda na operação, e como elas se conectam pra entregar coisas concretas. Vou seguir a ordem do cheatsheet só nas primeiras seções, depois agrupo por aplicação porque na vida real as fórmulas raramente aparecem sozinhas. Pra não perder o fio, o mapa das oito caixinhas contra o que aparece nas seções abaixo:

A correlação de ouro: estatística descritiva como bússola comercial

Começo pelo caso mais simples e mais importante. Nas análises internas que deram origem ao que a gente chama de Correlação de Ouro, loja com nota média mais alta no Google Business Profile também aparece com mais pedidos de rota gerados (os cliques de “como chegar”). E o efeito observado é grande o bastante pra ninguém ignorar: a cada 0,1 estrela adicional, aparece em média uma diferença de 8,8% nos pedidos de rota.

Vale separar as duas medidas, porque elas são confundidas o tempo todo, inclusive por mim em conversa apressada. Pearson mede a força e a direção da associação linear, num coeficiente que vive entre −1 e 1. Ele não cospe percentual por 0,1 estrela. O número de 8,8% vem da análise do tamanho do efeito, não do coeficiente. São leituras complementares que respondem perguntas diferentes: uma diz o quanto as duas variáveis andam juntas, a outra diz o quanto isso pesa na prática. Juntas, elas mostram que reputação não é apenas imagem: ela anda junto com indicador concreto de performance.

A fórmula em si é trivial. Correlação de Pearson é a covariância entre as duas variáveis normalizada pelo produto dos desvios padrão de cada uma, e está na primeira página de qualquer livro de estatística:

Aqui \(x\) é a nota média da loja e \(y\) o volume de pedidos de rota. O numerador mede se as duas variáveis se afastam da própria média na mesma direção; o denominador tira a escala, e é por isso que o resultado sempre cai entre −1 e 1.

Mas a aplicação é tudo menos trivial. Descobrir esse ponto, validar que ele se mantém em diferentes segmentos de varejo, sustentar ele dentro de reunião com CFO de cliente, e usar ele como bússola pra decisão de investimento em programa de reputação. Aí mora o valor real da fórmula.

Em paralelo a Pearson, a operação usa o resto da família descritiva o tempo inteiro. Média e desvio padrão pra entender distribuição de notas dentro de uma rede de cliente, identificando lojas que destoam pra cima ou pra baixo. Variância pra dimensionar o quanto os dados se espalham em volta da média, que é o insumo que depois alimenta erro padrão, intervalo de confiança e teste.

Variância e covariância lado a lado, na forma populacional. A segunda é a primeira com duas variáveis em vez de uma: troque o quadrado pelo produto dos dois desvios e a mesma conta passa a medir movimento conjunto. Em amostra, o divisor vira \(n-1\).

Ela sozinha não responde se a diferença entre dois grupos é sinal ou ruído, mas sem ela não dá nem pra fazer a pergunta direito. Covariância pra rastrear como pares de variáveis se movem juntos. Estatística descritiva é o que separa “achismo de loja” de “leitura de loja”, e essa diferença sustenta praticamente toda conversa estratégica entre Harmo e cliente.

Álgebra linear e cálculo: o motor de NLP por dentro

O motor de NLP da Harmo classifica sentimento de avaliação, extrai aspectos mencionados (atendimento, produto, preço, ambiente) e dá suporte a respostas em escala. Tudo isso é álgebra linear e cálculo combinados, em arquiteturas que aprenderam a fazer essas operações em paralelo na GPU.

Cada avaliação que chega vira um vetor numérico de centenas de dimensões através de um embedding. Comparar duas avaliações pra ver se são parecidas pode ser feito calculando a similaridade de cosseno entre os vetores delas:

Note que é a mesma estrutura da correlação de Pearson: produto no numerador, normalização pelas magnitudes no denominador. A diferença é que Pearson centra os dados na média antes, e o cosseno não. Por isso ele mede ângulo entre vetores e ignora o tamanho deles, que é exatamente o que se quer quando uma avaliação é longa e a outra curta.

Agrupar avaliações por similaridade pra entender padrões emergentes cai no mesmo terreno: distância euclidiana ou cosseno aplicados em larga escala, e qual das duas usar depende de como o espaço vetorial foi construído.

A euclidiana mede distância absoluta entre dois pontos; o cosseno mede direção. Duas avaliações sobre o mesmo assunto, uma detalhada e outra em duas linhas, ficam longe na euclidiana e perto no cosseno.

Identificar avaliações que poderiam ser respondidas com um mesmo template (porque tratam do mesmo tema) é busca de vizinhança no espaço de embedding.

A multiplicação de matrizes é a operação de base de tudo isso. Cada camada de um modelo neural moderno tem, no núcleo, uma matriz de pesos multiplicando uma matriz de entrada. Modelos de linguagem que rodam por trás de classificadores e extratores fazem isso milhares de vezes por inferência. A fórmula é esta, e ela descreve uma das operações que dominam o custo computacional da inferência desses modelos:

Uma multiplicação de matrizes de tamanho \(n\) custa na ordem de \(n^3\) operações na forma ingênua. É essa cúbica que explica por que inferência de modelo grande é caro, e por que GPU existe.

E quando o problema é o oposto, reduzir dimensão em vez de multiplicá-la, PCA e eigenvalues são o caminho clássico da família: comprimir dezenas ou centenas de métricas de loja em componentes que preservam a parcela de variância definida como suficiente pra aquela análise. Quanto de variância sobra não é dado da natureza, depende de quantos componentes você mantém e do threshold que decidiu adotar.

O cálculo entra no momento de treinar. Treinar um classificador de sentimento é minimizar uma função de erro, e minimizar uma função de erro é exatamente o gradiente descendente que descrevi no post anterior, repetido numa escala que seria impossível acompanhar manualmente. Derivada parcial em cada peso da rede, retropropagada pela regra da cadeia, parâmetro por parâmetro, batch por batch.

À esquerda, o passo do gradiente descendente: ande na direção contrária à do gradiente, num tamanho de passo \(\eta\). À direita, a regra da cadeia, que é como o erro medido na saída chega até um peso lá no meio da rede. A retropropagação é essa multiplicação aplicada camada a camada, de trás pra frente.

O Cálculo II da prova final virou infraestrutura silenciosa do classificador. A regra da cadeia que parecia exercício de aula virou o algoritmo de retropropagação que treina as redes neurais modernas.

Séries temporais e detecção de anomalia: matemática que dispara alarme

A operação gera séries temporais o tempo inteiro. Volume de avaliações por hora, latência de microserviço, custo AWS por serviço por dia, NPS rolando ao longo da semana, taxa de resposta a avaliações por loja. Boa parte das anomalias que disparam alarme operacional aqui dentro sai de alguma combinação de três fórmulas dessa família, quase sempre com uma comparação contra baseline em cima.

Moving average é o ponto de partida. Você compara o valor de hoje com a média rolling de 7 ou 14 dias. Se o valor escapa de uma faixa razoável, é sinal.

À esquerda a média dos \(k\) períodos anteriores; à direita o desvio percentual do valor de hoje contra ela. É literalmente o que os nossos alarmes calculam, com \(k = 7\) e limite em \(\Delta_t > 0{,}5\).

Aplicado: o robô diário de cost tracking compara o custo do dia com a média dos 7 dias anteriores e abre task automaticamente quando um serviço estoura 50% acima dela, com piso absoluto em dólar pra não alarmar sobre centavos. O alarme sobre concorrência de lambda contra baseline rolling de 7 dias, que ficou de pé depois do postmortem do loop em Step Functions, é moving average aplicado em métrica de invocação. Nos dois casos o mecanismo é desvio percentual contra a média móvel, não coisa mais sofisticada que isso.

Z-score é o irmão mais formal dessa abordagem. Normaliza o valor pelo desvio padrão da série e pergunta “quantos desvios padrão isso está fora da média?”.

A diferença entre esta fórmula e a de cima é o denominador, e é ela que separa as duas coisas: dividir pela média dá desvio percentual, dividir pelo desvio padrão dá z-score. Só a segunda é comparável entre séries de escalas diferentes.

A distinção importa na hora de nomear o que você tem: comparar valor contra baseline só vira z-score quando você divide pelo desvio padrão, e a maior parte dos alarmes que citei acima para no desvio percentual mesmo. Em série suficientemente estável, a gente usa valor acima de 3 como sinal forte e acima de 4 como caso extremo. É heurística operacional, não regra universal, e em série com cauda pesada ou sazonalidade forte esses cortes enganam. Onde isso encaixa no nosso mundo: detectar avaliação suspeita (loja recebendo 50 avaliações em uma hora quando o normal seriam 5), flagrar comportamento de pesquisa anômalo, investigar caso extremo antes de calcular correlação, separando erro de coleta de variação legítima pra não distorcer a leitura. Esse último ponto merece cuidado: loja que explodiu em avaliação porque tomou fraude é uma coisa, loja que explodiu porque abriu num shopping novo é outra, e jogar as duas no mesmo filtro automático é jogar informação fora.

Exponential smoothing e autocorrelação entram na previsão. Estimar quantos pedidos de rota uma loja deve gerar nas próximas duas semanas, dado o histórico dela e a sazonalidade conhecida.

A suavização exponencial dá peso decrescente ao passado, e \(\alpha\) decide o quanto o valor de hoje manda na estimativa. A autocorrelação é a correlação da série com ela mesma deslocada em \(k\) períodos: é assim que sazonalidade semanal aparece como pico em \(k = 7\).

Capacity planning de processamento em janelas de pico, baseado em volume previsto de avaliações. Quando o time fala em “previsão suavizada”, está aplicando exponential smoothing, mesmo quando ninguém chama por esse nome.

Probabilidade e information theory: decisão sob incerteza

A última camada que vale destacar mistura duas famílias: probabilidade e information theory, as ferramentas que sustentam decisão quando não há certeza completa, o que é praticamente sempre.

Bayes formaliza uma ideia que aparece o tempo inteiro em decisão sob incerteza: você parte de uma estimativa anterior e atualiza ela quando chega evidência nova. Estimar a probabilidade de um cliente fazer churn dado o histórico de NPS dele é um problema desse formato. Atualizar a probabilidade de uma avaliação ser falsa dado um padrão suspeito de IP, conta e timestamp também. Uma ressalva que eu mesmo já atropelei: o modelo cuspir uma probabilidade condicional no final não significa que ele seja bayesiano por dentro. Bayes aqui é o modo de raciocinar, não a descrição da implementação. A fórmula é compacta, três símbolos arrumados em uma razão, e esse modo de raciocinar cobre boa parte do nosso trabalho de classificação probabilística.

Lendo da direita pra esquerda: você tinha uma crença inicial \(P(A)\), chegou a evidência \(B\), e a razão ajusta essa crença conforme a evidência é mais ou menos esperada. Aplicado a avaliação falsa: \(A\) é "a avaliação é fraudulenta" e \(B\) é o padrão suspeito de IP, conta e horário.

Valor esperado é mais simples e igualmente potente. Se uma intervenção em loja tem 30% de chance de gerar 10 pedidos de rota adicionais e 70% de chance de gerar 2, o valor esperado é 4,4 pedidos por intervenção.

Toda a força dessa fórmula está em obrigar você a escrever a probabilidade que já estava na sua cabeça. Depois de escrita, ela pode ser discutida, e é aí que a conversa sai do achismo.

Multiplica isso por escala de milhares de lojas e você tem decisão de investimento orçamentário ancorada em matemática, não em achismo. Aparece em conversa de pricing, de roadmap de feature, de priorização de cliente.

Entropy, cross-entropy e KL-divergence são onde a coisa fica densa, mas valem o esforço. Entropia mede o quão incerto é um sistema.

As três são a mesma soma com peças trocadas. A entropia usa a distribuição contra si mesma; a cross-entropy troca o segundo termo pela distribuição prevista, e é isso que a torna função de erro; a KL é a diferença entre as duas, ou seja o custo de usar \(q\) quando a verdade é \(p\). Vale reparar que ela não é simétrica: trocar \(p\) e \(q\) de lugar muda o número.

Cross-entropy é uma das funções de erro mais usadas no treinamento de classificador com múltiplas classes; nos classificadores neurais de sentimento, é ela que o treino minimiza, debaixo dos panos. KL-divergence não é medida simétrica de semelhança: ela mede o quanto uma distribuição diverge de uma distribuição de referência, e a ordem importa, porque KL de A pra B não dá o mesmo número que KL de B pra A. Perguntar “o quanto a distribuição de sentimento da loja A se afasta da distribuição da rede dela?” é o tipo de pergunta que essa família responde, com leitura comercial direta. Quando o que você quer é comparar duas lojas de igual pra igual, aí é outra métrica, e a escolha muda a interpretação do resultado. Mutual information vira ferramenta de feature selection: qual variável carrega mais informação sobre o que queremos prever, e qual é redundante?

O termo dentro do logaritmo compara a distribuição conjunta com o que ela seria se as duas variáveis fossem independentes. Quando dá zero, a variável não diz nada sobre o alvo. Note que é uma KL disfarçada, entre a conjunta real e a conjunta hipotética das independentes.

Information theory parece esotérica até o momento em que você precisa selecionar features pra um modelo com centenas de candidatas. Aí ela vira ferramenta especialmente útil pra separar quais variáveis carregam informação relevante sobre o que você quer prever e quais são redundância cara de carregar. Registro honesto: aqui isso é aplicação possível da família, não etapa fixa do pipeline de hoje.

Fechamento

O cheatsheet tem oito caixinhas. Cada uma é uma família de ferramenta matemática. A leitura mais útil dele não é “preciso decorar tudo isso pra fazer data science”. É “cada uma dessas famílias tem aplicação concreta em produção, e a maioria delas é exatamente o que sustenta o que você consome hoje em qualquer plataforma SaaS séria”.

Na Harmo, a estatística descritiva sustenta a Correlação de Ouro que orienta a proposta de valor inteira. A álgebra linear e o cálculo sustentam o motor de NLP que processa avaliações em escala. As séries temporais sustentam os alarmes operacionais que evitam que incidente vire desastre. A probabilidade e a information theory organizam a decisão sob incerteza que define onde investir o tempo do time e o orçamento dos clientes. Cada caixinha do cheatsheet aparece em algum momento do dia operacional, mesmo quando ninguém chama as coisas por esses nomes.

Fechando a amarração do post do alpinista no nevoeiro: aquele aluno de Cálculo II que torcia o nariz pra derivada parcial estava aprendendo o motor de uma das oito famílias. As outras sete, ele já viu, em Cálculo I, em Estatística, em Álgebra Linear, em Probabilidade. Tudo o que parecia abstração de prova é, dez anos depois, infraestrutura silenciosa do que ele usa pra trabalhar. A diferença entre o aluno que aproveita isso na carreira e o que não aproveita é só saber onde olhar.

Qual dessas oito famílias você aplica em produção sem enxergar como matemática? Aparição disfarçada é o caso comum: regra de negócio que esconde uma probabilidade condicional, métrica de dashboard que esconde uma moving average, threshold de alarme que esconde uma comparação contra baseline. Rastrear essas é o exercício mais útil que o cheatsheet permite.

Um cérebro só decide a ordem; muitas mãos executam. O scheduler resolve o grafo de dependências e dispara os workers que fazem o trabalho pesado.

Introdução

Airflow é Python por natureza. MWAA é o Airflow gerenciado da AWS. EKS é onde nossos workloads pesados rodam, em Go (cluster Kubernetes). A combinação dos três não é a mais óbvia, mas é a que sustenta hoje a maior parte dos pipelines de dados que rodam por trás da Plataforma Harmo. Esse post conta o porquê dessa escolha e como as peças se encaixam.

A escala que essa stack sustenta hoje: mais de 25 DAGs ativas em produção, executando cerca de mil tasks por dia com taxa de falha de 0,35% no último mês. Dessas tasks, uma média de 500 por dia vira pod de Go no EKS, cerca de 15 mil pods em 30 dias, cuidando da coleta, do processamento e da sincronização das mais de 300 mil avaliações públicas que entram por mês na plataforma.

Antes de entrar na arquitetura, vale dizer o que isso substituiu. A geração anterior era cronjobs agendando Lambdas em Node.js, coladas por filas SQS, e mais tarde Step Functions coordenando os fluxos de coleta. O MWAA entrou em março de 2024, mas não houve corte: parte do legado coexistiu por mais dois anos.

Por que Airflow

DAG como código em Python virou o ganho mais imediato. Cadeias de dependência entre tasks que viravam código procedural feio em cron + script bash ganharam estrutura declarativa: quem depende de quem, qual o critério de sucesso, qual a política de retry, qual a janela de execução. UI nativa pra backfill, retry manual, visualização de dependências, gestão de SLA. Ecossistema maduro de operators que cobre a maioria dos casos de integração comum.

A maturidade do Airflow trouxe um custo conhecido: ele assume Python no plano da orquestração. E aí entra a decisão de manter Python apenas no scheduler, deixando o trabalho pesado fora dele.

Por que MWAA pro scheduler e EKS pro runtime

A primeira pergunta foi onde hospedar o Airflow em si. Self-hosted via Helm chart oficial no EKS era opção possível, mas trazia operação inteira do Airflow pra dentro do time: upgrade de versão, gerenciamento de scheduler/web server/workers, backup de metadata DB, segurança. MWAA absorve boa parte dessa operação como serviço gerenciado, em troca de menos flexibilidade fina. Pra um time que quer Airflow como ferramenta e não como produto operado, vale a troca.

Nosso ambiente é um mw1.medium rodando Airflow 2.10.1, com dois schedulers e workers Celery escalando de um a cinco. Classe modesta de propósito: o MWAA só coordena. Se o ambiente precisasse ser grande, seria sinal de que trabalho pesado está vazando pra dentro do scheduler.

A segunda pergunta foi onde rodar o trabalho pesado. A Harmo já roda mais de 50 microservices em Go no EKS, com observabilidade, autoscaling, secrets management e quotas de recurso compartilhados. Subir compute pro trabalho pesado em outro lugar (Lambda, ECS, Batch) seria duplicação de operação sem ganho. Então a decisão foi natural: scheduler no MWAA, workload no EKS.

O ponto que destrava a topologia é a integração entre os dois. MWAA tem permissão de chamar a API do EKS via execution role configurada com IAM. Isso permite que o KubernetesPodOperator dentro de uma DAG aponte pro nosso cluster EKS e suba pods lá, mesmo o Airflow não morando dentro do cluster. Cada task pesada vira um pod Go separado no EKS, disparado pelo MWAA via API call de pod create. O scheduler nunca hospeda o processo pesado: ele acompanha um pod e um estado.

Por que Go pros workers

Workers do Airflow padrão em Python sustentam a coordenação, não o trabalho pesado. Pro perfil dos nossos workers, que é muito I/O concorrente, paginação e escrita em massa em banco, Go tem entregado throughput maior, consumo previsível e uma operação que o time já domina. Footprint de container fica pequeno, startup time fica curto, e o padrão de worker pool com errgroup, context e cancelamento limpo já virou rotina por aqui.

Quatro categorias cobrem quase tudo que roda em Go por aqui. Coleta de avaliações em fontes externas (Google, iFood, TripAdvisor, etc), em lotes que chegam via arquivo no S3. Processamento de texto e IA sobre o que foi coletado, extraindo sentimento, termos e categorias, que é onde está o maior volume de pods do dia. Sincronização de feeds com a ponta do Google: catálogo, cardápio, ofertas. E disparo de notificações e consolidação de relatórios. Todos os workers seguem o mesmo formato: binário único compilado pra arm64, imagem mínima, cmds=["./main"] como entrypoint.

Em paralelo, mantemos workers em Python pra coisas em que Python ganha de Go por bibliotecas (manipulação de DataFrame com pandas, ML clássico com scikit-learn, integrações com bibliotecas científicas). A escolha de linguagem por task é feita conscientemente, não por inércia.

A topologia

O fluxo típico de uma task pesada é o seguinte. DAG em Python define o KubernetesPodOperator com a imagem do worker em Go, parâmetros de entrada via variáveis de ambiente ou arquivo de config, e política de retry/timeout. Airflow dispara o pod no cluster, o pod roda o binário Go que faz o trabalho, escreve resultado em destino persistente (S3, Postgres, Kafka, dependendo da task) e termina. O operator acompanha o estado do pod até o fim e traduz esse término em sucesso ou falha da task, e é isso que decide se o fluxo segue pra próxima ou entra em retry.

Uma DAG de coleta real, enxuta e anonimizada, fica assim:

import datetime
from airflow import DAG
from airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator
from airflow.utils.task_group import TaskGroup
from kubernetes.client import models as k8s

dag = DAG(
    dag_id="coleta_avaliacoes",
    start_date=datetime.datetime(2026, 5, 5),
    schedule="0 4,17 * * *",
    catchup=False,
)

def cria_pod(lote_id, arquivo, versao):
    return KubernetesPodOperator(
        dag=dag,
        task_id=f"coleta_avaliacoes_{lote_id}",
        namespace="<NAMESPACE>",
        image=f"<REGISTRY>/coletor-avaliacoes:{versao}",
        cmds=["./main"],
        arguments=["-data", arquivo],
        annotations={
            "karpenter.sh/do-not-disrupt": "true",
            "cluster-autoscaler.kubernetes.io/safe-to-evict": "false",
        },
        container_resources=k8s.V1ResourceRequirements(
            requests={"cpu": "500m", "memory": "1024Mi"},
            limits={"cpu": "500m", "memory": "1024Mi"},
        ),
        get_logs=True,
        is_delete_operator_pod=True,
        retries=3,
        startup_timeout_seconds=350,
    )

with TaskGroup("coleta", dag=dag) as grupo:
    for i, arquivo in enumerate(lista_arquivos_do_lote(), start=1):
        cria_pod(i, arquivo, versao_imagem())

As annotations de anti-disrupção e o requests igual ao limits não são decoração, e cada um resolve um problema diferente: cada uma dessas linhas é cicatriz de incidente, e conto a história na seção das cicatrizes. Boa parte das DAGs nem instancia o KubernetesPodOperator direto: usa um operator interno que o estende com os defaults (namespace, recursos, proteção contra disrupção), pra que DAG nova não reinvente configuração.

Pra dados pequenos entre tasks (IDs, timestamps, métricas de resumo), usamos XCom. Pra dados grandes (datasets, payloads completos), o intermediário é storage externo: o pod escreve em S3, a próxima task lê o path do XCom e busca o conteúdo de lá. A regra por aqui é XCom carrega referência, não payload. Isso é decisão da nossa arquitetura, não limitação universal do Airflow: o XCom aguenta mais do que a gente deixa passar por ele, mas dado grande no metadata DB é acoplamento que a gente não quer.

As cicatrizes da arquitetura

Cinco aprendizados que custaram tempo.

Eviction no meio da coleta. Uma das nossas coletoras leva cerca de meia hora pra varrer mais de 2 mil estabelecimentos. Em maio, execuções começaram a morrer no meio do caminho: numa delas, 1.189 de 2.037 estabelecimentos se perderam quando o pod foi despejado por EvictionByEvictionAPI. A consolidação do Karpenter tinha decidido que aquele nó podia ser drenado, e os pods rodavam em QoS Burstable, sem nenhuma proteção declarada. A correção saiu em duas ondas no mesmo dia, e ela junta dois mecanismos que a gente aprendeu a não confundir.

A annotation karpenter.sh/do-not-disrupt fala com o Karpenter: pede pra ele não escolher aquele nó pra consolidação ou drain voluntário. Requests iguais a limits fazem outra coisa: promovem o pod a QoS Guaranteed, o que reduz o risco de eviction quando o nó entra em pressão de recurso. Nenhuma das duas cobre o buraco da outra. QoS Guaranteed sozinho não impede o Karpenter de consolidar ou drenar o nó embaixo do pod, e do-not-disrupt não protege contra toda disrupção involuntária ou forçada: se o nó morre, se alguém drena na força, o pod cai igual. A cluster-autoscaler.kubernetes.io/safe-to-evict: "false" que aparece no exemplo entrou na mesma onda e continua lá, mas ela fala com o Cluster Autoscaler do Kubernetes, não com o Karpenter, então não é ela que segura a consolidação por aqui.

Na segunda onda, espelhamos as duas proteções nas duas coletoras mais longas do parque, com execuções de duas a três horas, que eram alvos ainda maiores. Pod de task longa sem proteção explícita é aposta contra o autoscaler, e o autoscaler ganha.

O retry do Airflow reinicia do zero. Todos os nossos pods rodam com retries=3, e o incidente de eviction confirmou na prática: task despejada aos 90% refaz 100%. Isso transforma idempotência em pré-requisito de design, não em refinamento. Cada worker recebe um lote fechado via arquivo no S3 e precisa poder reprocessar o mesmo lote sem duplicar no destino. Não temos registro de duplicação em produção, e quero que continue assim, porque isso é propriedade de desenho, não de sorte.

O CLI do MWAA não conhece as suas DAGs. Rodar dags list pelo endpoint de CLI do MWAA retornava 3 das nossas DAGs, com um ModuleNotFoundError: No module named 'airflow.providers.cncf' pras outras. O container que atende o CLI não tem o provider do Kubernetes instalado, então falha ao parsear qualquer arquivo que use KubernetesPodOperator, enquanto o scheduler parseia e executa tudo normalmente. dags details, que consulta o banco de metadados em vez de parsear arquivo, funciona pra todas. Custa alguns minutos de pânico até perceber que é artefato do CLI, não DAG quebrada.

Logs em dois lugares por construção. Com get_logs=True, o Airflow puxa o stdout do pod e reemite no log da própria task, que vai pro CloudWatch no log group de tasks do MWAA. Se o worker também envia log direto pro CloudWatch, a mesma linha passa a existir em dois grupos, com dois caminhos de busca diferentes. Vale decidir cedo qual é a fonte da verdade na hora do incidente, antes que a resposta seja descoberta às 3 da manhã.

A DAG que consulta a AWS no parse. Nas DAGs de coleta, a lista de pods é montada no nível do módulo: a cada ciclo do DAG processor, o arquivo consulta o ECR pra resolver a versão da imagem e lê o lote no S3 pra decidir a topologia. Funciona, mas acopla o parse das DAGs à disponibilidade de duas APIs da AWS e paga essas chamadas continuamente, não só na execução. Se o ECR soluçar, o scheduler enxerga DAG quebrada. É dívida assumida, e registrar ela num post público é um jeito de não fingir que não existe.

Lições aprendidas

• Worker padronizado corta custo de manutenção. Cada worker é um binário Go compilado pra arm64 numa imagem mínima, com ./main de entrypoint. Qualquer coisa além disso na imagem é sintoma de worker mal desenhado.

• XCom carrega referência, não payload. Lote entra por arquivo no S3 e o XCom leva só metadado: path, contagem, versão de imagem. É decisão nossa, não limite do Airflow, e precisa ser explícita no time, não convenção implícita, senão a DAG cresce torta.

• Idempotência vale mais que retry esperto. O retry do Airflow reinicia a task do zero, então o worker que não sabe reprocessar o próprio lote sem duplicar é uma duplicação agendada.

• Task longa exige proteção explícita, e são duas proteções distintas. Requests iguais a limits promovem o pod a QoS Guaranteed e reduzem eviction por pressão de recurso; karpenter.sh/do-not-disrupt é o que pede ao Karpenter pra não consolidar o nó embaixo do pod. Burstable e sem annotation numa task de 3 horas é aposta contra o autoscaler.

• Métrica retida não é alarme. O MWAA publica tudo em CloudWatch, mas não cria alarme nenhum por padrão. Alarme de orquestração é trabalho seu, e é o tipo de coisa que se descobre tarde.

• Pod não é pra task trivial. Aqui, aproximadamente metade das execuções vira pod; o resto roda em PythonOperator e afins dentro do próprio worker do MWAA. Subir pod, puxar imagem e inicializar runtime pra 200ms de trabalho transforma uma task rápida numa task de 30 segundos.

Conclusão

A maior parte das empresas trata Airflow e Python como um pacote indivisível: orquestra em Python, executa em Python, escala em Python. Pra quem já opera workload pesado em Kubernetes, o desenho mais limpo é outro. O scheduler resolve o grafo, dispara o pod e cobra o resultado, e nesse papel restrito o Airflow é excelente. O trabalho pesado fica onde a operação já sabe rodar, observar e escalar: no cluster, em Go.

Não escolhemos uma stack exótica. Escolhemos limitar a responsabilidade de cada peça.

O scheduler coordena. O cluster executa. O worker processa.

E cada um faz só o trabalho que sabe fazer melhor.

Duzentos alertas piscando, e o que importa é aquele único sinal que você consegue enxergar no meio do ruído.

Introdução

Essa é a última peça de uma série que caminhou por crise de performance no banco, batch inserts, IRSA e Pod Identity, relatórios de custo e concorrência em Go. Cada um desses posts resolveu um problema específico. Observabilidade é o que liga eles, o que transforma “consegui consertar” em “vou ver chegar da próxima vez”.

Vou falar do que realmente usamos na Harmo pra operar o cluster EKS: stack de métricas, estratégia de logs, e principalmente a filosofia de alerta, que é onde a maioria das operações se perde, seja por alertar demais, seja por alertar de menos.

Métricas: Prometheus + Grafana é o default por um motivo

O stack Prometheus + Grafana é o default no Kubernetes por motivos práticos:

• Integração nativa via ServiceMonitor. Qualquer serviço que exponha /metrics entra no scrape automaticamente.
• PromQL é a lingua franca. Aprende uma vez, usa em todo lugar.
• Alertmanager é separado de Grafana. Alerting não depende do dashboard estar respondendo.
• Custo controlado. Você paga storage e compute dos nós que já tem. Sem per-metric pricing.

Na prática, instala via Helm chart kube-prometheus-stack (antigo Prometheus Operator), ajusta retention conforme disco disponível, e está 80% do caminho.

prometheus:
  prometheusSpec:
    retention: 30d
    retentionSize: "80GB"
    storageSpec:
      volumeClaimTemplate:
        spec:
          storageClassName: gp3
          resources:
            requests:
              storage: 100Gi

30 dias de retention é suficiente pra investigar qualquer incidente recente. Pra análise de tendência mais longa, exporta pra S3 via Thanos ou Mimir, mas só se você tem caso real de uso. Não instala por instalar.

Logs: centralize, mas não tudo

Logs no Kubernetes têm três caminhos comuns:

Usamos Loki. Motivo: integra direto com Grafana (queria dashboards correlacionando log e métrica no mesmo painel), tem custo previsível, e força disciplina de labels. Indexar só labels e ler texto bruto vira hábito que paga.

O erro clássico: centralizar todo log de toda aplicação de todo nível. Você paga storage por ruído. Política que adotamos:

• Aplicação em produção: INFO e acima.
• Nó e infra: logs de sistema, kubelet, containerd.
• Audit log do Kubernetes: sim, sempre.
• Debug logs: só quando debug. Liga temporariamente via config, desliga depois.

A estratégia de alerta

Aqui mora o que mais diferencia operação boa de operação ruim. A armadilha é simples: você começa com poucos alertas, eles avisam bem, você vai ganhando confiança e adicionando mais. Em 6 meses você tem 200 alertas, metade é falso positivo, você começa a ignorar. E no dia que alerta verdadeiro chega, ele some no meio do ruído.

Regra que seguimos: alerta só existe se tem ação humana associada e precisa acontecer agora. Se a ação pode esperar o horário comercial, não é alerta, é uma task no board. Se não tem ação (“a CPU subiu”), não é alerta, é métrica no dashboard.

Três camadas que valem alertar:

1. Alertas de disponibilidade (página alguém)

• API principal retornando 5xx em taxa acima de baseline
• Fila de processamento com idade do item mais velho acima de threshold
• Banco indisponível ou latência de commit acima de patamar
• Cluster sem nós prontos ou com pressure crônico

Essas acordam gente de madrugada. Tem que ser tratadas como coisa séria: runbook conhecido, SLA de resposta, e postmortem depois.

2. Alertas de anomalia (não-urgente, mas sinal)

• Custo diário AWS acima do baseline (o CronJob do post 4 já resolve isso)
• Taxa de erro acima de baseline mas abaixo do crítico
• Queda súbita em throughput (queue drenando mais devagar)

Esses chegam em canal de Slack, sem on-call. Se ninguém olhar em 24h, não quebra nada, mas se aparecerem três juntos, muda de gravidade.

3. Alertas de saúde técnica (semanal)

• Índices do banco com idx_scan = 0 há mais de 30 dias
• Imagens com CVE alto não atualizadas
• Certificado vencendo em menos de 15 dias

Esses viram tasks num board. Nunca alerta real, só coisa pra revisar no ritmo certo.

Exemplos de regra no Prometheus

groups:
  - name: api-availability
    rules:
      - alert: ApiHighErrorRate
        expr: |
          sum(rate(http_requests_total{status=~"5.."}[5m]))
          / sum(rate(http_requests_total[5m])) > 0.05
        for: 3m
        labels:
          severity: page
        annotations:
          summary: "API com 5xx acima de 5% há 3 minutos"
          runbook: "https://wiki.internal/runbook/api-5xx"

      - alert: DbCommitLatencyHigh
        expr: pg_stat_database_commit_time_seconds > 1
        for: 5m
        labels:
          severity: page
        annotations:
          summary: "Latência de commit no Postgres > 1s"

Três detalhes não-negociáveis:

• for (duração antes de disparar): evita alarme por ruído de 30 segundos.
• severity: roteamento no Alertmanager. page acorda, ticket cria task, warning fica no Slack.
• annotations.runbook: link pra o que fazer. Alerta sem runbook é alerta novo, e alerta novo nunca deveria ir pra page na primeira vez.

Fechando o loop com os posts anteriores

Cada post da série deixou uma deixa pra cá:

• Crise no Aurora: alerta em latência de commit e em idx_scan = 0 (saúde técnica semanal) teria detectado a deterioração antes do pico.
• Batch inserts: alerta em idade do item mais velho na fila detecta regressão de throughput antes do cliente reclamar.
• IRSA / Pod Identity: alerta em AccessDeniedException com baseline por serviço detecta config quebrada rapidamente.
• Relatório de custo: o CronJob gera anomalia detectada, já é alerta estruturado.
• Worker pool em Go: expor métricas de goroutines ativas, queue length e erros por worker torna o pool observável.

Lições aprendidas

• Observabilidade é investimento contínuo. Cada incidente é uma oportunidade de adicionar a métrica ou o alerta que teria avisado antes. Feito depois, ainda é feito.
• Menos alerta é mais alerta. Alerta só existe se aciona humano e tem ação. Tudo outro é dashboard ou task.
• Runbook no annotation, sempre. Alerta sem runbook é quase um alerta falso, vai chegar numa pessoa que não sabe o que fazer.
• Custo também é métrica. Tratar custo como sinal técnico, não como “problema do financeiro”, reduz surpresa no fim do mês.
• Loop fechado vale mais que ferramenta cara. Um stack simples e bem usado bate um stack sofisticado e abandonado.

Fechando a série

Seis posts cobriram um corte de cloud-native operado de verdade: banco sob pressão e como reagir, consumer eficiente, permissões de pod, visibilidade de custo, concorrência na ponta, e a camada que fecha o loop: observabilidade e alerta.

Nada disso é novo. O valor está em colocar tudo junto e defender a decisão de não sofisticar onde não precisa. Operação boa é repetível, e repetível é o que você consegue explicar pra alguém que entrou no time ontem.

E no seu cluster, qual foi o último alerta que mudou como vocês operam: um que você adicionou preventivamente, ou um que só existe porque um incidente já tinha acontecido?

Descer no escuro, um passo de cada vez: é assim que o modelo encontra o fundo do vale.

Introdução

Em 2015 escrevi aqui no blog sobre como sobreviver a Cálculo I. Era um post de calouro recém-saído da prova final, escrito com a empolgação de quem tinha se apaixonado de vez por uma matéria que metade da turma jurou ser impossível. Dez anos depois, releio aquele post com afeto. O autor de vinte anos não tinha como saber, mas estava aprendendo o vocabulário básico de uma coisa que dez anos no futuro ia ser a infraestrutura silenciosa de tudo que ele usa pra trabalhar.

Nas últimas semanas escrevi por aqui sobre os 30 dias que passei dentro do Claude Code, rodando o equivalente a USD 8.069 em tokens e entregando quatro vezes mais que num mês normal. Escrevi também sobre construir um slash command pra não perder contexto entre sessões, e sobre o Clawtop, dashboard que montei pra acompanhar minha assinatura rodando em duas máquinas. Tudo tratando IA como uma caixa preta sofisticada. Caixa que eu sei usar, que eu sei me beneficiar, que entrega leverage de outro patamar.

Esse post é o olhar por dentro. E o engraçado é que o que tem ali é exatamente o que eu amei estudar em Cálculo II e nunca imaginei rever na vida prática. As derivadas parciais (sonho com elas até hoje). Aquele negócio que eu achava lindo de um jeito abstrato: gradiente, jacobiana, todo um vocabulário que eu curtia pela elegância, sem fazer a menor ideia de onde ele ia desembocar dez anos depois.

Pois é. O que eu amava como abstração elegante era, o tempo todo, pura aplicação esperando uma década pra aparecer. Porque o gradiente descendente, ferramenta que nasce direto das derivadas parciais de Cálculo II, é literalmente o motor que treina toda IA moderna. Cada resposta que sai do Claude, do ChatGPT, de qualquer LLM que você usa hoje, foi possível porque alguém calculou bilhões de gradientes em algum momento do treinamento. Esse post é sobre como isso funciona, contado com a intuição que eu queria ter tido em 2015.

O alpinista no nevoeiro

Pra entender o gradiente descendente sem cair em fórmula formal, segura essa imagem. Você é um alpinista. Está na encosta de uma montanha, num lugar qualquer, e tem uma única intenção: descer até o vale. Tem só um problema. Você está num nevoeiro tão denso que não consegue enxergar nem o vale nem o pico. Não tem GPS. Não tem mapa. Os olhos não servem pra nada ali.

O que você tem é a sola do pé. Você sente o chão. Pode pressionar com a bota em direções diferentes e perceber em qual direção o terreno inclina pra baixo mais rapidamente. É um sinal sensorial, físico, simples. A decisão também é simples: você dá um passo nessa direção. Não dois, não vinte. Um passo, cuidadoso, na direção que parecia descer mais.

Depois do passo, você para. Reposiciona a bota. Sente o chão de novo. A direção pode ter mudado, porque o terreno é irregular e o ponto onde você está agora não é o mesmo de antes. Então você recalcula. Identifica de novo a direção em que o chão inclina pra baixo mais rápido. Dá outro passo. Para. Sente.

Faz isso por horas. No começo o terreno desce bem, você sente progresso óbvio, cada passo é claramente descida. Conforme você se aproxima de uma região mais plana, a inclinação fica menos pronunciada, os passos viram exploração mais hesitante. Eventualmente, em algum momento, o chão fica plano em todas as direções que você consegue sentir. Não tem mais pra onde descer. Você chegou em algum vale.

Sem mapa, sem visão. Só com o pé e com a paciência de repetir o gesto. Essa é a intuição inteira. Guarda ela.

O alpinista é a matemática

Agora pega essa imagem e troca o vocabulário. O alpinista vira uma função matemática. A montanha vira a paisagem dessa função em algum espaço de coordenadas. A altura em cada ponto da montanha vira o valor da função nesse ponto. Você quer minimizar a função, o que significa querer chegar no ponto mais baixo, ou seja, no fundo do vale.

O ato de sentir o chão com o pé é literalmente o gradiente. O gradiente é o vetor formado pelas derivadas parciais da função em relação a cada coordenada. Cada componente desse vetor responde a uma pergunta simples e específica: se eu mexer só essa variável aqui, segurando todas as outras fixas, pra qual lado a função cresce mais rápido? Cada coordenada tem sua resposta. Quando você junta todas elas num vetor único, o vetor aponta na direção em que a função cresce mais rapidamente naquele ponto.

Como o alpinista quer descer, e não subir, ele caminha no sentido contrário ao gradiente. Pega o vetor que aponta pra cima e inverte a direção. Esse é o passo do gradiente descendente. Daí o nome do método, traduzido literalmente do inglês: gradient descent. Descer pelo gradiente.

E aqui reaparece, dez anos depois, aquela derivada de Cálculo I. Lembra dela? Aquela coisa de inclinação do gráfico, de tangente à curva, da régua imaginária encostada na curva pra medir o quão íngreme ela é naquele ponto. Pois é. Cada derivada parcial é exatamente isso, mas em uma única direção de cada vez, ignorando todas as outras. A derivada parcial em x mede inclinação no sentido de x. A derivada parcial em y mede inclinação no sentido de y. Junta as duas num vetor bidimensional e você tem o gradiente em um espaço de duas dimensões.

A sola do pé do alpinista é, literalmente, a coleção dessas derivadas parciais. Função objetivo virou montanha. Coordenadas viraram a posição na encosta. Derivada parcial virou sensor de inclinação por direção. Gradiente virou a bota sentindo o chão. Andar no sentido contrário ao gradiente virou o passo de descida. É a mesma matemática que você fez na prova, com nomes diferentes.

Pra cimentar: imagina uma função simples, uma parábola tridimensional que parece uma tigela. O fundo da tigela é o mínimo. Solta um alpinista em qualquer ponto da borda. A cada passo, ele sente o chão, calcula o gradiente, anda no sentido contrário. Em poucos passos, ele chega no fundo. Em duas dimensões, com uma tigela bem-comportada, é exercício de manhã de domingo.

Deixa eu sair da metáfora por dois minutos e mostrar a conta, porque ela é mais simples do que a fama sugere. Essa tigela é a função f(x, y) = x² + y². O fundo dela fica na origem, no ponto (0, 0), onde a função vale zero. É pra lá que o alpinista quer descer. A derivada parcial em x pergunta: segurando y fixo, como f muda quando eu mexo só em x? A resposta é 2x. A derivada parcial em y, pela mesma lógica, é 2y. O gradiente é só o par das duas junto: ∇f = (2x, 2y). Esse vetor aponta pra direção de subida mais rápida em cada ponto.

Agora solta o alpinista em (3, 1), lá na borda. O gradiente nesse ponto é (2·3, 2·1) = (6, 2), o lado pra cima. Como ele quer descer, inverte e caminha no sentido (-6, -2). Mas não anda o vetor inteiro de uma vez, senão passa do fundo e sobe do outro lado. Multiplica por um passo pequeno, digamos 0,1, e o deslocamento vira (-0,6, -0,2). Sai de (3, 1) e chega em (2,4, 0,8). Mais perto do fundo. No ponto novo recalcula o gradiente, (4,8, 1,6), inverte, dá outro passo pequeno, e vai pra (1,92, 0,64). E de novo. Cada passo encurta a distância até a origem. Repete umas dezenas de vezes e ele está praticamente no fundo da tigela. Sentir o chão é calcular (2x, 2y). Dar o passo é subtrair uma fração disso. É a metáfora inteira virando aritmética de ensino médio.

E repara numa coisa, porque é o que eu queria ter entendido lá em 2015: nada disso aí em cima é cálculo sozinho. Ponto com coordenadas, vetor com direção e sentido, uma superfície desenhada num sistema de eixos. Isso é geometria analítica inteira. O gradiente só faz sentido porque é um vetor num espaço de coordenadas, e o passo do alpinista só é um passo porque a gente sabe somar um vetor a um ponto. O aluno que trata geometria analítica como a matéria chata que antecede o cálculo de verdade é exatamente o que, lá na frente, olha pro gradiente descendente e enxerga símbolo solto. Quem dedica tempo aos eixos, aos vetores, às superfícies, ganha o olho que transforma fórmula em paisagem. Sem essa base, derivada parcial vira manipulação cega de letra. Com ela, vira o alpinista sentindo o chão.

A graça começa quando a função não é uma tigela limpa. É uma cordilheira com vales múltiplos, picos secundários, planaltos longos, falhas geológicas. O alpinista no nevoeiro ainda consegue descer, mas pode parar num vale local que não é o mais fundo da paisagem. Esse é o problema fundamental do método. Mas mesmo limitado, ele continua descendo, e em muitos casos o vale local é bom o suficiente pro que se quer fazer.

Bilhões de passos no nevoeiro

Agora cola tudo. Uma rede neural é uma função matemática descomunalmente grande. Tem bilhões de parâmetros, e cada parâmetro é uma coordenada num espaço de bilhões de dimensões. A função associa esses parâmetros a uma medida de erro: dado um conjunto de entradas (texto, imagem, código, o que for) e o que a rede produziu como resposta, o quão longe ela está do que se esperava? Quanto menor o erro, melhor a rede. Treinar a rede é encontrar os parâmetros que minimizam essa função de erro.

Treinar é exatamente o que o alpinista faz, mas em escala que beira o absurdo. Os pesos iniciais da rede são aleatórios, o que equivale a largar o alpinista em qualquer ponto dessa paisagem com bilhões de dimensões. A função de erro é a altura nessa paisagem, e o objetivo é descer. A cada lote de dados que entra, calcula-se o gradiente dessa função de erro em relação a cada um dos bilhões de parâmetros. Inverte o vetor. Dá um pequeno passo na direção oposta. Recalcula. Dá outro passo.

Faz isso milhões, bilhões de vezes. Cada passo é minúsculo, quase imperceptível na escala do total. Mas a paisagem é tão grande que a soma dos passos importa. Em algumas semanas de treinamento, em milhares de GPUs rodando em paralelo, um modelo grande converge pra algum vale dessa paisagem. Não necessariamente o vale mais fundo possível, porque o alpinista no nevoeiro não sabe diferenciar vale local de vale global em uma paisagem de bilhões de dimensões. Mas algum vale onde o erro é baixo o suficiente pra que a rede responda bem em cima de dados que ela nunca viu antes.

Aqui mora a piada que sustenta todo o restante. Toda vez que você faz uma pergunta pro Claude, pro ChatGPT, pra qualquer LLM moderno, a resposta que aparece é o resultado acumulado de bilhões e bilhões de passos desse alpinista no nevoeiro, dados em alguma paisagem com bilhões de dimensões que ninguém vê inteira. O modelo é o alpinista no final da jornada, parado num vale, agora competente em responder a partir do que aprendeu descendo. Você está conversando com o resultado de uma escalada às escuras.

Aquele USD 8.069 em tokens que eu rodei em 30 dias dentro do Claude Code, traduzido em quatro vezes mais entrega no roadmap, não é mágica nem algo misterioso. É o resultado de muito alpinismo no nevoeiro, que aconteceu uma vez durante o treinamento do modelo, e que agora é convocado em outra forma toda vez que eu mando uma mensagem pra ele. O ato de gerar a resposta (a inferência) usa a paisagem já treinada, mas a paisagem em si foi construída por bilhões de passos do alpinista no nevoeiro descendo a montanha do erro durante semanas, em milhares de máquinas que eu nunca vi.

E aqui amarra com 2015. Muito aluno atravessa derivadas parciais achando que é abstração de prova e larga assim que entrega a avaliação. Eu não fui esse aluno: eu amei aquilo. Mas amar a matéria não me deu o que faltava, a noção de onde ela ia desembocar. Dez anos depois, descobri que a elegância que eu curtia no quadro era a infraestrutura silenciosa do que ia me dar quatro vezes mais entrega no mesmo mês. A parte mais engraçada é que a essência continua a mesma coisa simples que era no laboratório de Cálculo. Sentir o chão. Dar um passo. Sentir de novo. Repetir.

Se você está na faculdade hoje, atravessando Cálculo II com a sensação de que nunca mais vai usar aquilo, peço atenção. Você está aprendendo a base do que sustenta a revolução tecnológica do nosso tempo. Talvez você acabe se beneficiando dela sem nunca fazer a conexão. Mas se um dia você decidir olhar pra dentro da caixa preta, vai encontrar a derivada parcial de Cálculo II do mesmo jeito que ela ficou na sua memória. Sentindo o chão. Dando um passo. Sentindo de novo.

Conclusão

Comecei essa minissérie tratando IA como caixa preta: os 30 dias dentro do Claude Code, o slash command pra não perder contexto, o Clawtop monitorando a assinatura em duas máquinas. Tudo da porta pra fora, eu operando a ferramenta sem precisar saber o que tinha dentro. Esse post foi abrir a porta. E o que tem lá dentro não é nenhuma feitiçaria nova: é a derivada parcial que eu calculei na prova de Cálculo II, repetida bilhões de vezes numa paisagem grande demais pra qualquer um enxergar inteira.

Acho que é essa a parte que eu queria ter sacado em 2015. Mas o primeiro lampejo veio antes do que esse arco de dez anos deixa parecer. Já em 2016, um ano depois daquele post de calouro, tive meu primeiro contato sério com machine learning e redes neurais, e ali eu já enxerguei muita coisa dos estudos de Cálculo e principalmente de geometria analítica encontrando aplicação direta, sem abstração nenhuma. Não era o entendimento que tenho hoje, mas foi a primeira vez que o vocabulário do quadro me mostrou que tinha endereço no mundo real. O que faltava era viver isso na pele, e foi o que esses 30 dias dentro do Claude Code finalmente fizeram. A distância entre a abstração elegante do quadro e a coisa que move o mundo é menor do que parece. Não tem um salto mágico no meio, tem acúmulo. Bilhões de passos pequenos numa direção, cada um quase imperceptível, somando até virar uma montanha descida. Vale pra rede neural e vale, sem forçar a metáfora, pra carreira de quem decide aprender a base direito em vez de decorar pra passar.

Quando você manda a próxima mensagem pro Claude e a resposta aparece em segundos, lembra do alpinista no nevoeiro. Você não está conversando com mágica. Está conversando com o resultado de uma escalada às escuras, montada em cima da mesma matemática que um dia te pareceu abstrata demais pra servir pra alguma coisa.

Um comando no fim da sessão: o contexto que importa vira memória, sincronizada entre as máquinas.

Introdução

Em pouco mais de um mês rodando dentro do Claude Code, em duas máquinas, atravessei 180 sessões. Em todas elas, no fechamento, o contexto morria. As decisões, as preferências reforçadas, os “não faz mais X assim” e os “esse padrão funcionou, repete depois” iam todos pro lixo. Na sessão seguinte, eu re-explicava.

Em um post anterior dessa série, sobre os 30 dias dentro do Claude Code, deixei pendente a história do slash command que entrou pra resolver esse problema. Esse aqui é ele. Te conto a necessidade que me fez construir, como funciona, e te ensino a montar o seu próprio. No fim, falo de compartilhar entre máquinas, que foi a peça que destravou pra valer.

A necessidade

O Claude Code já tem um sistema de memória persistente que roda no fundo. É o que a Anthropic chama de auto-memory: durante a conversa, o modelo pode decidir salvar fatos relevantes em arquivos no diretório ~/.claude/projects/<encoded-cwd>/memory/. Esses arquivos viram contexto carregado em conversas futuras no mesmo projeto. É bom, é automático, e cobre o caso óbvio.

O problema é a passividade. O modelo só salva quando “decide” que algo é digno. Coisas que pra mim eram óbvias de carregar (uma decisão de arquitetura específica, uma preferência de escrita validada, etc) ele às vezes salvava, às vezes não. E quando eu queria forçar, ficava digitando “salva isso na sua memória” no fim da sessão, sentindo como se estivesse instruindo um estagiário em três etapas.

A necessidade era simples: um comando que eu invocasse explicitamente no fim de qualquer sessão, com o entendimento de que naquele momento eu quero salvar, e o bar de “vale a pena guardar” pode ser mais baixo do que o automático. Esse é o /save-session.

O que é um slash command no Claude Code

Antes de ir pro código, contexto pra quem nunca construiu. Slash commands no Claude Code são skills custom que você invoca digitando /<nome> na conversa. O Claude detecta o comando, carrega as instruções daquele skill, e executa o procedimento descrito. Skills vivem em duas hierarquias possíveis:

• ~/.claude/skills/<nome>/SKILL.md: disponível em todas as conversas, em todas as pastas do seu sistema. (global no PC)
• <projeto>/.claude/skills/<nome>/SKILL.md: disponível só quando o Claude Code abre dentro daquele projeto. (somente em projeto específico)

Pra um comando utilitário como /save-session, que faz sentido em qualquer sessão, a hierarquia certa é a global em ~/.claude/skills/.

A estrutura mínima de um SKILL.md é frontmatter YAML mais corpo em markdown. O frontmatter declara o comando, o que ele faz e como o usuário interage. O corpo é o procedimento: a instrução em linguagem natural que o Claude vai executar quando você invocar.

---
name: meu-comando
description: O que ele faz, em uma frase
argument-hint: [opcional, ajuda de argumento que aparece no prompt]
disable-model-invocation: true
---

# meu-comando

Instruções em prosa do que o Claude deve fazer quando o usuário digitar /meu-comando.

O campo disable-model-invocation: true é importante: ele impede que o modelo invoque seu skill por conta própria sem o usuário ter digitado o comando. Pra um skill com efeito colateral (escrita de arquivo, leitura de memória, qualquer coisa que altera estado), isso é essencial.

Anatomia do /save-session

O SKILL.md inteiro do /save-session tem cerca de 50 linhas. Vou mostrar o esqueleto e comentar as decisões.

---
name: save-session
description: Extract durable, non-obvious learnings from the current conversation and persist them to the project memory system. Filters out code, ephemeral numbers, and anything derivable from the repo or git history. Use when the user wants to "save", "remember", or "salvar na memória" the current session, or just runs `/save-session`.
argument-hint: [optional scope hint, e.g. "só sobre Redis"]
disable-model-invocation: true
---

# save-session

Triggered explicitly by the user to capture what's worth carrying into future conversations.

## Procedure

1. Locate the memory directory at `~/.claude/projects/<encoded-cwd>/memory/`.
2. Read existing memories first. Update or remove before writing new ones.
3. Review the conversation for four memory types: user, feedback, project, reference.
4. Apply filters: do NOT save code patterns, file paths, ephemeral numbers.
5. Honour the scope hint if the user passed one.
6. Write the files with frontmatter (name, description, type) plus body.
7. Update MEMORY.md as an index (one line per memory, under 150 chars).
8. Report back: created, updated, skipped.

Três decisões valem comentar.

A primeira é o description em inglês cobrindo aliases naturais em PT-BR: “salvar na memória”, “remember”, “save the session”. Quando o modelo é treinado nativamente em inglês mas a conversa pode estar em português, o description que abraça os dois ajuda na detecção do trigger.

A segunda é o argument-hint. Você pode passar /save-session só sobre Redis e o skill respeita esse escopo, filtrando o que extrai. Sem isso, fica tudo-ou-nada.

A terceira é a disciplina de filtros explícitos no procedure. O auto-memory também filtra, mas o /save-session adiciona pressão: “do NOT save code patterns, file paths, ephemeral numbers”. O bar de relevância sobe, porque o usuário pediu, então o que entra precisa valer a pena ser carregado em todas as conversas futuras desse projeto.

Como ele funciona em uma sessão real

Quando você digita /save-session no fim de uma conversa, o Claude faz quatro coisas em ordem:

Primeiro, descobre o diretório de memória do projeto atual (~/.claude/projects/<encoded-cwd>/memory/) e lê o MEMORY.md mais os arquivos de memória existentes. Isso é regra mandatória, porque a primeira coisa que o skill precisa garantir é que ele não vai duplicar nem reescrever memória já registrada.

Segundo, revisa a conversa em busca de candidatos divididos em quatro tipos: user (perfil, expertise, perspectiva), feedback (correções e validações com o Why e o How to apply), project (estado de trabalho com Why e How to apply), e reference (apontadores pra sistemas externos, URLs, hostnames).

Terceiro, aplica os filtros. Coisas que estão no código não viram memória, porque o código é a fonte da verdade. Datas relativas viram absolutas. Números financeiros voláteis (vão mudar em semanas) ficam de fora.

Quarto, escreve os arquivos novos, atualiza os existentes que precisam, e atualiza o índice MEMORY.md. No fim, reporta o que criou, o que mexeu, o que deixou de fora.

O efeito prático é que a próxima conversa que eu abrir nesse projeto vai carregar como contexto inicial todas as preferências, decisões e referências que valeram a pena. Sem precisar re-explicar. Sem precisar copiar e colar texto antigo. O modelo me trata como alguém que ele já conhece.

Compartilhando o skill entre máquinas

Eu rodo Claude Code em duas máquinas ativas, desktop e notebook, conforme já contei no post sobre 30 dias dentro do Claude Code. Se eu criasse o skill só em uma delas, perderia metade do benefício.

A solução foi simples: o SKILL.md vive no meu repositório de dotfiles versionado, em ~/projects/personal/dotfiles/.claude/skills/save-session/SKILL.md. Aí, em cada máquina, eu rodo um stow ou um script de symlink que conecta ~/.claude/skills/save-session ao arquivo dentro de dotfiles.

Na prática, vira algo assim:

# uma vez por máquina, no setup
mkdir -p ~/.claude/skills
ln -s ~/projects/personal/dotfiles/.claude/skills/save-session ~/.claude/skills/save-session

Resultado: editar o skill em uma máquina, comitar no repo de dotfiles, dar pull na outra, e o /save-session está disponível com a mesma definição em todos os lugares. Mesma lógica vale pra outros skills que eu desenvolvi (scripts de stats, hooks de diagnóstico, custom commands de fluxo). Todos centralizados, todos versionados, todos sincronizados.

Esse é o passo que muita gente esquece: skill é código, e código você versiona. Se você está construindo um slash command que vai mexer com memória, com arquivos, com qualquer estado real, vale tratá-lo com a mesma seriedade que você trata qualquer parte da sua ferramentaria.

Cinco aprendizados do uso

• Bar de “vale salvar” deve ser explícito no skill, não implícito. Auto-memory deixa o bar implícito no julgamento do modelo. Slash command explícito permite codificar regras de inclusão/exclusão. Use isso.
• Memória boa é estruturada por tipo, não por ordem cronológica. Separe user, feedback, project, reference. Quando você for buscar algo em três meses, vai querer encontrar por categoria, não por “quando aconteceu”.
• Índice (MEMORY.md) precisa ser índice. Uma linha por memória, descrição curta. Não escreve conteúdo no índice. Conteúdo vai pros arquivos individuais. Senão você acaba com um único arquivo gigante que o modelo ignora por sobrecarga de contexto.
• Salve o “Why”, não só o “What”. Uma feedback memory que diz “evitar emoji em posts” é fraca. Uma que diz “evitar emoji em posts porque o público é C-level sênior e emoji destrói credibilidade na primeira leitura” é forte. O Why permite julgamento em casos novos.
• Versione o skill em dotfiles desde o dia um. Antes mesmo de ele ficar bom. Você vai iterar, e cada iteração precisa estar visível em todas as máquinas. Skill que mora em uma máquina só é skill que vai morrer no próximo backup que você esquecer de fazer.

Fechamento

O /save-session virou ritual de fechamento de cada sessão de trabalho importante. Antes de fechar o Claude Code, eu digito ele. Levam uns 20 a 40 segundos, e o que entra em memória ali volta na próxima sessão como contexto pronto, sem que eu precise pensar.

Construir slash commands custom no Claude Code é a fronteira que separa “uso a ferramenta” de “operacionalizo a ferramenta”. Auto-memory te dá o caminho fácil. Skills custom te dão a alavanca: você codifica seu próprio processo dentro do agente, e ele passa a executar do seu jeito, com seus filtros, com seus padrões.

Se você usa Claude Code com regularidade e ainda não tem nenhum skill custom rodando, esse é o ponto natural pra começar. Não precisa ser save-session. Pode ser qualquer ritual repetitivo que você executa hoje à mão. Codifica ele em um SKILL.md, joga no dotfiles, symlinka pra ~/.claude/skills/, e a partir da próxima sessão é só digitar /.

6 anos como CTO de uma infraestrutura Drive-to-Store

Introdução

A Harmo fez seis anos no mês de junho. Esse tipo de data costuma virar texto de marketing, mas eu queria escrever de outro lugar: o de quem assina o código e responde pelo time que o mantém. Então esquece o tom de release. Quero falar do que de fato custou caro construir, das decisões de arquitetura que sustentaram os outros cinco anos, e das lições de gestão que eu só aprendi errando.

A pergunta que a gente fazia no começo era simples e a resposta era difícil: por que a voz do cliente, que é o dado mais valioso que uma rede de varejo tem, vivia espalhada em ferramentas que não conversavam entre si? Avaliação num lugar, presença digital em outro, pesquisa em outro. Cada pedaço resolvido por uma solução isolada, nenhuma resolvendo o problema inteiro. A Harmo nasceu dessa inconformidade. Seis anos depois, ela não é uma ferramenta de GBP, não é uma plataforma de reputação e não é uma agência. É infraestrutura Drive-to-Store: um único sistema, integrado e governado, que transforma a voz do cliente em mais fluxo para a loja.

O problema técnico nunca foi o óbvio

De fora parece que o desafio é integrar APIs e mostrar avaliação num dash bonito. Não é. O desafio real é manter um ciclo contínuo rodando em escala, com dados que chegam o tempo todo, de fontes que mudam as regras sem avisar, sobre uma base que hoje passa de 60 mil lojas. Processar mais de 300 mil avaliações e mais de 10 milhões de pesquisas por mês não é número de dashboard, é problema de arquitetura de verdade, com tudo que isso implica: idempotência, deduplicação, reprocessamento, e a disciplina chata de tratar fonte externa como algo que vai falhar, mudar de contrato e te surpreender no pior dia.

A decisão que sustentou todo o resto foi tratar pilares Drive-to-Store como um sistema único, não como quatro produtos costurados depois. Isso significou pagar adiantado em complexidade de modelagem de dados para que cada avaliação, cada pesquisa e cada ponto de presença digital alimentassem o mesmo ciclo, com o mesmo identificador de loja, o mesmo conceito de evento, a mesma fonte de verdade. Foi mais difícil no começo e é exatamente o que hoje nos deixa entregar coisas que um amontoado de ferramentas isoladas nunca vai entregar. Inteligência de verdade não se pluga em dados desconectados.

Boa parte do que sustenta isso na prática é matemática: estatística, correlação e os modelos que ligam a nota da loja ao fluxo na porta. Já mostrei o lado de dados e Python disso em como começamos com Python para IA e dados na Harmo, e em breve vou dedicar um post inteiro às oito famílias de fórmulas que rodam por trás da plataforma. Do lado da entrega, já escrevi sobre como fazemos CI/CD na Harmo. Este post aqui é mais sobre as escolhas que vieram antes do código.

Time é arquitetura

A lição de gestão que eu mais carrego é que time e arquitetura são a mesma coisa. O sistema que você consegue construir é o sistema que o seu time consegue sustentar. A Lei de Conway não é uma curiosidade acadêmica, é uma profecia que se cumpre todo trimestre. Por seis anos a prioridade não foi contratar rápido, foi contratar gente que entendesse que estávamos construindo infraestrutura, não feature. São coisas diferentes. Feature você entrega e comemora. Infraestrutura você entrega e passa a sustentar para sempre, e a régua de qualidade é outra porque o custo de errar se acumula em vez de passar.

A parte mais difícil como CTO foi aprender a dizer não para o caminho fácil. Toda vez que aparecia o atalho de resolver um caso pontual com uma gambiarra que não cabia no ciclo, a resposta certa quase sempre era a mais cara no curto prazo. Manter a coerência do sistema acima da velocidade de uma entrega isolada é uma disciplina que custa caro e some das métricas de curto prazo, e é exatamente ela que separa uma plataforma de uma colcha de retalhos. Eu errei isso algumas vezes nos primeiros anos. Cada vez que cedi ao atalho, paguei depois, com juros, em reescrita.

A outra lição é sobre dívida técnica como decisão de negócio, não como pecado. Nem toda dívida é ruim. A dívida que você contrai consciente, anota e cobra de volta no prazo é alavanca. A que você contrai sem perceber, espalhada em mil decisões pequenas que ninguém documentou, é a que te quebra. O trabalho do líder técnico é separar uma da outra e ter a coragem de defender a primeira na frente do board.

O diferencial não é uma funcionalidade, é o sistema

Quando comparam a Harmo com o mercado, eu gosto de mostrar um número que diz muito: nas oito funcionalidades centrais de GBP, a Harmo cobre as oito. É o tipo de cobertura que só faz sentido quando você construiu infraestrutura, não quando empilhou recursos um sobre o outro. Cada funcionalidade isolada é fácil de copiar. O que é difícil de copiar é a integração que faz as oito conversarem entre si sobre a mesma base de dados.

E o salto dos últimos anos foi a FloraAI, nossa camada de inteligência transversal, já lançada e disponível em todos os planos. Ela não é um módulo à parte que vendemos como add-on, é inteligência rodando por cima de todo o ciclo. Isso só foi possível porque os dados já estavam integrados desde o primeiro dia. A FloraAI é, no fundo, a colheita de uma decisão de arquitetura que tomamos anos antes de existir hype de IA. A gente não construiu a fundação porque sabia que a IA viria assim. A gente construiu a fundação porque dado integrado sempre vale mais que dado disperso, e isso é verdade independente de moda.

Reputação é performance, e isso é mensurável

O que mantém tudo isso de pé não é estética, é resultado. Reputação não é imagem, é performance. A correlação que orienta nosso trabalho mostra isso de forma quase brutal: cada 0,1 estrela a mais se traduz em 8,8% a mais em pedidos de rota. Na prática, ao longo de doze meses, isso aparece como um aumento de 36% nos pedidos de rota para a loja. Quando você consegue ligar uma variável que o time de operação enxerga como subjetiva, a nota, a um número que o CFO enxerga como concreto, gente entrando na loja, a conversa muda de departamento.

É por isso que insisto que a voz do cliente é dado estratégico, não SAC. Todo o trabalho técnico, do pipeline de ingestão à modelagem, do CI/CD à FloraAI, existe para uma coisa só: transformar esse dado em fluxo na porta da loja, de forma mensurável e auditável. Se eu não consigo provar o impacto com número, é estética, e estética não é o que a gente vende.

O que vem agora

Seis anos depois, com mais de 200 clientes confiando na plataforma, eu olho menos para o que construímos e mais para o que essa fundação permite construir agora. Infraestrutura boa é assim: o valor dela não está no que ela já faz, está no que ela torna possível fazer a seguir. A FloraAI é o primeiro grande exemplo disso, e tenho convicção de que não vai ser o último.

Obrigado a todo mundo que escreveu uma linha desse sistema, abriu um chamado às três da manhã, ou brigou comigo numa revisão de arquitetura porque tinha um jeito melhor de fazer. Infraestrutura é coisa de time, e esse time é a melhor coisa que construímos em seis anos. Vamos para o sétimo.

Custo AWS mensal: pico de março com fator próximo de 6x sobre a baseline histórica.

Introdução

Na manhã de uma segunda-feira de março, abri o dashboard de billing como de hábito e a conta AWS do mês estava quase 6x acima da baseline histórica. Nenhum alarme técnico tinha disparado. Zero impacto pra usuário final, zero perda de dado, zero degradação em serviços vizinhos. Mas o billing sangrou por 76 horas seguidas.

A Harmo é uma Plataforma Drive-to-Store que processa +10 milhões de pesquisas e +300 mil avaliações públicas por mês. Cada um desses números toca uma família de fluxos serverless. Quando um único fluxo entra em loop improdutivo, ele paga o preço pelo restante.

Case público é prática consolidada na engenharia séria de software, e blameless é o nosso padrão interno. Resolvi escrever sobre esse case, porque a topologia da falha é generalizável: quem opera Step Functions, máquinas de estado ou qualquer fluxo com loop pode tropeçar na mesma armadilha. Foi o único evento desse perfil no histórico do ambiente, e a categoria de falha não tem mais como acontecer depois das contramedidas que descrevo abaixo.

A topologia do fluxo

O fluxo afetado é uma Step Function de coleta paginada de dados via API externa, agendada para rodar de madrugada. O desenho é trivial em pseudocódigo:

[Start] → [Invoke Lambda] → [Choice: isFinished?]
                              ├── true  → [Persist] → [End]
                              └── false → [Invoke Lambda]   (loop)

Um Choice state que retorna pra invocação da lambda enquanto $.collector.isFinished == false. Em operação normal, a lambda esgota a paginação da API de origem em 3 a 8 invocações por execução. Limpinho, funcionou estável por anos.

A regressão

Numa quinta-feira, 19h05, mergeei um PR que mudou a lógica de paginação dessa lambda. Passou no review, passou nos testes existentes, passou na esteira. Não violava o contrato de I/O da função, todos os campos do payload continuavam com o shape esperado, tipos corretos, schema válido.

Sob uma condição específica de entrada (combinação rara de filtros com janela temporal), a lambda passou a retornar o seguinte payload a cada invocação, idêntico, sem variar entre chamadas consecutivas da mesma execução:

Todos os sinais disponíveis indicavam ausência total de progresso: cursor não avança, nada acumulado, nada trazido, primeira página perpétua, e a chave de saída em false. Mas o payload era HTTP 200, bem-formado, schema-válido. Do ponto de vista do Choice state da Step Function, era instrução pra continuar. Ele continuou.

As quatro madrugadas

Cada execução afetada consumia o teto de 25.000 eventos do histórico da Step Function antes de falhar com um erro States.Runtime cuja causa era literalmente The execution reached the maximum number of history events (25000).. Eram cerca de 8 horas e meia de loop, com a Step Function consumindo invocações Lambda (por 15min) e transições SFN em ritmo frenético até bater no limite hard da AWS. Esse teto de 25.000 eventos é quota hard de Standard Workflow, não dá pra aumentar via Service Quotas \o/.

O padrão recorreu em quatro madrugadas consecutivas, atravessando um final de semana inteiro. No total, 76 horas de recorrência intermitente em que cada ciclo entregava States.Runtime.

Por que nada disparou

Três camadas falharam ao mesmo tempo, e cada uma vale comentar.

Camada de código. Os testes unitários da lambda validavam o shape do payload retornado. O bug não violou nenhum shape, retornou valores logicamente inconsistentes com tipos válidos. Teste de shape passa, problema de invariância não pega. Não havia teste validando “se isFinished=false, então deve haver evidência de progresso entre invocações”.

Camada de arquitetura. O Choice state da Step Function fazia inspeção puramente sintática de uma única chave: isFinished. Não havia comparação entre estado antes e depois da invocação, nem teto de iterações. Do ponto de vista da Step Function, o sistema estava se comportando corretamente: recebeu instrução pra continuar, continuou.

Camada de observabilidade. Não havia alarme sobre duração de execução de Step Function, sobre número de transições por execução, nem sobre concorrência da lambda contra baseline rolling. A única linha de defesa era o sinal financeiro, que por design tem latência de consolidação de 24 a 48 horas. O Cost Anomaly Detection da AWS requer múltiplos pontos de observação pra estabelecer baseline antes de disparar. Um único evento anômalo pode não ultrapassar o threshold estatístico nos primeiros dias, foi o que aconteceu.

Toda invocação retornou 200. Nenhum erro, nenhuma exceção, nenhum stack trace. O sistema estava funcionando, no sentido mais raso da palavra.

A detecção e a contenção

Trinta de março, segunda-feira, ~9h. Anomalia de custo identificada na revisão matinal do dashboard de billing. Em 15 minutos de investigação, correlacionei invocações da lambda com transições da Step Function, vi a assinatura do loop, conferi os payloads. Trinta minutos depois do disparo, o fluxo estava contido. No mesmo dia, root cause analysis concluída, correção preparada, deploy com validação ativa.

A partir de 31 de março, monitoramento intensificado, zero recorrência. Abril fechou exatamente na baseline histórica do ambiente. A correção foi efetiva e não havia dívida oculta.

Todo o processo, contamos com a parceria de anos com a Infomach, o que foi primordial para um bom sucesso.

A frente comercial: Infomach, TD Synnex e AWS

O delta do incidente concentrou-se em três serviços. Lambda multiplicou cerca de 100x sobre a média histórica, Step Functions cerca de 50x, e CloudWatch entre 4 e 5x. Somados, o evento representou aproximadamente 80% da conta total do mês. Em quatro madrugadas.

Trabalhei com a Infomach, nossa parceira AWS, articulada via TD Synnex como distribuidor. O time da Infomach atuou em duas frentes em paralelo: validação técnica do diagnóstico e desenho dos guard rails que descrevo abaixo, e abertura do ticket comercial junto à AWS apresentando o postmortem completo, a janela do incidente, a causa raiz e o plano de correção já executado. A AWS reconheceu o caso e concedeu uma fração relevante do delta como crédito. Parceria excelente em ambas as pontas, durante anos (rodamos em AWS desde 2016).

A lição operacional é direta: canal AWS bem ativado vira ativo estratégico. O blameless postmortem, com root cause clara e ações corretivas P0 já concluídas, foi o que sustentou a negociação. Documento técnico bem feito é insumo de negociação, não burocracia.

Os guard rails que entraram

Depois da contenção, o trabalho real começou. As ações P0 atacaram as três camadas que falharam.

No código, virou obrigatório teste de invariância para qualquer fluxo de paginação: se isFinished=false, então uma das três precisa ser verdadeira (cursor avançou, totalFetched aumentou, ou pageCount cresceu). Não é teste de shape, é teste de coerência entre invocações.

Na arquitetura, o Choice state ganhou guard rail de iterações máximas (hard stop por teto configurável por fluxo) e guard rail de progresso, em que a invocação precisa retornar evidência explícita de avanço, senão o fluxo encerra com erro de negócio. As duas proteções são complementares: o teto contém o pior caso, a invariância contém o caso comum.

Na observabilidade, três alarmes CloudWatch entraram com prioridade alta: duração de execução SFN acima do p99 histórico por fluxo, número de transições por execução acima de teto por fluxo, e concorrência da lambda versus baseline rolling de 7 dias. Latência de minutos, não de dias.

E mais duas mudanças de processo: freeze de deploy às sextas-feiras e nos últimos cinco dias do mês para pipelines billing-sensitive, e checklist obrigatório de validação D+1 após merge em SFN ou lambda de alto volume (execuções, duração, transições, custo). Janela de deploy importa: merge na quinta à noite mais execução agendada de madrugada mais final de semana na frente totalizam ~72 horas de cegueira operacional antes da primeira oportunidade de observação crítica.

Também construímos um robô diário de cost tracking rodando em EKS (CronJob Python via IRSA para credenciais AWS e Secrets Manager para o token do ClickUp). Ele posta o breakdown de custo por serviço e por dia no ClickUp e abre task automaticamente se houver anomalia. Sobre esse robô escrevi em separado no post anterior dessa série, ele virou peça central da rotina de FinOps.

As lições que ficam

A lição central é simples e desconfortável: sucesso técnico pode mascarar falha de negócio. Toda invocação retornou 200, nenhum erro foi registrado, nenhum stack trace apareceu em lugar nenhum. Monitoramento baseado só em erros e exceções é insuficiente para fluxos que podem falhar por ausência de progresso. É preciso monitorar comportamento, não apenas sucesso sintático.

Pensa num atleta correndo numa esteira de academia: é movimento sem deslocamento. Atleta correndo na rua: movimento com deslocamento. Pela frequência cardíaca, pelo suor, pelo gasto calórico, os dois são indistinguíveis. Só o GPS responde se a pessoa saiu do lugar. Nosso fluxo tinha frequência cardíaca, tinha suor, tinha cada métrica sintática esperada no payload. O que faltava era GPS. cursor=0, totalFetched=0, pageCount=1 era exatamente isso: indicador inequívoco de que ninguém estava saindo do lugar, ignorado porque os outros sinais estavam todos verdes. Em sistema distribuído, sinal de batimento cardíaco e sinal de deslocamento são coisas diferentes, e instrumentação madura precisa dos dois.

A segunda é que latência de sinal importa tanto quanto existência de sinal. Existia sinal de custo (mesmo que não consolidado 100% pela AWS), ele chegou com três dias de atraso. Em incidentes de consumo exponencial, três dias é a diferença entre um susto e um evento material. Sinais técnicos têm latência de minutos e devem ser primeira linha de defesa. Sinais financeiros são backstop, não primeira linha.

A terceira é mais cultural. A Step Function afetada operou de forma estável por muito tempo (desde mar/2018). Estabilidade gera familiaridade, familiaridade reduz escrutínio. Fluxos com potencial de custo exponencial merecem atenção proporcional ao seu pior caso, não à sua média histórica. Por isso entrou ação de inventário e revisão arquitetural de todos os workflows legados com potencial de loop ou custo exponencial, aplicando os mesmos guard rails onde couber.

A quarta, talvez a mais imediata pra quem está lendo: invariantes explícitas valem mais que happy path. Teste de shape confirma que os campos existem e têm o tipo certo. Teste de invariância confirma que os valores são coerentes entre si. Pra fluxos com loop de negócio, a invariante crítica é progresso. Se o fluxo diz pra continuar, algo precisa ter mudado. Esse tipo de invariante precisa ser explícita no código, no teste e no próprio desenho do fluxo.

Se você opera Step Functions ou qualquer máquina de estados com loop, dois pedidos diretos: audite hoje quais fluxos têm potencial de loop sem progresso, e veja se o sinal de defesa primário é técnico ou financeiro. Se for financeiro, você está confiando num sinal que chega com dias de atraso pra conter um evento que escala em horas.

Esse case está em público com um propósito específico: que outros times não descubram essa categoria de falha do mesmo jeito que a gente descobriu. Se uma única equipe ler isso, auditar seus fluxos de paginação ou loop, e encontrar uma armadilha equivalente antes dela cobrar, o post pagou o trabalho de escrever.

Gratidão.

Introdução

Em março, um loop improdutivo numa Step Function rodou por 76 horas e multiplicou a conta AWS do mês da Harmo por quase 6x. Vou falar sobre isso em um artigo aqui na sexta, mas um detalhe da detecção importa pra esse post: o consumo anômalo atravessou um final de semana inteiro sem ninguém perceber, porque a única linha de defesa que pegou o problema foi a revisão manual do dashboard de billing. E revisão manual não acontece no sábado. O anomaly detectou chegou na segunda.

Esse post é sobre uma das contramedidas que nasceram dali: um CronJob no próprio EKS que roda toda manhã, inclusive sábado e domingo, puxa dados do Cost Explorer, compara com a média dos últimos 7 dias e posta o resultado num Doc no ClickUp. Quando detecta anomalia, abre task pra investigação. Roda há dois meses sem falhar e virou peça central da rotina de FinOps de uma operação que processa 10 milhões de pesquisas por mês. O setup todo levou uma tarde. Vou contar aqui a arquitetura, o código essencial e as decisões que pouparam dor.

Arquitetura

Quatro peças:

1. CronJob no EKS — roda às 8h da manhã, todos os dias.
2. Script Python — chama Cost Explorer API, calcula deltas, detecta anomalia.
3. IRSA — dá permissão pra o pod chamar Cost Explorer sem credencial hardcoded.
4. Secrets Manager — guarda o token da API do ClickUp, lido em runtime.

Output vai pra um Doc no ClickUp com histórico (append-only) e, quando detecta anomalia, cria uma task pra investigar.

Por que ClickUp e não Slack, e-mail ou dashboard próprio? Porque é onde o time já trabalha. Relatório que mora fora da ferramenta do dia a dia vira aba esquecida em duas semanas. Task no board que todo mundo olha de manhã tem dono, prazo e cobrança natural. O destino do alerta importa tanto quanto o alerta.

IRSA pra credenciais AWS

Não precisa mais que isso. A role precisa de permissão pra Cost Explorer e pra ler do Secrets Manager:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "ce:GetCostForecast"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:clickup/token-*"
    }
  ]
}

A Service Account no Kubernetes anotada com a ARN da role (cobri IRSA em detalhe no post sobre IRSA vs Pod Identity). Pod puxa credenciais via SDK sem código específico.

O script Python

Simplificado mas próximo do real:

import boto3
import os
import json
import requests
from datetime import date, timedelta

ce = boto3.client("ce", region_name="us-east-1")
secrets = boto3.client("secretsmanager", region_name="us-east-1")

def get_clickup_token():
    resp = secrets.get_secret_value(SecretId="clickup/token")
    return json.loads(resp["SecretString"])["token"]

def get_cost_for_day(day):
    start = day.strftime("%Y-%m-%d")
    end = (day + timedelta(days=1)).strftime("%Y-%m-%d")
    resp = ce.get_cost_and_usage(
        TimePeriod={"Start": start, "End": end},
        Granularity="DAILY",
        Metrics=["UnblendedCost"],
        GroupBy=[{"Type": "DIMENSION", "Key": "SERVICE"}],
    )
    services = {}
    for group in resp["ResultsByTime"][0]["Groups"]:
        service = group["Keys"][0]
        amount = float(group["Metrics"]["UnblendedCost"]["Amount"])
        if amount > 0.01:
            services[service] = amount
    return services

def detect_anomaly(today, baseline):
    anomalies = []
    for service, cost in today.items():
        baseline_cost = baseline.get(service, 0)
        if baseline_cost > 0 and cost > baseline_cost * 1.5 and cost - baseline_cost > 5:
            anomalies.append({
                "service": service,
                "today": cost,
                "baseline": baseline_cost,
                "delta_pct": (cost - baseline_cost) / baseline_cost * 100,
            })
    return anomalies

def format_report(day, total, services, anomalies):
    lines = [f"## {day.strftime('%d/%m/%Y')} — total USD {total:.2f}", ""]
    for service, cost in sorted(services.items(), key=lambda s: -s[1]):
        lines.append(f"- {service}: USD {cost:.2f}")
    if anomalies:
        lines.append("")
        lines.append(f"**{len(anomalies)} anomalia(s) detectada(s), tasks criadas.**")
    return {"date": day.strftime("%Y-%m-%d"), "markdown": "\n".join(lines)}

def main():
    yesterday = date.today() - timedelta(days=1)

    today_costs = get_cost_for_day(yesterday)

    baseline = {}
    for i in range(2, 9):
        day = date.today() - timedelta(days=i)
        day_costs = get_cost_for_day(day)
        for service, cost in day_costs.items():
            baseline[service] = baseline.get(service, 0) + cost
    baseline = {k: v / 7 for k, v in baseline.items()}

    anomalies = detect_anomaly(today_costs, baseline)

    total = sum(today_costs.values())
    report = format_report(yesterday, total, today_costs, anomalies)

    post_to_clickup(report, anomalies, get_clickup_token())

if __name__ == "__main__":
    main()

Regra de anomalia é intencionalmente simples: serviço que gastou 50% acima da média dos 7 dias anteriores e a diferença absoluta é maior que USD 5. Os dois guard-rails evitam alertar sobre variação percentual em serviços que custam centavos.

A publicação no ClickUp

A API do ClickUp tem endpoints pra Docs e pra Tasks. Pro relatório diário, append num Doc fixo. Pra anomalias, cria task num list específico. Pedaço relevante:

def post_to_clickup(report, anomalies, token):
    headers = {"Authorization": token, "Content-Type": "application/json"}

    doc_id = os.environ["CLICKUP_DOC_ID"]
    list_id = os.environ["CLICKUP_LIST_ID"]

    requests.post(
        f"https://api.clickup.com/api/v3/docs/{doc_id}/pages",
        headers=headers,
        json={"name": report["date"], "content": report["markdown"]},
    )

    for anomaly in anomalies:
        requests.post(
            f"https://api.clickup.com/api/v2/list/{list_id}/task",
            headers=headers,
            json={
                "name": f"Custo anormal: {anomaly['service']}",
                "description": (
                    f"Custo de ontem: ${anomaly['today']:.2f}\n"
                    f"Média 7 dias: ${anomaly['baseline']:.2f}\n"
                    f"Variação: +{anomaly['delta_pct']:.0f}%"
                ),
                "priority": 2,
            },
        )

Doc ID e List ID vêm de variáveis de ambiente, definidas no manifest do CronJob. Token via Secrets Manager.

O manifest do CronJob

apiVersion: batch/v1
kind: CronJob
metadata:
  name: aws-cost-report
  namespace: finops
spec:
  schedule: "0 11 * * *"
  concurrencyPolicy: Forbid
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 5
  jobTemplate:
    spec:
      backoffLimit: 2
      template:
        spec:
          serviceAccountName: aws-cost-report-sa
          restartPolicy: OnFailure
          containers:
            - name: reporter
              image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/aws-cost-report:latest
              env:
                - name: CLICKUP_DOC_ID
                  value: "abc123"
                - name: CLICKUP_LIST_ID
                  value: "xyz789"
              resources:
                requests: { cpu: 100m, memory: 128Mi }
                limits:   { cpu: 500m, memory: 256Mi }

schedule em UTC. 11h UTC = 8h em Brasília, chegando antes de qualquer standup da manhã. concurrencyPolicy: Forbid evita rodar dois jobs sobrepostos. backoffLimit: 2 tenta no máximo 3 vezes em caso de falha — pra um relatório diário, basta.

Detalhes que poupam dor depois

• Granularidade da Cost Explorer: ficar em DAILY é mais barato e mais preciso pro que a gente quer. HOURLY custa mais e tem delay maior.
• Cost Explorer tem delay de ~24h: dado de “ontem” às 8h da manhã ainda pode ser parcial em alguns serviços (Lambda, S3 Requests). Relatório é diretivo, não auditoria final. Esse delay é estrutural: sinal financeiro nunca vai ser detecção em tempo real, e é por isso que o papel desse robô é encurtar a demora de detecção de dias pra no máximo um, não zerá-la.
• Separe Doc (histórico) de Tasks (ação): humano que vê Doc só no dia ignora; task aparece no board, é trackable.
• Tem custo a API do Cost Explorer: USD 0.01 por chamada. 8 chamadas por dia (hoje + 7 dias) dá USD 2,40/mês. Piada de preço, mas vale saber.
• Alerta pra quando o próprio job falha: se o CronJob não roda por 2 dias seguidos, você para de receber anomalias e pensa que está tudo bem. Um alert em cima do failed jobs do Kubernetes resolve. Detalho isso no post de observabilidade mais adiante na série.

Lições aprendidas

A lição central não é técnica: custo anômalo na AWS é assintomático. Não derruba serviço, não dispara exceção, não acorda ninguém de madrugada. Pressão arterial alta funciona igual. Não dói, não dá sinal, e por isso a medicina não espera sintoma: mede em toda consulta, de rotina. Quem só mede quando sente alguma coisa descobre tarde. O relatório diário é essa medição de rotina, transformando um problema invisível em número comparável todo dia, inclusive nos dias em que ninguém abriria o dashboard por conta própria.

A segunda lição é que detecção simples supera sofisticação ausente. A regra de 50% sobre a média de 7 dias com piso de USD 5 foi escrita numa tarde e captura a maior parte do que importa. Dá pra evoluir pra média móvel exponencial, sazonalidade, ML. Mas o robô imperfeito rodando todo dia vence o sofisticado que ficou no backlog.

E a terceira: sinal financeiro é backstop, não primeira linha de defesa. Ele chega com 24 a 48 horas de atraso por design. O papel dele é garantir que nenhuma anomalia atravessa um final de semana invisível, como aconteceu com a gente. A janela de minutos é trabalho de alarme técnico em cima de métrica de comportamento, e esse é assunto do post de observabilidade dessa série.

Se você usa o Cost Anomaly Detection nativo da AWS, fica uma pergunta honesta: ele já pegou alguma anomalia sua em tempo útil? No nosso incidente ele estava habilitado e não disparou a tempo. O porquê disso fica pro postmortem, que sai aqui na sexta.

A pergunta que me travou três dias

Construí uma ferramenta e mostrei pra um amigo. Ele olhou cinco segundos e disparou: “era só dar /usage e boa, não?”. Esse comentário me travou três dias. Não porque ele estivesse errado. Porque ele estava parcialmente certo, e eu precisava saber em que parte exatamente ele não estava, antes de seguir.

Esse post é sobre essa investigação, e sobre o que ela me deixou no fim: meu primeiro projeto open source de verdade, o clawtop. Um dashboard TUI multi-host pra acompanhar uso da subscription Claude. Sim, já existem várias ferramentas pra isso. Não, ele não é redundante com elas. Vou contar o caminho.

Como começou

Esses dias esbarrei no Clawdmeter, um projetinho muito massa ESP32 que mostra o consumo da subscription Claude num display AMOLED de duas polegadas, com sprites pixel-art do Clawd ficando mais agitados conforme você queima cota. É charmoso, é desnecessário, é o tipo de coisa que eu queria ter feito. Só que eu não tenho ESP32 sobrando, não queria pedir mais um pacote pra Aliexpress, e o que eu tenho é o cypher, meu home-server, com mais ciclos ociosos do que eu uso.

Mas tem um detalhe que ainda me incomodava antes mesmo de codar: eu uso Claude em três máquinas diferentes. Workstation principal, laptop de trabalho, eventualmente o próprio servidor pra testar coisas em GPU. Quando eu rodava /usage numa, via só o que aquela máquina sabia sobre a sessão local. O total da minha conta tava esparramado em três lugares, e nenhuma das ferramentas que olhei resolvia isso sem eu copiar o credencial OAuth pra um lugar central.

A primeira versão do clawtop nasceu pra resolver só o problema do display: rodar como TUI em vez de hardware. Aí veio a pergunta do amigo, eu fui investigar o que já existe, e percebi que o problema interessante não era o display. Era o que ele estava mostrando e em quantas máquinas ele estava vendo.

O que já existe (sendo honesto)

Antes de seguir construindo, sentei e fiz a lista do que o ecossistema open source já tem em 2026.

O ccusage é o padrão de facto. CLI em Node, parseia os mesmos arquivos JSONL que ficam em ~/.claude/projects e cospe relatórios bonitos por projeto, modelo, sessão, dia. Roda on-demand. Se você quer um snapshot rápido no terminal numa máquina só, ele é melhor do que qualquer coisa que eu vá construir.

O Claude-Code-Usage-Monitor do Maciek é o mais perto do que eu queria fazer: TUI Python rodando sempre ligada, com previsão de burn rate baseada em ML. A diferença é que ele assume que tudo roda na mesma máquina onde estão os transcripts.

O ccflare faz dashboard web com gráficos interativos, browser-based. O claude-usage é outra variação local com gráficos e estimativa de custos. E o Clawdmeter, claro, faz o display físico.

Lendo tudo isso, ficou claro que duas coisas ninguém estava cobrindo, ou estavam cobrindo mal: agregação multi-máquina e o modelo de segurança onde o credencial fica numa máquina diferente da que renderiza o dashboard. Esses dois pontos juntos viraram a razão de existir do clawtop. Tudo o mais é commodity.

A arquitetura, e por que ela tem duas pontas

O OAuth do Claude Pro/Max vive em ~/.claude/.credentials.json na máquina onde você roda o CLI. Esse arquivo é o portão da conta: se vaza, o atacante usa tua subscription até o token expirar. Toda ferramenta que vi assume que o consumidor desse arquivo e o renderizador do dashboard rodam no mesmo lugar. Pra quem trabalha em laptop e olha o dashboard nesse mesmo laptop, isso não importa. Pra quem quer ver em uma máquina X, importa muito: o servidor tem tunnel Cloudflare aberto, mais superfície de ataque, mais pessoas com SSH eventual. Não dá vontade de copiar o credencial pra lá.

Então o clawtop divide o sistema em duas peças. O daemon, chamado clawtopd, roda em cada máquina onde o credencial existe. Ele faz duas coisas a cada minuto: chama a API da Anthropic com Haiku e max_tokens: 1 pra ler os headers de rate limit do response, e varre os transcripts locais em ~/.claude/projects/**/*.jsonl agregando token por projeto, por modelo, por hora e por dia. O resultado vira um JSON pequeno que ele empurra pro servidor de visualização via SSH, escrita atômica via mkdir -p && cat > tmp && mv. Sem porta exposta, sem endpoint custom, sem autenticação pra eu errar. O TUI, chamado clawtop, roda no servidor dentro de um tmux, lê todos os JSONs da pasta e renderiza o merge.

┌──────────────┐                          ┌──────────────────┐
│ laptop       │──clawtopd──┐             │ cypher (server)  │
│              │            │             │                  │
│ ~/.claude/   │            │             │  /var/lib/       │
│ .credentials │            │   ssh push  │   clawtop/       │
└──────────────┘            ├────atomic──▶│   laptop.json    │
                            │             │   omen.json      │
┌──────────────┐            │             │   workpc.json    │
│ omen         │──clawtopd──┤             │        │         │
└──────────────┘            │             │        ▼         │
                            │             │  clawtop (TUI)   │
┌──────────────┐            │             │  inside tmux     │
│ workpc       │──clawtopd──┘             └──────────────────┘
└──────────────┘
        │
        │ HTTPS (1 Haiku token / min, fração de centavo / dia)
        ▼
   api.anthropic.com

O credencial nunca sai da workstation. Se o cypher for invadido amanhã, o atacante leva JSONs com percentuais e contadores. Não leva o token. Muito menos vai conseguir acessar as demais máquinas na rede.

A parte multi-host, que é o truque inteiro

A sacada que tornou o projeto não-redundante foi perceber que o rate limit da Anthropic é por conta, não por máquina. Os três daemons rodando ao mesmo tempo veem todos o mesmo percentual de utilização nas janelas de cinco horas e sete dias. Mas o breakdown por projeto e por modelo vem dos transcripts locais e é por máquina. Cada um sabe só do que rodou ali.

A combinação é que dá o ganho. O servidor de visualização recebe três JSONs diferentes, um por máquina. Na hora de renderizar, o TUI faz merge: pega o rate limit mais fresco, soma os tokens por projeto e por modelo, soma os buckets horários e diários elemento a elemento, e o detalhe que mais me deixou orgulhoso: preserva atribuição por host nos projetos que aparecem em mais de uma máquina. Se eu rodo rifeli.dev tanto no omen (PC1) quanto no notebook, a linha aparece como rifeli.dev 874k no total, com uma sub-linha discreta embaixo dizendo omen 800k · notebook 74k. Em projetos single-host, a sub-linha mostra a contagem de sessões distintas no período.

Pra quem roda Claude numa máquina só, o merge de um elemento é identidade e tudo funciona igual. Pra quem roda em três, é a diferença entre ter três relatórios separados e ter uma resposta clara pra “onde foi minha cota essa semana, e em qual máquina”.

Clawtop rodando no meu home-server

O que o dashboard mostra hoje

Depois de várias iterações respondendo perguntas reais de uso, o TUI tem seis abas ou, quando o terminal é grande o suficiente, um modo dashboard denso que mostra tudo numa tela só. As perguntas que ele responde:

Limits: percentual usado das janelas de cinco horas e sete dias, com countdown pro reset. A partir do v0.8 ele também calcula a taxa de queima a partir do histórico das últimas dezenas de polls e projeta: +8.2%/h · 100% em 4h 12m · OVER! quando o ritmo atual indica que você vai bater o limite antes da janela resetar. Verde “ok”, amarelo “close”, vermelho “OVER!” quando dá merda.

Projects: os projetos que mais consumiram tokens no período, com barra relativa, total formatado, contagem de sessões e “última vez tocado” pra distinguir o que tá ativo do que é só lixo histórico dentro da janela. Quando duas ou mais máquinas contribuíram pro mesmo projeto, mostra a atribuição por host.

Models: split por modelo (Opus, Sonnet, Haiku) com input, output, cache read, cache create, taxa de cache hit em porcentagem mais o equivalente em tokens economizados, e a contagem de sessões em que cada modelo foi usado. A linha do cache hit foi a que mais me surpreendeu: meus 99% de cache hit equivalem a centenas de milhões de tokens que eu não precisei mandar de novo, e nenhuma ferramenta que eu vi torna isso visível.

Hosts: tabela com cada máquina mostrando tokens contribuídos, projetos distintos, sessions distintas, freshness do último push. Quem é o cavalo, quem é o pônei, quem morreu.

Sessions: top 10 conversas mais caras do período, com projeto, modelo, duração e quando foi a última atividade. Detecta runaway antes de virar problema.

Hourly e Daily: sparkline de 24 horas em granularidade horária, e sparkline de 7 dias em granularidade diária. Identifica padrão de uso ao longo do dia e ao longo da semana.

A tecla t alterna entre o modo tabbed e o modo dashboard denso. A tecla f cicla um filtro por host (all → omen → notebook → all), pra quando você quer focar só numa máquina. Cores das barras: vermelho/laranja/verde nas barras de limit (alto é ruim), cyan único nas barras de projeto e modelo (rank não tem semântica de bom/ruim).

As decisões que valeram a pena

A primeira foi Go nos dois lados. Pensei em Python pro daemon, é mais rápido de rabiscar. Decidi Go porque o resultado é um binário único cross-compilável que copia com scp e roda. Sem virtualenv no servidor, sem pip install, sem versão de Python pra controlar. Pra um projeto que eu quero deixar funcionando por anos, vale o boilerplate extra.

A segunda foi bubbletea pra TUI. A primeira versão eu fiz com fmt.Print e ANSI escapes na mão. Funcionou em dez minutos e era impossível de evoluir. Troquei pelo bubbletea com lipgloss e o código ficou mais curto, não maior. Cada nova tela que apareceu na evolução foi quase de graça depois que o framework estava de pé.

A terceira foi reler o credencial a cada poll. A primeira tentativa carregava o credencial no startup e implementava refresh do OAuth no próprio daemon. Implementação chata, fácil de errar, e me deixaria com duas cópias do refresh logic, a do Claude CLI e a minha. Joguei tudo fora. Hoje o daemon reabre ~/.claude/.credentials.json a cada chamada. Se o CLI refrescou, eu pego o novo. Se não, falho explicitamente e o systemd reinicia. Menos código, menos jeitos de quebrar.

A quarta foi sobre descobrir o nome real do projeto a partir dos transcripts. Os diretórios em ~/.claude/projects têm nomes tipo -home-rifeli-projects-personal-rifeli-dev, onde - codifica tanto / quanto .. Ou seja, dá pra ser tanto /home/rifeli/projects/personal/rifeli/dev quanto /home/rifeli/projects/personal/rifeli.dev. Tentei várias estratégias de heurística pra decodificar e todas erravam em alguns casos. Quase desisti. Aí olhei dentro do JSONL e vi que cada mensagem do tipo user tem um campo cwd com o path absoluto, exato. Joguei o decoder fora, passei a usar cwd como verdade. Lição: antes de inventar parser, leia o arquivo até o fim \o/.

A quinta foi preservar último valor bom em caso de falha do probe. Na primeira release multi-host, o daemon zerava os percentuais quando a Anthropic devolvia 429 ou caía momentaneamente. O dashboard piscava em zero, depois voltava no próximo poll. Bug ridículo. Hoje o daemon guarda o último probe bem-sucedido em memória; se o próximo falhar, ele reusa os valores anteriores no JSON que escreve. Resultado: dashboard não pisca, e quando você olha o log vê que houve falha mas a tela continua útil.

A sexta foi o modelo de release com GoReleaser + install.sh idempotente. Cada tag dispara cross-compile pra Linux/macOS × amd64/arm64, gera .deb e .rpm, sobe pra GitHub Releases. O install.sh baixa o binário certo, deixa as units do systemd no lugar e, a partir do v0.8, detecta quais services tão habilitados e reinicia eles sozinho. Atualizar virou um comando: sh install.sh. Esse foi puxado por um pedido direto de teste real, que é a próxima seção.

Testando como um usuário de verdade

Cortei a primeira release achando que tava pronto. Aí fui ser o primeiro usuário do meu próprio projeto, seguindo o README, e cada passo revelou alguma fricção:

O install.sh aceitava silenciosamente flag desconhecida — install.sh daemon --host=cypher comia o --host=cypher sem reclamar e o usuário pensava que tinha configurado. Corrigi pro script rejeitar argumento desconhecido com erro claro.

O alias SSH do meu cypher estava quebrado naquele dia (DNS bagunçado), e o clawtopd doctor mostrou exatamente isso: FAIL ssh cypher: Permission denied (publickey), com HINT: ssh-copy-id cypher. Eu não tinha feito ssh-copy-id depois do reinstall do servidor. Sem o doctor, eu ia perder uma hora investigando. Doctor é a coisa mais barata de implementar que mais valor entrega.

O terminal que eu uso quebrava URLs longas no paste, transformando curl ... | sh em dois comandos separados que falhavam de jeitos confusos. Documentei o workaround com git clone /tmp/c && sh /tmp/c/install.sh no INSTALL.md.

A unit do systemd do viewer tinha uma flag desatualizada (--path em vez de --dir) que eu esqueci de atualizar quando renomeei. O serviço entrava em loop de start/fail/restart silenciosamente. Foi tipo o terceiro patch release, e nada vence cargo cult: você precisa de um usuário real fazendo o caminho real pra esses bugs aparecerem.

Cada uma dessas fricções virou commit, virou release, virou nota de troubleshooting no INSTALL.md. O projeto que existe hoje tem uma forma diferente do que eu publiquei na primeira tag, e cada diferença foi puxada por um momento de “ah, isso aqui tá chato”.

O que ficou de fora, e por que

Não tem TLS entre o daemon e o servidor porque SSH já é o TLS dessa conexão. Não tem queue, não tem retry com backoff agressivo, não tem persistência local de leituras. Se uma chamada falha, eu logo, espero um minuto, tento de novo. O dado é descartável, a próxima leitura sobrescreve. Quanto menos estado, menos coisa quebra às três da manhã.

Não tem auth via API key normal porque API key normal não devolve os headers da subscription, devolve os da tier de API. Pra ler anthropic-ratelimit-unified-5h-utilization da minha conta Team, OAuth é obrigatório.

Não tem dashboard web. Pensei em hospedar uma página HTML no cypher, mas era exatamente a coisa que não dava pra fazer sem expor algo novo no tunnel Cloudflare. A TUI dentro do tmux resolve sem novos vetores de ataque.

Não tem ML burn-rate prediction. O monitor do Maciek já faz isso muito bem com ML. Meu burn rate é regressão linear simples sobre os últimos polls — funciona o suficiente pra avisar “vai bater limite antes de resetar” sem complicar o código. Se você quer projeção sofisticada, use a ferramenta dele junto.

Não tem suporte a Windows. Linux e macOS por enquanto. Adicionar Windows não é difícil tecnicamente (é só compilar) mas demanda testar o caminho do credencial e do tmux equivalente, e eu não uso Windows. Issue aberta pra quem quiser contribuir.

O JSON que voa

{
  "schema": 3,
  "machine": "omen",
  "ts": 1716688320,
  "session": { "pct": 31.0, "reset_at": 1716700000 },
  "week":    { "pct":  5.0, "reset_at": 1717100000 },
  "limit":   "allowed",
  "subscription": "team",
  "window":  "7d",
  "sessions": 20,
  "by_project": [
    { "name": "rifeli", "path": "/home/rifeli/projects/personal/rifeli",
      "in": 12345, "out": 1900000, "cache_read": 45000000, "cache_create": 1400000,
      "sessions": 5, "last_at": 1716685200 }
  ],
  "by_model": [
    { "model": "claude-opus-4-7",
      "in": 200800, "out": 4300000, "cache_read": 462500000, "cache_create": 14600000,
      "sessions": 32 }
  ],
  "hourly_24h": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 107835, 7436, 0, 0, 0, 0, 0, 0, 178055],
  "daily_7d":   [120000, 250000, 80000, 400000, 600000, 1100000, 1300000],
  "top_sessions": [
    { "id": "abc-...", "project": "rifeli", "model": "claude-opus-4-7",
      "in": 186931, "out": 966588, "started_at": 1716680000, "last_at": 1716688000 }
  ]
}

Um a cinco kilobytes por máquina, schema versionado, sem nada sensível. Viewers antigos ignoram campos desconhecidos, viewers novos default-zero os que não vieram. Forward-compat barato.

Por que publicar mesmo já tendo alternativa

Esse é meu primeiro projeto open source de verdade, e a pergunta “isso já existe” me travou três dias antes de eu entender que ela está mal formulada. A pergunta certa é: “isso resolve um problema específico que as alternativas não resolvem para um conjunto de pessoas”. Se a resposta for sim, mesmo que o conjunto seja pequeno, vale publicar. Se a resposta for não, faça issue no projeto existente pedindo a feature.

No meu caso: tem gente que roda Claude em mais de uma máquina, e tem gente que se incomoda em copiar credencial pra servidor. Esses dois conjuntos somados não são o mundo, mas existem. E a forma de descobrir se existem mesmo é publicar e ver se chega issue ou PR. Eu vou descobrir junto com vocês.

Como rodar

Quando estiver na máquina que tem Claude rodando:

curl -fsSL https://raw.githubusercontent.com/leonardorifeli/clawtop/main/install.sh | sh
clawtopd doctor # confere creds, anthropic, destino
systemctl --user enable --now clawtopd-local
clawtop --dir=~/.local/share/clawtop

Se o terminal quebrar a URL no paste (alguns terminais fazem), troca por git clone https://github.com/leonardorifeli/clawtop /tmp/c && sh /tmp/c/install.sh.

Pra setup multi-host com viewer separado, o passo a passo completo está em deploy/INSTALL.md. Cerca de mil linhas de Go no total, MIT, PR aberto a quem quiser melhorar.

Créditos

Sem o Hermann Bjorgvin e o Clawdmeter eu não saberia que a Anthropic expõe esses headers via OAuth. Sem o ryoppippi e o ccusage eu provavelmente teria parado na pergunta do amigo. Construir em cima de prior art é fazer parte da conversa, não substituir.

O que importa não é USD 8.069 em tokens. É comprimir quatro meses de roadmap em um.

Introdução

Em 30 dias dentro do Claude Code, entreguei o equivalente a quatro meses de roadmap.

Não é métrica de IDE. É auto-observação calibrada por anos no mesmo conjunto de projetos. O que normalmente levaria 8 meses, coube em 2.

A maior parte desse roadmap aconteceu dentro da Harmo, infraestrutura Drive-to-Store que opera +60 mil lojas, processa +10 milhões de pesquisas e +300 mil avaliações por mês. Esse é o terreno em que esses 30 dias foram medidos.

Pra calibrar o tamanho do uso: rodei o equivalente a USD 8.069 em tokens nesses 30 dias, pagando um plano fixo de assinatura. Esse número não é a tese. É dimensão, ajuda a entender quanto a ferramenta esteve no fluxo. O que conta é o que saiu do outro lado.

Como cheguei nesses números

O Claude Code persiste cada sessão em ~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl. Cada linha é um evento estruturado: mensagem do humano, resposta do assistant, tool call, tool result. No caso do assistant, vem com contagem de tokens por categoria (input, output, cache write, cache read) e identificação do modelo usado.

Escrevi um script Python pequeno que soma sessões, turnos humanos, respostas, tokens por categoria e estima custo equivalente em USD usando a tabela pública da Anthropic. Roda local, sem mandar nada pra fora, com sanitização automática de credenciais antes de gravar relatório. Detalhes no apêndice.

Rodei nas duas máquinas que uso ativamente (desktop e notebook) e somei. Isso só funciona porque mantenho Claude Code sincronizado entre elas (com a pegadinha das memórias path-encoded resolvida), setup que detalhei em Sincronizando Claude Code entre máquinas.

O que saiu desses 30 dias

Em ordem de impacto, e citando só o que pode ir publicamente:

• Diagnóstico e ações ao vivo de uma crise de performance no Aurora PostgreSQL da Harmo (CPU 90% sustentada, 18 índices mortos, write amplification gratuita), com runbook documentado para o próximo incidente.
• Refator de consumer single-row para batch insert com ON CONFLICT num pipeline crítico da Harmo, levando o gargalo de 47 segundos para 1,4 segundo em 10 mil eventos. Eliminou uma classe inteira de incidentes futuros.
• Avanços no produto principal da Harmo equivalentes a meses do roadmap normal. Não dá para detalhar publicamente, mas é a maior parte do ×4 que abriu esse post. Inclui evolução da FloraAI (plataforma de chat conversacional com LLM, MCP, tools, etc), a camada de inteligência transversal que atravessa todos os planos da plataforma.
• Várias contribuições com comunidade tech.
• Mais de 10 reports internos + Gestão estratégica do nosso cluster EKS.
• Reforma da infraestrutura de SEO, analytics e privacidade do próprio blog rifeli.dev: canonical e Open Graph dinâmicos, JSON-LD Article, banner LGPD, política de privacidade. Coisa que estava em backlog há meses, fechada numa sessão.
• Um slash command custom no Claude Code (/save-session) e o script de análise (claude-code-stats.py) que gerou os próprios números desse post (vai pra outro artigo falando sobre ele).
• O clawtop, meu primeiro open source de verdade: dashboard TUI multi-host pra acompanhar uso da subscription Claude, com daemon em cada máquina e renderização centralizada num servidor de casa. Vai virar post próprio mais adiante na série \o/.

Nem tudo isso “veio do Claude Code”. Mas todos vieram mais rápido porque ele estava aberto no segundo monitor o tempo todo. No final, cada commit precisa carregar uma assinatura né.

Sobre nosso EKS

A espinha dorsal da Plataforma Harmo é um cluster Kubernetes gerenciado na AWS (EKS). São cerca de 90 microsserviços rodando em torno de 250 pods, a maior parte sobre instâncias ARM/Graviton, escolha que nos dá melhor relação custo por desempenho. Em vez de manter um parque fixo de servidores, usamos Karpenter para provisionar e consolidar nós automaticamente, de modo que a capacidade acompanha a carga minuto a minuto. Isso sustenta o volume de processamento da operação, na casa de entenas de milhares de avaliações e milhões de pesquisas por mês, mantendo a conta de infraestrutura sob controle.

Contribuições no período:

• 1407 commits.
• 189 PRs envolvidos no período.
• 50 code reviews em 40 dias, espalhados em 16 repos. 64 PRs onde participei comentando.
• 46+ repos diferentes tocados.

Anatomia do uso

68 sessões em 30 dias. 1.024 turnos humanos. 12.824 respostas do assistant. Em média, 12 respostas para cada coisa que eu digito. Bash domina como ferramenta usada (3.956 chamadas combinadas), seguido de Read (1.072) e Edit (969). Cache hit ratio de 96,6%.

Mediana de turnos humanos por sessão é baixa: 4 a 6. 52% das sessões são one-shot (≤ 4 turnos), 20% são ping-pong (> 10 turnos). A maioria das interações é cirúrgica, não conversa. Encomendo coisas. Quando preciso conversar, é em sessões de debug profundo, e essas pagam a fatura sozinhas.

A sessão mais cara do mês teve 152 turnos, 59 horas de relógio e custo equivalente de USD 1.741. Foi diagnóstico de incidente que destravou uma feature da Harmo em rota direta com o cliente. Em momentos assim, dimensão de uso vira diferencial de produto.

Por que isso comprime tempo

O número que mais explica o ×4 não é leverage de preço. É a razão 1.024 turnos meus contra 12.824 respostas do assistant. Cada coisa que digito vira, em média, 12 etapas executadas para mim: leitura de arquivo, escrita, busca, decisão, execução de bash, novo prompt para si mesmo. Bash domina como ferramenta porque a maior parte do trabalho técnico real é orquestração de comandos, não geração de prosa.

Não é “ChatGPT na linha de comando”. É um orquestrador que recebe intenção e devolve cadeia de ações. Compressão de tempo vem dessa relação de leverage por turno, repetida ao longo de horas, repetida ao longo de semanas. No fim do mês, sobra uma diferença de patamar entre o que eu teria feito sozinho e o que entreguei.

Toquei em 13 projetos diferentes

Oito com sessões reais. Os três que dominaram: a plataforma core da Harmo (mais de 70 microservices, +10 milhões de pesquisas e +300 mil avaliações por mês, em mais de 60 mil lojas), um motor de NLP da camada FloraAI da Harmo (que transforma voz de cliente em decisão operacional), e um repositório pessoal (esse blog). Contextos absurdamente diferentes em stack, domínio, vocabulário e decisões de arquitetura.

Variedade de stack e domínio que normalmente quebraria a coerência de qualquer assistente; o Claude Code carrega isso sem que eu reapresente o projeto a cada nova sessão. Pico de horário fica entre 12h-15h e 18h-21h (de manhã, geralmente em reuniões e análises estratégicas), com cauda longa até depois das 23h. Quarta-feira é o dia mais ativo. Usei a ferramenta em cerca de 70% dos dias do mês.

O que mudou no meu fluxo

Três coisas, sem ordem de importância.

A primeira foi começar a usar a ferramenta sem culpa de “isso vale o token?”. Plano fixo, custo marginal por uso adicional é zero, mas o instinto de “paga por chamada” de eras anteriores levou uns dias para sair.

A segunda foi virar default ter Claude Code aberto no segundo monitor. Não como assistente eventual, mas como ambiente de trabalho. A fronteira de “isso eu faço, isso eu delego” se move sem decisão consciente. Você se pega delegando algo que no mês passado teria escrito à mão.

A terceira foi escrever ferramentaria em cima da ferramenta. Construí um slash command (/save-session) que destila o que vale carregar para a próxima conversa antes de fechar a sessão. Sem isso, contexto entre conversas virava arquivo morto. Esse vira tema de um post próprio mais adiante na série.

Fechamento

O número que importa não é USD 8.069 em tokens. Nem 80x de leverage sobre o que pagaria via API. É que comprimi cerca de quatro meses de roadmap em um.

A pergunta certa para quem avalia Claude Code não é “quanto custa por hora de uso”, nem “quanto economiza em tokens”. É “quanto avança o produto enquanto a equipe inteira vai dormir”.

Apêndice: o script

O script Python que usei está em .claude/scripts/claude-code-stats.py. Lê ~/.claude/projects/ localmente, soma os últimos 30 dias (configurável), sanitiza credenciais detectadas em prompts e exporta markdown + JSON. Roda em Linux e macOS sem dependência externa além de Python 3.9+. Útil para rodar antes de qualquer conversa sobre “como você usa Claude Code” com o time. Os números reais costumam surpreender quem responde de cabeça.

IRSA vs Pod Identity

Introdução

Na Harmo, +70 microservices (Golang, python e node.js) rodam em EKS atendendo +10 milhões de pesquisas e +300 mil avaliações públicas por mês. Cada um desses serviços precisa de credencial AWS pra acessar S3, Secrets Manager, SQS, DynamoDB, o que for. Por anos, IRSA foi a resposta: IAM Role atrelada a Service Account via OIDC, e fim. Em 2023 a AWS lançou Pod Identity, que faz a mesma coisa de forma mais simples. Hoje os dois coexistem, e a dúvida de qual usar aparece em cluster novo e em qualquer conversa de migração.

Esse post é o destilado do que aprendi configurando, quebrando e migrando entre os dois nos últimos meses, incluindo um bug silencioso que me custou umas duas horas num cluster antigo. A mensagem de erro da AWS não ajudou em absolutamente nada.

Como IRSA funciona

IRSA associa uma Service Account do Kubernetes a uma IAM Role usando o provedor OIDC do cluster EKS. Em uma frase: você registra o OIDC issuer do cluster como Identity Provider na conta AWS, cria uma IAM Role cuja trust policy aceita sts:AssumeRoleWithWebIdentity vindo desse issuer pra uma Service Account específica, e anota a SA no Kubernetes com eks.amazonaws.com/role-arn. O EKS injeta token projetado e variáveis de ambiente no pod, e o SDK AWS faz o AssumeRoleWithWebIdentity sozinho.

A trust policy da role é onde mora a complexidade:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::123456789012:oidc-provider/oidc.eks.us-east-1.amazonaws.com/id/EXAMPLE"
    },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "oidc.eks.us-east-1.amazonaws.com/id/EXAMPLE:sub": "system:serviceaccount:default:minha-sa",
        "oidc.eks.us-east-1.amazonaws.com/id/EXAMPLE:aud": "sts.amazonaws.com"
      }
    }
  }]
}

Qualquer vírgula fora do lugar no sub e você pega AccessDenied sem pista do porquê.

O que mudou com Pod Identity

Pod Identity tira o OIDC da equação. Você instala o EKS Pod Identity Agent como addon do cluster, cria uma Role com trust policy pro principal pods.eks.amazonaws.com (não mais federated OIDC), e registra um “Pod Identity Association” linkando role e Service Account. O agent, que roda como DaemonSet, intercepta as chamadas do SDK e injeta credenciais.

A trust policy simplifica muito:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Service": "pods.eks.amazonaws.com" },
    "Action": ["sts:AssumeRole", "sts:TagSession"]
  }]
}

Pra criar a associação via CLI:

aws eks create-pod-identity-association \
  --cluster-name meu-cluster \
  --namespace default \
  --service-account minha-sa \
  --role-arn arn:aws:iam::123456789012:role/minha-role

Nenhuma annotation na Service Account. A associação mora no plano de controle do EKS.

Diferenças práticas

O bug silencioso

Estava migrando um serviço de IRSA pra Pod Identity num cluster da Harmo criado há mais de um ano. Fiz tudo: nova role, associação via CLI, removi a annotation antiga. Rollout do pod. Resultado:

AccessDeniedException: User: anonymous is not authorized to perform: secretsmanager:GetSecretValue

“User: anonymous”, ou seja, o pod estava fazendo a chamada sem nenhuma credencial. Não era problema de permissão da role, era problema de não ter role nenhuma injetada.

Checklist que rodei na sequência:

• Associação existe? Sim (aws eks list-pod-identity-associations confirma).
• Trust policy ok? Sim.
• Service Account certa no deployment? Sim.
• Logs do pod mostram tentativa de chamada? Sim.

Travei. Foram uns 40 minutos só de debug ativo em frente ao terminal, e o incidente todo, contando rollback do serviço pra IRSA, voltar pra Pod Identity depois do fix e revalidar, comeu umas duas horas no total. O erro era óbvio quando encontrei: o EKS Pod Identity Agent não estava instalado no cluster. Era um cluster antigo, criado antes do Pod Identity existir, e o addon simplesmente não estava lá. Sem o agent rodando como DaemonSet em cada nó, a interceptação não acontece, o SDK não encontra credencial e cai pra modo anonymous.

Solução, uma linha:

aws eks create-addon \
  --cluster-name meu-cluster \
  --addon-name eks-pod-identity-agent

O que piora é que a mensagem de erro da AWS não indica isso. “anonymous” parece problema de trust, não de infraestrutura ausente. A lição: quando um cluster é antigo e você está adotando um recurso novo do EKS, verifique primeiro se o addon correspondente está instalado.

Pra checar rapidamente:

kubectl get daemonset -n kube-system eks-pod-identity-agent

Se não retornar nada, está faltando.

Quando usar qual

Recomendação pragmática:

• Cluster novo, sem legado: Pod Identity. Setup mais simples, trust policy mais limpa, menos coisas pra errar.
• Cluster existente, IRSA funcionando: não migre só por migrar. Migração dá trabalho e o valor pode pode ser limitado. Migre quando tiver um motivo real (reuso de role entre clusters, simplificar auditoria).
• Role compartilhada entre vários clusters: Pod Identity ganha por muito. Com IRSA, cada OIDC provider precisa aparecer na trust policy, vira lista enorme. Com Pod Identity, uma trust policy serve todos.
• Ambiente multi-cloud ou precisa de OIDC issuer externo: IRSA. Pod Identity é AWS-only.

Lições

IRSA é sólido mas verboso. Trust policy com OIDC funciona bem até você precisar debugar, e qualquer erro de string no sub vira AccessDenied sem pista. Pod Identity simplifica o caminho feliz com menos peças móveis e trust policy legível, mas em troca depende de infraestrutura no cluster: o agent precisa estar rodando como DaemonSet, e se você está migrando cluster antigo, o primeiro passo é checar o addon, não a trust policy.

A lição transversal é mais geral. Erro de AccessDenied no EKS pede checagem de camadas, não só de permissão. “User: anonymous” não é permissão insuficiente, é credencial ausente, e isso vira problema de infraestrutura até prova em contrário.

Pensa num prédio com catraca controlada por leitor de crachá. Você passa o crachá e a catraca não abre, mostrando “acesso negado”. O reflexo é pensar que seu crachá perdeu permissão, foi desativado, mudou de departamento, e você vai falar com o RH, com a segurança, gasta uma hora investigando o cadastro. Aí descobre que o leitor de crachá daquele andar nunca foi instalado. O equipamento que faria a leitura simplesmente não está lá, e qualquer crachá apresentado vai cair na mesma mensagem genérica. É exatamente o que acontece sem o Pod Identity Agent: o leitor não existe, ninguém intercepta a credencial, e a AWS responde como se o pod fosse anônimo. A pista estava num andar acima do que eu estava investigando.

Por último, coexistência é viável: serviços com IRSA e outros com Pod Identity convivem no mesmo cluster sem atrito. Não precisa migrar tudo de uma vez, e talvez nem precise migrar.

Pra quem já roda IRSA bem mapeado em produção, qual foi o motivo concreto que te fez (ou te fará) migrar pra Pod Identity? Reuso de role entre clusters, simplificar trust policy, ou alguma dor específica de debugging que ainda não vi? Quero ler esses casos aqui embaixo, esse tipo de história economiza horas pra quem vem depois.

Goroutines, channels, fan-out/fan-in, worker pool com errgroup e cancelamento via context

Introdução

Na Harmo, +50 dos nossos microservices em produção rodam em Go. Eles atendem +10 milhões de pesquisas, +1 milhão de eventos de performance de loja e +300 mil avaliações públicas por mês em mais de 60 mil lojas físicas, com picos que estouram facilmente um worker pool mal dimensionado. Quando você opera nesse volume, um único serviço com goroutine sem limite vira gargalo da plataforma inteira em minutos, não em horas.

Também usamos Go pesado em workloads orquestrados pelo nosso Airflow rodando em MWAA, com workers em Go disparados sob demanda pelas DAGs. É uma stack que merece post próprio e vai sair aqui em breve: a topologia inteira, as decisões de orquestração entre o scheduler em Python e os workers em Go, e os gotchas operacionais que aparecem quando se opera DAGs grandes apoiadas em Kubernetes. Por enquanto, fica registrado que o worker pool desse post é a base mental de muito do que roda lá.

go func() { ... }() é uma linha. Disparar mil goroutines em um loop é tentador. Depois a conta chega: exaustão de memória, rate limit de API estourado, race condition sutil que só aparece em produção sob carga real.

Esse post é o conjunto mínimo de patterns que eu uso e reviso em code review na Harmo. Não é tutorial de goroutine nem de channel. É o que vira reflexo depois de alguns anos escrevendo Go em produção: worker pool bem feito, fan-out/fan-in com controle de erro, cancelamento via context, e o que mudou com Go 1.25 que vale incorporar agora.

Começamos a usar Go na Harmo em 2017, ainda na versão 1.7. Famosa frase: quando chegamos, era tudo mato haha.

Goroutines: mais é menos

O instinto errado é “se goroutines são baratas, use muitas”. Cada goroutine é barata sim (alguns KB iniciais), mas:

• Recurso externo não é. Se você abre 10.000 goroutines fazendo HTTP pra um serviço, a outra ponta te bloqueia (ou vai cair \o/).
• Conexão com banco é cara. Pool de conexões do PostgreSQL raramente é maior que 20 ou 30. 10.000 goroutines esperam uma conexão. Sem concorrência real, só enfileiramento disfarçado.
• CPU é finita. Trabalho CPU-bound não se beneficia de ter mais goroutines que cores disponíveis.

A pergunta certa não é “como disparar muitas goroutines”, é “quantas fazem sentido pra esse trabalho, e como limitar a esse número”.

Worker pool: o padrão básico

O worker pool resolve o problema de limitar concorrência. Estrutura:

func processItems(items []Item) error {
    const workers = 10
    jobs := make(chan Item)
    var wg sync.WaitGroup

    // producers
    for i := 0; i < workers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for item := range jobs {
                process(item)
            }
        }()
    }

    // workers
    for _, item := range items {
        jobs <- item
    }
    close(jobs)

    wg.Wait()
    return nil
}

Três partes:

• Abre N workers que consomem de um channel.
• Produtor envia trabalho e fecha o channel quando termina.
• WaitGroup espera todos os workers terminarem.

Funciona, mas tem dois problemas: não propaga erro, e não cancela se algum worker falhar.

errgroup: o que worker pool moderno deveria ser

golang.org/x/sync/errgroup resolve os dois problemas:

import "golang.org/x/sync/errgroup"

func processItems(ctx context.Context, items []Item) error {
    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(10)

    for _, item := range items {
        g.Go(func() error {
            return process(ctx, item)
        })
    }

    return g.Wait()
}

O que isso te dá:

• SetLimit(10) limita goroutines concorrentes. Chegou no limite, g.Go(...) bloqueia até uma terminar.
• Primeiro erro cancela o contexto derivado. Outras goroutines que respeitam ctx param sozinhas.
• g.Wait() retorna o primeiro erro. Os demais são ignorados, o que costuma ser o que você quer. Erro é erro, não precisa coletar todos.

Se você ainda roda em Go anterior à 1.22, precisa de item := item dentro do loop pra escapar o shadowing clássico do for/range com closure. A partir do 1.22, cada iteração cria variável nova automaticamente e a linha extra deixou de ser necessária.

O que mudou em Go 1.25

Duas mudanças do Go 1.25 entram direto nessa conversa e valem incorporar.

A primeira é sync.WaitGroup.Go(func()). O WaitGroup ganhou um método novo que substitui o trio wg.Add(1) + go func + defer wg.Done() por uma única chamada:

var wg sync.WaitGroup

for i := 0; i < workers; i++ {
    wg.Go(func() {
        for item := range jobs {
            process(item)
        }
    })
}

wg.Wait()

Mesmo comportamento do exemplo da seção de worker pool, três linhas a menos por chamada, e uma classe inteira de bug eliminada (esquecer o Add antes da goroutine, ou colocar dentro dela, que é o caso clássico de race entre Add e Wait). Se você usa WaitGroup cru sem propagação de erro, wg.Go(...) é o novo default. Pra fan-out com erro, errgroup continua sendo o caminho.

Por baixo dos panos, o wg.Go(f) é equivalente a três linhas que você já escreveu mil vezes na vida \o/:

func (wg *WaitGroup) Go(f func()) {
    wg.Add(1)
    go func() {
        defer wg.Done()
        f()
    }()
}

Não tem mágica, é só o idiom canônico empacotado dentro do próprio WaitGroup. O detalhe que importa está na ordem: o Add(1) acontece síncronamente, na mesma goroutine que chamou Go, antes do go func() que faz o spawn. Isso é o que elimina o race condition clássico (eu pelo menos, já esqueci muito de implementar certo haha).

No antigo, quando alguém colocava wg.Add(1) dentro da goroutine (em vez de antes), abria janela pro produtor chamar wg.Wait() antes da goroutine começar a executar. Wait() retornava imediatamente porque o contador ainda estava em zero, e o trabalho rodava sem nenhuma barreira de sincronização esperando por ele. Bug invisível em laptop, problema sério sob carga, daqueles que só aparecem quando você precisa explicar pro time por que o teste de integração passa mas a feature falha em staging.

O defer wg.Done() dentro da goroutine garante o decremento mesmo se f panicar, mantendo o WaitGroup consistente, e o panic propaga normalmente pra cima. E como wg.Go aceita só func(), não há captura de erro nem de retorno: pra trabalho com falha possível, errgroup continua sendo o caminho. A escolha de design é coerente com o resto do pacote sync: oferece primitivo baixo-nível correto, deixa abstrações de alto-nível (erro, contexto) pro errgroup e amigos.

A segunda mudança é mais profunda e operacional: o runtime agora respeita limites de CPU de cgroups ao definir GOMAXPROCS automaticamente. Antes do 1.25, um pod com limite de 2 CPUs rodando numa máquina física de 64 cores fazia o Go assumir GOMAXPROCS=64. Resultado: scheduler do Go competindo desnecessariamente com o cgroup do Linux pelo CPU real do pod, latência inflada sem causa aparente, contenção de scheduler invisível pro APM.

No EKS, isso sempre foi armadilha clássica. A mitigação até 1.24 era importar go.uber.org/automaxprocs em todo serviço Go pra ajustar manualmente na inicialização. A partir do 1.25, vira comportamento default do runtime. Quem opera em container ganha latência de graça só atualizando a versão. Vale o esforço de migração só por esse item.

E uma terceira que vale citar mesmo não sendo de concorrência direta: o pacote testing/synctest saiu de experimental e virou estável. Permite testar código concorrente de forma determinística, sem flakiness de teste que falha 1 em 100 execuções. Substitui boa parte dos time.Sleep feios que a gente colocava em teste de goroutine pra dar tempo da coisa rodar. Pelo menos aqui, fizemos festa por conta disso haha.

Fan-out / fan-in: quando tem transformação

Worker pool é bom pra processar items independentes. Fan-out/fan-in é pra pipeline: pegar entrada, transformar em paralelo, juntar resultados.

func fanOutFanIn(ctx context.Context, ids []string) ([]Result, error) {
    in := make(chan string)
    out := make(chan Result)

    g, ctx := errgroup.WithContext(ctx)

    g.Go(func() error {
        defer close(in)
        for _, id := range ids {
            select {
            case in <- id:
            case <-ctx.Done():
                return ctx.Err()
            }
        }
        return nil
    })

    const workers = 10
    workerGroup := errgroup.Group{}
    for i := 0; i < workers; i++ {
        workerGroup.Go(func() error {
            for id := range in {
                result, err := fetch(ctx, id)
                if err != nil {
                    return err
                }
                select {
                case out <- result:
                case <-ctx.Done():
                    return ctx.Err()
                }
            }
            return nil
        })
    }

    go func() {
        workerGroup.Wait()
        close(out)
    }()

    var results []Result
    for r := range out {
        results = append(results, r)
    }

    if err := g.Wait(); err != nil {
        return nil, err
    }
    if err := workerGroup.Wait(); err != nil {
        return nil, err
    }
    return results, nil
}

Mais verboso, mas o padrão é claro:

• Um produtor coloca IDs no channel in.
• Workers consomem de in, processam, colocam em out.
• Goroutine separada fecha out quando todos os workers terminam.
• Leitor principal drena out.

Detalhe crítico: todo envio em channel deve ter um select com ctx.Done(). Sem isso, se o contexto cancela mas um worker está bloqueado tentando enviar em out, a goroutine vaza.

Cancelamento com context

context.Context é o mecanismo padrão de cancelamento em Go. Qualquer função que faz trabalho não-trivial deve aceitar ctx e respeitar ctx.Done() (mas não vai passar ctx default em cada chamada né).

Padrão correto em loop longo:

func doWork(ctx context.Context) error {
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
        }

        if err := step(ctx); err != nil {
            return err
        }
    }
}

O default: no select faz ele não bloquear quando o contexto não está cancelado. O check roda uma vez por iteração, custo desprezível, e garante que um cancelamento externo pare o loop.

Em I/O (HTTP, SQL, Redis), não precisa do check manual. As libs modernas respeitam ctx automaticamente, então o check só aparece em loops CPU-bound longos.

Armadilhas comuns

Goroutine leak por send em channel não drenado. Se você sai de uma função e deixa uma goroutine bloqueada tentando enviar num channel sem leitor, ela vaza pra sempre. defer close() + select com ctx.Done() evita. Pra detectar leaks que já chegaram em produção, pprof (valida esse artigo massa na sequência) é a ferramenta padrão e cobri ela com detalhe num post separado sobre tooling nativo do Go.

sync.WaitGroup com Add dentro de goroutine. O Add tem que acontecer antes da goroutine começar. Dentro dela, existe race entre Add e Wait:

wg.Add(1)
go func() {
    defer wg.Done()
    ...
}()

Nunca:

go func() {
    wg.Add(1)
    defer wg.Done()
    ...
}()

Shared state sem mutex. Se duas goroutines escrevem no mesmo map, você tem race. go run -race detecta. Use sync.Mutex, sync.RWMutex, ou sync.Map quando fizer sentido.

Channel sem buffer em fan-in. Se o consumidor é mais lento que o produtor, produtores ficam bloqueados. Às vezes é o comportamento que você quer (backpressure). Às vezes não é, e nesses casos buffer pequeno (tamanho do número de workers) costuma ser um bom compromisso.

Lições aprendidas

Cinco fechamentos que valem internalizar antes de fechar essa aba.

Limite sempre, sem exceção. Worker pool ou errgroup.SetLimit, mas nunca dispare goroutines ilimitadas baseado em input externo. É a primeira gambiarra que vira incidente em produção quando o input chega 10x mais do que você esperava, e a fila a montante decide que hoje é dia de empurrar tudo (vai por mim, isso vai salvar tua vida).

errgroup é quase sempre o que você quer. Se você está usando sync.WaitGroup cru pra coordenar trabalho com possibilidade de erro, provavelmente está reescrevendo mal o que o errgroup faz bem. A partir do Go 1.25, o WaitGroup.Go(...) cobre o caso simples sem erro de forma muito mais limpa, mas pra qualquer coisa com propagação, errgroup segue como default.

Cancelamento é contrato, não opção. Se a sua função aceita ctx, precisa respeitar ctx.Done(). Função que faz I/O sem aceitar ctx é sinal de algo mal desenhado, e geralmente quem está no topo da pilha precisa fazer um milagre pra forçar timeout do lado de fora.

Teste com -race sempre. O race detector é um dos melhores recursos do Go. CI que não roda go test -race está perdendo bug invisível que vai aparecer em produção sob carga. No 1.25 ele ganhou companhia útil: testing/synctest permite testes determinísticos de código concorrente. Se você ainda escreve teste de goroutine com time.Sleep esperando a coisa rodar, troca essa abordagem.

Concorrência é técnica, não filosofia. Vai longe mais rápido quem tem quatro ou cinco patterns na ponta da língua e os usa consistentemente em todo lugar. Channel pattern exótico e goroutine com sinal customizado ficam pra quem já passou da regra básica. A maioria do código de produção precisa só do básico bem feito.

Se você está revendo um serviço crítico em Go essa semana, escolhe um worker pool da sua base e roda esse checklist mental:

1. tem limite?
2. aceita context?
3. propaga erro com errgroup?
4. tem teste com -race?

Já está no 1.25 pra colher o GOMAXPROCS container-aware de graça? Cada “não” é dívida técnica esperando incidente.

Pra fechar com uma curiosidade que me interessa de verdade: qual armadilha de concorrência em Go você já bateu em produção que não entrou nessa lista? Esse tipo de história, costuma valer mais que tutorial bem escrito. Vou ler os comentários abaixo com caderno em mãos, e provavelmente atualizando essa página com o que aparecer.

Obrigado.

Single-row vs batch de 500: mesma carga de 10 mil eventos, mesmo schema, mesmo Aurora. 47 segundos contra 1,4.

Introdução

Um consumer que lê de fila e grava um registro por vez no PostgreSQL é um erro que só aparece quando dá errado \o/. Em baixa frequência funciona bem, é código simples e cada evento é atômico. Em alta frequência, vira o gargalo do banco inteiro.

No post anterior da série, contei de um incidente no Aurora onde um consumer que escrevia evento-a-evento estava multiplicando a carga de escrita. Aqui desço ao nível de implementação: por que isso dói, como refatorar pra batch com INSERT ... ON CONFLICT, e onde moram as armadilhas.

Pra dar tamanho ao contexto: a Harmo opera mais de 70 microservices em produção, e esse Aurora absorve na média 4.500 operações de escrita por segundo, com picos passando de 24 mil em hora cheia. Quando um único consumer dessa arquitetura grava evento-a-evento, o pedágio fixo do PostgreSQL por INSERT vira a maior parte do trabalho do banco. Single-row em alta frequência não é erro de iniciante. É erro de quem ainda não levou banco ao limite.

Por que single-row inserts matam em alta frequência

Toda vez que você faz um INSERT único, o PostgreSQL paga um pedágio fixo:

• Round-trip de rede entre app e banco
• Parse e planning da query (aliviado por pg_prepare se você usar, mas ainda assim um custo)
• Adquirir e liberar lock no heap e no índice
• WAL write separado pra aquele registro
• Commit individual se você não agrupou em transação

Em baixa frequência (dezenas por segundo) esse pedágio é invisível. Quando o consumer chega em alguns milhares de eventos por segundo, ele passa a ser a maior parte do trabalho do banco. O PostgreSQL gasta mais energia na cerimônia do insert do que gravando dado útil.

Um lote de 500 registros em um único INSERT paga esse pedágio uma vez. O INSERT em si fica maior, claro, mas a razão custo-fixo/trabalho-útil melhora drasticamente.

Estruturando o batch insert

Duas formas de montar um batch no PostgreSQL:

Forma 1: VALUES com múltiplas linhas

INSERT INTO events (tenant_id, event_type, payload, received_at)
VALUES
  ($1, $2, $3, $4),
  ($5, $6, $7, $8),
  ($9, $10, $11, $12);

Simples, legível, funciona. Desvantagem: se você precisa parametrizar 500 linhas com 4 colunas cada, são 2000 placeholders. O driver do cliente começa a reclamar, e o limite máximo de parâmetros do PostgreSQL é 65.535. Viável pra batches médios, mas não é a forma mais limpa.

Forma 2: UNNEST de arrays

INSERT INTO events (tenant_id, event_type, payload, received_at)
SELECT * FROM unnest(
  $1::uuid[],
  $2::text[],
  $3::jsonb[],
  $4::timestamptz[]
);

Aqui você passa 4 parâmetros, independente do tamanho do batch — cada um é um array. O driver serializa tudo em uma única chamada. É mais eficiente pra batches grandes e é a forma que a gente preferiu na refatoração.

Em Go, usando pgx, fica assim:

type Event struct {
    EventID    uuid.UUID
    TenantID   uuid.UUID
    Type       string
    Payload    map[string]any
    ReceivedAt time.Time
}

func InsertEvents(ctx context.Context, db DBTX, events []Event) error {
    if len(events) == 0 {
        return nil
    }

    tenantIDs := make([]uuid.UUID, len(events))
    types := make([]string, len(events))
    payloads := make([]string, len(events))
    receivedAts := make([]time.Time, len(events))

    for i, e := range events {
        b, err := json.Marshal(e.Payload)
        if err != nil {
            return fmt.Errorf("marshal payload event %d: %w", i, err)
        }
        tenantIDs[i] = e.TenantID
        types[i] = e.Type
        payloads[i] = string(b)
        receivedAts[i] = e.ReceivedAt
    }

    _, err := db.Exec(ctx, `
        INSERT INTO events (tenant_id, event_type, payload, received_at)
        SELECT tenant_id, event_type, payload::jsonb, received_at
        FROM unnest($1::uuid[], $2::text[], $3::text[], $4::timestamptz[])
          AS u(tenant_id, event_type, payload, received_at)
    `, tenantIDs, types, payloads, receivedAts)
    if err != nil {
        return fmt.Errorf("bulk insert events: %w", err)
    }
    return nil
}

Três detalhes que valem comentar. Primeiro, DBTX é uma interface mínima que aceita *pgx.Conn, *pgxpool.Pool e pgx.Tx, você passa qualquer um sem mudar a assinatura, e testar a função com transação fica trivial. Segundo, o cast payload::jsonb no SELECT: array de jsonb direto no pgx ainda dá fricção de encoding em algumas versões, então passar JSON como text[] e converter no SELECT funciona em qualquer setup, sem registrar tipo custom. Terceiro, o guard de len(events) == 0 evita uma query desnecessária e uma mensagem de erro pouco amigável do pgx em array vazio.

ON CONFLICT: DO NOTHING vs DO UPDATE

Quando o consumer pode receber eventos duplicados (e numa fila à-la-SQS com at-least-once, sempre pode), você precisa decidir o que fazer em colisão de chave única.

DO NOTHING — ignora silenciosamente:

INSERT INTO events (event_id, tenant_id, payload)
VALUES ($1, $2, $3)
ON CONFLICT (event_id) DO NOTHING;

Uso: quando o dado mais novo não vale mais que o mais velho. Eventos imutáveis, logs append-only, eventos idempotentes. Na maioria dos consumers de fila, é isso que você quer.

DO UPDATE — faz upsert:

INSERT INTO events (event_id, name, updated_at)
VALUES ($1, $2, now())
ON CONFLICT (event_id) DO UPDATE
  SET name = EXCLUDED.name,
      updated_at = EXCLUDED.updated_at
  WHERE events.updated_at < EXCLUDED.updated_at;

Uso: quando o registro mais novo sobrepõe o antigo. Note a cláusula WHERE na ponta, é o que garante que um evento atrasado não sobrescreva um evento mais recente que já chegou antes. Sem isso, você cria inconsistência temporal.

O EXCLUDED é uma pseudo-tabela que representa a linha que tentou entrar no INSERT. Fundamental pra diferenciar “o que está no banco” de “o que eu estou tentando gravar”.

Armadilha: ON CONFLICT em batch com duplicatas dentro do próprio batch

Essa pegou a gente de surpresa. Em um batch de 500 eventos, o consumer pode ter 2 ou 3 com a mesma chave (a fila entregou duplicatas no mesmo pull). O ON CONFLICT só age contra o que já está no heap, dentro do batch, ele não ajuda. O resultado é um erro:

ERROR: ON CONFLICT DO UPDATE command cannot affect row a second time

Solução: deduplicate no cliente antes de mandar pro banco.

seen := make(map[uuid.UUID]struct{}, len(events))
deduped := make([]Event, 0, len(events))
for _, e := range events {
    if _, ok := seen[e.EventID]; ok {
        continue
    }
    seen[e.EventID] = struct{}{}
    deduped = append(deduped, e)
}

Barato, defensivo, resolve.

Benchmarks

Teste sintético, mesma carga total de 10.000 eventos, mesmo schema, mesma tabela com 50M registros, Aurora PostgreSQL. Três cenários:

O salto de single-row pra batch de 100 é o que mais pesa. De 100 pra 500 o retorno é decrescente: você ganha throughput, mas aumenta o tamanho de lock e o custo de erro (se o batch falhar, 500 eventos precisam ser reprocessados).

Qual batch size escolher

Sem regra universal, mas orientação prática. Lotes de 50 a 100 são conservadores e cabem bem em tabelas com muita contenção de lock. Entre 200 e 500 fica a faixa que a maioria dos consumers acerta sem precisar pensar muito, e é o que a gente roda em produção. Acima de 1000, só se a tabela é dedicada, sem contenção, e você tolera latência de processamento maior.

Batch size é troca entre throughput e latência. Um consumer que junta 500 eventos antes de gravar tem p99 pior que um que grava de 50 em 50. Se seu caso é “realtime”, isso pesa.

Falando em latência: nem mesmo o Sol é realtime. Se ele “sumir” agora, a gente só perceberia daqui a 8 minutos e 20 segundos, que é o tempo que a luz leva pra cruzar os 150 milhões de quilômetros até a Terra. E não é só a luz. Pela relatividade geral, o efeito gravitacional também viaja na velocidade da luz, então a Terra continuaria seguindo a órbita atual nesses mesmos 8 minutos antes de “sentir” o sumiço e sair em linha reta.

A moral pro nosso problema é a mesma. A única coisa instantânea em qualquer sistema é a parte que cabe num único ciclo de CPU. Tudo que cruza barreira, rede, disco ou escala, paga latência. Quando você projeta um consumer pra batch de 500 em vez de single-row, está aceitando explicitamente o que sistemas distribuídos te impõem implicitamente. Realtime, no sentido estrito, é uma promessa que nem a física faz.

Lições aprendidas

• Nunca nasça em single-row. Qualquer consumer de fila deveria ter batch desde o dia um. É mais código, mas é o código certo.
• Dedup no cliente antes do batch. ON CONFLICT não ajuda contra duplicatas internas ao batch.
• Escolha conscientemente DO NOTHING vs DO UPDATE. Os dois são corretos, mas pra problemas diferentes. Se você está em dúvida, DO NOTHING é o default mais seguro.
• Na cláusula de UPDATE, proteja contra out-of-order. Inclua um WHERE que compara timestamp. Sem isso, evento atrasado sobrescreve evento recente, e você vai descobrir isso da pior forma.
• Benchmark no seu ambiente. Os números acima servem pra ordem de grandeza. Tempo absoluto depende de schema, índices, concorrência e instância.

DO NOTHING ou DO UPDATE como default no seu time? Tenho visto muito reflexo de sempre fazer upsert e pouca análise da semântica antes da escolha. Curioso pra saber se outras pessoas se incomodam com isso também.

O que coletamos

Quando você aceita os cookies de analytics no banner, usamos Google Analytics 4 com IP anonimizado para registrar:

• Páginas que você visita
• Tempo aproximado em cada página
• Tipo de dispositivo (mobile/desktop) e navegador
• Origem do tráfego (Google, LinkedIn, link direto, etc.)
• Localização aproximada (cidade e país, a partir do IP anonimizado)

Não coletamos seu nome, e-mail, telefone, nem qualquer dado que te identifique pessoalmente.

Se você clicar em Recusar no banner, nenhum desses dados é coletado.

O que NÃO coletamos

• Endereço de e-mail
• Dados de pagamento (não vendemos nada aqui)
• Tracking entre sites
• Anúncios personalizados
• Sinais avançados do Google Signals

Comentários

Se você comentar em um post, os dados ficam armazenados pelo provedor de comentários sob a política dele, não sob essa.

Seus direitos sob a LGPD

Pela Lei Geral de Proteção de Dados (Lei 13.709/2018), você tem direito a:

• Saber o que coletamos sobre você (essa página explica)
• Solicitar exclusão dos seus dados
• Retirar o consentimento a qualquer momento (limpando cookies/localStorage do site, ou clicando em “Recusar” no banner em uma próxima visita)
• Reclamar à ANPD se entender que houve uso indevido

Contato

Para qualquer questão sobre privacidade: leonardo@rifeli.dev.

Mudanças

Essa política pode mudar. Quando mudar, a data de atualização abaixo é alterada.

Última atualização: 25 de maio de 2026.

AWS Aurora

Introdução

Ninguém planeja uma crise de performance. Ela chega numa quarta-feira de manhã, quando o dashboard fica vermelho e os alertas começam a apitar. Foi mais ou menos assim que começou uma das crises mais instrutivas que atravessei em um Aurora Cluster PostgreSQL 13.18, e o que quero contar aqui não é o “fizemos tudo certo”, mas a ordem real em que apaguei o fogo, o que funcionou de primeira e o que eu não tinha mapeado direito antes.

Na Harmo, o core transacional roda em Cluster Aurora PostgreSQL, single writer numa instância db.r8g.4xlarge (16 vCPU, 128 GB de RAM), storage I/O-Optimized e uma reader db.r8g.4xlarge. A plataforma processa +10 milhões de pesquisas e +300k avaliações públicas por mês, e cada uma toca o banco mais de uma vez: avaliação registrada, pesquisa enviada, pesquisa respondida, e-mail aberto, webhook de fornecedor. Quando esse fluxo degrada, a plataforma inteira sente. Mesmo que raro, com crescimento pode acontecer.

O sintoma

O primeiro sinal foi CPU de writer subindo de um patamar de 35–45% pra beirar 90% de forma sustentada. Commit latency acompanhou: o p95 de gravação subiu de dezenas de milissegundos pra mais de um segundo. Connections ativas também: o que costumava ficar em torno de 120 foi pra 380 em 15 minutos. Não usamos proxy na frente do banco. Estamos estudando usarmos prest.

Três sintomas simultâneos quase nunca têm uma única causa. Eu sabia disso, mas o instinto inicial foi buscar a bala de prata, provavelmente uma query nova de uma feature recém-deployada. Gastei uns cinco minutos olhando a timeline de deploys antes de aceitar que não era isso e partir pra investigação sistêmica.

Primeira hora: localizando a dor

Comecei pelo óbvio:

SELECT query, calls, total_exec_time, mean_exec_time, rows
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 20;

Três coisas saltaram:

1. Uma tabela grande que fazia INSERT em alta frequência, um registro por vez, disparado por um consumer que processava eventos vindos do SES.
2. Uma query de leitura recorrente estava em Seq Scan num relacionamento de centenas de milhões de linhas, índice existia, mas o planner não usava.
3. Vários índices apareciam como ativos mas com zero uso em 30 dias.

Pra confirmar a terceira hipótese:

SELECT schemaname, relname, indexrelname, idx_scan, pg_size_pretty(pg_relation_size(indexrelid)) AS size
FROM pg_stat_user_indexes
WHERE idx_scan = 0
ORDER BY pg_relation_size(indexrelid) DESC;

O resultado: 18 índices com idx_scan = 0 nos últimos 30 dias, alguns com mais de 2GB cada. Índices não lidos ainda são escritos em toda operação de INSERT/UPDATE/DELETE. Ou seja: write amplification gratuita.

As três causas se reforçando

Isso não era um problema, eram três problemas compostos:

• Write amplification por índices mortos encarecendo cada insert.
• Inserts single-row de alta frequência multiplicando round-trips, parse, planning e WAL por registro.
• Sequential scan recorrente consumindo CPU de leitura enquanto o banco já sofria com escrita.

Cada um sozinho seria digerível. Os três juntos explicavam o pico simultâneo de CPU, latência e conexões.

A ordem das ações

Primeira questão foi conter acessos e controles de comunicação com clientes. Depois veio a tentação de uma crise: atacar tudo ao mesmo tempo. Errado. Cada ação precisa ter rollback possível e janela de verificação. Fiz assim:

1. Terminar conexões antigas em idle-in-transaction

Alívio imediato. Tinha dezenas de conexões penduradas há mais de 30 minutos:

SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND now() - state_change > interval '10 minutes';

Isso sozinho tirou 40% das conexões ativas e deu fôlego pra investigar com mais calma.

2. Drop dos 18 índices mortos

Em ambiente de produção quente, DROP INDEX CONCURRENTLY pra evitar lock. Um de cada vez, monitorando. Cada drop reduziu write amplification das tabelas afetadas. CPU começou a ceder.

DROP INDEX CONCURRENTLY IF EXISTS idx_some_unused_composite;

3. Índice cirúrgico na tabela grande

A query de leitura fazia Seq Scan porque o índice existente era em uma coluna sozinha, e o planner optava por varrer. Criei o índice composto certo, também com CONCURRENTLY:

CREATE INDEX CONCURRENTLY idx_tablex_namey_lookup
  ON tablex_namey_flowz (tenant_id, status, created_at DESC);

Depois disso, EXPLAIN ANALYZE da query problemática caiu de 4.2 segundos pra 38 milissegundos.

4. Refatoração do consumer SES pra batch insert com ON CONFLICT

Essa foi a ação que não fiz ao vivo, era mudança de código. Agendamos o deploy pro fim do dia. Mas sem essa parte, o alívio das outras três seria temporário: o volume de writes single-row voltaria a pressionar o banco no próximo pico.

No próximo post dessa série vou detalhar essa refatoração. Resumindo: saímos de INSERT um-a-um pra lotes de 500 com INSERT ... ON CONFLICT DO NOTHING. O throughput subiu em ordem de grandeza.

O que mudou depois

Na primeira hora pós-ações: CPU caiu de 90% pra 55%. Connections ativas voltaram pro patamar normal. Latência de commit caiu em torno de 3x.

Na semana seguinte, com o consumer já em batch insert, a CPU média em horário de pico estabilizou em torno de 25–30%. O mesmo hardware, a mesma carga de negócio, só que sem os três multiplicadores compostos.

Lições

1. Índice custa no write path. Revisar pg_stat_user_indexes uma vez por trimestre é barato e teria evitado boa parte dessa crise.
2. Single-row insert é inofensivo em baixa frequência e assassino em alta: consumer que processa fila deveria nascer com batch, e se nasceu single-row, é dívida técnica com data de vencimento.
3. Seq scan não é necessariamente o vilão, mas em tabela grande quase sempre é, e quando o planner ainda escolhe seq scan com índice disponível, o índice provavelmente não é o certo.
4. Numa crise, ordem importa: matar conexões penduradas compra tempo, dropar índices reduz write amplification antes de criar novos, e mudança de código fica pro deploy calmo.
5. E um bom alerta teria detectado tudo isso dias antes do alarme que tocou no dia. O próximo post da série destrincha a refatoração do consumer single-row para batch insert, que foi o que estabilizou o quadro definitivamente.

Numa crise como essa, qual ação você atacaria primeiro: matar conexões idle, dropar índice morto ou refatorar o consumer? A ordem que escolhi tem motivo e gostaria de ver runbooks alternativos.

Você abre o Claude Code no desktop de trabalho pela primeira vez na semana e percebe que ele não lembra de nada: as skills customizadas que você criou, os slash commands que refinou, as memórias acumuladas sobre cada projeto. O CLI não tem sync nativo do diretório ~/.claude/. Cada máquina é uma ilha.

“Mas eu só preciso commitar o .claude/ do projeto, né?”

Essa é a primeira reação de quem lê o título — e ela ignora o problema. Claude Code guarda config em dois lugares diferentes, e só um deles é resolvido versionando o .claude/ dentro do repo:

Por projeto (<repo>/.claude/) — mora dentro de cada repositório. Tem o settings.json (compartilhável com o time) e o settings.local.json (permissões pessoais de tool use). Esse caso é fácil: basta versionar o que for compartilhado e adicionar settings.local.json ao .git/info/exclude local se você não quiser mesclar permissões com o time.

Global do usuário (~/.claude/) — mora no seu home, fora de qualquer repo. Inclui:

• Skills customizadas (~/.claude/plugins/)
• Slash commands customizados (~/.claude/commands/)
• Config global do CLI (~/.claude/settings.json)
• Memórias de contexto por projeto (~/.claude/projects/<path-encoded>/memory/)

Este artigo é sobre o segundo caso. Versionar o .claude/ do repo não transfere nenhum dos itens acima, porque eles não vivem dentro do repo — vivem no seu $HOME. E é ali que mora o grosso do trabalho de configuração que você acumula ao longo de meses.

Por que isso importa

Na Harmo adotamos o Claude Code como ferramenta default de AI para o time de engenharia, então essa dor de sync entre máquinas aparece no dia a dia e não é hipotética.

Quem usa Claude Code a sério acumula configuração global rapidamente: skills que você escreveu pra adequar o comportamento do agente ao seu stack, slash commands que automatizam fluxos repetidos, memórias construídas por semanas de conversa sobre cada projeto. Recriar isso manualmente numa segunda máquina custa horas e é o tipo de tarefa que ninguém faz — simplesmente se trabalha pior do outro lado.

O problema é agravado por um detalhe pouco documentado: memórias de projeto são indexadas pelo path absoluto do diretório. Se no laptop o projeto está em /Users/rifeli/work/harmo e no desktop em /home/rifeli/projects/harmo, as memórias não se transferem mesmo que você copie o diretório ~/.claude/ inteiro.

Sync também é backup

Mesmo que você use uma máquina só, vale configurar uma das estratégias abaixo. SSD morre, sistema é reinstalado, rm -rf acontece na pasta errada. Perder o ~/.claude/ significa perder semanas de memória de contexto acumulada sobre cada projeto, todas as permissões ajustadas, skills customizadas que você foi refinando. É o tipo de estado que você nem lembra que construiu até ele sumir.

A diferença entre um backup que salva sua pele e um que não salva é o que você excluiu dele. Um backup completo de ~/.claude/ inclui sessions/, cache/ e history.jsonl — conteúdo pesado, inútil para restauração e que vai fazer você desistir do backup porque leva tempo demais. Os mesmos ignores que você configura para sync servem para backup. Qualquer uma das três abordagens deste artigo te dá backup de graça como efeito colateral.

O que é portável e o que não é

O ~/.claude/ tem conteúdo misturado. Separar o que faz sentido sincar evita dor de cabeça depois. A tabela abaixo está agrupada por escopo — note que só as duas primeiras linhas são o famoso “basta commitar no repo”:

Escopo por-projeto (dentro do repo):

Escopo global (~/.claude/, fora de qualquer repo):

A regra prática: sincar o que você configurou conscientemente, ignorar o que o CLI gerou para si próprio. E, importante, o problema deste artigo é o segundo grupo — o primeiro já é resolvido pelo fluxo normal de git do repo.

Três abordagens

1. Git repo privado + symlinks

A solução mais simples e auditável. Funciona bem se você não precisa de sync em tempo real e gosta de controlar o que vai versionado.

# Na primeira máquina: criar o repo
mkdir -p ~/dotfiles/claude
cd ~/dotfiles

git init
cat > .gitignore <<'EOF'
claude/cache/
claude/sessions/
claude/history.jsonl
claude/shell-snapshots/
claude/statsig/
claude/.credentials.json
claude/todos/
EOF

# Mover os arquivos reais para o repo e deixar symlinks no lugar
mv ~/.claude/settings.json       ~/dotfiles/claude/settings.json
mv ~/.claude/plugins             ~/dotfiles/claude/plugins
mv ~/.claude/commands            ~/dotfiles/claude/commands 2>/dev/null || true

ln -s ~/dotfiles/claude/settings.json ~/.claude/settings.json
ln -s ~/dotfiles/claude/plugins       ~/.claude/plugins
ln -s ~/dotfiles/claude/commands      ~/.claude/commands

git add . && git commit -m "initial claude config"
git remote add origin git@github.com:seu-user/dotfiles.git
git push -u origin main

Na segunda máquina:

git clone git@github.com:seu-user/dotfiles.git ~/dotfiles

# Fazer backup de qualquer config existente antes de linkar
mv ~/.claude/settings.json ~/.claude/settings.json.bak 2>/dev/null

ln -s ~/dotfiles/claude/settings.json ~/.claude/settings.json
ln -s ~/dotfiles/claude/plugins       ~/.claude/plugins
ln -s ~/dotfiles/claude/commands      ~/.claude/commands

Vantagens: histórico completo, rollback trivial, code review antes de propagar mudanças. Desvantagem: você precisa lembrar de git pull e git push. Não é automático.

Para o settings.local.json de cada repo, a abordagem é diferente — esse arquivo mora dentro do projeto e é gitignored por padrão. Se você confia no time, basta adicionar .claude/settings.local.json ao .git/info/exclude local e versionar .claude/settings.json (versão compartilhada) no repo principal.

2. chezmoi (ou yadm) com suporte a segredos

O chezmoi resolve dois problemas que o git puro não trata bem: templates por máquina (o path do home no macOS é /Users/rifeli, no Linux é /home/rifeli) e segredos encriptados.

# Instalar chezmoi
sh -c "$(curl -fsLS get.chezmoi.io)"

chezmoi init
chezmoi add ~/.claude/settings.json
chezmoi add ~/.claude/plugins
chezmoi add ~/.claude/commands

# Editar o arquivo de ignorar no source state
chezmoi edit-config

Adicione ao ~/.local/share/chezmoi/.chezmoiignore:

.claude/cache
.claude/sessions
.claude/history.jsonl
.claude/shell-snapshots
.claude/statsig
.claude/.credentials.json
.claude/todos

Para config que varia entre máquinas, transforme o arquivo em template. Renomeie dot_claude/settings.json para dot_claude/settings.json.tmpl e use:

{
  "model": "sonnet",
  "env": {
    "EDITOR": "{{ if eq .chezmoi.os \"darwin\" }}cursor{{ else }}code{{ end }}"
  }
}

Na segunda máquina:

sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply seu-user

Se você tem chaves que precisam viajar junto (API keys de outras ferramentas referenciadas no settings), integre com age ou gpg:

chezmoi add --encrypt ~/.claude/some-secret-config

Vantagens: template-aware, integração nativa com secret managers, um comando para aplicar tudo. Desvantagem: curva de aprendizado maior que git puro; se você nunca usou, é uma ferramenta nova para dominar só para isso.

3. Syncthing / Dropbox / iCloud com symlinks seletivos

Sync em tempo real, sem git commit. A diferença crítica em relação aos outros: se você não configurar os ignores corretamente, vai sincar cache, sessões ativas, e eventualmente corromper arquivos com escritas concorrentes.

Usando Syncthing como exemplo (mais seguro que Dropbox para arquivos ativamente escritos porque tem versioning e resolução de conflito explícita):

# Criar diretório de sync
mkdir -p ~/Sync/claude-config

# Mover apenas os arquivos seguros
mv ~/.claude/settings.json ~/Sync/claude-config/
mv ~/.claude/plugins       ~/Sync/claude-config/
mv ~/.claude/commands      ~/Sync/claude-config/ 2>/dev/null

ln -s ~/Sync/claude-config/settings.json ~/.claude/settings.json
ln -s ~/Sync/claude-config/plugins       ~/.claude/plugins
ln -s ~/Sync/claude-config/commands      ~/.claude/commands

No Syncthing, adicione ~/Sync/claude-config como pasta compartilhada entre as máquinas. Não sincronize o ~/.claude/ inteiro — é tentador e vai te morder.

Com Dropbox ou iCloud o princípio é o mesmo, mas evite ativamente:

• Sincar sessions/ ou history.jsonl: o CLI escreve neles durante uso e sync em tempo real gera conflitos.
• Sincar cache/: pode ficar pesado e gerar upload infinito.
• Confiar na resolução automática de conflitos: Dropbox cria arquivo (conflicted copy).json silenciosamente, e o Claude Code não sabe o que fazer com isso.

Vantagens: zero ação manual após setup. Desvantagens: sem histórico acionável, risco alto se a lista de ignore estiver errada, e se as duas máquinas estiverem online simultaneamente e você editar de um lado, o outro lado pode ver estado inconsistente.

O pega da memória path-encoded

Memórias vivem em ~/.claude/projects/<path-encoded>/memory/, onde <path-encoded> é o path absoluto do projeto com separadores trocados por hífens. Um projeto em /Users/rifeli/work/harmo vira -Users-rifeli-work-harmo. Em /home/rifeli/projects/harmo vira -home-rifeli-projects-harmo. Mesmo repo, duas chaves diferentes, memórias órfãs.

Duas soluções, escolha uma:

Opção A: padronizar o path em todas as máquinas. A mais limpa. Adote ~/projects/<repo> como convenção e crie symlinks se o path real for diferente:

# No desktop, se o repo real está em /mnt/data/work/harmo
mkdir -p ~/projects
ln -s /mnt/data/work/harmo ~/projects/harmo

# Sempre abrir o Claude Code via ~/projects/harmo
cd ~/projects/harmo && claude

Opção B: script de renomeio pós-sync. Útil quando padronizar não é viável (diferenças de SO, ou times onde cada dev tem layout próprio). Depois de puxar as memórias, renomeie os diretórios:

#!/bin/bash
# remap-memory.sh — rodar após sync para remapear path-encoded dirs

SOURCE_MACHINE_PATH="-Users-rifeli-work-harmo"
TARGET_MACHINE_PATH="-home-rifeli-projects-harmo"

cd ~/.claude/projects

if [ -d "$SOURCE_MACHINE_PATH" ] && [ ! -d "$TARGET_MACHINE_PATH" ]; then
  cp -r "$SOURCE_MACHINE_PATH" "$TARGET_MACHINE_PATH"
  echo "Remapped $SOURCE_MACHINE_PATH -> $TARGET_MACHINE_PATH"
fi

Dá pra integrar isso como hook do chezmoi (run_after_remap-memory.sh.tmpl) ou como post-merge hook do git no repo de dotfiles.

Decisão rápida

• Se você quer o mínimo de ferramentas novas e confia em git pull: git + symlinks.
• Se você sincroniza mais do que só Claude Code (zshrc, nvim, etc) e quer templates por SO: chezmoi.
• Se você odeia comandar sync manualmente e topa o risco: Syncthing com ignores rigorosos. Não Dropbox, não iCloud, por causa do comportamento de conflito.
• Se você trabalha em dois SOs diferentes (mac + linux): chezmoi, pelo suporte a template.
• Se você precisa versionar segredos junto da config: chezmoi + age.

Limitações honestas

Nada disso resolve:

• Token de auth. ~/.claude/.credentials.json expira e não vale o risco de espalhar entre máquinas. Faça login em cada uma separadamente.
• Sessões ativas. Se você está no meio de uma conversa no laptop e abre a mesma no desktop, elas não se encontram. Sessão é local.
• Cache e downloads de modelo. Claude Code usa a API; não há modelo local para sincar. Mas se você tem ferramentas que cacheiam respostas, essas caches são por máquina.
• Estado de permissões no meio de uma run. Se você aprovou “sempre permitir” para uma tool no laptop durante uma sessão e sincou, pode ser que na outra máquina a aprovação só apareça na próxima reinicialização do CLI.

Comparação final

Conclusão

A recomendação pragmática para a maioria: git + symlinks para config estável, e padronizar os paths dos projetos para resolver a questão das memórias. Passa para chezmoi só quando a dor do manual vira maior que a dor de aprender a ferramenta.

💬 E você, como tem sincronizado sua configuração do Claude Code?

Usa dotfiles, sync em nuvem, ou simplesmente aceita a duplicação e reconfigura do zero? Conta nos comentários como você lida com isso no dia a dia.

Introdução

Na Harmo, lidamos com grandes volumes de dados, modelos de IA e pipelines que precisam ser eficientes, escaláveis e fáceis de manter. Python surgiu como a linguagem principal por sua versatilidade, ecossistema maduro e fácil integração com ferramentas de ML/IA, como TensorFlow, PyTorch e LangChain. Utilizamos Python desde 2017 com foco em scrappings, ML e data pipelines (com Spark e EMR).

Neste artigo vamos:

• Mostrar o porquê de Python ser essencial para IA e dados;
• Apresentar conceitos práticos usados no dia a dia da Harmo;
• Demonstrar exemplos de código e pipelines reais.

🧠 Por que Python para IA e Dados

Python se tornou o padrão para IA e ciência de dados por:

1. Ecossistema rico: NumPy, Pandas, scikit-learn, PyTorch, etc.
2. Documentação e comunidade com suporte massivo.
3. Produtização facilitada, APIs e deployment com FastAPI, Docker, etc.

Na Harmo, usamos Python em:

• ETL de dados (extração, transformação e carga);
• Treinamento e inferência de modelos;
• Orquestração de pipelines (Airflow / Prefect);
• APIs de serviço inteligente.

🔧 Começando com Python

Antes de tudo, vamos configurar um ambiente de desenvolvimento.

Instalar Python e Virtualenv

# instalar pyenv (opcional)
curl https://pyenv.run | bash

# instalar Python 3.11
pyenv install 3.11.2
pyenv local 3.11.2

# criar virtualenv
python -m venv .venv
source .venv/bin/activate

Dependências comuns na Harmo

pip install pandas numpy scikit-learn torch transformers fastapi uvicorn

📊 Trabalhando com Dados

Na Harmo, muitos dados vêm de feedback de usuários, logs de uso e integrações externas. O Pandas é nossa ferramenta principal.

Exemplo de carregamento e análise

import pandas as pd

df = pd.read_csv("feedbacks.csv")
print(df.head())

# contar tópicos mais frequentes
top_topics = df["topic"].value_counts().nlargest(10)
print(top_topics)

🤖 IA Prática em Python

Modelos de NLP com Transformers

from transformers import pipeline

classifier = pipeline("sentiment-analysis")

results = classifier([
    "A experiência com o produto foi ótima!",
    "O sistema ficou fora do ar por muito tempo."
])

for r in results:
    print(r)

Esse tipo de análise é usado na Harmo para:

• entender feedback de clientes;
• classificar comentários por sentimento;
• alimentar dashboards de decisão.

🚀 Orquestração de Pipelines

Usamos Airflow ou Prefect para agendar tarefas de dados e IA.

Exemplo (Prefect)

from prefect import flow, task

@task
def extract():
    ...

@task
def transform(data):
    ...

@task
def load(data):
    ...

@flow
def etl_pipeline():
    data = extract()
    transformed = transform(data)
    load(transformed)

PS.: Farei um artigo sobre como utilizar pipelines airflow pra orquestrar pods K8S para tarefas.

📡 APIs Inteligentes com FastAPI

Depois de treinar modelos, a próxima etapa é disponibilizar inferência via API:

from fastapi import FastAPI
import torch

app = FastAPI()

@app.post("/predict")
def predict(text: str):
    # chamada do modelo treinado
    return {"prediction": "positivo"}

Servimos essas APIs em containers Docker e fazemos deploy com CI/CD.

🧪 Testes e Qualidade

No dia a dia da Harmo, código de dados e IA é coberto por testes unitários:

pip install pytest

def test_model_output():
    assert model.predict("bom") == "positivo"

📈 Métricas e Monitoramento

Importante acompanhar:

• Latência de inferência
• Precisão / recall dos modelos
• Logs e alertas

Usamos ferramentas como:

• Prometheus
• Grafana
• Newrelic

🧪 Lições aprendidas na Harmo

1. Comece simples: protótipos ajudam validar modelos antes de escalar.
2. Automatize tudo: da coleta de dados até o deploy.
3. Monitore em produção: sem métricas, não há melhoria.
4. Código é arte e engenharia: mantenha legível e testado.

🔚 Conclusão

Python não é apenas uma linguagem, é a base sobre a qual construímos valor em IA e dados na Harmo. Seu ecossistema acelerou nossa entrega de soluções inteligentes e nos permitiu inovar constantemente.

Se você está começando, foque em dominar:

• pandas/numpy
• ML frameworks
• APIs e deploy
• Testes e automação

Python faz a ponte entre dados e impacto real.

golang/go

Introdução

No meu último artigo, discutimos como Go lida com orientação a objetos através de composição (veja aqui). Mas composição sozinha não garante bom design.

Go te dá liberdade: structs simples, métodos livres e interfaces implícitas, porém, é justamente por isso é fácil cair em:

• Funções gigantes
• Services que sabem demais
• DTOs anêmicos
• Lógica espalhada pelo projeto

A pergunta não é “Go suporta OO?”. Ela precisa ser: Como manter disciplina arquitetural numa linguagem que não impõe nada?

É aqui que entra Object Calisthenics.

O que é Object Calisthenics?

Tem uma palestra que marcou minha carreira, é do Guilherme Blanco e foi PHP para Adultos – Object Calisthenics e Clean Code - Guilherme Blanco no InterCon PHP 2014 em set/2014 (entreguei a idade).

Criado por Jeff Bay, é um conjunto de 9 regras de design pensadas como treino de musculação para código.

No começo dói. Depois você começa a enxergar problemas antes deles virarem débito técnico.

Mas aqui vai o ponto importante:

Object Calisthenics não deve ser aplicado como dogma. Ele deve ser usado como lente.

Vamos adaptar as 9 regras para a realidade do Go.

1. Apenas um nível de indentação por função

Se sua função parece uma pirâmide, ela já está fazendo coisa demais.

Código em flecha:

func Process(order Order) error {
	if order.IsValid() {
		if order.HasStock() {
			if err := order.Pay(); err != nil {
				return err
			}
		}
	}
	return nil
}

Versão idiomática em Go:

func Process(order Order) error {
	if !order.IsValid() {
		return ErrInvalidOrder
	}

	if !order.HasStock() {
		return ErrNoStock
	}

	return order.Pay()
}

Go já incentiva isso naturalmente via guard clauses (Está PROIBIDO usar ELSE).

Essa regra é praticamente um reforço do estilo idiomático da linguagem.

2. Não use else

O else geralmente indica que você poderia ter retornado antes.

Em Go isso é ainda mais evidente:

if err != nil {
	return err
}

Esse padrão não é só estilo, ele reduz:

• Profundidade cognitiva
• Complexidade ciclomática
• Carga mental ao revisar código

3. Encapsule todos os primitivos (Value Objects)

Aqui começa a ficar interessante em Go.

Problema comum:

func CreateUser(id int, age int, email string)

Nada impede você de trocar id e age.

Agora:

type UserID int
type Age int
type Email string

Ou melhor:

type Email struct {
	value string
}

func NewEmail(v string) (Email, error) {
	if !strings.Contains(v, "@") {
		return Email{}, ErrInvalidEmail
	}
	return Email{value: v}, nil
}

Agora o erro é impossível de existir fora da criação.

Esse padrão é poderoso especialmente em sistemas de domínio rico, algo comum em produtos SaaS complexos.

4. Coleções como cidadãos de primeira classe

Se você tem isso:

func CalculateTotal(prices []float64) float64

Você espalha lógica por todo lugar.

Prefira:

type Prices []float64

func (p Prices) Total() float64 {
	var total float64
	for _, price := range p {
		total += price
	}
	return total
}

Agora o comportamento mora com o dado.

Isso reduz:

• Vazamento de regras
• Duplicação de loops
• Inconsistência

5. Um ponto por linha (Lei de Demeter)

Evite isso:

order.Customer.Address.City.Name

Isso cria acoplamento estrutural profundo.

Prefira:

order.CityName()

Se amanhã, a estrutura de City mudar, só um lugar precisa ser alterado.

6. Não abrevie nomes

Go aceita variáveis curtas. Mas isso não significa que tudo deve ser abreviado.

Existe diferença entre:

i, r, w

E:

usrSvcProcMgr

Se o nome precisa ser abreviado para caber, talvez a responsabilidade esteja grande demais.

7. Entidades pequenas

Structs grandes quase sempre indicam:

• Baixa coesão
• Muitas razões para mudar
• Violação de SRP (tenho um artigo antigo sobre o assunto)

Se você tem:

type UserService struct {
	repo Repository
	cache Cache
	mailer Mailer
	logger Logger
	metrics Metrics
}

Talvez você tenha:

• Um Service Orquestrador
• Um Service de Notificação
• Um Service de Persistência

Composição > concentração.

8. Sem Getters e Setters

Go já não força encapsulamento clássico.

Mas o problema real não é o método. É o modelo anêmico.

Em vez de:

if order.Status() == Pending {
	order.SetStatus(Paid)
}

Prefira:

order.Pay()

Isso mantém regras de negócio dentro da entidade.

9. No máximo dois campos por struct

Essa é a mais polêmica. Ela força alta coesão.

Mas em Go isso precisa ser interpretado com cuidado.

DTOs de transporte? Podem ter muitos campos. Entidades de domínio? Devem ter poucos e bem relacionados. Essa regra não é literal, é um detector de alerta.

Onde Object Calisthenics NÃO funciona bem em Go:

• Código de infraestrutura
• Adaptadores HTTP
• Serialização
• Mappers
• DTOs de banco

Aplicar rigor extremo ali gera abstração artificial.

Object Calisthenics brilha em:

• Domínio rico
• Lógica de negócio
• Regras complexas
• Sistemas que vivem muitos anos

O Verdadeiro Valor

Object Calisthenics não é sobre OO.

É sobre:

• Coesão
• Encapsulamento
• Redução de acoplamento
• Fluxos simples
• Modelagem intencional

Go não impõe arquitetura.

Ele expõe seu design.

E isso é perigoso.

Porque você pode escrever código simples… ou simplesmente simplista.

Conclusão

Aplicar as 9 regras ao mesmo tempo em produção pode ser exagero.

Mas praticá-las:

• Em refatorações
• Em projetos paralelos
• Em código crítico

Treina seu cérebro para enxergar problemas antes deles virarem dívida técnica.

Design em Go não é sobre herança. Não é sobre frameworks. Não é sobre patterns da moda.

É sobre disciplina. E disciplina não é imposta pela linguagem. É escolhida pelo desenvolvedor.

Na Harmo, usamos Object Calisthenics como disciplina de modelagem para manter nosso domínio coeso, explícito e sustentável ao longo do tempo.

golang/go

Introdução

Se você perguntar para três desenvolvedores se Go é uma linguagem Orientada a Objetos (OO), você provavelmente receberá quatro respostas diferentes. Uns dirão que é procedural “com esteroides”, outros que é funcional por causa das funções de primeira classe, e alguns defenderão que é OO purista.

Sempre gosto de dizer que a melhor linguagem é que resolverá o seu problema da melhor forma.

A verdade? Go é o que você precisa que ela seja, mas ela odeia burocracia (isso que me fez amar desde cedo).

Mas a realidade é mais sofisticada. Segundo o FAQ oficial do Go: “Sim e não”. Go é OO, mas não da forma que você aprendeu na faculdade. Vamos entender os pilares da OO sob a ótica de um Gopher.

O que Go NÃO tem (e por que isso confunde)

Para quem vem do Java ou C#, a falta de certos pilares pode parecer estranha:

• Não existem classes: Temos structs;
• Não existe herança: Você não pode fazer uma struct Dog extends Animal;
• Não existe polimorfismo de subtipo: Esqueça as hierarquias complexas.

O que Go TEM (A alma da OO)

Se definirmos OO como “objetos que encapsulam estado e expõem comportamento”, Go é absolutamente OO:

• Encapsulamento: Usamos maiúsculas e minúsculas para exportar (ou não) campos e funções;
• Métodos: Você pode pendurar métodos em qualquer tipo, não só em structs;
• Interfaces (O superpoder): Em Go, as interfaces são satisfeitas implicitamente. Se algo “caminha como um pato”, ele é um pato. Não precisa de implements.

O veredito: Composição sobre Herança

Tenho um artigo antigo onde explico a diferença entre Herança e Composição.

Sobre o Veredito: Go é Orientada a Objetos?

Se você define OO como hierarquias de classes e herança de tipos, então não. Mas, se você define OO como um paradigma que permite:

• Encapsular estado;
• Definir comportamento (métodos) para tipos;
• Usar polimorfismo (interfaces).

Então Go é uma das linguagens OO mais pragmáticas e eficientes que existem. Ela remove a “cerimônia” e foca na composição, o que evita o famoso problema da “fronteira frágil” em sistemas grandes.

Go força você a usar composição. Em vez de dizer que um Gerente é um Funcionario, em Go dizemos que um Gerente contém um Funcionario. É uma mudança de mindset que gera códigos mais flexíveis e fáceis de testar.

Exemplos

1. Encapsulamento: O poder das iniciais

Em linguagens tradicionais, usamos public, private e protected. Em Go, o encapsulamento é resolvido no nível do package através da capitalização.

• Inicia com Maiúscula: Exportado (Público);
• Inicia com Minúscula: Não exportado (Privado ao package).

package account

type CheckingAccount struct {
  Owner  string  // Público
  balance float64 // Privado: ninguém fora do package 'account' altera o saldo direto
}

// NewCheckingAccount é o nosso "Construtor"
func NewCheckingAccount(owner string) *CheckingAccount {
  return &CheckingAccount{Owner: owner, balance: 0}
}

// Deposit é um método (comportamento)
func (c *CheckingAccount) Deposit(amount float64) {
  if amount > 0 {
    c.balance += amount
  }
}

2. Métodos em qualquer lugar

Diferente do Java, onde métodos pertencem a classes, em Go você pode adicionar comportamento a qualquer tipo definido no seu package. Isso é OO puro: associar dado ao comportamento.

type Celsius float64

// Adicionando comportamento a um tipo primitivo (float64)
func (c Celsius) IsFreezing() bool {
  return c <= 0
}

func main() {
  temp := Celsius(25.5)
  fmt.Println(temp.IsFreezing()) // false
}

3. Adeus Herança, Olá Composição

Este é o ponto onde muitos desenvolvedores “travam”. Go não permite que uma struct herde campos e métodos de outra. Em vez disso, usamos Struct Embedding (composição).

Em vez de dizer que um Gerente é um Funcionario, dizemos que um Gerente contém um Funcionario.

type User struct {
  Name  string
  Email string
}

func (u User) Label() string {
  return fmt.Sprintf("%s (%s)", u.Name, u.Email)
}

type Admin struct {
  User  // Embedding: Admin "ganha" os campos e métodos de User
  Level int
}

func main() {
  a := Admin{
      User:  User{Name: "Alice", Email: "alice@dev.com"},
      Level: 1,
  }
  
  // Podemos acessar Label() direto em 'a' como se fosse dele
  fmt.Println(a.Label()) 
}

4.Interfaces: O Polimorfismo Implícito

O maior trunfo do Go é a interface. Em C#, você precisa declarar class Pato: IPato. Em Go, se a sua struct tem os métodos que uma interface pede, ela automaticamente satisfaz a interface.

Isso é chamado de Structural Typing (ou Duck Typing estático).

type Speaker interface {
    Speak() string
}

type Dog struct{}
type Robot struct{}

func (d Dog) Speak() string { 
  return "Au Au!" 
}

func (r Robot) Speak() string {
  return "Beep Boop!" 
}

// Esta função não sabe (nem se importa) o que é um Dog ou Robot
func MakeItSpeak(s Speaker) {
  fmt.Println(s.Speak())
}

O que vem a seguir?

Agora que entendemos que Go favorece a composição e o desacoplamento, como aplicamos regras rígidas de design para manter esse código limpo? No próximo artigo, vamos explorar o Object Calisthenics aplicado ao Go.

Mas, você já pode dar uma lida sobre, neste artigo do mestre Elton Minetto sobre o assunto: Como melhorar seus códigos usando Object Calisthenics

Conclusão

Go é uma linguagem multiparadigma que abraça a simplicidade. Ela pega o melhor da OO (interfaces e encapsulamento) e joga fora o pior (hierarquias de herança profundas).

Introdução

A maioria das linguagens modernas prometem produtividade, mas poucas realmente entregam isso na prática sem depender de plugins, frameworks adicionais ou configurações complexas. Com Go, a história é diferente. Programo em Go desde a versão 1.7, e lá já tínhamos alguns recursos nativos, inclusive o próprio pprof. E atualmente, logo após instalar a linguagem, você descobre que não ganhou apenas um compilador, mas também um ecossistema completo de ferramentas, projetado para reduzir atrito, eliminar decisões desnecessárias e permitir que times construam software robusto com muito menos esforço.

Foi justamente isso que me fez perceber por que Go se tornou a base de projetos gigantes como Kubernetes, Docker, Etcd, Terraform e tantos outros sistemas críticos: a linguagem é simples, mas o tooling nativo é extraordinariamente poderoso.

E entre todas essas ferramentas, uma mega importante (que comentei no inicio), existe e poucos desenvolvedores exploram a fundo, mas que deveria ser usada diariamente em aplicações que buscam alta performance: o pprof, o profiler nativo capaz de revelar CPU hotspots, consumo real de memória, leaks, disputas entre goroutines, blocagens, mutexes e tudo que realmente importa em sistemas concorrentes.

Este artigo explora justamente isso: como o tooling nativo do Go multiplica produtividade desde o primeiro dia, e como o profiling com pprof te permite evoluir sua aplicação com decisões baseadas em evidência, não em achismo. Além, de passar por outras toolchains nativas que ajudam na produtividade.

Por que o tooling nativo do Go?

O Tooling nativo do Go é um divisor de águas para a produtividade, mas como usar o poder do profiling para ir além?

Quando falamos sobre Go, é comum destacar sua simplicidade, velocidade de compilação e facilidade de manutenção. Mas, depois de anos trabalhando com a linguagem, percebi que o verdadeiro diferencial não é apenas a sintaxe minimalista: é o ecossistema de ferramentas nativas que vêm embutidas no próprio Go.

Enquanto outras linguagens dependem fortemente de bibliotecas externas para tarefas essenciais, como: formatação, análise estática, testes, gestão de dependências, segurança. Go entrega tudo isso sem você instalar absolutamente nada além da linguagem.

E isso muda o jogo.

profiling nativo

Você pode ter código limpo, testes robustos e dependências organizadas, mas sem medir performance, qualquer otimização é chute e mero achismo. É aí que entra o santo graal do ecossistema Go:

pprof: profiling nativo de CPU, memória, goroutines e mais

O Go inclui um profiler completo, extremamente eficiente e simples de usar. Nada de instalar libs ou plugins. Basta importar um pacote e rodar seu app.

Mas, vamos por partes.

O que você pode medir com o pprof?

Com o profiler nativo, você consegue extrair insights críticos:

• CPU: quais funções consomem mais processamento;
• Memória: onde está o maior volume de alocações;
• Goroutines: leaks e explosão de concorrência;
• Blocagem: contenção de mutexes;
• Heap / stack: entender crescimento ao longo do tempo;
• Latência: registrar delays inesperados no fluxo.

Tudo isso com overhead extremamente baixo, adequado inclusive para produção.

Como utilizar o profiling

Para extrair o máximo de dados da sua aplicação é muito simples.

1. Habilitar endpoint de profiling no servidor

O pprof já vem com um servidor HTTP pronto. Fiz um código com diversos problemas para validarmos.

package main

import (
	"log"
	"math/rand"
	"net/http"
	_ "net/http/pprof"
	"time"
)

func workCPU() {
	for {
		// Simula um cálculo pesado
		x := 0
		for i := 0; i < 5_000_000; i++ {
			x += rand.Intn(10)
		}
		_ = x
	}
}

func workMemory() {
	var store [][]byte
	for {
		// Aloca memória aleatória \o/
		b := make([]byte, rand.Intn(5_000_00))
		store = append(store, b)

		// Limpando de tempo em tepo, para mudar o padrão de alocação
		if len(store) > 50 {
			store = store[:0]
		}

		time.Sleep(50 * time.Millisecond)
	}
}

func workGoroutines() {
	for {
		go func() {
			time.Sleep(100 * time.Millisecond)
		}()
		time.Sleep(10 * time.Millisecond)
	}
}

func main() {
	// Inicia o servidor pprof
	go func() {
		log.Println("pprof ativo em :6060")
		log.Println("Acesse: http://localhost:6060/debug/pprof/")
		if err := http.ListenAndServe("localhost:6060", nil); err != nil {
			log.Fatal(err)
		}
	}()

	// Carga para gerar perfis reais
	go workCPU()
	go workMemory()
	go workGoroutines()

	// Mantém a aplicação viva
	select {}
}

Após, só acessar: http://localhost:6060/debug/pprof/

Aplicação pprof rodando em :6060

2. Coletar um perfil de CPU

go tool pprof http://localhost:6060/debug/pprof/profile

O Go captura 30s de execuções por padrão. Depois abre um shell interativo onde você pode rodar:

• top
• top -cum
• web (gera um gráfico FlameGraph automático!)

Pra usar o web, você precisa instalar o Graphviz.

Resultado:

O shell interativo após o pprof ter finalizado

Versão WEB com o mapa da aplicação

Você pode fazer isso também:

Memória

go tool pprof http://localhost:6060/debug/pprof/heap

Ideal para:

• identificar alocações frequentes;
• descobrir vazamentos;
• otimizar estruturas de dados.

Goroutines

curl http://localhost:6060/debug/pprof/goroutine?debug=2

Ideal para:

• encontrar deadlocks
• goroutines que nunca finalizam
• fan-outs excessivos

Exemplo mais prático ainda

Imagine que sua função mais crítica está lenta:

func Process() {
  for i := 0; i < 10_000_000; i++ {
    _ = fmt.Sprintf("%d", i)
  }
}

Rodando o profiler:

go tool pprof http://localhost:6060/debug/pprof/profile
(pprof) top

Veremos algo como:

80% runtime.slicebytetostring
15% fmt.(*pp).doPrint
5% sua função

Diagnóstico imediato:

fmt.Sprintf é absurdamente lento para esse caso.

Solução:

• usar strconv.Itoa (100x mais rápido);
• evitar alocações com buffer pré-alocado.

Esse tipo de melhoria só aparece com profiler, dificilmente com “feeling”.

Por que o profiler nativo é tão poderoso?

Porque ele é integrado ao runtime. Ele entende:

• scheduler do Go
• garbage collector
• blocagem de goroutines
• time spent inside syscalls
• concorrência e contenção de locks

Ferramentas externas jamais alcançam esse nível de precisão.

Toolchains nativas que também auxiliam

🧰 O toolchain nativo que multiplica sua produtividade

1. go fmt / gofmt: Formatação automática

• Código sempre consistente;
• Zero debates sobre estilo no time;
• Formatação idempotente e global.

2. go vet: Análise estática poderosa

• Detecta bugs sutis antes mesmo da compilação;
• Erros de Printf, escapes de variáveis, loops suspeitos;
• Evita classes inteiras de falhas silenciosas.

3. go test: Testes, benchmarks e fuzzing

• Framework nativo;
• Sem dependências externas;
• Comando único para testes, -bench para benchmarks, -fuzz para fuzz testing.

4. go mod: Dependências previsíveis

• Cache global;
• Builds reproduzíveis;
• Versionamento semântico respeitado automaticamente.

Quando comecei em Golang, na v1.7 era punk rsrs!

5. govulncheck: Segurança integrada

• Scanner oficial de vulnerabilidades;
• Analisa código e binários;
• Foco em vulnerabilidades reais, não ruído.

Conclusão

Go te entrega uma caixa de ferramentas completa, use tudo.

O Go é rápido, simples e direto. Mas o que realmente o coloca em outro patamar é seu tooling nativo:

• fmt padroniza;
• vet previne;
• test garante;
• mod organiza;
• govulncheck protege;
• pprof evolui seu sistema de verdade.

Se você quer extrair o máximo da linguagem, aprender profiling é obrigatório. Com dois comandos você já está medindo performance de forma profissional:

go tool pprof -http=:8081 cpu.prof
go tool pprof -http=:8082 mem.prof

E você começa a enxergar sua aplicação como ela realmente é e se comporta, não como você imagina.

Se você já utiliza o tooling nativo do Go no dia a dia, principalmente profiling com pprof, compartilhe sua experiência comigo. Quais ferramentas mais aceleram sua produtividade? Que desafios você já resolveu com profiling? Seu ponto de vista enriquece a discussão e ajuda outros desenvolvedores a evoluírem também.

Deixe seu comentário, compartilhe o artigo e vamos continuar construindo software de alta performance juntos. 🚀

Introdução

Nos últimos anos, a forma como construímos e operamos sistemas evoluiu radicalmente (sou do tempo que subiamos arquivos via sFTP). A migração para a nuvem deixou de ser apenas um movimento tecnológico e passou a ser um movimento cultural, que redefine não só onde rodamos software, mas principalmente como pensamos, desenvolvemos, implantamos e mantemos aplicações em produção.

Antes de entrar nas lições práticas sobre operar uma plataforma cloud-native na AWS, é fundamental alinhar dois conceitos que frequentemente são confundidos, mas que definem todo o restante da arquitetura moderna: Cloud e Cloud-Native.

O que é Cloud?

Cloud é um modelo de computação com base no acesso sob demanda a recursos de infraestrutura, armazenamento, redes, dados e serviços gerenciados através da internet.

A nuvem permite:

• provisionar recursos em minutos, não semanas;
• escalar horizontalmente;
• automatizar ambientes inteiros;
• reduzir custos ao pagar só pelo uso;
• acessar serviços avançados sem comprar hardware;
• criar ambientes efêmeros para testes e validação.

Mais importante que isso: a nuvem muda o ritmo da engenharia, possibilitando uma velocidade que seria impossível em ambientes tradicionais.

O que é Cloud-Native?

Cloud-native não significa simplesmente “estar na nuvem”. Significa projetar e operar sistemas que exploram a nuvem ao máximo.

Um sistema cloud-native nasce com:

• elasticidade como padrão,
• resiliência embutida,
• automação de ponta a ponta,
• forte observabilidade,
• implantação contínua,
• componentes desacoplados,
• infraestrutura declarativa,
• e claro, alta tolerância a falhas.

Em outras palavras:

Cloud-native é a combinação de arquitetura, cultura e automação para que sistemas sobrevivam e evoluam em ambientes dinâmicos.

Lições Aprendidas

Construir e operar uma plataforma verdadeiramente cloud-native vai muito além de rodar workloads em containers. Envolve pessoas, processos, arquitetura, governança, automação e uma disciplina contínua de observabilidade.

Nos últimos anos rodando uma stack distribuída na AWS, com EKS, Aurora PostgreSQL, Firehose, Lambda, SQS, OpenSearch, Athena e pipelines de GenAI, aprendemos que o maior desafio não é adotar a nuvem, e sim operacionalizá-la com confiabilidade e custo-eficiência.

Agora, trago as principais lições aprendidas em todo esse processo.

1. Cloud-native não é Kubernetes: é um mindset

Quando migramos nossos primeiros serviços para EKS, fizemos o clássico erro: tratamos Kubernetes como se fosse um datacenter com YAML.

Cloud-native é:

• Elasticidade real
• Efemeridade como padrão
• Observabilidade first-class
• Automação desde o início

A mudança mais impactante não foi a tecnologia, mas sim abandonar o “servidorzão confiável” e abraçar o caos controlado.

2. Observabilidade é o que transforma caos em previsibilidade

Os maiores problemas vieram de falta de visibilidade.

Lições essenciais:

• CloudWatch sozinho não resolve, centralize o máximo possível (aqui usamos OpenSearch)
• Busque correlacionar as requisições via trace_id (microserviço A fala com B, etc)
• Crie SLOs reais com alertas de burn rate
• Sem P95/P99 você está cego

Sem observabilidade, Kubernetes vira aleatoriedade.

PS.: Em outro artigo, falarei como nós fazemos.

3. Custos se gerenciam no código, não no financeiro

A AWS cobra por tudo que movimenta, armazena ou respira. Costumo dizer que AWS escala na mesma proporção que o limite do cartão de crédito.s

Aprendizados:

• O custo real do EKS são os nós, não o cluster
• Aurora cobra caro em I/O (busca usar aurora cluster com I/O otimizado)
• OpenSearch escala a fatura rápido demais
• Firehose precisa de compressão

Estratégias que funcionaram:

• Autoscaling agressivo
• Instâncias Spot (cuidado com interrupções)
• Revisão mensal FinOps

Custos são uma skill técnica.

Busque alinhar o custo da infra com o business.

4. Multi-account é segurança operacional

O modelo multi-account trouxe:

• Limitação de impactos
• Ambientes isolados de verdade
• Controle granular de IAM
• Governança mais previsível

Ambientes independentes tornam incidentes muito menos catastróficos.

5. Deploy contínuo só é bom com rollback contínuo

CI/CD não é sobre deploy rápido, é sobre desfazer rápido.

Práticas essenciais:

• Blue/Green ou Canary (estamos melhorando)
• Feature flags
• Versionamento de configs
• Health checks reais

Um deploy não termina até existir rollback de código, infra e dados.

6. O banco é o coração, mas também é o gargalo

Aurora PostgreSQL é poderoso, mas impõe lições:

• Cuidado com I/O (pode sair muito caro)
• Use BRIN em tabelas largas
• Separe leituras e escritas
• Use cache (Redis) para amenizar instância e I/O

Quando o banco vira gargalo, quase sempre a culpa é sua.

7. Autoscaling só funciona com stateless de verdade

Problemas clássicos:

• Sticky sessions
• Buffers locais
• Operações não idempotentes

Quando a plataforma virou 100% stateless, o HPA finalmente começou a funcionar como esperado.

8. Segurança é atributo do design

Funciona quando:

• IAM é minimizado
• Roles são por serviço
• VPC é segmentada
• Imagens são imutáveis
• Secrets são gerenciados

Segurança não é time; é arquitetura.

9. Testes em produção não são tabus, são obrigatórios

Claro, sempre com responsabilidade:

• Chaos engineering leve
• Canary releases
• Traffic shadowing
• Testes de carga periódicos

Nada simula produção, então teste em produção com método.

10. As maiores lições são humanas

Nada substitui:

• Disciplina de engenharia
• Comunicação clara
• Documentação viva
• Postmortems sem culpados (mas com ações)
• On-call saudável

Ferramentas viram plataforma quando existe cultura.

Conclusão

Rodar uma plataforma cloud-native na AWS é uma jornada contínua.

A tecnologia evolui, os desafios mudam, mas a essência permanece.

Cloud-native não é sobre tecnologia, mas sim sobre resiliência, automação e maturidade de engenharia.

Introdução

Construir uma plataforma cloud-native moderna não depende apenas de Kubernetes, observabilidade e arquitetura distribuída, mas sim de um pipeline de entrega contínua confiável, capaz de compilar, testar, versionar, empacotar e implantar aplicações de forma consistente.

Na Harmo, adotamos um fluxo que conecta:

• GitHub (código + PRs)
• Copilot AI (code-review, refinamento, lint, segurança, padrões)
• CircleCI (build, testes, análise estática, push no ECR)
• AWS ECR (registry de imagens)
• Jenkins (orquestração do deploy)
• Amazon EKS (execução final das aplicações)

Como fazemos

Buscamos ao longo dos anos, um fluxo confiável e robusto de entrega contínua.

1. O dev abre um Pull Request no GitHub.
2. O Copilot AI sugere melhorias de código, segurança, testes e estilo. Além de outras pessoas desenvolvedoras.
3. O PR é revisado com regras rígidas e padronizadas.
4. Ao receber approve, o merge dispara pipelines no CircleCI.
5. O CircleCI:
   • roda testes
   • executa linting
   • builda a imagem Docker
   • faz push no AWS ECR
   • chama o Jenkins via CLI
6. O Jenkins executa o pipeline de deploy:
   • baixa a nova imagem
   • aplica YAML ou roda Helm
   • valida readiness
   • realiza rollback automático se necessário
7. A aplicação é atualizada no EKS.

Resultado: deploys previsíveis, auditáveis e rastreáveis.

Por que CI/CD é um pilar do cloud-native

Cloud-native não significa simplesmente “estar na nuvem"s. Significa projetar e operar sistemas que exploram a nuvem ao máximo. Tendo autonomia e facilidade para entrega contínua de soluções.

Em uma filosofia Cloud-native exige:

• deploys frequentes
• rollback instantâneo
• ambientes efêmeros
• consistência entre ambientes
• imagens imutáveis
• infra em YAML ou Helm
• zero intervenção manual

Na minha visão, sem um pipeline maduro, Kubernetes vira risco, não vantagem.

Visão geral da arquitetura do nosso pipeline

Fluxo completo:

GitHub → Pull Request → Copilot AI → Code Review → Merge → CircleCI → Build Docker → Scan → Push ECR → Trigger Jenkins → Deploy no EKS → Observabilidade

Pontos fundamentais:

• Um PR nunca vira deploy sem revisão humana.
• Toda imagem tem tag semântica + tag por SHA.
• Todo deploy é rastreável até o commit original.

GitHub + Copilot AI: a primeira linha de defesa e automação

O GitHub atua como centro de controle:

✔️ Branching model padrão

• main → produção
• develop → staging (estamos em constante avanço nessa parte)
• branches de feature: feature/nome
• hotfixes controlados por tag

✔️ O Copilot ajuda no PR

Usamos o Copilot para:

• detectar código inseguro
• revisar padrões de estilo
• identificar endpoints sem cobertura
• explicar diffs complexos durante code review

Ele não substitui a revisão humana, mas agiliza muito.

Template de Pull Request (padrão Harmo)

Usamos um PR enxuto, objetivo e baseado em engenharia madura:

## 🔍 Descrição
O que foi alterado? Por quê?

## 🎯 Motivação / Contexto
Qual problema isso resolve?

## 📊 Observabilidade
- [ ] Logs ajustados
- [ ] Métricas adicionadas/alteradas
- [ ] Dashboards/alerts impactados?

## 💰 Impacto em Custos
- [ ] Avaliado (I/O, memória, storage, execuções, banda)

## 🚀 Deploy
Serviço / namespace afetado:

## 🔙 Rollback
Como desfazer? (passo a passo)

CircleCI: build, scan e push para o ECR

Quando o PR é aprovado e mergeado, pipeline CircleCI executa:

• Checkout do código
• Lint + análise estática
• Testes unitários
• Build da imagem Docker

Tag da imagem com:

• versão semântica
• commit SHA
• timestamp
• Push para o AWS ECR

Chamada ao Jenkins:

Temos um repositório interno de CLI, ele é clonado durante o build, e o jenkins é acionado via bash, usando a API do jenkins.

Jenkins: deploy seguro no EKS

O Jenkins recebe o trigger e roda o pipeline de deploy:

• Baixar imagem do ECR
• Edita os arquivos helm
• Atualiza o EKS/pods

Utilizando a flag --atomic, o Helm reverte sozinho se algo falhar.

Rastreabilidade e confiabilidade

Toda versão na produção possui:

• referência ao SHA do commit
• tag exata da imagem
• ambiente, namespace e cluster
• pipeline de origem (CircleCI job ID)
• logs de deploy no Jenkins
• métricas de latência pós-deploy

Isso facilita postmortems (fica pra um próximo artigo), auditorias e diagnósticos.

Benefícios reais

• Deploys rápidos e previsíveis
• Zero intervenção manual
• Menos incidentes
• Versionamento rigoroso
• Segurança reforçada
• Redução drástica de falhas humanas
• Replicabilidade entre ambientes
• Cultura de engenharia madura
• Time mais rápido e com mais confiança

Conclusão

CI/CD não é um acessório, é a coluna vertebral de uma plataforma cloud-native. Sem automação, sem padrões e sem disciplina, Kubernetes se torna uma fábrica de riscos.

Ao integrar GitHub, Copilot, CircleCI, ECR, Jenkins e EKS, criamos um pipeline:

• seguro
• rastreável
• escalável
• automatizado
• de fácil auditoria
• e resiliente a falhas

Esse pipeline permite que a Harmo evolua sua plataforma sem medo de quebrar produção, com velocidade de startup e qualidade de empresa enterprise. s E quais são suas experiências em CI/CD? Compartilha conosco nos comentários.

ClickUp

Introdução

Aqui na Harmo, migramos do Slack para o Discord em 2022. A mudança parecia ideal no início, afinal, conseguimos liberdade, integração com bots e boa performance.
Mas, com o tempo, os desafios de governança, histórico e centralização da informação começaram a pesar. Precisávamos de uma ferramenta que reunisse tudo: chat, tarefas, docs, dashboards e gestão, sem o custo de um carro por mês.

Foi aí que chegamos ao ClickUp. E não, este artigo não é patrocinado 😄, é apenas o relato de quem usa intensamente a ferramenta e descobriu alguns truques úteis, como ativar dicionários personalizados para escrever sem erros (e sem perder o português).

Afinal, sempre uso OS em US.

O ClickUp como central de operações

O ClickUp se posiciona como uma plataforma “tudo-em-um” para produtividade de times.
A ideia é simples: um único lugar para conversar, planejar, fazer calls (isso é muit massa), documentar e acompanhar tudo o que acontece dentro da empresa. Também tendo a opção de conectar tudo isso com modelos LLM.

Na Harmo, usamos o ClickUp como nossa central de operações para praticamente tudo:

• Comunicação assíncrona entre times técnicos e de negócio;
• Reuniões (calls) com o time, sempre com gravação e histórico centralizado;
• Planejamento semanal e roadmaps por área;
• Documentação interna e repositórios de conhecimento;
• Gestão de demandas e integrações automáticas com GitHub, AWS e Google Drive;
• Alertas de engenharia e notificações automáticas (deploys, falhas, métricas);
• Análises semanais com IA, enviadas automaticamente nos canais oficiais de cada área (Suporte, Engenharia,Produto, etc.), trazendo uma retrospectiva visual e interpretável dos principais indicadores.

Mas, ao instalar o aplicativo desktop Linux (o AppImage oficial), percebi um pequeno detalhe: o dicionário de correção automática vem apenas em inglês, e não há um menu visível para adicionar outros idiomas.
Foi o início de uma pequena investigação técnica. Afinal, ele é um Electron rodando a aplicação web 😄.

O problema: autocorreção em inglês

Se você escreve em português dentro do ClickUp, especialmente em docs ou comentários, já deve ter notado:

Tudo fica sublinhado em vermelho, inclusive palavras corretas (pra mim é depressivo isso haha).

Isso acontece porque o aplicativo desktop do ClickUp (assim como muitos Electron apps) usa o dicionário do Chromium embutido, e não herda automaticamente o dicionário do sistema.

Ou seja: mesmo que o seu sistema operacional esteja em português, o ClickUp ignora isso.

A solução: adicionando dicionários manualmente

Depois de algumas horas de experimentos (e erros), chegamos à solução definitiva para o Linux, que também funciona com pequenas variações no Windows e macOS.

🔧 Passo a passo (Linux)

1. Localize a pasta de configuração do ClickUp:

~/.config/ClickUp

2. Crie (ou edite) o arquivo Preferences e adicione a configuração de idioma:

vim ~/.config/ClickUp/Preferences

{
   "migrated_user_scripts_toggle":true,
   "spellcheck":{
      "dictionaries":[
         "en-US",
         "pt-BR"
      ],
      "dictionary":""
   }
}

3. Baixe o dicionário pt-BR para Chromium

No meu caso, só de instalar o pacote do idioma no OS, já funcionou perfeitamente.

4. Reinicie o aplicativo.

Agora o ClickUp reconhecerá automaticamente o novo idioma, e o corretor deixará de marcar todas as palavras em português como erro. E n omeu caso, mantenho o ClickUp em en-US, mas ele consegue validar idioma pt-BR na escrita também.

ClickUp rodando em en-US, validando pt-BR

Valores

Aqui, conseguimos diversos contatos no BR para intermediar as assinaturas, mas como não temos tantas assinaturas (30 no total), resolvemos fazer direto com eles. Pagando o pricing atualizado de assinatura mensal.

Conclusão

Pequenos detalhes fazem grande diferença no dia a dia de times técnicos.
Ao ativar o dicionário correto no ClickUp, eliminamos ruído visual, reduzimos erros em docs e ganhamos agilidade na comunicação escrita, especialmente em empresas com fluxo intenso de documentação, como a Harmo.

Essa configuração simples é um ótimo exemplo de como ajustes técnicos aparentemente pequenos refletem em produtividade e clareza organizacional.

E se você também vive no ecossistema Linux ou busca uma alternativa mais governável ao Slack/Discord, vale explorar o ClickUp com carinho, com dicionário em português e tudo 😄

Node.js

Na Harmo, nosso codebase é bastante diverso. Sempre buscamos equilíbrio entre as linguagens, usando cada uma para aquilo que faz de melhor. Começamos nosso core em Node.js e, desde 2017, evoluímos muito com Golang (desde a versão 1.7). Hoje, também contamos com Python, Vue.js e até shell scripts para infra.

No ecossistema Node.js é comum haver múltiplas formas de resolver o mesmo problema. Por isso, adotamos uma diretriz clara: sempre priorizar o que é nativo, evitando dependências externas desnecessárias. Quando precisamos de algo mais específico, criamos pacotes privados que abstraem essa lógica, garantindo reaproveitamento e segurança.

Dessa forma, para gerir os clients back-end que fazem requisições HTTPS (internas e externas), usamos desde o Node v18 o fetch nativo. Porém, ele não possui uma forma “oficial” de configurar timeout. Vamos ver como contornar isso.

Distribuição das linguagens no codebase da Harmo

Por que usar fetch nativo?

A primeira pergunta que sempre aparece é: “Por que usar algo nativo e contornar essa limitação, se eu posso importar o Axios e setar timeout facilmente?”.

Pontos que pesam a favor do fetch:

• Livre de dependências externas: menos pacotes para atualizar, menos riscos de vulnerabilidades.
• Adoção e padronização: hoje é API estável, padronizada e suportada oficialmente no Node 18+.
• API moderna: suporta streaming, trabalha com Promises e se alinha ao padrão da Web.

Comparativo mais amplo — fetch vs Axios

1. Zero dependências, menos superfície de risco

   • Nada de instalar libs só para HTTP.
   • Menos código de terceiros no deploy, menos CVEs para monitorar.

2. Padrão da Web (WHATWG) e futuro-proof

   • Mesma API usada em navegadores, Deno, Bun, runtimes serverless/edge.
   • Isomórfico: o mesmo código funciona em front e back.

3. Disponível nativamente no Node 18+

   • Já faz parte do runtime, baseado em undici.
   • Suporte a AbortController e AbortSignal.timeout(ms).

4. API moderna e composável

   • Request, Response, Headers padronizados.
   • Composição simples via funções, sem precisar de interceptors acoplados.

5. Performance e simplicidade operacional

   • Menos camadas ⇒ overhead menor.
   • Tree-shaking natural: usa a API do runtime, não importa um bundle extra.

E quando faz sentido usar Axios (ou outra lib)?

Não é sobre “nunca usar Axios”, mas sim começar com fetch e só adicionar uma lib se o caso justificar.

Exemplos em que pode valer a pena:

• Interceptors prontos para logging, métricas ou autenticação.
• Retries/backoff já implementados.
• Serialização automática de params e normalização de erros.
• Ambientes legados (Node < 18).
• Ergonomia de configuração (axios.create, defaults globais, etc.).

Problema de Timeout e helpers

O fetch não tem uma opção timeout nativa no objeto de configuração. Se você não tratar isso, uma requisição pode ficar pendurada indefinidamente, travando fluxo e degradando UX.

Solução 1: AbortController + setTimeout

async function fetchWithTimeout(url, options = {}, timeout = 5000) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeout);

  try {
    return await fetch(url, { ...options, signal: controller.signal });
  } finally {
    clearTimeout(timer);
  }
}

Solução 2: AbortSignal.timeout (mais moderna)

const response = await fetch("https://api.exemplo.com", {
  signal: AbortSignal.timeout(3000),
});

Conclusão

Como trabalhamos com microsserviços e serverless, estamos sempre atualizando nosso codebase e priorizando recursos nativos.

• O fetch nativo deve ser sempre a primeira escolha: leve, padronizado e futuro-proof;
• Timeout não é um problema: com AbortController ou AbortSignal.timeout, você cobre 99% dos cenários;
• Axios e outras libs ainda têm espaço, mas só quando há uma necessidade clara (interceptors complexos, retrys prontos, ergonomia global).

Lições aprendidas

Interessante refletir e analisar cada caso, mas o que sempre buscamos ter aqui é o básico bem feito.

• Comece simples: fetch nativo atende a maioria dos casos;
• Priorize o controle: implemente timeout sempre, mesmo em chamadas internas;
• Reduza dependências: cada pacote a menos significa menos riscos, menos manutenção e menos bugs;
• Crie seus utilitários: pequenos helpers (fetchJson, fetchWithRetry) podem substituir dezenas de linhas de configs em libs externas;
• Padronize no time: uma decisão simples como “usar fetch nativo com helper padrão” já elimina inconsistências e acelera onboarding de devs.

💬 E você, como lida com requisições no Node.js?

Prefere ficar só no fetch nativo ou ainda vê valor em libs como Axios? Deixa sua experiência nos comentários, quero muito ouvir como outros times têm tratado esse tema no dia a dia.

Sempre em busca da melhor versão

Comecei a programar aos 14 anos, tendo um site de streaming de áudio e um servidor de Tibia (vulgo OT Server), na época rodando na versão 8.5. Desde cedo, soluções self-hosted foram parte essencial do meu aprendizado: de protocolos de comunicação até sistemas de auto-gestão.

Isso se estendeu até em uma solução pessoal para gestão de finanças, também self-hosted, feita em PHP. Dá um visu aqui.

Depois de quase dez anos, decidi montar novamente meu próprio home server para centralizar arquivos, ter mais controle e segurança, expandir conhecimentos em infraestrutura e substituir serviços pagos por alternativas self-hosted.

O resultado foi um ambiente poderoso:

• NAS em ZFS (5TB)
• Containers Docker gerenciados via Portainer
• Interface web para gestão dos arquivos
• Acesso externo seguro para serviços e SSH via Cloudflare Tunnel

O que é NAS e por que usar RAID/ZFS?

Antes de mergulhar na prática, vale entender alguns conceitos fundamentais.

📦 O que é NAS?

NAS (Network Attached Storage) é basicamente um servidor de arquivos conectado à rede.

• Funciona como uma central de armazenamento, acessível de qualquer dispositivo (PC, notebook, celular, TV etc).
• Diferente de um HD externo, o NAS está sempre disponível, seja localmente ou pela internet (no nosso caso, via Cloudflare Tunnel).
• É comum em empresas, mas também faz todo sentido em casa, para fotos, vídeos, documentos ou até para hospedar Nextcloud ou Jellyfin/Plex.

🔄 O que é RAID?

RAID (Redundant Array of Independent Disks) combina múltiplos discos em um volume lógico, trazendo:

• Redundância: se um disco falhar, os dados continuam acessíveis.
• Performance: alguns níveis distribuem dados entre discos, acelerando leitura/escrita.

Exemplos:

• RAID 1: espelhamento — dois discos, um copia o outro.
• RAID 5: três ou mais discos, com paridade (suporta falha de 1 disco).
• RAID 6: como o RAID 5, mas suporta falha de até 2 discos.

⚠️ Importante: RAID não substitui backup. Ele apenas protege contra falhas físicas. (aprendi isso da pior forma 😅)

🛡️ E onde entra o ZFS?

O ZFS (Zettabyte File System) combina filesystem + RAID + volume manager em uma só solução.

Ele oferece:

• Integridade de dados: cada bloco tem checksum, evitando corrupções silenciosas.
• Snapshots e clones: restauração rápida de versões anteriores.
• Compressão transparente: economiza espaço automaticamente.
• Escalabilidade: projetado para petabytes de dados (eu sigo com 5TB, por enquanto).

No meu setup, uso ZFS com RAID-Z (semelhante ao RAID 5), que equilibra espaço, performance e tolerância a falhas.

O que é Cloudflare e por que usei no meu Home Server

Quando expomos serviços caseiros na internet, temos duas grandes preocupações:

• Segurança (não deixar a rede vulnerável)
• Praticidade (dispensar configurações complexas de NAT/IP fixo)

É aí que entra o Cloudflare.

🌍 O que é Cloudflare?

O Cloudflare é famoso pelo CDN e proteção contra DDoS, mas também oferece recursos que facilitam o self-hosting, como o Cloudflare Tunnel.

🚇 O que é Cloudflare Tunnel?

O Cloudflare Tunnel cria um túnel seguro entre meu servidor e a rede Cloudflare.

Benefícios:

• Nada de abrir portas no roteador
• Não preciso de IP fixo
• Meus serviços ficam acessíveis via domínio com HTTPS válido automático

Exemplo prático:

• https://files.seudominio.com → File Browser (porta 8080)
• https://portainer.seudominio.com → Portainer (porta 9443)

Tudo isso sem precisar configurar NGINX ou Let’s Encrypt manualmente.

🎯 Por que escolhi o Cloudflare?

• Facilidade: poucos comandos e já estava acessível.
• Segurança: tráfego criptografado fim a fim.
• Custo baixo: plano gratuito cobre bem (o Tunnel avançado custa ~US$10/mês).
• Escalabilidade: novos serviços são só uma linha no config.yml.

Setup

Server com AMD-A8-5600k, 16GB RAM e NAS 5TB

🖥️ Servidor

• CPU: AMD-A8-5600k
• RAM: 16 GB
• NAS: pool ZFS de múltiplos HDs (5 TB)
• SO: Ubuntu Server 24.10

Os HDs estão ligados via gaveta hot-swap, e não diretamente à placa-mãe.

Vantagens:

• 🔄 Troca rápida de discos defeituosos
• 📦 Expansão simples (basta adicionar novo HD)
• 🛡️ Perfeito para ZFS/RAID, com reconstrução automática (resilver)

NAS com gavetas hot-swap

⚡ Gestão de energia

Para mitigar quedas de energia, configurei:

• Gerador: 3.75 kVA 3000W
• Nobreak SMS Lite 1200VA (~6h autonomia)
• Nobreak SMS NET 4+ 1400VA (~8h autonomia)

💰 Custo de eletricidade

No meu caso:

• Idle/leve: 80–120 W
• Carga moderada: 150–200 W

Em média, gasto R$ 60–110/mês, dependendo da carga e da tarifa.

Arquitetura

Arquitetura do Home Server

🔍 Como funciona o fluxo

1. Usuário → acessa pelo navegador
2. Internet → tráfego normal pela rede pública
3. Cloudflare Tunnel → cria ponte segura sem NAT/IP fixo
4. Servidor (Ubuntu 24.10) → roda Docker + ZFS
5. NAS (ZFS Pool) → armazena dados com redundância e snapshots

✅ Benefícios

• Segurança: IP residencial não exposto
• Flexibilidade: qualquer container pode virar subdomínio
• Resiliência: ZFS garante integridade dos dados
• Simplicidade: acesso com domínio e SSL válido

💡 Dicas

🔐 Segurança

• Ative o fail2ban para proteger o SSH:

  sudo apt install fail2ban -y
  sudo systemctl enable fail2ban
  sudo systemctl start fail2ban
  

  Configuração básica:

  [sshd]
  enabled = true
  port    = ssh
  filter  = sshd
  logpath = /var/log/auth.log
  maxretry = 5
  

• Use chave SSH em vez de senha.
• Cloudflare Access (opcional): autenticação em duas etapas para subdomínios.

⚡ Eficiência energética

• Configure spindown para HDs pouco usados.
• Ajuste CPU para modo powersave.

🛡️ Resiliência

• Rode zpool scrub periodicamente.
• Configure snapshots automáticos no ZFS.
• Backup externo continua essencial.

🧩 Automação

• Configure o cloudflared para iniciar no boot.
• Centralize logs dos containers via Portainer.

✅ Conclusão

Montar esse home server foi mais do que um exercício técnico: foi uma forma de ter controle total dos meus dados, aprendendo tecnologias enterprise como ZFS, Docker e Cloudflare Tunnel no meu próprio ambiente.

Hoje centralizo arquivos, rodo containers em produção pessoal e acesso tudo de forma segura e simples pela internet, sem depender de serviços pagos ou limitados.

Existem desafios (manutenção, energia, configuração), mas o ganho em flexibilidade e aprendizado compensa. E o melhor: é facilmente expansível — seja com mais HDs no ZFS, novos containers ou serviços como Nextcloud e Jellyfin.

No fim, percebi que um NAS caseiro pode ser tão poderoso quanto soluções comerciais, com a liberdade de adaptar às minhas necessidades. 🚀

👉 E você, montaria o seu próprio servidor ou prefere uma solução pronta? Comenta aí!

🏊‍♂️🚴‍♂️🏃‍♂️ “Good dream is a dream lived” — Avelino, Thiago

📌 Changelog

• 2025-08-10 → Versão inicial do setup publicada

Ao longo da minha jornada como CTO da Harmo, mentor na ACATE e avaliador de startups no MIDITEC, percebi um padrão recorrente: times tecnicamente fortes enfrentando desafios estratégicos por falta de direcionamento claro. Em um mercado cada vez mais acelerado, tomar decisões técnicas sem contexto, profundidade ou visão de negócio pode custar caro, e isso me motivou a criar um espaço dedicado para ajudar quem está nesse momento decisivo.

Essa não é uma consultoria genérica. É algo premium, pensado para founders, tech leads e CTOs que não podem errar. Aqui, o foco é destravar gargalos reais com experiência prática, análise estratégica e conversas que vão direto ao ponto. Se você sente que chegou a hora de elevar seu produto, stack ou time técnico a um novo nível, essa pode ser a parceria que estava faltando.

E, por que decidi oferecer consultoria técnica?

Nos últimos anos, à frente da Harmo como CTO e Co-fundador, estive no centro de decisões críticas que impactaram diretamente o crescimento e a escalabilidade do nosso produto, decisões que envolvem arquitetura distribuída, engenharia de dados, IA aplicada e liderança técnica de alto nível.

Percebi que, embora existam muitos conteúdos técnicos por aí, são raros os momentos em que fundadores e times conseguem parar e conversar com alguém que vive esses desafios na prática, todos os dias. Alguém que, além da teoria, entende as implicações reais de uma escolha técnica no negócio. Foi isso que me motivou a abrir espaço na agenda para uma consultoria premium, direcionada, com propósito claro: destravar o que está travando você e sua operação.

Ao longo da minha jornada, fui construindo essa autoridade com consistência. Sou mentor na ACATE (Associação Catarinense de Tecnologia), participo de bancas e acelerações no programa MIDITEC, um dos mais tradicionais do Brasil, e atuo como CTO de uma plataforma AI-first que processa milhões de dados por dia. Além de 15+ anos de experiência, sou formado em Ciência de Dados e tenho pós-graduação em Estatística Aplicada, o que me permite aliar visão estratégica e profundidade técnica com decisões orientadas por dados, sempre com foco em impacto.

Para quem é essa consultoria?

Essa consultoria não é para quem busca fórmulas prontas ou implementações genéricas. Ela é pensada para quem está lidando com problemas reais, complexos e inadiáveis, como escalabilidade, gargalos técnicos, dúvidas arquiteturais, uso de IA com responsabilidade ou times que precisam evoluir com mais direção.

Ela é ideal para:

• Fundadores e CTOs que precisam tomar decisões críticas com segurança
• Tech leads que buscam validar caminhos técnicos e destravar o roadmap
• Startups que estão escalando rápido e precisam de um olhar externo experiente
• Times que querem implementar IA, dados ou LLMs com base sólida e visão de produto

Como funciona?

As consultorias são pagas, premium e personalizadas. Cada sessão é pensada para gerar resultado direto: mais clareza, melhores decisões e menos tempo perdido com dúvidas técnicas que te afastam daquilo que realmente importa.

💬 Não trabalho com fórmulas. Trabalho com contexto. 🔎 Cada caso é analisado com profundidade, sem pressa, mas com objetividade. ⚠️ Vagas limitadas, minha agenda permite apenas alguns atendimentos por mês. 📍 Vagas limitadas, apenas para quem valoriza profundidade e excelência.

👉 Saiba mais e solicite sua sessão: consultoria.rifeli.dev

Gerenciar um time técnico em constante evolução exige mais do que domínio de ferramentas: exige clareza de propósito, boas decisões arquiteturais e foco no que realmente gera valor para o negócio. Como CTO e Co-fundador da Harmo, essa é a lente pela qual enxergo tecnologia todos os dias.

Tive a honra de compartilhar um pouco dessa jornada na newsletter Mais Que Senior, em uma entrevista conduzida com sensibilidade e profundidade por um grande amigo, Elton Minetto. Falamos sobre liderança técnica, decisões estratégicas, dicas de carreira e trajetória.

Neste artigo, aprofundo alguns dos pontos abordados na entrevista, detalhando nossa stack, práticas e aprendizados práticos que sustentam a operação diária da Harmo. Se você lidera times técnicos, atua com cloud ou busca boas práticas em arquitetura e gestão de infraestrutura, essa leitura é pra você.

Conte um pouco sobre sua posição atual, como CTO. Que tipo de trabalho você faz geralmente?

Sou CTO e Co-fundador da Harmo, uma plataforma Martech AI-first que transforma feedbacks e dados operacionais em decisões inteligentes. Minha atuação é dividida entre frentes estratégicas e operacionais (cerca de 60/40), com foco em tecnologia, produto e dados.

Co-lidero a arquitetura de sistemas e lidero diretamente três especialistas, incluindo um Tech Manager que conduz o time de engenharia, atualmente com sete profissionais de diferentes níveis. Acompanho de perto o roadmap de produto e continuo atuando com código, especialmente em Golang, Python e aplicações de IA, áreas em que tenho mais profundidade.

Também estou à frente da integração de LLMs, IA generativa e pipelines de dados em larga escala. E sigo como revisor técnico ativo: nossa média gira em torno de 50 pull-requests por sprint, com cerca de 60 microsserviços em produção, rodando em K8s e Airflow.

Que tipo de impacto você sente que mais gera na sua posição atual? E como isso é diferente em relação a sua posição anterior?

Hoje meu impacto é sistêmico: construo os alicerces técnicos que permitem escalar o negócio com inteligência e sustentabilidade. Diferente de posições anteriores, onde o foco era na entrega individual, agora meu papel é potencializar a performance do time como um todo, garantindo alinhamento entre tecnologia, produto e estratégia.

Qual é o percentual de trabalho entre código e liderança que você desempenha hoje? 50/50? Passa mais tempo trabalhando com tecnologia/codando ou mais tempo liderando pessoas? Hoje minha atuação está quase equilibrada, com cerca de 40% dedicada ao código e 60% voltada à liderança. Sigo atuando tecnicamente por afinidade e por necessidade, especialmente nas frentes de IA, NLP e arquiteturas de dados mais complexas, mas meu foco principal está nas decisões estratégicas, no acompanhamento próximo dos times e na estruturação de processos técnicos que sustentem nosso crescimento.

Como é um dia normal na sua rotina? Ou como é uma semana normal para você? Quais são suas rotinas principais?

Minhas semanas são marcadas por cerimônias técnicas, revisões de arquitetura, mentorias, revisões de código e bastante atividade prática, sigo codando em frentes estratégicas, especialmente em features e arquiteturas voltadas a NLP, IA, LangChain e ML.

Reservo blocos de tempo para deep work técnico e acompanhamento próximo do roadmap de produto e dados. Também mantenho cadências com os especialistas do time, garantindo fluidez técnica, alinhamento com o negócio e evolução contínua da equipe.

Além disso, tenho rotinas regulares com os demais sócios, conselheiros e investidores, equilibrando a visão técnica com a visão de negócio e crescimento da empresa.

Como você mede seu sucesso? Quando somos pessoas desenvolvedoras de software é comum medirmos nosso sucesso pelo número de commits, pull requests, entregas realizadas. Isso mudou de alguma forma em sua posição atual?

Sim, mudou bastante. Mesmo no inicio de carreira, já buscava enxergar sucesso além de horas trabalhadas, commits ou linhas de código, mas foi com o tempo e com a experiência que essa visão amadureceu.

Antes, eu media meu sucesso por entregas concretas: features lançadas, melhorias de performance, soluções técnicas. Hoje, minha métrica é o impacto técnico e estratégico que consigo gerar: a performance do time, a sustentabilidade das decisões de arquitetura, a velocidade de aprendizado da organização e, principalmente, o valor que a tecnologia entrega para o negócio. Além, de avaliar o impacto em custos vs crescimento comercial.

Você participa das decisões de tecnologia ou arquitetura? Como gerencia essa influência em relação aos demais times? Você toma boa parte das decisões ou guia os times para que eles cheguem às conclusões?

Sim, participo ativamente das decisões de tecnologia e arquitetura. Costumo guiar o time em discussões técnicas, sempre priorizando debates estruturados e incentivando o ownership das decisões. Evito ser o gargalo ou o “dono da verdade”, busco atuar como facilitador, tomando decisões quando necessário, mas sempre com base em construção coletiva.

Mesmo com o crescimento exponencial do negócio, acredito que a visão estratégica precisa estar presente também no nível técnico. É essa presença que garante que as decisões do dia a dia estejam alinhadas com nossa bússola de médio-longo prazo.

Que soft-skills você percebe que fazem a diferença na sua posição? E como eles diferem da posição anterior? Costumo enxergar habilidades técnicas ou comportamentais em dois grupos: as treináveis e as que vêm de forma mais natural. Me esforço para desenvolver continuamente as treináveis que geram impacto direto no negócio, mas também aprendi a valorizar e canalizar as que já fazem parte do meu perfil, como criatividade e empatia.

Com a maturidade profissional e como empreendedor, percebi que as soft-skills passaram a ter um papel central. As que mais fazem diferença para mim hoje são: escuta ativa, clareza e objetividade na comunicação, gestão de conflitos e leitura de cenário. Antes, meu foco era resolver problemas técnicos diretamente. Hoje, minha principal missão é criar os contextos certos para que outras pessoas consigam resolver com excelência, e isso exige inteligência relacional e liderança com propósito.

Você dedica tempo para mentorar as demais pessoas dos times?

Sim, e considero isso uma das partes mais gratificantes do papel de liderança. No dia a dia, as mentorias acontecem de forma natural, nos rituais, revisões técnicas e discussões de arquitetura. Além disso, mantenho momentos dedicados de 1:1 com os especialistas e apoio diretamente profissionais mais plenos e juniores, incentivando tanto o desenvolvimento técnico quanto o comportamental.

Acredito que as mentorias aceleram o amadurecimento técnico, cultural e emocional do time. Sou alguém que gosta de aprender, ensinar e trocar constantemente. Para mim, o verdadeiro motor da evolução é o exemplo, e liderar pelo exemplo é o que mais inspira e transforma.

Como CTO em algum momento a empresa começa a crescer e é necessário tomar uma decisão entre a parte técnica e as demais demandas de negócio/gestão. Como você está se preparando para esse momento de decisão? Você se imagina seguindo pelo caminho técnico ou de gestão/negócio?

Me vejo em uma posição híbrida, com forte raiz técnica e visão estratégica. Gosto de construir, resolver problemas complexos, transformar dados em decisões inteligentes e estruturar times de alta performance. Mesmo com o crescimento da Harmo, meu objetivo é seguir como uma liderança técnica que conecta engenharia ao negócio e impulsiona inovação com propósito.

Acredito que escalar também é saber colaborar. Por isso, visualizo uma parceria próxima com alguém na cadeira de VP de Engenharia, permitindo que eu mantenha o foco em arquitetura, IA e visão de produto, enquanto garantimos excelência na operação e na gestão do time.

Que dicas você pode dar para quem está decidindo se continua o caminho de desenvolvimento ou se deve empreender?

Comecei a empreender aos 21 anos, após mais de cinco anos de carreira como desenvolvedor. O que aprendi até aqui é que não existe uma resposta certa ou um único caminho para o sucesso, mas sim autoconhecimento, consistência e coragem para se adaptar em cenários diversos.

Se você gosta de resolver problemas complexos com profundidade técnica, talvez o caminho de especialista seja o mais natural, e é totalmente possível crescer nessa trilha sem ir para a gestão. Se, por outro lado, você se interessa por liderar pessoas, estruturar times e facilitar o crescimento de outros, a trilha de gestão pode ser muito recompensadora. Deixando claro, que até mesmo um especialista, precisará ensinar e ser referência para outras pessoas e áreas.

Já a questão de empreender, exige um perfil diferente: é preciso ter visão de longo prazo, capacidade de lidar com incertezas, adaptação constante, apetite a risco e resiliência para errar e aprender rápido. Se você sente prazer em transformar problemas reais com tecnologia, não tem medo de sair da zona de conforto e quer gerar impacto direto, empreender pode ser um caminho transformador.

Minha dica é: teste, se observe e não tenha medo de mudar de rota (erre rápido e mude rápido). Já vi excelentes devs virarem grandes líderes, líderes voltarem a se especializar e até mesmo especialistas fundarem empresas de sucesso. O mais importante é ser intencional com seus passos.

Você lembra de algum conselho ou dica que recebeu quando entrou nesta posição e que foi importante para você?

Venho de uma cultura afro-indígena e, desde muito cedo, aprendi a ser meu próprio líder e a valorizar quem trilhou caminhos antes de mim. Isso moldou minha visão sobre liderança e me ajudou a entender que meu foco natural sempre foi a parte técnica e estratégica.

Ao assumir a cadeira de CTO, tomei uma decisão importante: treinei uma pessoa sênior com perfil de governança para assumir a liderança direta do time, cuidando da gestão de pessoas, carreira e cultura. Isso me permitiu atuar com mais profundidade técnica e arquitetural, onde realmente gero valor.

Um conselho que me marcou, e ainda guia minha trajetória, foi:

“Você não vai escalar se tentar ser o melhor em tudo. Foque em criar contextos para que outras pessoas brilhem.”

Essa frase consolidou minha transição de desenvolvedor para uma cadeira executiva com consciência e propósito.

Quais fontes você usa para se especializar? Blogs, livros, canais do Youtube.

Comecei a estudar computação em 2008 e programar em 2010, aos 14 anos. Desde então, desenvolvi um perfil autodidata forte. Me aprofundo por meio de blogs técnicos (como Medium, Towards Data Science, dev.to e ByteByteGo), papers acadêmicos, documentação oficial e livros técnicos, especialmente nas áreas de arquitetura, dados e IA. Também acompanho canais no YouTube focados em engenharia de dados e exatas (matemática/estatística). Além disso, valorizo muito trocar experiências com profissionais da área, e busco ativamente conversas para benchmarking e aprendizado contínuo.

Onde as pessoas podem te encontrar? Site, Linkedin, Twitter, etc.

Sou acessível e ativo pelo LinkedIn, e também mantenho um blog técnico onde compartilho experiências com IA, golang, python, arquitetura distribuída e dados.

E-mail Blog LinkedIn

Veja a entrevista na newsletter: maisquesenior.dev

Em ambientes modernos de produção, como o nosso na Harmo, gerenciar clusters Kubernetes de forma eficiente e segura é essencial. Utilizamos o Amazon EKS como nossa base de orquestração, e para operações diárias: observabilidade, debug, troubleshooting e deploys, utilizamos principalmente duas ferramentas: Lens e k9s.

Neste artigo, explico como estruturamos nosso acesso, como usamos essas ferramentas no dia a dia e quais os benefícios que elas trazem para nosso time técnico.

Visão geral da arquitetura

• Clusters gerenciados no Amazon EKS, com múltiplos ambientes (dev, staging, prod);
• Acesso via aws eks update-kubeconfig com autenticação via IAM;
• Configuração de kubeconfig versionado por ambiente;
• Monitoramento integrado via Prometheus e Grafana (externos ao artigo, mas conectados ao Lens via plugins).

Por que usamos Lens e k9s

O uso se dá de acordo com a sua necessidade, eu particularmente, prefiro o k9s pela praticidade de não sair do terminal.

Alias úteis para k9s por ambiente

É possível facilitar o dia a dia com alguns alias no teu bash profile.

# ~/.bashrc ou ~/.zshrc

alias k9s-dev="k9s --context harmo-dev"
alias k9s-prod="k9s --context harmo-prod"
alias k9s-stg="k9s --context harmo-staging"

# Também pode abrir com namespace já definido:
alias k9s-namespace="k9s --context {context-name} -n {namespace-name}"

Exemplo do k9s:

Exemplo do Lens:

Benefícios reais no dia a dia

• Time técnico é mais produtivo: reduz o uso de kubectl manual;
• Integração visual com Lens facilita aprendizado para novos devs;
• CLI do k9s é absurdamente rápida para alterações pequenas;
• Observabilidade aumentada (com plugins como Prometheus no Lens).

Cuidados e boas práticas

• Nunca salve kubeconfigs sensíveis localmente sem proteção;
• Mantenha o acesso IAM dos clusters restrito;
• Revogue acessos inativos ou não rotacionados;
• Versione e audite permissões RBAC com clareza.

Conclusão

O uso combinado de Lens e k9s transformou a forma como operamos nossos clusters no EKS. Ganhamos velocidade, confiabilidade e uma visão muito mais clara do ambiente. Recomendo fortemente essas ferramentas, principalmente quando combinadas com boas práticas de segurança e governança nos clusters.

As pessoas que gostam do meio tecnológico, acabam esbarrando neste assunto, um conceito que existe antes dos anos 1970 - como deixar agendado a execução de taferas com SQL em minha base de dados?

A ideia aqui, é trazer informações sobre agendamento de tarefas no AWS RDS Aurora Cluster com PostgreSQL.

Em muitas aplicações, é comum a necessidade de executar tarefas recorrentes: limpar dados antigos, atualizar tabelas derivadas ou enviar notificações. Em servidores tradicionais, usamos o cron, um agendador de tarefas do sistema operacional, para executar esses processos de forma automática.

Desde 2021, conseguimos fazer isso de forma nativa, sem precisar criar nenhuma estrutura adicional, como Lambdas, EC2 e/ou EventBridge.

Neste artigo, mostro como ativar o pg_cron, criar tarefas agendadas e compartilhar dicas práticas para usar cronjobs diretamente no RDS Aurora PostgreSQL.

O que é cronjob

Um cronjob é uma tarefa que roda automaticamente em horários definidos. É muito usado para tarefas recorrentes como backup, limpeza de dados e/ou geração de relatórios.

Em ambientes Linux, cron é um agendador de processos do sistema. Mas em bancos PostgreSQL com pg_cron, conseguimos usar sintaxe semelhante ao crontab, com agendamento diretamente via comandos SQL, o que possibilita deixarmos queries agendadas, sem a necessidade do uso de máquinas+triggers.

Como funciona

Desde a versão 12.5 é possível fazer de forma nativa no RDS Aurora PostgreSQL (antes a gente contornava com evento e lambda). Ou seja, é nativo e permite definir jobs que executam comandos SQL com agendamento cron (ex: todo dia às 2h). Um detalhe importante é que no RDS Aurora, ele roda no mesmo nó primário da instância, então não exige infraestrutura adicional.

Cenários

O recurso de cron pode ser utilizado em diversos cenários, principalmente com rotinas na base.

• Limpeza de dados antigos (data retention);
• Geração de relatórios periódicos;
• Atualização de dados derivativos ou caches (ex REFRESH MATERIALIZED VIEW);
• Detecção de anomalias ou padrões incomuns (agendar análise estatística e salvar alertas);
• Manutenção preventiva (como REINDEX e VACUUM).

Como habilitar

Pra usar o recurso cron em seu cluster RDS Aurora PostgreSQL, segue alguns pontos:

• A versão dele precisa ser 12.5+ (se for menos, tu tem um problemão haha);
• Validar se o parâmetro shared_preload_libraries contém pg_cron (via parameter group do banco);
• Ativar a extensão, como user principal da base, rode CREATE EXTENSION IF NOT EXISTS pg_cron;;
• Criar suas crons e ser feliz \o/.

Pra criar as suas crons, é muito simples:

SELECT cron.schedule(
  'cleanup_old_data', -- name
  '0 2 * * *', -- crontab config (aqui roda 2am)
  $$DELETE FROM logs WHERE created_at < NOW() - interval '30 days'$$ -- query
);

Pra gerenciar suas crons, basta validar o que tem: SELECT * FROM cron.job; e pra desativar SELECT cron.unschedule(jobid);

🔐 Alguns cuidados

Como sempre, nem tudo são flores, segue alguns avisos para você ficar alerta:

• O pg_cron executa jobs com o mesmo privilégio do usuário que os criou;
• Jobs falham silenciosamente se houver erro de permissão;
• Ele só roda no nó primário, não em réplicas;
• Monitore uso de CPU/memória caso agende jobs pesados.

Conclusão

A extensão pg_cron transforma o RDS Aurora PostgreSQL em um banco ainda mais poderoso, permitindo automação direta, sem precisar de infraestrutura externa. É ideal para tarefas periódicas como limpeza de dados, atualização de caches e envio de notificações.

Diz aí, tá usando cron nativo e otimizando recurso de infra?

Headings

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Emphasis

Emphasis, aka italics, with asterisks or underscores. Strong emphasis, aka bold, with asterisks or underscores. Combined emphasis with asterisks and underscores. Strikethrough with two tildes. Bold and nested italic. All bold and italic. Bold and italic nested.

Images

Lists

Ordered:

1. First ordered list item
2. Another item
3. Actual numbers don’t matter, just that it’s a number
   1. 1st.
   2. 2nd.
   3. 3rd.

Unordered:

• This is a list item
  • This is a nested list item
    • This is a nested list item
  • This is another list item
• This is another list item

Task:

• Write the press release
• Update the website
• Contact the media