Os materiais dos vídeos, completos e nesta página

Como eu sei que a minha operação de IA custou US$ 8,64 em 12.438 chamadas — e como você monta a sua numa tarde

De graça, sem cadastro. Copia, roda, adapta. Se te servir, o crédito é seu.

Companheira do vídeo "O modelo caro não digita". Tudo aqui saiu de consulta rodada, log lido ou página oficial de fornecedor. Onde não havia contador, eu digo que não havia — inclusive quando isso joga contra mim.

Para quem é: quem opera IA em produção (não demo) e não consegue responder "quanto isso custa por mês, e por etapa?" sem chutar.

1 · A régua antes dos números: status de fonte

Nada entra na tabela sem carimbo. É a única parte disto que importa mesmo — os números são meus, o método é seu.

A regra que faz isso funcionar: ALEGADO não vira MEDIDO com o tempo. Ou você tem o contador hoje, ou o número não existe. Repetir cinco vezes numa reunião não promove um número.

2 · A consulta

O custo real não está no painel do fornecedor — está no seu banco, se você registrar cada chamada. Uma linha por chamada, com etapa, modelo e custo. A partir daí:

SELECT workflow, count(*), sum(cost_usd)
FROM llm_usage
WHERE created_at > now() - interval '30 days'
GROUP BY workflow
ORDER BY sum(cost_usd) DESC;

Se você não tem a tabela llm_usage, esse é o trabalho da tarde — não a migração de modelo. Sem ela, qualquer decisão de custo é preço de tabela, e preço de tabela é o que o fornecedor cobra, não o que a sua operação gasta.

3 · A minha conta, aberta

Sistema meu em produção que classifica documentos. Sem nome de cliente, sem setor: o custo é da minha operação, não dado de negócio de ninguém.

A escada — a parte que interessa

198 chamadas custam mais que 9.005. E é exatamente o que tem que acontecer: 9 mil das 12 mil chamadas nunca chegam perto do modelo caro. O barato filtra volume, o forte decide o que sobrou.

Como ler a sua: o total não diz nada. O formato diz tudo. Se o seu custo unitário for parecido entre as etapas, você não tem arquitetura — tem um modelo só fazendo tudo, e está pagando preço de julgamento por trabalho de digitação.

Efeito medido de mexer na etapa certa (subir a triagem para um modelo mais forte, não trocar tudo): 84 → 48 aprovados de 99, e 8 → 0 falsos positivos de alta prioridade. Metade do trabalho a jusante desapareceu — e isso não aparece na conta de tokens.

Comparação direta que eu tenho, com a ressalva junto: a mesma análise completa saiu por US$ 0,00881 no modelo aberto contra US$ 0,01666 no americano equivalente — 1,9×. ⚠️ n = 143 de um lado, 5 do outro. Cinco é pouco. Eu não vou fingir que não é.

4 · Qual modelo em qual camada

Bateria controlada: 3 cenários (bug fix · refatoração · feature por TDD) × 3 modelos, fixtures isoladas, verificada por um agente que não executou nada.

Resultado da bateria: 12 agentes · 9/9 suítes verdes · 9/9 checksums intactos (ninguém adulterou o teste pra fazer passar) · 0 retentativas. RE-MEDIDO 3 dias depois, no servidor: 9/9 verdes, 60 asserções. O código continuava de pé.

O dado que mais me convenceu: o cenário mais difícil — feature por TDD — saiu com nota 9,5 usando 26.733 tokens de entrada, 45% a menos que o executor rápido e 40% a menos que o revisor. Modelo melhor não é o que pensa mais; é o que precisa reler menos.

A falha do rápido, literal: não tratou hífen na borda da string. Não é "alucinação". É bug de borda, do tipo que teste pega. É por isso que a régua é o comando, não a impressão.

5 · O que quebra (e o que eu tive que refutar)

Esta seção é o motivo de a tabela ser confiável. Se a sua não tem uma, ela é folder.

• ❌ REFUTADO — "existe um teto de ~2,7 KB no briefing". Já foi item desta tabela. Caiu: travou com 1.860 bytes também, e 4 briefings dentro da faixa "segura" não entregaram. As três ocorrências de exit=124 foram com 3.404, 2.304 e 1.860 bytes — a variável não era o tamanho.
• Memória, não tamanho: mortes com 0,77 GB e 0,41 GB livres; entrega com 3,3 GB. E o contra-exemplo honesto: um caso mudo com 2,8 GB livres. Correlação, não lei. Na mesma amostra: 5.378 MB em 27 processos do orquestrador contra 1.312 MB do executor — quem estoura a máquina é a orquestração, não o modelo que trabalha.
• O gargalo foi o caro, não o barato. A rodada mais ambiciosa — 157 agentes — morreu com 144 de 156 linhas de log dizendo "limite de sessão atingido", do lado do orquestrador. 3 estouros em 3 dias (76, 28 e 4 sessões derrubadas) e 9 tarefas mortas com 0 token — nem começaram.
• O número desconfortável: no dia em que instrumentei tudo e contei de verdade, o executor entregou 1 vez em 11 lançamentos. Os modelos são bons quando rodam. O encanamento em volta deles é que ainda não é confiável. Quem vende isso como "configura e esquece" não rodou o suficiente pra ter apanhado.

6 · Onde o dinheiro realmente estava

Do lado do orquestrador, dentro de um plano fixo: 3,9 milhões de tokens de entrada processados. Por tabela isso seria US$ 1,99 — e eu paguei US$ 9,99.

Eu pago mais caro que o meu próprio consumo, e vale a pena. O que se compra ali não é token: é não ficar sem arquiteto às três da tarde. Quando a cota estourou, até chamada de 50 tokens foi recusada — e aí o custo não é o plano, é o dia parado.

Conclusão que a tabela sustenta e a maioria dos artigos não: a economia não estava em dólar. A conta inteira é US$ 8,64. Migrando tudo, a economia caberia numa moeda. Estava em janela — em não gastar a capacidade do modelo que decide com trabalho que qualquer modelo faz.

7 · O que NÃO entrou nesta tabela, e por quê

A parte que quase ninguém publica, e que é onde a régua prova que funciona:

8 · A sua matriz — 5 passos, uma tarde

1. Crie a linha por chamada. Etapa, modelo, tokens, custo, timestamp. Sem isso, pare aqui: nada do resto é medição.
2. Rode a consulta da §2 e monte a sua escada: chamadas, custo e custo unitário por etapa.
3. Olhe o formato, não o total. Ache a etapa com maior custo unitário e pergunte: quantas dessas chamadas precisavam mesmo de julgamento?
4. Escolha UMA tarefa chata e fechada para descer de camada. Escreva o comando que prova antes de trocar o modelo. Se você não consegue escrever o comando, escolheu a tarefa errada.
5. Rode o comando você — não leia o resumo do agente. Só então traga o modelo caro pra revisar o diff. Quem implementa não aprova.

Modelo em branco

O teste final da sua tabela: se alguém perguntar de onde veio um número e a resposta for "acho que foi de...", esse número é ALEGADO — apague ou vá medir.

Por que eu tenho essa régua

Minerei 784 sessões do meu histórico e auditei 79 casos um a um, procurando por que uma entrega volta. 68,4% do retrabalho tinha uma causa só: declarar pronto sem ter percorrido o caminho. "Entendeu errado o pedido" foi 1,3%.

O gargalo nunca foi compreensão. Era conferência. Numa auditoria minha, 2 de 7 alegações do implementador eram falsas — e verificáveis em um comando. Em outra, o verificador derrubou 6 critérios de aceite vazios, com o laudo literal "o arquivo de teste NÃO EXISTE".

Trocar o caro pelo barato sem a régua não otimiza nada — só troca dólar por retrabalho, que é a moeda mais cara que existe.

9 · O lugar onde isso continua

Se você chegou até aqui, provavelmente vai fazer a coisa mais chata de todas: abrir o terminal e rodar a consulta na sua operação. E aí acontece uma coisa que eu não previ quando montei a minha:

você acha o teu número e não tem com quem falar sobre ele.

Discussão de custo de IA hoje é preço de tabela e opinião. Quase ninguém abre a conta, e quem abre não mostra o que apagou. É por isso que eu tô montando um lugar só com quem opera de verdade — quem tem a tabela, não a opinião. Gente que roda em produção, apanha, mede, e volta com a saída colada.

O que eu não vou fingir que sei: não tem data, não tem preço, não tem formato fechado. Não tem nada pra vender hoje. Tem uma lista — e quem tá nela sabe primeiro quando abrir.

👉 Entrar na lista: https://wa.me/5551993299031?text=lista%20de%20espera É um e-mail. Sem spam, sem sequência de vendas, sem "última chance". Sai quando quiser, em um clique — e se você nunca mais quiser ouvir falar disso, essa página continua no ar de graça do mesmo jeito.

Antes de entrar, faz o que vale mais: roda a consulta da §2 e monta a sua escada. Se ela sair com um formato diferente do meu, é essa conversa que eu quero ter. Quem chega com número entra falando.

Um processo que hoje roda no braço e você acha que dava pra ter um sistema desses? A DM tá aberta — eu abro o sistema e te mostro rodando.

↑ voltar ao índice

O desenho de três camadas que eu uso pra transformar uma pilha de documento público numa fila curta — e as quatro decisões que fazem ele funcionar ou virar teatro

Companheiro do vídeo "Parei de fazer uma IA que lê edital. Fiz uma que descarta." De graça, sem cadastro. Copia o desenho, adapta ao teu domínio, usa.

Para quem é: quem tem muito documento público e pouca gente pra ler — licitação, diário oficial, publicação de órgão regulador, decisão de tribunal, edital de fomento, chamada de compra de empresa grande. É sempre o mesmo problema com outra roupa.

1 · O padrão (não é sobre licitação)

O sistema descrito aqui foi construído para editais, mas o desenho não é sobre editais. Ele resolve uma forma:

muito documento entrando  ·  pouca gente pra ler  ·  decisão cara se errar

Se o teu domínio tem essas três coisas, a anatomia serve. Se falta a terceira — se ninguém perde nada quando o documento passa batido — não construa isso: você vai gastar engenharia para produzir um resumo que ninguém lê.

2 · Por que a solução óbvia quebra

Todo mundo pensa a mesma primeira solução: pega o PDF, joga num modelo, pede um resumo. Três motivos para ela não funcionar — e nenhum é sobre o modelo ser burro:

A virada que muda tudo: pare de tentar fazer uma IA que lê documento. Faça uma IA que descarta documento. O produto não é compreensão — é redução.

3 · A anatomia — três camadas

Camada 1 · Buscar e endireitar

Um coletor passa nas fontes públicas e traz o que é novo. Antes de qualquer inteligência, vem a etapa chata que ninguém posta: transformar o documento em texto de verdade. Imagem vira texto, o que está torto endireita, e o anexo que ninguém abre entra — porque costuma ser onde está o que interessa.

⚠️ Se esta camada falhar, o resto é teatro. O modelo mais caro do mundo não conserta um documento que chegou vazio. Se você só tem orçamento para caprichar em uma camada, é esta.

Camada 2 · O descarte barato — o coração

Tudo que entra passa por uma peneira rápida e barata que responde uma pergunta só:

isso aqui tem alguma chance de ser para este cliente?

Repare na palavra: chance, não certeza. Esta camada é calibrada para ser generosa — na dúvida, deixa passar. É ela que enfrenta o volume, e por isso ela é barata de propósito.

Camada 3 · A leitura cara

O que sobreviveu à peneira vai para a leitura de verdade: o modelo bom, lendo com calma, extraindo o que estão comprando, quanto, até quando, quem pode entrar, o que precisa entregar — e o mais importante: por que isso é para você.

O resultado não é um resumo. É uma fila. Lista ordenada, mais promissor no topo, e do lado de cada item o motivo, em uma frase que um humano entende sem abrir o PDF.

FILA DE HOJE
 1. [ALTA]  ......  porque: o objeto é exatamente o teu item principal e o prazo cabe
 2. [ALTA]  ......  porque: mesma região, valor dentro do teu teto, exige certidão que você tem
 3. [MÉDIA] ......  porque: serve, mas o prazo de entrega é apertado pro teu estoque

Quem fazia isso na mão volta para o jogo: não lê mais o documento inteiro — confere o topo da fila e decide.

4 · As quatro decisões que definem se funciona

Estas quatro valem para qualquer sistema deste tipo. São elas que separam o que roda em produção do que morre na demo.

1 · O gargalo não é o modelo. É o documento.

Passa-se muito mais tempo resolvendo arquivo quebrado, imagem torta e anexo escondido do que ajustando prompt. Quando alguém disser "a IA não funcionou no meu caso", a primeira pergunta é como o dado chegou nela — não qual modelo era.

2 · Existem dois tipos de erro, e eles não custam a mesma coisa.

Por isso o sistema é enviesado de propósito para o lado barato do erro. Isso não é preguiça de engenharia: é a engenharia.

Como levar isso para o teu domínio: escreva, antes de codar, qual dos dois erros é o caro. Se você não souber responder, não sabe ainda o que está construindo.

3 · A régua é do cliente, e tem que ser um documento.

O que faz um edital ser bom para uma empresa não está no modelo — está na cabeça de quem trabalha lá. Então isso vira um arquivo escrito. Quando o critério muda, muda o arquivo, não o código.

Modelo em branco — a régua do cliente:

O QUE A GENTE VENDE (itens/serviços, com sinônimos que aparecem no documento):
ONDE A GENTE ENTREGA (regiões, e o limite real de logística):
O TAMANHO QUE A GENTE AGUENTA (valor mínimo que vale o esforço · máximo que cabe):
O QUE A GENTE NUNCA PEGA (e por quê — isto economiza mais que tudo acima):
EXIGÊNCIAS QUE A GENTE CUMPRE (certidões, atestados, qualificação):
SINAIS DE "É PRA NÓS" (as palavras que quem faz na mão procura primeiro):
SINAIS DE "NÃO É PRA NÓS" (o que faz a pessoa fechar o documento em 5 segundos):

As duas últimas linhas são as que quase ninguém escreve, e são as que mais mudam o resultado. Elas se obtêm de um jeito só: sentando com quem faz o trabalho na mão e perguntando o que ela olha primeiro.

4 · O humano fica no fim, não no meio.

Nada aqui decide sozinho nem envia proposta. O sistema entrega a fila; a pessoa decide. Isso não é limitação técnica esperando conserto — é desenho. Sistema que decide sozinho num domínio onde o erro custa contrato não é mais autônomo: é mais caro.

5 · Onde está a oportunidade (e onde ela não está)

Não está no modelo. Modelo todo mundo tem — é a mesma API para você e para o Vale do Silício.

Está em conhecer o trabalho: saber qual campo daquele documento faz alguém tomar uma decisão, por que o anexo três importa mais que o corpo do edital, o que faz a pessoa descartar em cinco segundos. Isso não está no modelo. Isso se aprende sentando com quem faz o trabalho na mão.

Sem promessa: isso dá trabalho. Não é o que se monta num fim de semana. É um problema real, caro e chato que quase ninguém quer resolver — e é exatamente por isso que quem resolve é pago para isso.

6 · Serve para o meu caso? — 5 perguntas

Responda em voz alta. Se travar em alguma, é ali que o projeto começa (não no código):

1. Quantos documentos entram por dia, e quem lê hoje? (se ninguém lê, você não tem o problema — tem outro)
2. Qual dos dois erros é o caro no seu caso — deixar passar, ou descartar por engano?
3. O que a pessoa que faz na mão olha primeiro? Se você não sabe, essa é a primeira reunião.
4. O critério de "serve pra gente" cabe num documento de uma página? Se não cabe, ele ainda não está claro o bastante para virar sistema.
5. Quem vai receber a fila, e o que ela faz com o item do topo? Fila que ninguém abre é relatório.

7 · O que este documento NÃO te dá

A parte que sustenta o resto:

• Taxa de acerto. O sistema roda e tem feedback de quem usa, mas não houve medição controlada — e sem medição controlada não sai número daqui. Quando houver, ele é publicado com a conta junto.
• O código. Isto é a anatomia e as decisões, não um repositório. O valor está nas decisões: elas sobrevivem à troca de linguagem, de nuvem e de modelo. O código, não.
• Nome de cliente, setor ou volume de contrato. Não é o meu de contar.
• Promessa de prazo. Um sistema desses não nasce em uma sprint, e quem disser que nasce está vendendo a camada 3 sem ter feito a 1.

8 · Se você tem esse problema hoje

Este documento existe para uma coisa: você reconhecer o teu caso aqui dentro.

Se enquanto lia você foi pensando "é exatamente isso que a minha equipe faz na mão" — essa é a conversa. Não é apresentação comercial, não é diagnóstico pago, não é proposta: eu abro o sistema e te mostro rodando, e você decide sozinho se aquilo resolve o teu caso.

👉 Chamar na DM: https://wa.me/5551993299031?text=Vi%20o%20video%20do%20sistema%20de%20licitacao 20 minutos, sem compromisso. Leve a resposta da pergunta 2 da §6 (qual erro é o caro) — com ela a conversa começa no lugar certo em vez de gastar a primeira metade em contexto.

E se você é dev e quer construir: o desenho está inteiro aí em cima, de graça. Constrói. A porta está pouco disputada, e ninguém precisa pedir licença para resolver um problema público.

↑ voltar ao índice

O protocolo de três carimbos e as três perguntas que uma notícia tem que passar pra entrar no Radar — com a lista das fontes que eu leio toda semana

Companheiro da série Radar IA. De graça, sem cadastro. É o método, não a opinião — use com as suas fontes.

Para quem é: quem opera alguma coisa com IA e precisa decidir o que fazer na segunda de manhã, não acompanhar hype. E para quem já repassou uma notícia que virou pó no dia seguinte.

1 · O problema: quase toda notícia de IA que você lê é sobre outra notícia

A cadeia costuma ser esta:

o fato  →  relatório de quem apurou  →  reportagem sobre o relatório
        →  post sobre a reportagem  →  thread sobre o post  →  você

Cada elo perde precisão e ganha certeza. O número fica mais redondo, a ressalva some, o "segundo pessoas com conhecimento do assunto" vira "a empresa confirmou". No fim, quem repassa está mais confiante que quem apurou.

O protocolo não resolve isso ficando cético com tudo. Resolve carimbando onde você parou.

2 · Os três carimbos

Todo item recebe um, e o carimbo muda o que você tem direito de dizer:

A regra que faz isso funcionar: o carimbo não melhora com o tempo nem com repetição. Uma notícia SECUNDÁRIA não vira PRIMÁRIA porque três canais repetiram — vira PRIMÁRIA quando você abre a fonte original. Enquanto não abrir, ela fica onde está.

O teste de honestidade: se alguém perguntar "você leu o relatório?" e a resposta for "li quem leu", o carimbo é SECUNDÁRIA. Dizer isso em voz alta custa três segundos e é a diferença entre analista e repetidor.

Duas armadilhas que os carimbos pegam

3 · As três perguntas (o filtro)

Carimbo diz o que a notícia é. As perguntas dizem se ela entra:

1. O que exatamente aconteceu, e quando?

Se você não consegue dizer o fato em uma frase com data, não é notícia — é clima. Item com mais de uma semana normalmente já é análise, e análise tem outra régua.

2. Qual a fonte, e qual carimbo ela leva?

Sem fonte nomeada e carimbo, não entra. Não importa quantas pessoas repassaram.

3. O que muda para quem opera?

A pergunta que reprova mais gente. Se a resposta é "mostra pra onde o mercado tá indo", é reprovação: isso serve para conversa, não para decisão. A resposta boa cabe numa ação de segunda de manhã — trocar isso, isolar aquilo, medir esse custo, parar de fazer aquilo.

Se a notícia passa em 1 e 2 mas falha na 3, ela não é ruim — ela é de outra pessoa. Deixe passar sem culpa. Quem publica tudo que é verdadeiro publica ruído com procedência.

4 · Onde eu leio (a lista, não o segredo)

Não há fonte secreta. O que existe é ordem de leitura:

Como montar a sua em uma tarde: liste as ferramentas que você realmente opera. Para cada uma, ache a página oficial de mudanças. Isso é a camada 1 — e ela é mais de metade do valor. Só depois acrescente as outras.

O que eu não uso como fonte: thread sem link para a origem, blog de empresa do setor citando número redondo sem apuração (quando dois desses se contradizem na primeira conta, os dois saem), e qualquer coisa cuja fonte é "vi por aí".

5 · A ficha (copie e use)

NOTÍCIA:
DATA DO FATO:                         DATA QUE EU LI:
FONTE QUE EU LI (link):
FONTE PRIMÁRIA DO FATO:               EU ABRI? ( ) sim ( ) não
CARIMBO:  ( ) PRIMÁRIA  ( ) SECUNDÁRIA  ( ) REPORTADO
NÚMEROS (só os que estão literais na fonte):
RESSALVA QUE VAI JUNTO DO NÚMERO:
------------------------------------------------------------
O QUE MUDA PRA QUEM OPERA (uma ação de segunda de manhã):
SE ESTA LINHA FICAR VAZIA, A NOTÍCIA NÃO ENTRA.

6 · O que este protocolo não faz

• Não te dá razão numa discussão. Ele te dá o direito de dizer o que você diz — que é outra coisa, e mais útil.
• Não prevê nada. Sem previsão: comenta-se o que aconteceu e o que fazer amanhã de manhã.
• Não substitui ler a fonte. Ele só torna óbvio quando você não leu.
• Não te protege de errar. Protege de errar com confiança — que é o erro caro.

7 · O lugar onde isso continua

Rodar este protocolo sozinho tem um efeito colateral: você começa a ver o carimbo faltando em todo lugar — e não tem com quem falar sobre isso sem parecer chato.

É por isso que eu tô montando um lugar fechado só com quem opera de verdade — gente que lê o model card, que confere o número, que diz "isso é reportado" antes de repassar.

Não tem data, não tem preço, não tem nada pra vender hoje. Tem uma lista — e quem tá nela sabe primeiro quando abrir.

👉 Entrar na lista: https://wa.me/5551993299031?text=lista%20de%20espera É um e-mail. Sem spam, sem sequência de vendas. Sai quando quiser, em um clique — e esta página continua aqui de graça do mesmo jeito.

E o mais barato que você pode fazer agora: pega a última notícia de IA que você repassou e preenche a ficha da §5. Se a linha do "o que muda pra quem opera" ficar vazia, você acabou de descobrir por que ninguém respondeu.

↑ voltar ao índice

O gate em cinco passos que impede uma sessão de apagar o que a outra acabou de colocar no ar

A regra serve em qualquer stack. Os comandos são os das ferramentas mais comuns — confira a saída na sua antes de confiar (§3)

De graça, sem cadastro. Copia, adapta, cola no teu repositório. Se te servir, o crédito é teu.

Companheiro do vídeo "6 clobbers em 4 dias". Isto aqui é o procedimento que rodou na minha operação depois de seis deploys-por-cima em quatro dias no mesmo serviço — um serviço, em container. A pergunta de cada passo vale para qualquer deploy; os comandos você traduz para a sua casa, e o §3 diz exatamente como.

Para quem é: quem tem mais de uma sessão de agente (ou mais de uma pessoa) mexendo no mesmo repositório com deploy independente. Se é você e mais ninguém, guarda para quando não for.

1 · A regra, em uma linha

A checagem é na IMAGEM QUE ESTÁ NO AR. Nunca no seu branch.

Antes de construir qualquer coisa, a pergunta não é "meu código está pronto?". É: "o que está rodando agora — e o que eu vou apagar dele?"

Por que a sua ferramenta não te avisa:

As quatro são cegas para a mesma coisa: a diferença entre o seu branch e o binário no ar. (As três primeiras estão medidas no caso; a quarta é a mesma cegueira, um passo adiante.) O deploy é uma cópia congelada do repositório num instante — depois do build ela é um objeto independente, e o git não tem ponteiro para ela.

2 · A sentinela — o que você vai procurar

Sentinela é uma string única, curta e improvável, que só existe se uma funcionalidade estiver dentro do artefato. É o que transforma "eu acho que está lá" em grep.

Uma boa sentinela é:

• única no repositório (grep -rc retorna poucas ocorrências);
• textual e literal — sobrevive a build, minificação parcial, empacotamento;
• estável — não muda a cada release (nada de timestamp, hash ou número de build).

Serve como sentinela: o caminho de uma rota nova (/relatorios/mensal) · o texto de um botão · o nome de uma coluna ou de um campo novo · o identificador de uma migração · uma chave de tradução · o nome de uma função exportada.

Não serve: número de versão (muda sempre) · nome de arquivo (pode ser renomeado no build) · comentário de código (some na minificação) · nada que exista em duas features diferentes.

🔑 A regra que faz isso funcionar no dia a dia: quem entrega uma funcionalidade declara a sentinela dela em um arquivo do repositório. Uma linha por funcionalidade, append-only. Sem isso, o passo 2 vira arqueologia. Com isso, vira grep.

# SENTINELAS.md — append-only. Linha nova no fim, nunca reescreve.
2026-08-27 · relatório mensal   · sentinela: "relatorios/mensal"     · sessão A
2026-08-27 · exportar CSV       · sentinela: "exportar-csv-v2"       · sessão B

3 · O GATE — cinco passos, sempre nesta ordem

Passo 1 · Descubra o que está no ar (o que o servidor responde, não o que você acha)

Você quer o identificador exato da versão em execução agora. Não o painel, não o log do último deploy, não o histórico do git — os três te contam uma história sobre o que está no ar.

⚠️ A tag latest (ou main, ou prod) não é resposta. Ela é um apelido: aponta para coisas diferentes em momentos diferentes. Só o digest/hash identifica o artefato.

Passo 2 · Abra o artefato, não o repositório

Procure dentro do que está no ar a sentinela da funcionalidade mais recente que não é sua.

# 1) qual imagem está REALMENTE no ar (o digest, não a tag)
docker inspect <CONTAINER>          --format '{{.Image}}'            # host único
docker service inspect <SERVICO>    --format '{{.Spec.TaskTemplate.ContainerSpec.Image}}'
kubectl get pod <POD> -o jsonpath='{.status.containerStatuses[0].imageID}'

# 2) inspeciona o artefato no ar sem subir nada
docker run --rm --entrypoint sh <IMAGEM_NO_AR_COM_DIGEST> \
  -c 'grep -rl "<SENTINELA>" /app || echo "AUSENTE"'

# padrão bundle estático — o que o usuário realmente baixa
curl -s https://<HOST>/<BUNDLE_QUE_O_INDEX_APONTA>.js | grep -c "<SENTINELA>"

# padrão diretório servido
grep -rl "<SENTINELA>" <DIR_SERVIDO_NO_HOST> || echo "AUSENTE"

Não achou a sentinela do outro no que está no ar? Então ou ela nunca subiu, ou já foi clobbada antes de você chegar. Nos dois casos: descobre antes de continuar.

⚠️ Sobre os comandos deste documento: são a tradução da regra para as ferramentas mais comuns, escritos pelo padrão documentado de cada uma. Confira a saída na sua stack antes de confiar. O que é obrigatório é a pergunta — o comando é só o jeito de fazê-la na sua casa.

Passo 3 · Faça a mesma busca no que você vai subir

Mesmo comando, no seu artefato candidato (construa localmente, não publique ainda).

Agora você tem duas listas. A diferença entre elas não é um relatório — é literalmente a lista do que você vai apagar.

NO AR:      relatorios/mensal · exportar-csv-v2 · webhook-pagamento
CANDIDATO:  relatorios/mensal ·                   webhook-pagamento · painel-metricas
                               ^^^^^^^^^^^^^^^^
                               você está prestes a apagar isto

Passo 4 · Se falta alguma coisa, PARA

Este é o passo que todo mundo pula, e é o único que impede o acidente.

1. Não construa a versão final. Não publique.
2. Traga o que está no ar para o seu lado (fetch + rebase/merge, ou o equivalente na sua casa).
3. Se o que está no ar não existe no repositório (alguém publicou a partir de um branch que nunca foi integrado) — pare de verdade e resolva isso com quem publicou. Esse é o caso grave: existe código servindo usuário que ninguém tem.
4. Volte ao passo 1. O mundo pode ter mudado enquanto você resolvia.

Passo 5 · Depois de subir, prove as duas

A sua sentinela respondendo no ar. E a do outro respondendo no ar. As duas.

for S in "<SUA_SENTINELA>" "<SENTINELA_DO_OUTRO>"; do
  curl -sf "https://<HOST>/<ROTA_QUE_PROVA>" | grep -q "$S" \
    && echo "OK   $S" || echo "FALTA $S  <-- CLOBBER"
done

Se você conferiu só a sua, você não sabe que não clobbou. Você está torcendo.

4 · A parte que decide se o gate funciona: ele é uma PARADA

O erro que produziu os seis clobbers foi encadear:

build && push && deploy      # ❌ numa linha só não existe lugar para parar

Um gate encadeado com && não é um gate — é um comentário. O procedimento tem que ter um ponto em que a coisa não continua sozinha:

./gate-anticlobber.sh || exit 1   # ✅ falhou = não constrói, não publica
build && push && deploy

Se você automatizar uma coisa só deste runbook, automatize isto: o script que compara as duas listas do passo 3 e retorna diferente de zero quando falta sentinela. Ele cabe em quinze linhas e é a diferença entre o método existir no papel e existir na prática.

5 · As três práticas-irmãs (baratas, e nenhuma substitui o gate)

1. Worktree isolada por sessão. Cada agente numa cópia própria do repositório. Não impede o clobber no deploy — impede duas sessões brigando pelo mesmo diretório e uma salvando por cima do arquivo da outra em disco.
2. Decisão em arquivo append-only. Decisão entra no fim e não se reescreve. Antes de decidir, lê o que já foi decidido. É o que evita a sessão três desfazer o que a sessão um decidiu. (O SENTINELAS.md do §2 é o mesmo padrão aplicado a deploy.)
3. Verificação independente. Quem implementa não aprova. Outra sessão, com a tarefa de achar defeito, olha antes de a coisa ser declarada pronta.

6 · O que este gate não faz (declarado, porque é o que o torna confiável)

• O que foi medido: neste caso, na minha operação — quem seguiu o gate não clobbou nenhuma vez; quem encadeou o deploy sem parar, clobbou; depois do gate obrigatório, zero recorrência.
• O que isso não é: promessa de que erro acaba. Nenhum processo elimina erro. Este gate elimina uma classe de erro: subir por cima do trabalho que já está no ar sem saber que está.
• Onde ele não alcança: conflito de dados (duas migrações incompatíveis no mesmo banco) é outro problema, com outra solução. Este runbook cuida do artefato.
• Onde ele falha se você relaxar: sentinela mal escolhida (aparece em duas features, ou some no build) faz o passo 2 dar falso verde. Teste a sentinela uma vez, no artefato, antes de confiar nela.
• Não é sobre modelo ser bom ou ruim. Duas sessões fizeram tudo certo do ponto de vista delas. O defeito é de processo. Dois humanos com a mesma disciplina chegariam ao mesmo lugar — a IA só fecha o ciclo mais rápido, e de novo, enquanto você está almoçando.

7 · A ficha do gate (copie para o seu repositório)

GATE ANTI-CLOBBER — <serviço> — <data/hora> — <quem está subindo>

[ ] 1. Versão no ar (digest/hash, não a tag): ______________________
       Como eu perguntei: ______________________________________

[ ] 2. Sentinelas encontradas DENTRO do artefato no ar:
       ______________________________________________________

[ ] 3. Sentinelas dentro do MEU candidato:
       ______________________________________________________
       DIFERENÇA (o que eu apagaria): ___________________________

[ ] 4. Se a diferença não está vazia → PAREI, integrei, voltei ao passo 1.
       Integrei o quê: __________________________________________

[ ] 5. Pós-deploy, respondendo no ar:
       [ ] minha sentinela      [ ] sentinela do outro

Assinatura da sessão: ____________   Resultado: (  ) subiu  (  ) parou no gate

Guarde as fichas. Duas semanas delas te dizem, sem discussão, quem encadeia deploy e onde o processo vaza.

8 · O buraco que este runbook não fecha sozinho

O passo 4 diz "resolva isso com quem publicou". E aí está o problema real de quem opera assim: quase ninguém tem com quem resolver. Rodar duas, cinco, oitenta sessões de agente no mesmo repositório é uma prática tão nova que o teu colega de trabalho provavelmente ainda não passou por isto — e o pessoal que passou está espalhado, cada um descobrindo sozinho o mesmo buraco.

Eu estou montando um lugar só com quem opera de verdade: gente com agente em produção, com deploy de verdade, com cliente do outro lado. Não tem data, não tem preço, não tem nada para vender hoje. Tem uma lista de espera no fim desta página — um e-mail, e você sai quando quiser.

👉 https://wa.me/5551993299031?text=lista%20de%20espera

Este runbook é completo sem a lista. Quem só quer o procedimento leva o procedimento — está tudo certo assim.

↑ voltar ao índice