DEV Community: Tiago Vilas Boas (Montanha)

Como o Sentry passou a mostrar o funil. A jornada antes do stacktrace

Tiago Vilas Boas (Montanha) — Tue, 15 Sep 2026 16:05:39 +0000

Pessoal, o SDK tava verde. Chegava TypeError. Eu não sabia se era o pagar, o cupom ou o pixel.

Dashboard cheio. Três stacks iguais. A próxima pessoa abria o evento e ia pro arquivo no bundle.

O denso do +10% no checkout é o dinheiro. Este texto é o recorte que faz o Sentry falar a mesma língua: a ação da pessoa, não o SDK.

O ponto é: se o filtro não nomeia o passo, você instalou. Não instrumentou.

Tabela de Conteúdo

1. Sintoma: o tracker gritava, o funil não
2. Causa: instalar não é instrumentar
3. O que mudou: jornada no evento, não só a stack
4. Como eu medi: o filtro da próxima pessoa
5. Resultado: o filtro passou a ser a jornada
6. O que copiar no próximo alerta

1. Sintoma: o tracker gritava, o funil não

O SDK tava instalado. Volume de evento subia. Ninguém decidia.

Um TypeError em massa, sem domínio e sem a ação, só prova que o JS quebrou. Não prova se o comprador estava no pagar, no cupom ou no pixel que nem deveria derrubar o checkout. O filtro no Discover era o arquivo minificado. Não era a jornada.

Produto olhava conversão. Engenharia olhava stack. Os dois boards não se falavam. Timeout na hora de pagar e pixel quebrado depois da venda viravam o mesmo card.

2. Causa: instalar não é instrumentar

Auto-instrumentation pega HTTP, crash, às vezes replay. Não pega “a pessoa apertou pagar e o request nem saiu”. Esse é o furo do denso: timeout no first load, catch silencioso, UI genérica, back sem request.

Catch que só faz console.error: a tela mostra “tente de novo”, o gateway nem foi chamado, o Sentry não vê. Você instalou. Não instrumentou.

Não é pitch de vendor. Grafana, Sentry, Datadog: a ferramenta é o adapter. O domínio emite o evento. Se a regra de cupom importa Sentry.captureException no meio do if, você inverteu. A regra não deveria saber o nome da ferramenta.

Form incompleto, cupom expirado, cartão recusado: a regra funcionou. Breadcrumb. Não incidente. Se misturar com gateway 500, o board grita e você trata recusa de cartão como queda de conversão.

3. O que mudou: jornada no evento, não só a stack

Eu parei de mandar stack nua. Passei a mandar a ação.

Quatro campos. Não uma taxonomia de 40 tags:

domain: checkout, payment, lead, pixel
phase: a ação (coupon.apply, payment.updateCard, checkout.pay.submit)
tipo: exception vs resultado de negócio
sem user_id em label de métrica (explode cardinalidade)

IDs de pedido e de pessoa: log e trace. Não série do Prometheus.

Alerta de sintoma de usuário: o pagar não completa. Não cada if da regra de desconto. Replay, se existir, no caminho curto do dinheiro. Admin longo não precisa da mesma cota.

Exemplo sintético, de propósito. Dois eventos iguais na stack:

A  extra.phase = checkout.pay.submit     → o POST de pagar nem saiu
B  extra.phase = pixel.purchase.track    → o pixel quebrou depois da venda

A é receita em risco. B é ruído com a venda já feita. Sem phase, os dois viram o mesmo card. Com phase, o Sentry nomeia o passo. Aí dá pra olhar o mesmo funil que o painel.

4. Como eu medi: o filtro da próxima pessoa

A prova não é “temos Sentry”. É: a próxima pessoa filtra a ação do usuário antes de abrir o stacktrace.

Cola no Discover. Sintético, de propósito. Sem org, sem issue ID:

extra.phase:checkout.pay.submit AND (
  error.type:TimeoutError OR message:*timeout* OR mechanism:*timeout*
)

O teste: a próxima pessoa vê o pagar. Não o arquivo minificado. Pixel depois da venda é outro phase (pixel.purchase.track). Se os dois caem no mesmo card, você instalou. Não instrumentou.

No Datadog, se o caminho até o JS saturava. No backoffice, se vendeu. Lighthouse fora dessa conta: lab.

Se o alerta não cabe numa frase (“o pagar não completa”), ainda é volume. Não é funil.

5. Resultado: o filtro passou a ser a jornada

Eu não fechei o +10% neste texto. Fechei se a próxima pessoa filtrava checkout.pay.submit antes de abrir o arquivo minificado.

Quando dava, timeout de pagar e conversão do mês apontavam pro mesmo lugar. Quando não dava, o painel subia e o Sentry gritava pixel.

O JS chegar a tempo está no denso. Aqui o contrato é só este: o timeout aparece no mesmo dia, no recorte que o passo entende.

6. O que copiar no próximo alerta

1. O último evento tem domain + phase, ou só a stack?
2. Dá pra nomear a ação do usuário em uma frase?
3. Exception ou resultado de negócio (cupom, recusa, form)?
4. O alerta é sintoma de usuário (pagar não completa) ou qualquer JS?
5. user_id foi pra log/trace, ou virou label de métrica?
6. Esse recorte conversa com conversão, ou só com o board de erro?

Último alerta que você abriu: consegue nomear a ação do usuário em uma frase? Sim, não, ou só o stack?

+10% de conversão no checkout no mês. A campanha quebrava na hora de pagar

Tiago Vilas Boas (Montanha) — Tue, 15 Sep 2026 16:05:38 +0000

Pessoal, tinha campanha de influenciador no ar. Eu abria o Sentry e via timeout. O canal falava de Lighthouse.

Checkout de infoproduto, alto volume, micro frontend. O link saía, o pico chegava junto, e o passo de pagar transbordava. A sessão morria. No dia seguinte o painel caía e a conversa era score. Ou Nuxt.

Aí o backoffice do cliente fechou o mês. +10% de conversão. Pico nessas campanhas. Métrica de venda, cruzada com o que eu via no Sentry (jornada de pagar) e no Datadog (o caminho até o arquivo). O JS chegou a tempo. O timeout apareceu no mesmo dia.

O ponto é: o Lighthouse verde não pagou. O POST de pagar, sim.

Um limite só: não tenho o print do Lighthouse daquela janela no arquivo público. O +10% veio do painel.

Como etiquetar o Sentry pra isso não virar TypeError órfão fica no complementar. Aqui é o dinheiro.

Tabela de Conteúdo

1. Sintoma: a campanha quebrava na hora de pagar
2. Causa: o MFE baixava o time inteiro
3. O que mudou: SSR, JS sob demanda, CDN
4. Como eu medi: quatro lentes
5. Resultado: +10% no mês
6. O que copiar no próximo PR

1. Sintoma: a campanha quebrava na hora de pagar

Checkout de infoproduto no organic é uma fila educada. Na campanha de influenciador não é. O link sai, o pico chega junto, e o passo de pagar ou aguenta o first load ou transborda.

Timeout, pra mim, era o browser não terminar o trabalho a tempo. A pessoa já tinha escolhido o produto. Muitas vezes o pixel de view já tinha ido. Faltava o POST de pagamento. Se o JS daquele passo ainda tava puxando o mundo, a sessão morria. O backoffice nem via a tentativa. No dia seguinte alguém falava “a campanha foi ruim”.

Transbordo é o irmão: origem fria, fila, saturação, bundle grande demais pro celular na 4G. Os dois matam a mesma linha do painel.

No canal a resposta fácil era stack. Vue 3, Nuxt, Lighthouse verde. Eu fiz isso também. Nenhum desses, sozinho, prova que vendeu. O Lighthouse roda no lab, no cabo, num CPU que não é o do comprador no horário da live.

Se o teu checkout só dói no organic, o bundle inchado passa. Dói quando o influenciador manda o link.

2. Causa: o MFE baixava o time inteiro

O checkout era um micro frontend. Vários times, várias fatias, um único caminho de pagamento. Isso é bom pra merge. Time de cupom não espera time de pixel. MFE resolve deploy. Não resolve o que o celular baixa nos primeiros dois segundos.

O que rolava: o host puxava o shell e, se ninguém olhasse o grafo, cada fatia trazia o que era dela e um pedaço do vizinho. Runtime duplicado. Pixel. Upsell. Modal. Às vezes um resto de área logada. O comprador, no passo de pagar, baixava isso antes de ver o botão.

SPA seca piora. HTML quase vazio, JS inteiro do MFE, parse, hidrata, aí o botão existe. No Wi-Fi do escritório passa. Na live, no celular, é timeout.

Pra mim a conta virou uma frase só: o passo atual baixa o JS do passo atual. O resto espera o clique.

“A gente tem MFE” descreve o organograma. Não descreve o Network daquele passo. Se você abre o DevTools no pagar e ainda vê chunk de dashboard, o MFE não te salvou. Ele te faturou o first load.

3. O que mudou: SSR, JS sob demanda, CDN

Tinha BFF. Por isso SSR era opção de verdade, não slide. Sem BFF, o browser monta o pagar com vários round-trips e um bundle que hidrata tudo. Com BFF, o servidor já conhece o passo. Dá pra mandar HTML que serve pra pessoa ver preço, meio e botão sem esperar o mundo hidratar.

Foi isso que eu fiz no first paint do crítico. O JS ainda hidrata o que o POST precisa. Não hidrata o dashboard no meio do caminho.

Vue 2 pra Vue 3 / Nuxt 3 entrou aqui. Não porque “a lib nova é mais rápida” no vazio. Porque o legado não entregava SSR e split de verdade no MFE com a mesma facilidade. E eu não virei o checkout inteiro num dia. As rotas que a campanha batia foram pro stack novo. O resto ficou no legado. Roteador de borda decide. Sem big bang.

SSR sozinho não basta. Se a hidratação ainda manda o MFE inteiro, você só adiou o timeout.

Aí entra JavaScript sob demanda. Code splitting é o bundler gerar mais de um arquivo. Lazy load é o browser só pedir o arquivo quando o passo precisa. Os dois andam juntos. Split sem lazy: você ainda baixa os chunks “por precaução”. Lazy sem split de verdade:

const PayStep = () => import('./PayStep.vue')

Se o PayStep.vue no topo importa upsell, chart e admin, o import() é teatro. O chunk do pagar ainda é o mundo.

O teste não é ter import() no PR. É abrir o Network no passo de pagar e não ver o JS do admin. Order bump, meio extra, modal que quase ninguém abre: depois do clique.

Tem um furo irmão: cada fatia do MFE traz o Vue de novo. Você splittou o app e duplicou o runtime.

Onde isso invertia tudo

SSR na tela interna. Bundle único no checkout. O Lighthouse do admin ficava lindo. A campanha caía. A regra que ficou: SSR quando o first paint é pagar. Lazy quando o código só existe depois do clique.

Depois do split, o arquivo ainda precisa chegar. Eu já tinha cortado o JS e o timeout continuava em região. O chunk do PayStep saía longe, ou frio, ou sem compressão.

CDN perto de quem compra. Cache longo no estático com hash no nome. Gzip no que sobrou. Brotli se o edge já tiver, sem religião. Se o lazy sai de origem fria, você não fez lazy load. Fez “espera a origem acordar”. O spinner só mudou de lugar. O POST continua sem sair.

4. Como eu medi: quatro lentes

Eu parei de tratar ferramenta como tese. Trato como pergunta.

O hábito que ficou: no pico, eu abria o Network no pagar antes do Lighthouse. Se tinha chunk de dashboard, o PR de bundle ainda não tinha acabado.

O Sentry pergunta: o timeout foi no pagar, ou foi pixel quebrado depois da venda? Sem a ação do usuário no evento, os dois viram o mesmo TypeError. Aí você trata ruído como incidente, ou trata pagar que não saiu como “JS genérico”. O contrato disso está no outro texto.

O Datadog pergunta: o caminho até o arquivo e até o POST tava saturado? Sentry conta o erro da jornada. Datadog conta se a origem ajoelhou. Timeout com origem ok é bundle. Origem ajoelhada com bundle ok é infra. No pico os dois acontecem. Uma lente só te faz otimizar a errada.

O Lighthouse pergunta: no lab, o que está bloqueando o first paint? Eu coletei. Serve pra hipótese. Não fecha receita. Não tem influenciador. Não tem a fila da CDN.

O backoffice pergunta: vendeu? Sem a métrica de venda, bundle menor é hipótese. Essa pergunta fecha o mês. A resposta está no próximo bloco.

Recibo (o que fecha, o que não linko)

PRs e dashboards reais ficam atrás de NDA. O que o leitor consegue checar é este recorte. O +10% é o número do painel. O resto é o hábito + o filtro. Sem print forjado.

Lente	O que eu olhava	O que este post pode mostrar
Backoffice	conversão do mês, pico na campanha	+10% (número do cliente)
Sentry	timeout no passo de pagar, não TypeError órfão	query abaixo (sintético)
Datadog	TTFB / saturação / região no chunk do pagar	o que eu perguntava
Lighthouse	first paint no lab	limite: print não arquivado
Código	split, SSR, CDN	PRs internos. Não linko

Network no /pagar. Sintético, de propósito. Sem kB inventado. O furo é a presença do arquivo, não um score:

antes (furo)
  PayStep.js
  vue.runtime.js
  dashboard.chunk.js   ← não deveria estar no pagar
  admin-charts.js      ← idem

depois (o teste)
  PayStep.js
  vue.runtime.js

Se o dashboard ainda aparece, o import() é teatro. Não importa o Lighthouse.

Sentry. Mesmo recorte do complementar. Cola no Discover:

extra.phase:checkout.pay.submit AND (
  error.type:TimeoutError OR message:*timeout* OR mechanism:*timeout*
)

Pixel quebrado depois da venda não entra nesse filtro. É outro phase.

Datadog, a pergunta que eu fazia no pico: o TTFB do chunk do PayStep subiu na região da campanha, ou a origem tava ok e o bundle que era grande? Uma lente só te faz otimizar a errada.

Cupom inválido, cartão recusado, form incompleto: a regra funcionou. Breadcrumb. Não exception. Exception é gateway 500, timeout de rede, SDK que estourou no submit. Se misturar, o board grita e você trata recusa de cartão como queda de conversão.

5. Resultado: +10% no mês

O cliente leu o painel. +10% de conversão no mês. Pico nas campanhas de influenciador.

Esse número não veio de uma ferramenta só. Veio de três camadas juntas:

Métrica de venda: backoffice do cliente. Quem vende lê isso.
Jornada: Sentry com timeout/transbordo no pagar, não TypeError órfão.
Caminho: Datadog com TTFB, saturação, região.

Lighthouse ficou de hipótese de lab. Não fecha o mês.

O +10% não veio de silenciar recusa de cartão. Veio de o JS do pagar chegar a tempo, e de eu ver o timeout no mesmo dia.

Eu toquei esse recorte sozinho: o caminho do pagar, o split, essas lentes. Depois pesou numa promoção. O que ficou copiável foi a ordem: painel primeiro, lab por último. Bundle menor sem esse fechamento era só PR bonito.

6. O que copiar no próximo PR

Antes de mergear “otimizar o bundle”:

1. Qual jornada perde dinheiro se o JS atrasar? (pagar, não o admin)
2. No Network do passo de pagar, aparece JS de dashboard?
3. SSR no first paint do pagar, ou SPA seca esperando hidratar?
4. O import() puxa o passo, ou o passo importa o mundo no topo?
5. O chunk lazy está no edge, com hash e gzip, ou sai frio?
6. Venda (backoffice) e obs (Sentry/Datadog) olham o mesmo número, ou só o Lighthouse?
7. Timeout/transbordo alertam sintoma de usuário, ou qualquer JS?

Ordem: backoffice → Sentry → Datadog → Lighthouse

Se o PR não responde 1 e 6, pode ser um PR bom. Não é este case.

O número que paga é a conversão. Vue 3, MFE e Lighthouse entram se ajudam esse número. Se não ajudam, são logo.

Última campanha que você pegou: olhou primeiro o timeout no Sentry, o TTFB no Datadog, ou o backoffice?

Observabilidade no frontend: o HTTP 200 esconde ~900 catch vazios

Tiago Vilas Boas (Montanha) — Sun, 13 Sep 2026 17:51:10 +0000

Pessoal, abri o checkout. O BFF de pagamento devolveu HTTP 200. No botão, TypeError. Quem vendia e quem comprava falhavam sem stack, sem release, sem rota. Infra já tinha métrica. O navegador, onde o dinheiro vive, era ponto cego.

Eu contei da ordem de ~900 catch vazios ou logs que engoliam a exceção. Quatro fronts. Sem dono. Se eu ligasse o SDK no default do wizard, ia queimar quota e ainda assim não ter sinal.

O ponto é: HTTP 200 no BFF não prova que o clique viveu. catch {} também não.

A conta foi grep no repo, não runtime. Se você rodar as duas buscas, já vê a classe. Não é o regex que fechou o ~900:

rg -n --glob '*.{js,ts,tsx,vue}' 'catch\s*\([^)]*\)\s*\{\s*\}'
rg -n --glob '*.{js,ts,tsx,vue}' 'catch\s*\([^)]*\)\s*\{\s*console\.(log|error|warn)'

Como etiquetar a jornada no evento (pagar vs pixel) fica no complementar. O denso do +10% é o dinheiro. Aqui é o buraco que os dois encontram: o front engoliu o erro e o BFF disse 200.

Tabela de Conteúdo

1. HTTP 200 não é o sinal do usuário
2. Empty catch não é telemetria
3. O que entrou nos quatro fronts
4. Depois da adoção: talk, triagem, o tempo até a task
5. Dois clients no mesmo origin. Shell sem SDK
6. PII, replay, sample
7. O irmão de 30 dias
8. O que copiar no próximo PR

1. HTTP 200 não é o sinal do usuário

O servidor pode estar verde e o clique morto. Métrica de API responde tráfego e saturação. Ela não vê o TypeError no onClick do pagar.

Quatro repos, stacks distintas. Calendário de checkout não parava pra um “projeto de observabilidade”. A premissa era complementar Grafana e APM, não substituir.

Google SRE lista quatro sinais: Latency, Traffic, Errors, Saturation. No client, o pedaço que um SDK de erro carrega barato é Errors e um pouco de Latency. Traffic e saturação de fila ficam no backend. Se o setup promete os quatro sinais num projeto de front, a premissa está errada.

Eu recusei três coisas no mesmo dia: só APM (não vê o botão), captureException nu (sem dono) e sampling 1.0 (custo + ruído). Sem essas recusas, o dashboard mentia com mais volume.

2. Empty catch não é telemetria

catch vazio é o oposto de sinal. A exceção existe, a pessoa sente, o time descobre no ticket dias depois.

Sem tag de domínio, erro de PIX misturava com erro de upload. Sem máscara, qualquer SDK virava risco de PII.

A cadeia de pagamento piora isso. O mesmo erro sobe processPayment → executePayment → o handler. Sem dedup, você manda o mesmo TypeError três vezes e acha que o volume é incidente.

O que eu cobrei depois que o SDK entrou (formato, não issue de produção):

release:  checkout@git-a1b2c3
title:    TypeError: Cannot read properties of undefined (reading 'pix')
culprit:  PayButton.tsx:onClick
tags:     domain=checkout flow=pay error_type=timeout

Se falta release ou domain, a issue ainda é ticket com stack. Não é sinal.

3. O que entrou nos quatro fronts

Não foi um Sentry.init colado quatro vezes. Foram quatro jeitos, um contrato.

Front	Stack	O que o SDK (ou a ausência dele) faz
Checkout	Nuxt 3 / Vue	Plugin client. Só produção. Domínio no composable (`payment`, `checkout_load`, pixel, lead).
Admin novo	React 19, MFE	Init no boot. Error boundary. Interceptor do HTTP mapeia a URL da API pro domínio. Hook de rota seta `flow`.
Admin legado	Vue	Projeto separado. Mesmo contrato de tag. Sem misturar evento com o MFE novo.
Shell de rota	Go + JS inline	Sem SDK no `window`. Envelope na mão, `fetch` + `keepalive`.

Init só em produção. Hostname de PRD e flag de build. Localhost com bundle de prod não dispara. Sem DSN no env, return. Guard contra double-init (HMR / remount do MFE).

A API que o time chama não é Sentry.captureException. É o módulo de domínio:

sentry.capturePaymentError(error, { flow: 'pix' })
sentry.captureFinanceError(error, { action: 'withdraw' })
sentry.captureApiError(error, endpoint, { url })

O interceptor lê o path (/withdraw, /pay, /auth). Classifica timeout | network_error | server_error | client_error. Coloca http_status e error_type na tag. Fingerprint: domínio + flow + tipo. Assim PIX e boleto com o mesmo TypeError não viram o mesmo card.

Dedup: chave domain:message, TTL 5s. Cobre o boundary, o captureException nu e o handler do Vue. Sem isso o clique duplo vira storm.

ignoreErrors não é “esconder bug”. É não pagar quota com ResizeObserver, chunk que o retry resolve, navegação cancelada, pixel de terceiro, WebView (Java object is gone, webkit.messageHandlers). Failed to fetch no admin eu não ignorei: quero falha de API. No checkout ignorei rede do comprador. O ignore é contrato por app, não lista copiada.

Replay no checkout só se domain é payment ou checkout_load. Pixel e lead resolvem no stack. Cota de sessão não é pra gravar o admin inteiro.

Tinha um ReferenceError em tela de detalhe. Centenas de eventos. Dezenas de contas. Silencioso até o projeto certo existir. Isolar o client não foi estética. Foi conseguir achar o arquivo.

4. Depois da adoção: talk, triagem, o tempo até a task

Ligar o SDK não era o fim. Sem cultura, vira dashboard que ninguém abre.

Eu apresentei. Chapter de front: dezenove slides, demo ao vivo, guia escrito pra qualquer squad copiar o contrato (domínio, produção-only, máscara). Checkpoint no meio: o que o APM via vs o que o browser via. Depois, reunião pra estender o mesmo contrato pro fluxo de identidade, com client isolado. Não foi pitch de vendor. Foi “assim a gente investiga”.

Nas primeiras 24h no admin, sample a 10%: 98 eventos. Volume real, se o sample vale, na casa de mil erros de client. Vinte issues. Poucas causas raiz. Um crash de login no mobile saiu com um caractere (?. no reset do captcha). Navegação com router-link pra null antes do dado. RangeError: Invalid Date no Safari. Isso existia. Só não tinha dono.

Em ~25 dias de instrumentação ativa: 15 bugs de verdade (sem E2E, sem teste), da ordem de 300 contas no total, dezenas de PRs (setup + fix + tag). Custo do ciclo: frações de dólar. Só replay passou da cota.

Aí entra o que o volume faz com a cabeça. O board de erro aumenta. Antes o front era zero. Zero não é saúde. É cegueira. Quem olha só a fila acha que o Sentry piorou o MTTR porque agora tem issue. O que caiu foi o tempo até agir.

Antes: chamado vago, horas ou dias depois, “não consigo acessar”. Depois: o primeiro erro e a task na mesma janela. Nos casos que eu fechei no doc de produto, menos de 24h do evento até o card. A meta escrita de investigação era 4-6h no escuro para 15-30min com stack e breadcrumb. O cronômetro de cada fix eu não publico aqui. O que eu medi foi o tempo até a task, e o fato de achar dezenas de contas antes do chamado (o login travado depois da senha errada).

Triagem virou rito. Todo sprint: o que é novo, o que é regressão, o que é E2E fingindo usuário. Filtro de ambiente sintético. Issue que “resolveu” e voltou no lastSeen depois do deploy. Sem isso o SDK mente duas vezes: no silêncio, e no falso positivo.

5. Dois clients no mesmo origin. Shell sem SDK

Dois SPAs no mesmo origin. Um Vue legado (SDK velho no CDN, window.Sentry). Um React novo (SDK 9, namespace versionado). Se os dois escrevem no mesmo global, o evento do filho cai no projeto do pai. Ou some.

O shell de roteamento (Go + JS inline) não carrega o SDK. Monta o envelope, posta no ingest, keepalive: true pra sobreviver ao unload. Expõe captureError / captureWarning pro interceptor de rota. Breadcrumb no shell é no-op: sem SDK, não inventa timeline.

No MFE novo, o fluxo de identidade/documentos ganhou client isolado. BrowserClient próprio, Scope próprio. Client isolado não herda breadcrumb do scope global. Se você captura no client B e o addBreadcrumb foi no A, a timeline some. Por isso o scope dedicado: o passo (upload_document, submit_data) acompanha o evento no projeto certo.

Diagnóstico em PRD: um status() no window (namespace do app, não window.Sentry). DSN não se loga. Só: inicializou? env? o segundo client subiu?

O guia público do padrão está no sentry-golden-path. Ele prova o contrato. Não prova rate de uma marca.

6. PII, replay, sample

LGPD: documento, cartão, telefone, senha não vão pro vendor.

Máscara em duas camadas, no beforeSend:

Por nome de campo: cpf, document, card_number, cvv, password. Substitui por [PII_MASKED]. Não pega order_id.
Por regex em texto livre: CPF formatado (000.000.000-00), cartão, telefone. CPF sem pontuação eu não mascaro: pega id numérico.

Replay: maskAllInputs: true. Sessão aleatória: 0. Replay no erro: fração baixa, e ainda filtrada por domínio.

Sample: o wizard empurra tracesSampleRate: 1.0 e replay em 10% das sessões. Isso é demo.

No checkout eu subi sample de erro na casa de um terço, trace em 5%, replay de sessão zero. Replay no erro só no domínio que perde venda. No admin, no rollout, o erro foi mais alto que o 10% do guia. Trace igual: 5%. O número mora no PR. Se você não consegue escrever por que subiu, ele não sobe.

sampleRate é evento de erro. tracesSampleRate é span de pageload. São independentes. Cortar trace não esconde 100% das exceptions.

// ordem de grandeza do contrato. não é o wizard.
export const TRACES_SAMPLE_RATE = 0.05
export const REPLAY_SESSION_SAMPLE_RATE = 0

7. O irmão de 30 dias

No mesmo tipo de buraco, por outro canal: da ordem de quatro mil contas ficaram ~30 dias sem push. HTTP aparentava sucesso. API de terceiro deprecada, client antigo sem header, catch otimista, zero alerta de queda de entrega.

Achei no dashboard, não na fila de ticket. Happy path mente. $response->failed() (ou o equivalente) é o teste de sanidade de toda integração. Fallback gracioso sem alerta é o mesmo silêncio com nome bonito.

O que eu não publico neste texto: “60% dos bugs antes do suporte”, crash-free, dinheiro projetado. Contei os catches na estática. Vi o padrão entrar nos quatro fronts. PII deixou de ser risco aberto no beforeSend. Ainda ficou catch financeiro no legado e uma dezena no checkout sem fechar aqui.

Se o sample estiver errado, o blast é quota + alerta mutado + PII no vendor. Por isso o número começa escrito e só sobe com motivo.

8. O que copiar no próximo PR

1. grep do catch vazio / console.error no glob do front. Qual o número da classe?
2. Init só em PRD (hostname + flag de build). Sem DSN, return.
3. O time chama captureXError, ou Sentry.captureException no if?
4. Interceptor mapeia URL → domain, ou cada hook captura de novo?
5. Dedup 5s por domain:message? A cadeia de pagamento dispara uma vez ou três?
6. Dois SPAs no mesmo origin: cada um tem client/projeto, ou compartilham window.Sentry?
7. Shell de rota usa SDK no window, ou envelope na mão?
8. beforeSend mascara campo + CPF formatado? Replay de sessão está 0?
9. ignoreErrors é contrato do app, ou lista copiada do wizard?
10. $response->failed() (ou equivalente) no client HTTP. 200 não é entrega.
11. Tem rito de triagem (novo vs regressão vs E2E), ou só o SDK?

Kit: https://github.com/tiagovilasboas/sentry-golden-path

Premissa, target sample, dono. Depois o golden signal. Sem isso, você tem dashboard.

Qual catch vazio ou integração “200” o seu time ainda trata como silêncio? Catch no botão, client HTTP, ou os dois?

IA generativa e agentic: o README diz agent. O git não mudou

Tiago Vilas Boas (Montanha) — Sat, 12 Sep 2026 20:17:09 +0000

Você já teve aquele chat. O “agente” resolveu tudo em Markdown. git status limpo. Billing igual. Os dois usam o mesmo modelo. A diferença não está no vocabulário. Está no que aconteceu depois do prompt.

O histórico decide, não o README

Cursor, Claude Code, Codex, um StateGraph na API: o mesmo produto pode ser generativo numa rodada e agentic na outra. O nome da caixa não decide. O histórico decide.

Só completou Markdown? Generativo. Chamou busca, Read, gh? Agentic de leitura. Já tem blast (segredo no arquivo, dado que não devia sair). Chamou merge, migrate, deploy, pagar? Agentic que grava. Sem humano no meio, incidente.

Uma rodada é só o próximo passo

Você manda uma mensagem. O modelo recebe o histórico, escolhe o próximo passo e devolve alguma coisa. Isso é uma rodada.

Nada no git. Nada no banco. Nada no gateway. Generativo bem feito já vale. Classificar issue. Esboçar teste. Explicar um diff. Isso não é menor. É outro risco.

Agir devolve string e decide de novo

No agentic, o próximo passo pode ser uma ferramenta. O ciclo é curto e sempre o mesmo:

O modelo para e monta a chamada (nome da tool, argumentos).
O runtime executa no mundo.
O resultado volta como mais texto no histórico.
Ele decide de novo: responde pra você, ou chama outra tool.

Pode fazer isso várias vezes antes da frase final. Se a string mente, ele segue. Se a ferramenta é larga demais, ele age largo. Agentic sem política não é produto. É um invoke com efeito colateral.

O modelo não sabe que pagou

Ele só vê a string que a ferramenta devolveu. Não “sabe” que a assinatura caiu, que o PR abriu, que o deploy passou. Confiança alta no texto não muda isso.

Isso aqui não é log de produção. É o exemplo que eu uso pra não misturar as duas:

Empty invoke não é agente

O erro é chamar de agente um invoke sem loop. Agente, neste texto, é o ciclo: observa o estado, decide, usa ferramenta, lê o resultado, decide de novo.

Teste de bolso: se o git não mudou, o banco não mudou e nenhuma API foi chamada, aquela rodada foi generativa. Por mais que o README diga agent. Sem arquivo:linha no review, a gente já aprendeu a não misturar finding com palpite. Aqui é o mesmo músculo: texto não é efeito.

No último chat, 20 segundos:

1. tem tool call?            nao: gerou
2. a tool so le (Read, rg)?  sim: agir, leitura
3. a tool grava, paga, push? sim: humano antes

Se você não abre o transcript, o README decide por você.

Leitura e escrita não andam no mesmo cano

Confiança do modelo não é autorização

O modelo pode ter certeza alta e ainda assim chamar o path errado. Se ele errar, o pior é uma frase ruim, ou um deploy? Se for frase, gera. Se for deploy, cobra humano antes da tool que grava.

Cadeia, grafo e harness entram no runtime. O post irmão é LangGraph versus LangChain. RAG, MCP e fine-tuning são outro texto. Aqui o knob é um: você deixou o modelo agir?

O que eu não medi

Isso não é transcript de produção. Não contei quantos READMEs da sua org mentem. Não tenho taxa de agente de mentira. Tenho o teste: histórico, não vocabulário. Se eu estiver errado e a tool de escrita for larga, o blast é PR, deploy ou cobrança. Por isso a chave não fica com o modelo.

Gera é texto. Age é ferramenta. Olha o git.

No último chat: ele só escreveu, leu alguma ferramenta, ou gravou no mundo?
Ler README é uma ferramenta. git push é outra. As duas não andam no mesmo cano. A de leitura pode ser larga. A de escrita, não.

Humano no meio, aqui, não é revisar o Markdown depois. É confirmar antes da tool que grava, apaga, publica ou cobra. O modelo não segura essa chave. Sandbox, allowlist e audit trail existem pra essa rodada. A que só gera não precisa disso.

você:  cancela a assinatura 441
gerar: o path costuma ser DELETE /v1/subscriptions/{id}
agir:  tool HTTP, status 204, a assinatura caiu

O primeiro é hipótese. Pode estar certo. Pode ter alucinado o path. O git não mudou. O billing não mudou. O segundo é o mundo. Alguém de verdade perdeu a assinatura.
Não é “turno mágico”. Não é autonomia. É uma decisão, um retorno, e a chance de decidir de novo. Se você não consegue apontar onde a rodada acabou, você não sabe se gerou ou agiu.

Gerar acaba no buffer

No generativo, o próximo passo é só token. Prompt entra, texto sai. Traduz, resume, sugere um patch em Markdown. A rodada acaba no buffer do chat.

LangGraph versus LangChain: a conta é cadeia, grafo ou harness

Tiago Vilas Boas (Montanha) — Sat, 12 Sep 2026 20:17:08 +0000

Pessoal, eu ia responder LangGraph ou LangChain. Tipo React ou Vue.

Terminei o Agentic AI with LangChain and LangGraph, no Coursera (IBM). O curso ainda empurra um pouco pra escolher um logo. A pergunta que ficou depois do certificado não era o logo. Era: este fluxo é uma cadeia (entra, sai, acabou)? É um grafo (estado, ciclo, pausa pra gente)? Ou o cérebro nem está na lib: está no Cursor, no Kiro, no Claude Code?

O que você leva daqui: nomeia o fluxo antes do logo. Cadeia, grafo ou o desk. LangChain e LangGraph se encaixam. Nenhum substitui o harness.

A nota gerar vs agir para na rodada. O post de RAG e MCP é outra camada. Aqui é orquestração.

Um limite só: eu não rodei benchmark de latência Chain versus Graph neste laboratório. A conta abaixo é de forma, não de milissegundo.

Nomeia o fluxo antes do logo

Três formas. Não são três produtos.

Cadeia. Prompt, modelo, parser. Um sentido. Sem loop. LCEL: prompt | model | parser. Traduz, classifica, extrai. Acabou.

Grafo. Nós, arestas, estado. Pode voltar. Pode pausar. Pode retomar depois de falha. Docs oficiais: execução durável, memória de curto e longo prazo, interrupt com gente no meio. Isso é LangGraph.

Harness. O IDE chama tool, lê arquivo, espera você. Não precisa do grafo Python pra existir. Precisa de política: o que lê, o que grava, quem aprova.

No grafo, uma pergunta extra: quem escolhe o próximo passo? Se o código escolhe (aresta que você escreveu), é workflow. Se o modelo escolhe (ReAct, create_react_agent), é agent. LangGraph faz os dois. Por isso “coloquei LangGraph” não diz se você tem agente.

Se o time discute logo e o fluxo ainda é um invoke sem estado, vocês estão no item 1 fingindo que é o 2. Se no teu time já abriu PR de StateGraph pra um classificador, você já viu isso.

LangChain: a cadeia

A forma mínima, da documentação LCEL:

chain = prompt | model | StrOutputParser()
chain.invoke({"text": "Hello", "input_language": "English", "output_language": "Spanish"})

Entra dict. Sai string. Não tem “tenta de novo se a tool falhar”. Não tem “espera o humano”. Não tem checkpoint.

LangChain também entrega atalho de agente (create_agent no pacote atual). O detalhe está no H3 abaixo.

O que você ganha: integração, LCEL, um invoke que o time lê em dez linhas.
O que você paga: quando precisa de ciclo, persistência e pausa de verdade, a cadeia não chega. Você sobe de knob. Ou finge que subiu.

atalho de agente versus cadeia

create_agent no pacote atual não apaga o grafo. Por baixo, o runtime de agente da casa ainda é grafo. Você não desenhou os nós. O ciclo está lá. Se o pedido é traduzir e não há tool, o atalho é cadeia cara.

LangGraph: estado, ciclo, pausa

O README lista o que a cadeia não promete: execução que sobrevive a falha, HITL, memória de trabalho e entre sessões.

Ciclo: aresta condicional. O nó agent decide se chama tools ou END. Tool volta pro agent. ReAct não é marketing. É esse loop.

Pausa: interrupt(). Sobe valor pro cliente. Retoma com Command. Sem checkpointer, a pausa não existe: o estado não grava.

interrupt versus print("confirma?")

HITL que é print("confirma?") no log não é o interrupt da lib. Sem checkpointer, a pausa some no crash.

Cena pedagógica (não é log de produção):

você:     faz deploy da branch feature/pix
cadeia:   gera um YAML de pipeline. ninguém chamou o CI
grafo:    nó agent → nó tools → interrupt (HITL)
humano:   aprova
grafo:    retoma do checkpoint, dispara o workflow

A cadeia “fez o texto do deploy”. O grafo “quase publicou”. São contas diferentes. Least privilege e HITL no que grava. Sem isso o grafo é force push com estado.

O que você ganha: estado explícito, ciclo, pausa retomável.
O que você paga: desenho. Cada nó a mais é um jeito de errar no mundo. Blast radius da tool.

O grafo que ainda é uma cadeia

Atalho:

from langgraph.prebuilt import create_react_agent

agent = create_react_agent(model, tools)
agent.invoke({"messages": [("human", "traduz isto")]})

Isso compila um StateGraph e devolve um Runnable do LangChain. Você pode invoke como cadeia. Por dentro tem ciclo se houver tool.

Se a tool não existe e o pedido é “traduz”, você pagou grafo pra fazer LCEL. Estado vazio. Sem interrupt. Sem checkpointer. Logo Graph no requirements.txt. Fluxo de cadeia.

O teste: o transcript tem mais de um nó, ou tem um invoke e acabou?

Não usei ChargePaidHandler aqui. Essa cena é do post do grafo de código. Aqui o knob é orquestração, não dump do repo.

Quatro perguntas antes de adicionar o grafo

Copia. Cola no PR do agente.

## Cadeia, grafo ou harness

1. O fluxo é um sentido só (gera, classifica, extrai)? Cadeia. LCEL chega.
2. Precisa voltar (tool falhou, tenta de novo) ou parar pra gente (push, pagar, deploy)? Grafo. Checkpointer. `interrupt` no que grava. Aí: o **código** escolhe o próximo nó (workflow) ou o **modelo** (agent)?
3. O “agente” é o Cursor/Kiro neste pedido, não o Python? Harness. Não invente um StateGraph pra duplicar o que o IDE já faz.
4. Se o servidor do grafo cair, o time ainda trabalha? Se não, você acoplou o desk num processo.

HITL, least privilege, blast radius: a tool que grava não anda no mesmo cano da que só lê.

Se a resposta da 1 for sim e você mesmo assim abriu StateGraph, você comprou ciclo pra um invoke. O prompt da seção seguinte monta a arquitetura no teu repo. Sem pular pra StateGraph no escuro.

O contrato cola depois das quatro perguntas

Isto não é receita de instalar LangChain e LangGraph. É o contrato das três formas, pra colar numa conversa nova. Arquiteto, não gerador de código. Se você não tem nada, ele assume cadeia (LCEL) e semana 1 no README. Se tem tool que grava, pergunta HITL e espera.

Conversa nova. Cinco linhas do seu repo. Ele lê README e o que já existe (LCEL, StateGraph, create_agent). Sem stack: default cadeia. Stack complexa: até 8 perguntas, aí para.

Se devolver um StateGraph pra traduzir texto, você pulou as perguntas. Manda o trecho no comentário.

You are an architect, not a code generator.

I am designing a LangChain + LangGraph setup for a software team. I may paste repo context, a stack description, or a messy Slack thread. Do not assume Cursor, LangSmith Cloud, or any host. Talk in terms of three shapes: chain, graph, harness.

Do not write application code in the first reply. Do not invent tools, models, or vendors I did not mention. Do not open a StateGraph because the hype asked.

First pass, before any questionnaire: inspect what I pasted. If the harness can see the repo, look only at README, existing chains/graphs (LCEL, StateGraph, create_agent / create_react_agent), tools, checkpointer config. A handful of Reads. Not ten. Not dump. Cite what you found. Then classify from that evidence: chain-only vs needs-graph vs harness-already-does-it. Do not pick 3 or 8 questions before this pass.

If the pass shows nothing (no LangChain, no LangGraph, no tools): ask at most 3 short questions: (1) one-way generate/classify/extract, or a loop with tools, (2) does anything write (push, pay, deploy, email), (3) is the “agent” this Python process or an IDE chat. If I skip them, assume: one-way chain; no writes; one IDE for daily work; no StateGraph this week. Then output the sections below in this same reply. Week-1 bullets must be doable with LCEL in that repo. They are the first correct setup, not a shopping list of integrations.

If the pass already has enough, skip questions and output. If the pass shows a complex stack (tools that mutate, existing graph, checkpointer, or I proposed “add LangGraph for everything”) and something material is still missing, ask up to 8 short questions, then stop and wait. The 8 are for that case. Not for the nothing-case.

Mental model (non-negotiable):
- LangChain vs LangGraph is the wrong fight. Chain = one-way compose (LCEL: prompt | model | parser). Graph = state, cycles, durable execution, interrupt for humans. They fit: a compiled StateGraph is a LangChain Runnable. create_react_agent / create_agent is a shortcut that still compiles a graph. A shortcut with no tools and no interrupt is a chain you overpaid for.
- Harness (Cursor, Claude Code, Codex, Kiro) is a third shape. Do not duplicate the IDE with a Python graph if this request already lives in the chat with tools.
- interrupt() without a checkpointer is not HITL. print("confirm?") is not interrupt.
- Read tools ≠ write tools. Push, pay, deploy, email: HITL. Least privilege. Blast radius. No unbounded shell “to make the demo work”.
- Checkpointer memory is not a knowledge-base contract. Retrieval/RAG is another layer. Do not stuff the repo or OpenAPI into graph state.
- Start with the smallest shape that matches the flow. Chain first. Graph when you need to come back or pause. Harness policy always.

Also respect:
- If I said LangGraph or LangChain as alternatives, correct me and classify my flow as chain, graph, or harness.
- If I asked to “add LangGraph” to a translate/classify pipeline, refuse the graph and specify the LCEL chain.
- LangSmith is optional observability. Not a layer that replaces chain/graph/harness.

After you have enough answers, output exactly these sections in my language (pt-BR unless I write in English):

1. Diagnosis — for MY flow: chain vs graph vs harness. One paragraph. If I treated LangGraph as a competitor to LangChain, say so.
2. Chain (LangChain / LCEL) — what stays a one-way invoke. What must never become a node.
3. Graph (LangGraph) — “not now”, or nodes / edges / state fields / checkpointer / interrupt points. Table: node, read vs write, blast radius, HITL yes/no.
4. Shortcut — create_react_agent / create_agent: allowed only if the table needs a tool cycle. Otherwise forbid.
5. Harness — what stays in the IDE and must not be copied into Python this week.
6. Week-1 plan — 5 bullets in the repo. No new logo unless I already have it. If I had nothing, bullets are LCEL only.

End with 3 risks if I skip the diagnosis and jump to StateGraph.

O prompt já dá pra colar. O gist vive sem o artigo:

Se o server cai, o desk segue

No meu setup o cérebro do servidor defaultou pra Goose. LangGraph ficou legado. Não li isso num slide. Olhei o stack.

Quando o server está down, o Cursor continua: rules, vault, MCP. Doctor reclama. Você não para. A lib do grafo não era o harness. Era um cérebro atrás de um HTTP.

Isso não mata LangGraph. Mata a ideia de que escolher Graph ou Chain é montar o agente. Montar o agente é política no desk +, se você precisa de processo longo no servidor, um runtime com estado. Goose, Graph, o que for: o knob 3 (harness) continua existindo.

A memória é outra porta. Retrieve não é o checkpointer do Graph. Não misture as duas.

No último fluxo que você subiu: foi prompt | model | parser, foi grafo com interrupt, ou foi o chat do IDE sem Python no meio?

13 findings no Juice Shop. Nenhuma virou issue.

Tiago Vilas Boas (Montanha) — Sun, 06 Sep 2026 01:54:22 +0000

Pessoal, eu ia colar o Juice Shop na tabela do post das três portas.

Tinha 13 findings com requisito ASVS e arquivo:linha. SQL concatenado, eval no username, CORS *, cesto de outro usuário. O modelo tinha trabalhado. A tabela ia ficar “mais completa”.

Aí li o package.json: probably the most modern and sophisticated insecure web application. Não é gap. É o produto.

O que você leva daqui: lab de propósito inseguro calibra o procedimento. Não entra nas três portas. Silêncio aqui não é “invariante manteve”. É não abrir issue no scoreboard dos outros.

1. A tabela errada

O post pai é sobre OSS que alguém usa de verdade. Formbricks, Dub, Cal.com, Magnitude. Issue de hardening, e-mail quando for exploitable, nada quando o denominador fecha.

Juice Shop e WebGoat não são essa classe. O README do WebGoat avisa: a máquina fica vulnerável de propósito; o default escuta em localhost. O SECURITY.md do Juice Shop pede contato só para o que não faz parte de nenhum hacking challenge. O resto já está no placar.

Somar 13 linhas naquela tabela seria o mesmo reflexo dos 23 findings que eu quase mandei. Volume. A pergunta de segurança some: disto aqui, o que vira issue?

Nada. Porque o sink já tem nome de challenge.

2. Round 1: o que a varredura achou

Estático. Sem PoC. Sem tráfego. Fatia estreita, não o monorepo. YAML de challenges depois, só pra recall. Issue: nenhuma.

Juice Shop v20.2.0. 13 findings (10 L1, 3 L2). 10 chaves do catálogo bateram depois, de 116.

#	Problema	ASVS	Onde
1	Busca concatena `q` em SQL	`V1.2.4`	`routes/search.ts`
2	Login concatena email em SQL	`V1.2.4`	`routes/login.ts`
3	Username via `eval`	`V1.3.2`	`routes/userProfile.ts`
4	Search query com `bypassSecurityTrustHtml`	`V3.2.2`	`search-result.component.ts`
5	Description HTML sem encoding	`V3.2.2`	`search-result.component.ts`
6	CORS default `*`	`V3.4.2`	`server.ts`
7	Cesto por id sem dono	`V8.2.2`	`routes/basket.ts`
8	Senha em MD5	`V11.4.1`	`lib/insecurity.ts`
9	Admin seed `admin123`	`V6.3.2`	`data/static/users.yml`
10	FTP: allowlist de extensão depois null-byte	`V5.3.2`	`routes/fileServer.ts`
11	`fetch(imageUrl)` sem allowlist	`V1.3.6`	`routes/profileImageUrlUpload.ts`
12	Redirect com `url.includes`	`V3.7.2`	`lib/insecurity.ts`
13	Chave RSA do JWT no source	`V13.3.1`	`lib/insecurity.ts`

WebGoat. 11 findings. Uma lição de SSRF não abre URL: não entrei como SSRF.

#	Problema	ASVS	Onde
1	SQL concatena params	`V1.2.4`	`SqlInjectionLesson5a.java`
2	XML parser com entidade externa	`V1.5.1`	`CommentsCache.java`
3	Upload usa `fullName` no path	`V5.3.2`	`ProfileUploadBase.java`
4	XSS refletido em HTML	`V1.2.1`	`CrossSiteScriptingLesson5a.java`
5	Comment stored sem encoding	`V3.2.2`	`StoredXssComments.java`
6	Profile por `userId` sem dono	`V8.2.2`	`IDORViewOtherProfile.java`
7	JWT `jku` busca chave na URL do token	`V9.1.3`	`JWTHeaderJKUEndpoint.java`
8	Default `admin` / `admin`	`V6.3.2`	`DefaultCredentialsTask.java`
9	Lista de users sem role (Needs-runtime)	`V8.2.1`	`MissingFunctionACUsers.java`
10	`redirect:` sem allowlist	`V3.7.2`	`OpenRedirectRealRedirect.java`
11	HMAC JWT com palavra do source	`V13.3.1`	`JWTSecretKeyEndpoint.java`

Round 1 responde se inventa ID, inventa finding ou vaza PoC. Não responde se cobriu o placar.

3. A academia não é o jogo

Essa tabela não é troféu. É o Juice Shop fazendo o trabalho que a OWASP se propôs: um lugar onde a gente pode errar de propósito, ver o sink com nome, e voltar pro código que paga boleto com o olho mais treinado.

Quem mantém isso (e o WebGoat no mesmo espírito) está doando academia pra uma indústria que, no dia a dia, mistura pressão de entrega com risco de verdade. Sem esse tipo de lab, o atalho vira “rodei o scanner, achei 23 coisas, mandei pro tracker”. Com ele, dá pra ensaiar o reflexo certo: isto aqui é aula. Aquilo ali é produto. A porta não é a mesma.

Ferramenta ajuda. Prompt ajuda. Modelo de raciocínio alto ajuda. Nada disso substitui a pessoa no time que já viu o suficiente de segurança pra não confundir volume com cuidado.

O profissional avançado em AppSec não é o que gera a lista mais longa. É o que segura a mão do time quando a lista pede 13 issues num CTF. É o que olha um eval no username e pergunta: isso é challenge ou é o checkout de amanhã? É o que sabe que silêncio também é ofício. Não o silêncio de quem não olhou. O de quem olhou e escolheu não fazer barulho no lugar errado.

Time sem essa voz vira fábrica de card. Time com essa voz usa o Juice Shop como aquecimento e reserva o tracker pra quem realmente vai ler a issue no sábado.

O checklist de lab vs produto, se você quiser copiar: está no gist. O post das três portas continua sendo o mapa quando o alvo é OSS de verdade.

Takeaway: 13 sinks, zero issues, porque academia não se reporta como incidente. O que se leva pro time é o julgamento.

No seu time, quem é a pessoa que olha uma tabela dessas e pergunta a porta, em vez de abrir treze cards?

RAG e MCP, na prática. Cole o prompt e monte os dois

Tiago Vilas Boas (Montanha) — Sat, 05 Sep 2026 23:43:57 +0000

Pessoal, hoje todo mundo sabe falar de RAG, MCP e fine-tuning. Pouca gente tem isso no harness. Menos ainda com arquitetura: o que busca o doc, o que conecta, o que só muda o jeito.

Não é falta de artigo. É falta de prática.

Na prática: você pergunta o TTL do cache de idempotência. O agente lê o runbook: 60s, a janela. Você abre o código: 120. Ele não alucinou. O doc documenta a janela. O TTL nunca esteve no índice. Colar a nota no chat também não resolve.

O modelo não ficou mais esperto. Ele só prevê a próxima palavra com o que está no contexto agora. RAG colocou a janela nesse contexto. Sem o trecho, ele chuta. Com o runbook pela metade, cita certo o número que estava lá: 60. A pergunta era 120. Fine-tuning não coloca o TTL nos pesos. Muda o jeito da frase, se o fato já estiver no turno.

Como o trecho chega neste desk:

pergunta → harness → MCP → RAG busca o doc → contexto → resposta

MCP no meio não porque MCP “é pedir trecho”. MCP é protocolo: tool, resource, API, arquivo, banco. Neste fluxo a busca entra como tool. Fine-tuning fica fora do caminho.

O que você leva daqui: cole o prompt e monte os dois. RAG busca o doc. MCP conecta o harness ao que o servidor expõe. Fine-tuning muda o jeito. Se a primeira ferramenta do último chat não casa com a camada, você ainda está na teoria.

Camada	Papel	No desk
RAG	Busca o doc	Logseq, Notion, Confluence. Devolve o trecho certo.
MCP	Protocolo	Tool, resource, API, arquivo, banco. Neste fluxo: o harness alcança a busca por ele. Um host, duas tools: function calling nativo resolve.
Fine-tuning	Muda o jeito	Não guarda o doc. Só o padrão da resposta. Fora do runtime da pergunta.

Neste desk: monta a busca, depois o conector até ela. Se o formato ainda vazar, aí sim fine-tuning muda o jeito.

Depois de montar, o fato que faltava entra no doc. TTL 120: uma linha no runbook e no índice. A próxima pergunta pega o 120. O modelo não retreina. Se o código mudou e o runbook não, volta a mesma pergunta: retrieve certo, índice pela metade. MCP muda o conector, não o corpus. Fine-tuning não recebe o 120. Só entra de novo se o jeito mudou, e ainda assim depois de prompt e schema.

O erro é pular etapa. Colar a nota no chat não é MCP. Um conector que além de buscar também grava, sem gente no meio, vira incidente.

Abaixo: quatro perguntas. Se o último chat já responde, pode parar. Quem monta segue no prompt.

Tabela de Conteúdo

1. Nomeia o problema antes da ferramenta
2. RAG: busca o doc, não o peso
3. MCP: protocolo, não a busca
4. Fine-tuning: muda o jeito, não o catálogo
5. Cole isto no seu agente
6. Context window grande não é desculpa pra jogar o repositório inteiro
7. Não use o mesmo modelo (LLM) para tudo
8. O modelo é o mesmo. O harness muda
9. Se for implementar RAG, MCP ou fine-tuning de verdade, lê isto depois

1. Nomeia o problema antes da ferramenta

Antes de ligar mais uma ferramenta, pergunta:

Você precisa de um texto que já existe (política no Notion, ADR, README, o retry da API) e só quer o trecho certo? Isso muda em dias. É RAG. O harness alcança essa busca por MCP ou por function calling. Ou você precisa do agora: o pipeline passou, o PR está aberto, o teste quebrou, o banco tem o registro? Isso não é RAG. Está no CI, no git, no banco: outra tool, no mesmo protocolo ou nativo.
Se o agente errar, o pior é uma frase ruim no chat, ou ele pode gravar de verdade: merge, apagar arquivo, disparar pagamento, fazer deploy? Consultar e gravar podem ir no mesmo conector. Gravar precisa de gente no meio.
O trecho certo já está na conversa (você vê o arquivo, a regra, o JSON) e o que sai torto é só o formato: mistura finding com palpite, tom errado, label errada? Aí não falta fato. Falta jeito. Fine-tuning, depois de prompt e schema.
Vocês estão colando o repositório inteiro no chat para achar dois arquivos? Isso não é busca. É dump. Janela grande não acha o handler. Acha o meio.

Se o time grita fine-tuning e o fato nem entrou na conversa, vocês estão no item 1 fingindo que é o 4.

Quem constrói confere no histórico da conversa. Qual foi a primeira ferramenta que o agente usou nesta rodada? A tabela abaixo é o mesmo diagnóstico, em código.

O que você perguntou	Primeiro tool caro	Primeiro tool barato
Timeout, retry, contrato deste serviço	Busca no README de janeiro	`Read` do código agora. Reindex se o doc mentir.
O pipeline da `main` passou?	XML / JUnit no vetor	`gh run` agora
Quem chama este handler?	Dez `Read` “só pra garantir”	Mapa (grafo / LSP), depois 1–2 arquivos
JSON do review mistura finding e palpite	LoRA no OpenAPI	Schema no prompt. Finding ≠ hipótese.

Abre o último chat. O de ontem, não o demo. Primeira ferramenta: busca no doc, Read/gh, algo que grava, ou “vamos treinar”? Se não foi o barato da tabela, a camada estava errada.

Duas perguntas que eu fiz no chat. Histórico anonimizado. A primeira ferramenta foi busca no vault, via MCP, nas duas. O que muda é o índice.

Número de negócio. Doc e código bateram.

você:     qual é a janela de idempotência neste serviço?
primeira: MCP read no vault  (hub)
depois:   MCP read  (runbook.md → 60s, ADR datado)
          grep      (middleware.php → 60)
doc:      60s
código:   60s
camada:   índice vivo

Detalhe de implementação. O runbook documenta a janela. Não o TTL do cache. Grep no vault: vazio. O número estava no código.

você:     qual é o TTL do cache de idempotência?
primeira: MCP read no vault  (hub)
depois:   MCP read  (runbook.md → 60s, janela)
          grep no vault  (nada sobre TTL)
          Read  (middleware.php → 120)
doc:      vazio no TTL
código:   120s
camada:   índice pela metade

O vault não mentiu. Documentou o fato de negócio. Quem debuga “por que a chave ainda está no cache depois da janela?” não acha resposta no índice. Vai pro Read. A correção é uma linha no runbook, não LoRA. Dez Read vs mapa: neste post.

Cartão + prompt: Antes de ligar RAG, MCP ou LoRA: vê a primeira ferramenta que o agente usou.

2. RAG: busca o doc, não o peso

Logseq, Notion, Confluence, o runbook. Mesma conta da abertura: o fato está no doc. RAG busca o trecho. Não treina o doc de novo.

Isso mora no ADR, no runbook, no comentário do handler. Não mora no gh pr view de agora. Busca a regra no doc. Consulta o PR aberto na ferramenta. Inverter é inventar política ou procurar ADR na API do GitHub.

A janela estava no runbook. O TTL, não. Fine-tuning não escreve essa linha. Tool de GitHub também não. Se o fato mudou, você fornece o fato agora, na fonte. Treinar de novo é o caminho rígido e caro pra número que vive no runbook.

O modelo sabe HTTP. Não sabe o contrato deste serviço, a não ser que o trecho esteja no turno. RAG é a busca na pergunta, com fonte. Não é treinar de novo cada vez que o time muda o retry.

O que RAG não é: o status do Actions agora. Se muda a cada push, o índice mente educado.

O que você ganha: fato que atualiza sem treinar de novo, e dá pra apontar o arquivo. No trabalho: o modelo busca menos pra fora. Decide no contexto do time.
O que você paga: alguém tem que cuidar da base. Nota de janeiro no índice, política de março no jurídico: citação bonita, regra morta.

O doc ainda não chegou no harness. Isso é o próximo passo.

3. MCP: protocolo, não a busca

MCP não é a busca. É o protocolo: tool, resource, API, arquivo, banco. O harness chama o que o servidor expõe.

O fluxo da abertura é uma composição, não a definição. MCP no meio não porque “MCP pede trecho” seja o que MCP é. Porque neste desk a busca entra como tool.

O Logseq não anda sozinho até o chat. Sem conector, você cola a nota. Com o conector, a tool de retrieve entra no turno. RAG continua sendo a busca. MCP, neste desk, é como o harness chega nela.

Se o servidor está verde e o transcript ainda começa em dez Read, você não ligou o RAG. Só instalou o protocolo.

Um host, duas tools? Function calling nativo resolve. MCP começa a valer quando a mesma busca precisa aparecer em mais de um IDE, ou quando o time não quer reinventar o conector a cada harness.

O mesmo servidor pode expor outra coisa: git, CI, banco, pagamento. Isso não vira RAG. Leitura da busca ≠ push. HITL no que grava. Sem isso, o servidor “só de busca” vira force push. A sessão que consulta o manual não é a sessão que dispara o pagamento.

O que você ganha: o harness chega no doc (Logseq, Notion, Confluence) sem colar a nota no chat. E, se precisar, chega em sistema vivo pelo mesmo protocolo, em outro cano.
O que você paga: superfície. Cada tool a mais no mesmo servidor é um jeito de errar no mundo real.

4. Fine-tuning: muda o jeito, não o catálogo

Aqui o fine-tuning muda o jeito. Não busca o doc. Se a busca já devolve o trecho certo (RAG) e o harness já alcança essa busca (MCP ou function calling), e mesmo assim o formato vaza, aí conversa treino.

Fine-tuning não é o próximo passo porque o hype pediu. Prompt e schema são o degrau do meio. Treino é o último. Ele muda como o modelo responde: estilo, formato, padrão que se repete. Não é o jeito de ensinar as 400 rotas da API.

Um limite só: eu não treinei um modelo grande neste laboratório. O passo barato que eu uso é schema no prompt. Finding, observação e hipótese em campos separados. Sem arquivo:linha não é finding. Fine-tuning seria treinar esse jeito, mil vezes, se o schema não segurasse. Não seria gravar o OpenAPI nos pesos.

“Vamos treinar com o OpenAPI inteiro”

Amanhã o endpoint muda. O modelo, não. O spec de terça ficou preso nos pesos. Cena pedagógica:

você:     qual o path de cancelamento?
agente:   POST /v1/subscriptions/cancel  (spec de junho)
código:   POST /v2/billing/cancel        (desde agosto)
alguém:   "alucinou"

Não alucinou. Você pediu pra ele lembrar rota. Rota é fato. Fato vai pra busca no spec, ou pra tool que lê o OpenAPI no repo. Nunca pro peso, se muda.

Indexar o código-fonte no dataset de treino é o mesmo erro. O time muda o handler. Você ficou com um Readme.bak caro, que não dá grep.

O JSON do review sai torto

O arquivo certo já está no contexto. O modelo mistura “acho que é CSRF” com finding, quebra o JSON, escreve como blog.

Aí pode ser comportamento. Ainda não é abrir o painel de treino.

Ordem: prompt claro, dois exemplos bons, schema. Finding só com arquivo:linha. Hipótese em outro campo.

Se depois disso o formato ainda vaza em mil reviews por dia, aí sim: exemplos do jeito certo de reportar. Não o repositório no JSONL.

Quando fine-tuning vale

Classificar issue o dia inteiro: bug, dívida, feature. O rótulo quase não muda. Um modelo menor sai mais barato que o modelo caro lendo prosa.

Tom do time no review em escala, sem system prompt de oito mil tokens. O conteúdo (qual handler, qual timeout) continua de fora: busca ou tool.

“Não gera PoC, não abre PR nesta sessão” automático, quando o prompt já não segura.

Regra: se a correção é “atualiza o README”, não é fine-tuning. Se ele viu o código e mesmo assim escreve o review errado do mesmo jeito, mil vezes, aí conversa.

5. Cole isto no seu agente

Isto não é receita de instalar RAG, MCP e LoRA. É o contrato das camadas, pra colar numa conversa nova. Se você não tem nada, o agente monta a semana 1 do jeito certo: README do repo, tools nativas, fine-tuning depois. Arquiteto, não gerador de código. O bloco é longo de propósito.

Conversa nova. Cinco linhas do seu repo. Ele vasculha o que você colou (e o README/docs/MCP do tree, se o IDE deixar). Só então escolhe: 3 perguntas, 8, ou já o plano. Sem stack: default e semana 1. Stack complexa: até 8, aí espera. Não manda já commitar.

Se devolver “vamos treinar o OpenAPI” ou “um MCP com as 40 APIs”, você pulou as perguntas. Manda o trecho no comentário.

Antes de ligar RAG, MCP ou LoRA: vê a primeira ferramenta que o agente usou (prompt + cartão):

You are an architect, not a code generator.

I am designing an agentic setup for a software team. I may paste repo context, a stack description, or a messy Slack thread. Do not assume Cursor, Claude, Copilot, or any other host. Talk in terms of layers.

Do not write application code in the first reply. Do not invent tools, datasets, or vendors I did not mention.

First pass, before any questionnaire: inspect what I pasted. If the harness can see the repo, look only at README, docs/ (or where docs are pointed), connector/MCP config, any existing index. A handful of Reads. Not ten. Not dump. Cite what you found. Then classify from that evidence: nothing vs complex. Do not pick 3 or 8 before this pass.

If the pass shows nothing (no RAG, no MCP, no LoRA): ask at most 3 short questions: (1) where do docs live today, (2) one IDE or several, (3) does anything need to write (push, pay, deploy). If I skip them or say I have nothing, assume: corpus = README/ADR in the repo; one host; native function calling (no MCP yet); fine-tune = not now; do not dump the repo. Then output the sections below in this same reply. Week-1 bullets must be doable with only that repo and that IDE. They are the first correct setup, not a shopping list.

If the pass already has enough, skip questions and output. If the pass shows a complex stack (several hosts, writes, existing MCP, index, or I proposed fine-tuning) and something material is still missing, ask up to 8 short questions, then stop and wait. The 8 are for that case. Not for the nothing-case.

Mental model (non-negotiable):
- This stack does not make the model smarter. It is harness discipline: directed context at query time, so next-token prediction is better grounded. At work, retrieve in-corpus first: less fishing on the public web, fewer exploratory Reads. Tokens drop vs dump or ten Reads, not vs an empty chat.
- RAG / retrieval = the knowledge base (Logseq, Notion, Confluence, ADRs, READMEs) plus search at query time. Cite sources. Not a substitute for live CI, git, or DB.
- MCP = a protocol (tools, resources, APIs, files, DBs). Not the corpus. Not RAG. This article's happy path is a composition: the harness reaches retrieval through MCP, or through native function calling. Native function calling is enough if I have one host and two tools.
- Tools that mutate (push, pay, email) may ride the same connector. They are not RAG. Read ≠ write. HITL on writes.
- Fine-tuning = behavior (format, tone, labels) AFTER retrieval is reachable and facts are right. Try system prompt, few-shot, and strict JSON schema first. Never fine-tune to inject an OpenAPI spec, a codebase, or API paths that change.
- Context budget = do not dump the monorepo. Prefer a code map / graph / LSP query, then 1–2 files. A large context window still loses the middle.
- Model role = pick by trained skill and claimed capability, not the IDE logo. The turn only tells you which of those skills you need now: daily craft, hard architecture, code review, security review.

Also respect:
- Least privilege: read tools ≠ write tools. git push, merge, migrate, deploy need a human in the loop. No unbounded shell “to make the demo work”.
- Exposing remember()/recall() as a tool does not make a memory policy.
- Exposing RAG as one MCP tool is allowed, but the agent must still know WHEN to search docs vs WHEN to call git/CI.

After you have enough answers, output exactly these sections in my language (pt-BR unless I write in English):

1. Diagnosis — for MY repo/workflow, what is knowledge vs action vs behavior vs budget vs model role. One paragraph.
2. RAG — what corpus (docs vs code), what must NEVER go in the index, how we know a hit is stale vs the tree.
3. MCP / protocol — what the harness can call. Table: server, what it exposes (retrieve vs git vs mutate), blast radius, HITL, MCP vs native function calling and why. If I treated MCP as a synonym of RAG, or as “the thing that asks for the snippet”, correct me: that is a composition, not the definition.
4. Fine-tune — “not now” or a precise behavior to learn, with the prompt/schema alternative we will try first. If I proposed fine-tuning OpenAPI or the repo, refuse and reroute to RAG or a tool that reads the spec from git.
5. Context budget — dump vs map. One indexer max.
6. Model posts — map daily craft / hard architecture / code review / security review onto models by trained skill and claimed capability, using whatever I already pay for. If I named none, propose the jobs without vendor lock-in.
7. Week-1 plan — 5 bullets I can do in the repo without buying a new course. No new logo unless I already have it. If I had nothing, these bullets are how I mount week 1 the right way.

End with 3 risks if I ignore the diagnosis.

O prompt já dá pra colar. As duas seções seguintes não são RAG nem MCP. São o que ainda quebra na prática: jogar o repo no context window, e trocar de modelo achando que montou camada.

6. Context window grande não é desculpa pra jogar o repositório inteiro

“O context window é enorme, manda o monorepo.”

Você não economizou. Enterrou o handler certo no meio.

Na prática (cena pedagógica):

você:     quem chama applyTimeout neste serviço?
dump:     monorepo no context window
agente:   cita vendor/retry/README.md
          "30s, 3 tentativas"  (achou o que parecia)
mapa:     applyTimeout ← PaymentHttpClient ← WebhookController
código:   src/http/client.ts, 5s, um caller

O modelo citou. Citou o arquivo errado. Context window grande entrega o meio. Não o handler.

Indexar o repo no vetor e chamar de RAG também não resolve. Mapa responde quem chama. Vetor de 40 mil chunks responde parece com. Se o histórico começa em dez Read, não tem mágica. Tem pasta no disco.

7. Não use o mesmo modelo (LLM) para tudo

Isso não é a quarta camada. É o seletor. Trocar o logo não busca o doc, não conecta o harness e não muda o jeito.

“Arruma o auth.”

Pode ser typo no middleware. Um if, um import, o token caiu no header errado. Um arquivo. Coding no fluxo. O modelo que se propõe a isso resolve e segue.

Pode ser recorte de seis módulos. Gateway, sessão, cookie, refresh, o middleware que ainda deixa passar o path antigo. Vira desenho. ADR. Troca de contrato. Vários arquivos, horizonte longo. O pedido é o mesmo. O skill não é.

Pode ser code review. O patch passou. Quem implementou quer terminar. Quem revisa quer discordar. Isso pede o teto, não o modelo que acabou de escrever o diff.

Pode ser security review no source. O furo de autorização ficou no PR. Não é pentest. É ler o diff contra o contrato de auth.

O texto do pedido sozinho não separa. “Arruma o auth” não diz se você precisa de um patch, de um recorte ou de um review. Quem escolhe modelo sem isso cola o skill errado no seletor.

Não escolhe pela IDE. Escolhe pelo skill / capability que o modelo declara. Sem ranking. Não rodei o leaderboard deles.

Skill / capability	Vendor
Coding in the loop, ship	Grok 4.6 High: coding, agentic, knowledge work
Multi-file recorte, ADR	Claude Opus 5: complex agentic coding, long refactor
Code review	Claude Fable 5: highest capability, long SWE
Security review (source)	Claude Fable 5: Mythos-class. Cyber no GA, com safeguard

O modelo do dia a dia revisando o diff de auth é viés do próprio patch. Quem escreveu o patch não é quem caça o furo. Fable no seletor é o teto GA: Mythos-class com safeguard. Mythos 5 é o mesmo peso, acesso restrito. Code review e security review de source no PR. Não é pentest.

Trocar de modelo não substitui RAG, MCP ou fine-tuning. Fine-tuning não substitui o README que faltava.

8. O modelo é o mesmo. O harness muda

Não ganhamos um modelo mais inteligente. Ganhamos um harness que para de chute: o trecho certo entra no turno, o context window não vira dump. Predição mais acertada. O cérebro é o mesmo.

No trabalho isso pesa. A política já está no doc. O modelo para de completar com o treino público, para de abrir dez arquivos “só pra garantir”. Token cai quando a alternativa era dump ou dez Read. Retrieve ainda gasta contexto. Gasta o certo.

O que ganhamos não é “ter RAG, MCP e LoRA” no vocabulário. É ter busca, protocolo e jeito no harness, cada um no papel certo. Página velha não se resolve treinando. Colar no chat não é protocolo. Trocar o logo no seletor não atualiza o README.

Dá pra usar no Kiro, no Cursor, no Claude Code, no Codex. A conta não é do logo. Knowledge base, conector, jeito, context window: isso mora no harness que você estiver. Um host, duas tools: function calling nativo resolve. Vários hosts, a mesma base: aí o MCP vale, pra não reinventar o conector em cada um. O histórico da primeira ferramenta funciona em todos. Se o primeiro movimento muda quando você troca de IDE, você não montou camada. Montou atalho daquele app.

9. Se for implementar RAG, MCP ou fine-tuning de verdade, lê isto depois

Até aqui a gente só fechou a conta: o que é cada camada, o que não é, o que olhar no histórico. Chunk, servidor MCP, memória entre sessões, mapa do repo: isso não cabia neste texto. Se você for implementar isso no IDE, esses cinco links são o próximo passo. Na ordem. Cada um cobre uma coisa que eu deixei de fora de propósito.

Mesmo com GraphRAG, o agent se perde sem contrato de memória. Retrieve não é memória. Hub, o que gravar, o que não.
Indexar o código fora do repo. Mapa vs dump. Context window grande não acha o handler. O histórico da primeira ferramenta mora lá, não aqui.
MCP: intro oficial. Host, client, server. Tools e resources. Como o protocolo existe de fato.
Contextual retrieval (Anthropic). Chunk, embedding, o que a busca devolve quando o índice é mais do que “joga no vetor”.
Fine-tuning (OpenAI). Quando é comportamento. Quando não é fato. Dataset, não OpenAPI nos pesos.

Os cinco links são o passo seguinte, se for montar de verdade. O que este texto pede é não pular a camada. O prompt + cartão não instala a stack. Diagnostica a sua. Cola no Kiro, no Cursor, no Claude Code, no Codex.

No seu último chat: a primeira ferramenta foi a busca do RAG (MCP ou function calling), outra tool no mesmo protocolo, ou ele tentou treinar o OpenAPI?

O prompt de AppSec que eu criei achou 4 gaps de segurança

Tiago Vilas Boas (Montanha) — Wed, 02 Sep 2026 03:58:17 +0000

Pessoal, eu quase mandei uma lista de 23 "vulnerabilidades" pra mantenedores de código aberto.

XSS, CORS, CSP, um SVG suspeito. O modelo tinha devolvido volume. Eu sentia que tinha trabalhado. Aí parei. Se eu fosse o cara do outro lado da issue, eu levaria isso a sério?

A conta virou quando eu parei de pedir "audita meu código". Passei a escrever o contrato antes de abrir o repo. Direção (o que o modelo pode afirmar) e disciplina (o que ele não pode). Isso não deixa o LLM mais inteligente. Controla o comportamento. Em segurança, isso é o que separa auditoria de lista.

O que você leva daqui: o contrato (esqueleto), por que o scanner não substitui hunt, e as três portas pra não colar relatório no tracker. Os repos no meio são prova. Não são o ponto.

Tabela de Conteúdo

1. Direção e disciplina não deixam o modelo mais inteligente
2. O scanner vê o que está. O hunt vê o que falta
3. Silêncio também é resultado
4. As três portas
5. O que você monta amanhã

1. Direção e disciplina não deixam o modelo mais inteligente

Esse é o ponto que eu demorei pra aceitar.

O modelo já conhece OWASP. O que muda é o que ele tem permissão de afirmar. Sem isso, "audita meu código" devolve XSS fantasma, CORS, CSP, um SVG. Volume. A pergunta de segurança some: disto aqui, o que vira issue, o que vai pro e-mail privado, o que é silêncio?

Direção amarra três coisas antes da leitura:

Padrão externo. OWASP ASVS 5.0, com o ID do requisito. "Boas práticas" não conta.
Invariante em uma frase, falsificável. "Webhooks deveriam ser autenticados" é opinião. "Todo handler de webhook de entrada verifica autenticidade do remetente antes de mutar estado" é hunt.
Formato único. Finding, observação e hipótese não misturam.

Disciplina é o que corta o teatro. O texto que o modelo vê antes de abrir arquivo:

Padrão: OWASP ASVS 5.0, com o ID do requisito. "Boas práticas" não conta.
Invariante: uma frase, falsificável.
Relatório: finding, observação e hipótese não misturam.

Sem arquivo:linha → não é finding.
CWE inventado → encerra a sessão.
Needs-runtime → não vira card.
Sem X de Y → não é hunt.
Estático. Sem PoC. Sem request no ambiente deles.
A sessão que encontra não é a sessão que corrige.

Esse último item parece burocracia até o modelo achar um gap e, empolgado, reescrever o where do Prisma no mesmo fôlego, sem teste. Finding de um lado. Fix de outro.

O prompt completo é privado. Por trás dele tem regras numa knowledge base (quando hunt, quando varredura, o que é finding, as três portas) e skills do harness que amarram o modelo nisso. Sem a KB o modelo improvisa. Sem a skill ele lê o bloco e segue viagem. O esqueleto acima é o que cabe num artigo.

Um limite honesto: isso só rende em modelo de raciocínio alto. Num modelo fraco, prompt bom organiza melhor o erro.

2. O scanner vê o que está. O hunt vê o que falta

Scanner estático (Semgrep, CodeQL, Bandit) acha padrão que existe. Chamada perigosa, query concatenada, header ausente. É rápido, determinístico, barato. Roda a cada push. Eu não troco isso por LLM.

O que ele estruturalmente não vê é um controle ausente. "Esta rota deveria checar o dono do recurso antes de retornar, e não checa" não é regex. É propriedade semântica: o que é um tenant, que recurso pertence a quem, qual rota é pública de propósito.

Por isso o Semgrep entra neste texto. Não porque ele tenha achado os gaps. Porque, no mesmo commit do caso das 174 rotas, ele foi o baseline de CI. Sete rulesets, 25 segundos:

semgrep --config p/default --config p/typescript --config p/react \
        --config p/nextjs --config p/owasp-top-ten \
        --config p/javascript --config p/secrets

23 findings. 17 eram unsafe-formatstring em template. Zero de authorization.

Broken authorization (BOLA, OWASP API #1) não tem regra sintática estável: o padrão certo e o errado usam o mesmo findUnique.

O hunt começa invertido. Você escreve a invariante antes de abrir o arquivo. Enumera caminhos. Classifica: enforced-explicitly, inherited, gap, out-of-scope. No fim tem denominador. "Achei um IDOR" sem "1 de 174" não é hunt. É vibe.

Naquele commit: 173 de 174 rotas seguravam. Uma não. Esse é 1 dos 4 authorization gaps da rodada. Os outros 3 estão num alvo cujo detalhe de rota não entra neste post. Formbricks e Dub são hardening, não entram nos 4.

Não é um contra o outro. O scanner pega injeção, XSS, secret, header. O hunt pega o caminho que usa o mesmo findUnique e esquece o dono. Um é CI. O outro é pergunta. Verde no pipeline nunca respondeu se a invariante ainda vale.

3. Silêncio também é resultado

A falha mais comum de IA em segurança é fabricar achado para não devolver silêncio. Disciplina se mede nisso.

Busca ingênua por dangerouslySetInnerHTML em um app Next: oito hits, XSS crítico fantasma. Seguindo o dado até a função, é DOMPurify. Em SSR o React escapa. Zero finding. O que virou issue foi CORS contraditório (* + credentials), que o navegador rejeita. formbricks#9081. Tinha um SVG Needs-runtime. Não virou card. Prompt solto teria aberto dois. O dirigido abriu um.

Webhook de entrada: 7 de 7 autenticam o remetente. Semgrep no escopo: 0. Autenticidade não é padrão sintático. Dois HMAC com !== no mesmo repo que já usa timingSafeEqual. Observação, não gap da invariante. dubinc/dub#4415.

Mesma classe, outro alvo. No Cal.com, 8 de 8 webhooks de entrada verificam o remetente antes de mutar. HitPay, o token do Google Calendar e o secret de credential-sync ainda comparam com !==. O BTCPay, no mesmo monorepo, já usa timingSafeEqual. cal.com#30100.

Axios, gin, Guzzle, Medusa, Documenso: invariante manteve. 3/3, 4/4, 11/11. Não abri issue. Abrir card pra dizer "olhei e está ok" é o mesmo ruído que o modelo solto fabrica.

Daemon local é o mesmo teste com outra forma. No Magnitude o ACN já escuta em loopback. Isso é controle. CORS na porta pública ainda refletia Origin: null. Markdown passava href sem allowlist de protocolo. Três issues no tracker que o README aponta: #78, #79, #80. Shell do agent (-c) não virou finding: é a ferramenta do produto. Dashboard de debug: o maintainer já tinha fechado essa classe no tracker. Não abri mais três cards no dia seguinte. Volume aqui também seria ruído.

A prova compacta, estático, sem PoC:

Alvo	O que a disciplina fez
Formbricks	XSS não confirmado. Hardening CORS → #9081
axios, gin, Guzzle	invariante manteve. Silêncio.
Dub	7/7 autenticam. Timing → #4415
Cal.com	8/8 autenticam. Timing → #30100
Medusa, Documenso	payment idempotency e file namespace: denominador cheio, 0 gap. Silêncio.
Magnitude	daemon local. #78 #79 #80. Dashboard de debug: silêncio.
Plane	3 gaps de object-level authorization. Canal privado. Sem path aqui.

Juice Shop e WebGoat não estão nesta tabela. São lab de propósito inseguro: o SQL concatenado já é o produto. Abrir issue ali seria o volume que este post recusa. O complemento deste fio: 13 findings no Juice Shop. Nenhuma virou issue. Lab calibra precisão. Não prova as três portas.

Se o seu critério de sucesso for volume, metade dessa tabela parece desperdício. Pra mim as linhas em silêncio são as que sustentam as outras. Impacto verificável não é o mesmo que "issue aceita": a #9081 ganhou security e agent-ready; a #4415 entrou no Linear deles como ENG-1732. As duas continuam abertas. A #30100 é a mesma porta: hardening, sem PoC.

4. As três portas

Disciplina de divulgação é a mesma disciplina de finding. Least privilege aqui é o blast radius do texto. HITL é você escolhendo a porta, não o modelo. Audit trail é a issue ou o e-mail, nunca o transcript.

Issue pública: hardening. Bypass, injeção, secret, authorization gap: privado primeiro. Sem SECURITY.md, o README ainda pode apontar o tracker: aí hardening vai pra issue, como no Magnitude. O resto continua e-mail ou advisory, não thread de exploit.

Copia. Cola no fim da sessão, antes de abrir o browser.

O e-mail da trilha, com os links do que foi aberto e o porquê do silêncio:

5. O que você monta amanhã

Pega o repo que você mantém. Escreve uma invariante falsificável antes de abrir arquivo. "Todo webhook de entrada verifica assinatura antes de mutar estado" serve.

Roda o scanner primeiro. Depois pede ao modelo o passe só naquela invariante, com denominador e arquivo:linha, sem PoC, sem fix na mesma sessão.

Se voltar "23 findings" sem X de Y e sem citação, você não tem auditoria. Tem lista. Faltou direção. Faltou disciplina.

No último output de "audit" que um modelo te deu: você teria aberto issue pública, mandado e-mail privado, ou deixado nada? Se a resposta honesta for "ia colar o relatório inteiro no tracker", a porta ainda está solta.

Sobre o produto: o prompt é privado. Neste post vai o esqueleto. Por trás dele tem regras numa knowledge base e skills no harness. O pack (metodologia, cases, templates) está sendo refinado. Se você quer ser avisado quando sair mais, ou tem caso de uso específico, me chama no LinkedIn ou GitHub.

Mesmo com GraphRAG, o agent se perde sem contrato de memória

Tiago Vilas Boas (Montanha) — Fri, 28 Aug 2026 17:50:21 +0000

Pessoal, o agent puxou um trecho bonito. Similaridade alta. Confiança alta. Estava no stub errado.

Não foi “RAG fraco”. Foi porta errada. Índice caro, lixo na entrada.

O post anterior foi sobre consultar o grafo de código: token cai quando o agent pergunta ao mapa, não quando o gitignore está certo. Aqui é a outra conta. Vector, GraphRAG, híbrido: como recuperar. Contrato: o que pode ser lembrado e por onde se entra. Sem a segunda, o índice só erra mais rápido.

A prova também não é o vendor. É o transcript. Primeiro passo foi abrir o hub canônico, ou foi grep no cemitério?

Tabela de Conteúdo

1. O índice acertou. O mundo, não
2. O que o mercado está vendendo
3. A prova está na porta
4. O contrato em quatro peças
5. O que eu corto amanhã

1. O índice acertou. O mundo, não

A pergunta clássica era qual banco de vetor? A de 2026 é vector, grafo ou os dois?

A minha ficou outra: quando o agent pergunta “onde está X?”, ele entra pelo hub ou grepa o bak?

Se for a segunda, tanto faz o logo. Você indexou o labirinto.

2. O que o mercado está vendendo

O debate público é retrieval. Lookup (“qual o prazo neste contrato?”) vs síntese (“quais os riscos em todos?”). Vector costuma ganhar no primeiro. GraphRAG no segundo, caro de manter. Híbrido roteia. Um recorte com data: vector vs GraphRAG, 2026. Snapshot. Não ranking.

Isso importa. Não decide se legado/ pode ser porta. Não decide se o agent mistura diário com runbook no mesmo contexto. Embedding “certo” em guia morto: política ausente.

No meu setup o contrato veio antes do vetor. Não estou dizendo que vetor é inútil. Estou dizendo que porta entrega valor no dia zero. Eval de recall é outra conta. Um limite só: contrato não substitui GraphRAG quando a pergunta é síntese em grafo de entidades, e não é AppSec de prompt sozinho.

3. A prova está na porta

Mesma lógica do grafo de código. Lá eu olho se o primeiro tool foi query ou o décimo Read. Aqui eu olho se o agent cita o hub ou só a similaridade.

Pergunta sintético: qual a regra de entrada da memória do agent?

Turno caro (reconstruído, não é log de produção):

grep "memória" (em tudo)
Read README.bak
Read (mais três hits no lixo)
→ responde com confiança, regra invertida

Turno barato:

scope = meta / ops
Read o hub
segue o canônico
grep só depois, se precisar
→ a resposta diz por qual hub entrou

Se o agent não consegue dizer por qual porta entrou, você não tem contrato. Tem índice.

4. O contrato em quatro peças

Cabem em qualquer vault. Os nomes das caixas são seus.

Fonte única. Um canônico. O resto é espelho ou lixo.

Scopes. Pessoal, carreira, ops, meta, o que for. Página nova declara a caixa. Sem isso o search mistura incidente com diário.

Porta. Escolhe o scope, abre o hub, segue canônicos. Search é complemento. “Onde está X?” só com grep é o anti-padrão.

Hop. Redirect fino. Um pulo. Labirinto de stub é indexar lixo de propósito.

O que nunca vai pro contexto: segredo, PII, case que identifica empresa. Least privilege de memória. Não é feature do Pinecone.

5. O que eu corto amanhã

Copia. Cola no vault.

## Memory contract (agente)

1. Fonte canônica: um vault, não cinco?
2. Scopes: o que cada caixa pode conter?
3. Página nova declara scope?
4. Porta: hub-first por tipo de pergunta?
5. Redirect: hop máximo?
6. Proibido como entrada: legado, lixeira, bak?
7. Search é complemento, nunca substituto do hub?
8. Nunca no contexto: segredo, PII, case identificável?
9. Como você sabe que errou? (cita o hub usado)

No seu último “RAG”: o agent entrou por porta, por similaridade, ou por grep no bak? O que você proibiria como entrada amanhã?

Consultar o grafo economiza token. Tirar o índice do git, não

Tiago Vilas Boas (Montanha) — Thu, 27 Aug 2026 18:41:59 +0000

Pessoal, eu ia vender a tese errada.

“Tirei o índice do git, então a sessão ficou barata.” Mentira educada. O modelo não lê gitignore. Se o agent abre dez arquivos, você pagou dez arquivos. A pasta do índice pode estar no lixo do disco que a fatura não muda.

O que mudou na minha cabeça: a prova não é a tool instalada. É o transcript. Primeiro tool foi query/neighbors/go-to-def, ou foi Read de um arquivo “suspeito”?

Token cai quando o agent pergunta ao mapa com orçamento. Fora do git só impede o mapa de ir no PR. São contas diferentes. Graphify, Serena, LSP, índice do editor: o logo não importa.

Tabela de Conteúdo

1. Eu misturava três coisas
2. A prova está no transcript
3. Se o seu indexer não é o meu
4. O que eu corto (e o que eu não vendo como economia)

1. Eu misturava três coisas

Uma é política: o que pode ser lembrado, por qual porta se entra. Isso é memória de domínio. Outro post.

Outra é o turno: “quem chama este handler?” sem pagar o monorepo. Isso é mapa de código + budget.

A terceira é onde o arquivo do mapa mora. Disco, gitignore, cache fora da árvore. Blast radius. Quase zero na fatura.

Eu vendi a terceira como se fosse a segunda. Por isso o texto antigo parecia raso.

Se a pergunta é “o que a gente decidiu sobre retry?”, grep no repo é porta errada. Se é “quem chama?”, despejar dez arquivos “pra garantir” também é.

2. A prova está no transcript

Não tenho % de token pra te vender. Tenho um hábito que qualquer um reproduz: abre a sessão e conta os tools.

Pergunta sintético (de propósito): quem chama o handler de charge.paid, e o que quebra se o payload mudar?

Turno que eu classifico caro (reconstruído, não é log de produção):

grep charge.paid
Read WebhookController.php
Read ChargePaidHandler.php
Read PayloadDto.php
Read tests/ChargePaidTest.php
Read (mais quatro “só pra garantir”)

Você pagou o repo pra uma pergunta de vizinho.

Turno que eu classifico barato:

neighbors / path / go-to-def  →  ChargePaidHandler
Read ChargePaidHandler.php
Read (no máximo mais um caller)

O mapa já existia. O agent perguntou. Aí leu pouco.

Como eu sei que “o Graphify está ajudando”? Não é porque o MCP está verde. É porque o primeiro tool não é um Read de arquivo aleatório. Se o indexer está instalado e o transcript ainda começa com dez Read, você não economizou. Só gerou pasta de índice.

Índice velho tem cara própria: o agent cita função que você apagou ontem, com confiança. Aí reindexa. CLI (test, git status, build) é outra conta. Comprime ou lê o trecho. Não mistura com o grafo.

E o gitignore: vários indexers despejam output na raiz. Ignore. Isso não é a economia. É pra o mapa não ir no PR.

3. Se o seu indexer não é o meu

No desk o mapa é Graphify. A conta não precisa do nome.

Você tem	Sinal caro no transcript	Sinal barato
Grafo / symbol index	Instalar e começar em `Read`	Query / neighbors / go-to-def, depois 1–2 arquivos
Só grep	Dez arquivos “pra garantir”	Grep estreito + 1–2 arquivos
Dois indexers	Dois mapas, zero consulta	Um por sessão

Dois indexers na mesma conversa dilui o hábito que importa: consultar. Mede pelo transcript, não pelo setup.

4. O que eu corto (e o que eu não vendo como economia)

Gist:

Corta contexto: perguntar ao mapa com budget; Read cirúrgico; CLI resumido; um indexer.

Não corta contexto (e mesmo assim faça): output fora do git; saber quem lê o mapa; reindex quando ele mentir.

Fora do git protege o mapa. Consulta com budget é o que corta a janela.

No seu último turno: o primeiro tool foi query, Read em massa, ou dump de CLI? O que você cortaria na próxima?

Ownership não é o PR. É não deixar o problema só na sua cabeça

Tiago Vilas Boas (Montanha) — Thu, 27 Aug 2026 18:01:31 +0000

Pessoal, tem um padrão que eu vi demais em time que já sabe entregar.

O erro está no board de observabilidade há meses. Alguém já comentou no canal. Suporte eventualmente reclama. Nunca virou card. Um dia vira incidente.

Aí a pergunta aparece, desconfortável: de quem era a responsabilidade?

Eu costumava responder errado. Ownership, pra mim, era pegar o código. Se eu vi, eu conserto. Ou o contrário: se não tem task, não é comigo. Os dois lados quebram o time.

O que você leva daqui: uma distinção de uma frase e um ritual de três perguntas. Ver um problema não te obriga a implementá-lo. Obriga você a não fingir que não viu.

Tabela de Conteúdo

1. Todo mundo via. Ninguém possuía
2. Quatro posturas: a pergunta muda
3. See it, own it. OWN não é CODE
4. Evidência antes de feeling
5. Três perguntas, três saídas
6. Onde o seu time para?

1. Todo mundo via. Ninguém possuía

O salto não é de júnior pra Staff. É de pergunta.

Enquanto a unidade for o card, o time otimiza “done”. O problema que não virou card continua existindo. Só mudou de lugar: saiu do board e foi morar na cabeça de três pessoas.

Eu fiquei um tempo nos dois extremos. Herói (vi, então eu implemento). Ou espectador (não tem task, não é comigo). Os dois normalizam o mesmo buraco: o sistema não tem dono do problema, só dono do ticket.

2. Quatro posturas: a pergunta muda

Nenhuma é “errada” sozinha. O problema é o time inteiro parar no primeiro degrau.

Postura	Pergunta que guia	Sinal
Task	“Está done?”	Fecha o card sem olhar comportamento em produção
Delivery	“Está em produção?”	Acompanha o deploy, não o resultado
Outcome	“Resolveu o problema do usuário?”	Olha métrica depois do merge
Ownership	“O que mais está errado aqui?”	Percebe o adjacente sem esperar task

Task e delivery

Task pergunta pelo card. Delivery pergunta pelo deploy. As duas são necessárias. Nenhuma das duas pergunta se o usuário parou de sofrer, nem se o modo de falha do lado ainda está aberto.

Outcome e ownership

Outcome pergunta pelo resultado. Ownership pergunta pelo sistema: o que mais está errado aqui, mesmo sem task.

Ownership não substitui as outras. Ela impede que o time chame de “resolvido” o que só foi movido.

3. See it, own it. OWN não é CODE

Na prática eu uso quatro passos. Nomes feios de propósito, pra não virar poster.

SEE          percebi algo estranho
UNDERSTAND   isso importa? recorrente? quem se ferrar?
EXPOSE       o problema precisa de dado, não de feeling
OWN          existe decisão ou dono. Inclusive “aceitamos o risco”.

OWN não significa CODE.

Pode ser um card com contexto de verdade. Uma conversa com quem prioriza. Um parágrafo escrito. Uma investigação com prazo. Inclusive: “vamos conviver com isso por enquanto”, desde que isso seja decisão, não esquecimento.

Se ownership virar “quem viu implementa”, o Senior/TL vira o único adulto da sala. Isso não escala. E queima gente boa.

O que isso não é

Ownership não é resolver tudo que passar na timeline, furar priorização porque você ficou inquieto, trabalhar fora do horário pra “provar” que é dono, nem caçar culpado no post-mortem.

Se o framework criar ansiedade, ele falhou. O objetivo é sistema mais saudável, não indivíduo exausto.

4. Evidência antes de feeling

“Corrigimos um bug” é output.

O que costuma destravar priorização é outra frase:

Problema → evidência → impacto → ação → (depois) resultado.

Exemplo sintético, de propósito:

Uma API crítica seguia respondendo 200. Em três semanas o P95 foi de ~400 ms para quase 2 s. Ninguém tinha aberto incidente porque “ainda funciona”. Alguém colocou o gráfico no canal e perguntou o que tinha mudado. Aí deixou de ser feeling.

Sem número, o problema compete com o backlog e perde. Com número, ele vira escolha consciente.

DORA coloca o dedo nisso há anos: time de alto desempenho não é só o que mergeia rápido. É o que detecta e responde. Achar tarde custa mais. A indústria de qualidade, incluindo trabalhos associados ao NIST, repete isso em variações. O ponto prático pra mim não é o fator exato. É que “ainda está 200” não é saúde.

5. Três perguntas, três saídas

Dá pra usar numa retro, num 1:1 ou sozinho no fim da semana. Cópia solta: gist do radar.

Que problema você viu nas últimas duas semanas que ninguém está tratando?
Se continuar um mês, o que piora (usuário, on-call, lead time)?
Quem deveria ser o owner, ou quem decide que não tem owner agora?

Ignorar, investigar ou abrir card

Cada item sai com um status, sem teatro:

ignorar com consciência (risco aceito, data pra rever);
investigar (hipótese + evidência);
abrir card (com as duas linhas de cima, não “olhar depois”).

Quinze minutos de retro bastam: cada pessoa traz um item. Sem ranking de herói. Se ninguém trouxer nada, o dado também vale: ou o sistema está saudável, ou o time ainda não se sente seguro pra expor.

Se a mesma coisa aparecer toda quinzena, o problema não é o card. É o sistema que ensinou o time a esperar o card.

A frase que eu ainda seguro em público:

Seu trabalho não termina quando o código funciona. Termina quando o problema deixa de existir, ou quando você garante que alguém é responsável por fazê-lo deixar de existir.

6. Onde o seu time para?

Não preciso do seu pior incidente. Quero a postura.

No último problema chato que todo mundo já via: vocês ignoraram com consciência, investigaram ou abriram card? E o que impediu a opção que vocês não escolheram?

Referências

O framework SEE → UNDERSTAND → EXPOSE → OWN e a distinção OWN ≠ CODE são síntese minha. Os links abaixo são o contexto público que usei pra amarrar “detectar tarde custa” e “entrega ≠ resultado”:

Accelerate State of DevOps Report 2023 (DORA)
DORA: capacidades e four keys
NIST: The Economic Impacts of Inadequate Infrastructure for Software Testing (2002; o “quanto mais tarde, mais caro” que o mercado cita)
Stripe: The Developer Coefficient (tempo gasto em legado / débito; leitura complementar)

Por que um Staff Engineer está estudando AI Security

Tiago Vilas Boas (Montanha) — Mon, 03 Aug 2026 07:15:17 +0000

Pessoal, a pergunta do meu trabalho mudou.

Antes: como eu faço esse agente entregar mais rápido?

Agora: se esse agente tem ferramenta, o que ele pode quebrar, e quem assume o risco?

A trava que você cola no PR amanhã: sete perguntas antes de dar tool access a um agente. Se alguma resposta ficar vaga, a tool não entra.

Não escrevo como expert. Em agosto de 2026 comecei Defesa Cibernética na Impacta. Este post é o marco zero público.

Tabela de Conteúdo

1. A pergunta mudou
2. Texto errado é uma coisa. Ação indevida é outra
3. O caso que eu já rodei. O rm é o desenho
4. Sete perguntas antes da tool entrar no agente
5. Qual trava você colocaria primeiro?

1. A pergunta mudou

Eu passo o dia em cima de sistema sob pressão: confiabilidade, observabilidade, incidente, decisão que precisa continuar fazendo sentido quando eu saio da sala. Nos últimos tempos, passei a operar de verdade com LLM, agente, MCP e memória/RAG.

Staff, pra mim, nunca foi aparecer em tudo. Foi construir condições para que as squads tomem boas decisões sem depender da minha memória.

Isso cria um reflexo meio chato: olhar pra demo bonita e perguntar pelo modo de falha.

O webhook falha como?
O retry duplica o quê?
Essa métrica explica impacto ou só joga stacktrace na tela?
Tem kill switch ou a gente só torce?

Agora esse mesmo reflexo precisa olhar pra prompt, ferramenta, memória e permissão de agente. Não porque eu mudei de carreira da noite pro dia. Porque a unidade de risco mudou.

2. Texto errado é uma coisa. Ação indevida é outra

Quando o modelo só gera texto, o estrago costuma ser contido: chato, caro às vezes, mas contido. Alucinação, vazamento por descuido, resposta ruim.

Quando o mesmo modelo ganha ferramenta (ler arquivo, chamar API, abrir PR, mexer em dado, acionar automation), o jogo muda.

Aí o risco deixa de ser só “falou besteira”. Passa a ser:

fez uma ação irreversível com confiança alta demais;
tinha permissão bem maior do que o trabalho pedia;
puxou pro contexto uma informação que não deveria sair dali;
conectou um MCP/skill poderoso sem auditoria decente.

Isso não é paranoia de blog. A OWASP chama o desenho de Excessive Agency (LLM06:2025): tool demais, permissão demais, autonomia demais. O NIST AI RMF fala a mesma coisa em linguagem de governança. Eu estudo pelos dois. O gate mais abaixo é o dia 1 no desk.

A leitura de Staff que eu carrego é bem direta:

Acelerar agente sem olhar permissão é otimizar velocidade com o cinto solto.

3. O caso que eu já rodei. O `rm` é o desenho

O caso meu no ar não é shell em prod. É texto.

No 09 eu quase mandei 23 “vulnerabilidades” pra maintainer. XSS fantasma, CORS, um SVG. Volume. Se eu fosse o cara do outro lado da issue, eu levaria isso a sério? Parei. O que vingou foi hardening público e silêncio quando a invariante segurou. O denominador está lá. Aqui não reconto os findings.

No gate, isso é pergunta 1 e pergunta 7. A ação irreversível era abrir issue com ruído. O que impediu o dano fui eu na porta, não o modelo. HITL. Blast radius do texto.

Este post é a outra ponta. Não o que o agente afirma. O que ele pode executar.

Desenho do gate. Pedagógico. Não é o caso acima.

você:     limpa os temporários da pasta de build
agente:   rm -rf ./build ../tmp
          (prestativo. path saiu da pasta. token ainda chama API)
você:     quase dá enter

Sem allowlist de path, sem dry-run, sem humano no rm, o modelo não “alucinou um ensaio”. Montou o rm na leitura generosa de “temporários”.

O gate, preenchido neste desenho. Resposta vaga = a tool não entra.

#	Pergunta	Neste desenho	Entra?
1	Ação irreversível mais cara	`rm` no tree. Token que chama API.	Não
2	Menor escopo que ainda resolve	Token amplo “pra não travar”.	Não
3	Precisa escrever, ou leitura basta?	Escrita porque senão não demo.	Não
4	O que no contexto não deveria sair	Nota interna misturada no ticket.	Não
5	Como detecta abuso ou erro	Sem dry-run. Sem log do comando.	Não
6	Kill switch, com dono	Ninguém nomeado pra revogar o token.	Não
7	Se alucinar a intenção, o que impede o dano	Sem allowlist de path. Sem HITL no `rm`.	Não

Sete vagos. A tool não entra. LLM06 neste caso não é paper. É essa tabela. O caso meu, com issue, já está no 09: mesma disciplina, outra porta.

4. Sete perguntas antes da tool entrar no agente

Copia, cola no PR da automação, e não segue em frente sem responder. Cópia solta: gist do gate.

## Tool access gate (agente)

1. Qual é a ação irreversível mais cara que essa tool permite?
   (apagar, pagar, publicar, exfiltrar, merge, deploy)
2. Qual é o menor escopo de permissão que ainda resolve o trabalho?
3. O agente precisa de escrita, ou leitura bastaria na maior parte do tempo?
4. O que entra no contexto (RAG/memória) que não deveria sair dali?
5. Como eu detecto abuso ou erro? (log, audit trail, alerta, dry-run)
6. Qual é o kill switch? (revogar token, desligar tool, pausar automation)
7. Se o modelo alucinar a intenção, o que ainda impede o dano?
   (allowlist, HITL, confirmação humana, sandbox)

No fundo, as sete perguntas tentam aplicar princípios antigos (menor privilégio, redução de blast radius, auditabilidade, defesa em profundidade) a uma interface nova: o agente. Capability boundaries e human-in-the-loop entram aí sem drama.

Se alguma resposta ficar vaga

Regra de bolso:

Se alguma resposta ficar vaga, a tool não entra no agente.

Leitura vs escrita é a ramificação que mais gente pula. “Precisa escrever porque senão não demo” não é menor escopo. É conveniência. Kill switch sem dono também não conta: se ninguém sabe quem revoga o token, você não tem kill switch.

É a trava mínima pra gente não confundir produtividade com negligência.

5. Qual trava você colocaria primeiro?

Este texto para no gate. O dia 1. O caso que eu já rodei está no H3, no 09. RAG, MCP e fine-tuning como camada é o 10. Sem calendário.

Filtro que eu uso, pra não trocar de hobby toda semana:

Isso me deixa mais confiável com agente, ou só me distrai com logo novo?

Você já viu um agente receber mais permissão do que precisava? O que colocaria como primeira trava: allowlist, sandbox, aprovação humana ou token restrito?

Caso concreto fica opcional. O gate preenchido no rm já dá pra responder. O 09 também.