DEV Community: Alessandro Nunes

Cache impecavel e o app continuava lento

Alessandro Nunes — Sat, 25 Jul 2026 14:39:17 +0000

Trocar de página no meu SaaS estava arrastando. Não era lentidão de deixar o usuário esperando dez segundos, era aquela demora curta e constante que faz o app parecer barato. Sentei pra resolver com a hipótese pronta na cabeça: falta cache em algum lugar.

Estava errado, e a hipótese errada era exatamente o que me impedia de achar o problema. O gargalo não estava em nada que eu pudesse cachear. Estava numa camada que eu tinha parado de enxergar faz tempo, porque ela funciona bem demais pra chamar atenção.

O que eu já tinha, e por que não adiantava nada

Vale começar por aqui, porque é a parte contraintuitiva. Cache no meu projeto não é improviso. Tem duas fachadas finas, TenantCache e GlobalCache, que embrulham o cache do Laravel e garantem três coisas: toda chave nasce com escopo de time (t{teamId}:{domínio}:{sufixo}), toda entrada nasce com TTL vindo de um enum (não existe "cachear pra sempre") e toda entrada nasce com tag pra invalidação em bloco. Tem flexible pro stale-while-revalidate nos lugares quentes, tem observer invalidando por domínio quando o dado muda, e tem teste de arquitetura proibindo Cache:: e cache() direto no código de domínio, pra ninguém (nem a IA, nem eu às 2 da manhã) furar a fila.

É a parte da infra que eu tenho mais orgulho. E ela não tinha nada a ver com o problema.

A lição, que eu só entendi depois de perder um tempo bom procurando no lugar errado: cache resolve computação cara que se repete. Ele não resolve payload que é remontado do zero em toda navegação. Se o custo é "vinte queries baratinhas que rodam sempre", cache não te salva, porque não tem uma resposta cara pra guardar. Só tem muita coisa pequena acontecendo demais.

Onde estava, de verdade

No Inertia, cada navegação é um request completo pro servidor. E existe um lugar central, o HandleInertiaRequests, que monta os props compartilhados que toda página recebe: usuário logado, times do usuário, time atual, permissões, features do plano, contadores da navegação. Isso remonta em toda navegação. É o código mais executado do sistema inteiro, e o que menos aparece quando você vai investigar performance, porque ninguém abre o middleware de shared props procurando query lenta.

Liguei o log de queries e contei. Um usuário com 10 times pagava 27 queries por navegação. Duas causas, e as duas são clássicas com fantasia nova.

A primeira é um N+1 escondido atrás de um método de conveniência. O toUserTeams() carrega os times numa query só, bonito, e depois mapeia cada time pra montar o payload. Só que dentro desse map ele chama teamRole($team) pra saber o papel do usuário naquele time, e o teamRole() era uma query. Uma por time. O eager loading estava lá, na relação errada: eu carregava os times e continuava buscando as memberships uma a uma. Cada time novo que o usuário entrasse adicionava uma query a cada clique dele no app pra sempre.

A segunda foi a que mais me irritou, porque é uma pegadinha específica de Inertia. Os props são closures, e closures avaliam de forma independente:

// app/Http/Middleware/HandleInertiaRequests.php
'currentTeam'     => fn () => $this->resolveCurrentUserTeam($user),
'teamPermissions' => fn () => $user->toTeamPermissions($this->resolveActiveTeam($user)),
'teamFeatures'    => fn () => $this->teamFeatures($this->resolveActiveTeam($user)),
'teamTrial'       => fn () => $this->teamTrial($this->resolveActiveTeam($user)),

Quatro props diferentes precisam do time ativo, e o resolveActiveTeam resolvia tudo do zero nas quatro vezes: lê a sessão, busca o time, confere se o usuário pertence a ele. Quatro vezes o mesmo trabalho, todo request. Não tem nada de errado com o código de cada linha isolada, e é justamente por isso que passa despercebido em code review: o problema não está em nenhuma delas, está no fato de serem quatro.

O conserto das duas cabe em pouca coisa. Carrega a relação uma vez, no ponto onde o payload é montado:

// app/Http/Middleware/HandleInertiaRequests.php
// Uma leitura de membership pro payload inteiro: teams, currentTeam e
// teamPermissions todos resolvem papel, e toUserTeams() faz isso uma vez por time.
$user?->load('teamMemberships');

E o teamRole() passa a preferir a relação quando ela já está em memória:

// app/Concerns/HasTeams.php
public function teamRole(Team $team): ?TeamRole
{
    if ($this->relationLoaded('teamMemberships')) {
        return $this->teamMemberships->firstWhere('team_id', $team->id)?->role;
    }

    return $this->teamMemberships()->where('team_id', $team->id)->first()?->role;
}

Mais a memoização do time ativo, e são 15 queries em vez de 27. O número menor é bom, mas não é o ponto. O ponto é que agora é constante. Antes, o custo de cada navegação crescia junto com a quantidade de times do usuário, o que significa que o app ficava mais lento exatamente pros clientes mais engajados. Esse é o tipo de curva que você não quer descobrir em produção.

A correção óbvia quebrou 208 testes, e ela estava certa em quebrar

Agora a parte que interessa mais que o ganho.

Se teamRole() fica mais rápido lendo da relação carregada, o belongsToTeam() também deveria, certo? É a mesma tabela, a mesma pergunta, e ele é chamado várias vezes por request. Fiz a mudança óbvia. 208 testes ficaram vermelhos.

O primeiro impulso quando 208 testes quebram de uma vez é achar que os testes estão errados, ou que é setup de teste, alguma coisa de fixture. Não era. Era um bug de verdade, e o cenário é este:

O usuário aceita um convite pra um time. No meio desse request, a membership é criada no banco. Logo depois, no mesmo request, o switchTeam() chama belongsToTeam() pra confirmar que ele pode entrar naquele time antes de trocar. Com a relação carregada em memória, essa leitura devolve o estado de antes da escrita que acabou de acontecer. A membership existe no banco, e o objeto na memória não sabe. O belongsToTeam() responde "não pertence", o switchTeam() desiste, e o usuário aceita o convite e continua no time anterior.

Sem erro. Sem exceção. Sem log. A tela recarrega e ele está no lugar errado.

Esse é o mesmo inimigo dos dois posts anteriores com outra roupa. Lá foi um teste verde guardando a porta errada, e uma cláusula falsa escrita com confiança porque era plausível. Aqui é uma otimização legítima que troca correção por velocidade num caminho que ninguém percorre com frequência suficiente pra notar. Otimização não avisa quando quebra alguma coisa. Ela fica rápida e errada, que é bem pior que devagar e certa.

Então belongsToTeam() continua sendo query de propósito, e isso virou comentário no código, porque uma decisão dessas sem o porquê escrito ao lado dura até a próxima pessoa (ou o próximo prompt) achar que está otimizando:

// app/Concerns/HasTeams.php
/**
 * Deliberadamente sempre query, diferente do teamRole(). O switchTeam() gateia
 * nisso logo depois de um convite criar a membership, e uma relação pré-carregada
 * ainda estaria mostrando o estado de antes dessa escrita: a troca falharia calada
 * e deixaria o usuário no time anterior.
 */

O critério geral que eu tirei disso, e que eu vou levar pros próximos: relação em cache é segura pra leitura de exibição, e perigosa pra leitura de decisão. Montar o payload que a tela vai renderizar pode ler de memória à vontade, o pior caso é mostrar um papel desatualizado por um request. Autorizar, gatear, decidir se o usuário pode entrar, isso precisa da verdade do banco naquele instante. E é exatamente por isso que a relação é carregada no middleware, na hora de montar a resposta, e não dentro do model. Se eu carregasse dentro do model, ela ficaria grudada ali pelo resto do request e envenenaria toda decisão que viesse depois.

O teste que trava a regressão sem me atrapalhar depois

Otimização sem teste volta atrás sozinha na terceira feature. Mas eu não queria um teste que trava número absoluto de queries, porque esse tipo de teste vira inimigo: qualquer feature nova que adicione uma query legítima deixa o build vermelho, alguém sobe o número, e em três meses ele não guarda mais nada.

Então o teste principal é de escala, não de contagem:

// tests/Feature/SharedPropsQueryBudgetTest.php
test('props compartilhados custam o mesmo, independente de quantos times o usuário tem', function (): void {
    $user = User::factory()->create();
    $team = $user->currentTeam;

    $comUmTime = queriesForVisit($this, $user->id, $team);

    Team::factory()->count(9)->create()->each(
        fn (Team $extra) => $extra->members()->attach($user, ['role' => TeamRole::Member->value])
    );

    // Se teamRole() virar query por chamada de novo, cada time extra soma
    // uma query a toda navegação do app. Aqui isso fica vermelho na hora.
    expect(queriesForVisit($this, $user->id, $team))->toBe($comUmTime);
});

Ele não diz "custe 15 queries", diz "custe o mesmo com 1 time e com 10". Ou seja, ele não me atrapalha quando eu adicionar uma query honesta, e só abre a boca quando alguém reintroduzir a curva.

Duas armadilhas na hora de escrever isso, e as duas fariam o teste passar mentindo. A primeira: o usuário precisa ser rebuscado do banco a cada visita, senão a segunda visita começa com a relação já carregada da primeira e esconde justamente a regressão que o teste existe pra pegar. A segunda: precisa dar Cache::flush() entre as medições, porque o store de array usado em teste sobrevive entre requests, e a segunda visita sairia "mais barata" por servir contador de navegação do cache, um motivo que não tem nada a ver com o que está sendo medido.

E a parte que faltava: eu não media nada

O achado mais constrangedor da sessão não foi o N+1. Foi perceber que eu descobri o N+1 na mão, contando query com log ligado, porque não existia nenhuma medição de performance no projeto. Um SaaS em produção, com fila, com cache tenant-aware, com multi-tenancy, e zero visibilidade de quanto custa um request.

Entraram os dois oficiais do Laravel, com papéis bem separados. Telescope pra local, que é onde você quer ver a lista crua de queries de um request específico. Pulse pra produção, que é onde você quer tendência ao longo do tempo. Telescope é dependência de dev, excluído do package discovery e registrado à mão só quando APP_ENV=local, porque Telescope ligado em produção é ele próprio um problema de performance.

O Pulse tem um detalhe que quase ninguém conta e que vale o post inteiro: no default, ele grava direto no banco, em todo request. Ou seja, se você instalar e sair usando, as tabelas pulse_* viram o gargalo que o Pulse existe pra medir. As travas que eu coloquei:

Trava	Por quê
`PULSE_INGEST_DRIVER=redis`	Request grava num stream Redis e um daemon (`pulse:work`) drena em lote. É a trava principal.
Redis DB 2, separado	Exigência do próprio Pulse: ele nunca deve dividir conexão com a fila que o Horizon drena.
`PULSE_STORAGE_KEEP="7 days"`	Retenção com poda automática. Sem isso as tabelas crescem pra sempre.
`sample_rate` 0.1 nos recorders de volume	Grava ~10% e escala o número no dashboard.
Recorder de cache desligado	Com `TenantCache` rodando em todo request, registrar cada hit/miss é a via mais rápida de inchar tudo. Ligo só pra investigar taxa de acerto, e desligo depois.

E aí, no meio disso, mais uma falha silenciosa, que já virou o tema da minha vida. O PULSE_STORAGE_KEEP espera uma string de intervalo, "7 days". Se você escrever 7, o CarbonInterval estoura com Invalid part 7 in definition 7. Só que o Pulse engole exceções por design, pra nunca derrubar a aplicação por causa de telemetria. Resultado: a poda falha calada, você não vê nada de errado no app, e descobre daqui a uns meses quando o banco estiver gordo sem explicação. Está anotado no runbook de deploy junto com o resto.

As 3 regras que eu tiro disso

Antes de cachear, conte. Cache é a primeira hipótese de todo mundo e resolve um problema específico: computação cara que se repete. Se o custo é muita coisa pequena rodando sempre, você não precisa de cache, precisa de menos queries. Ligue o log e conte antes de decidir.
Olhe primeiro o código que roda em toda navegação. No Inertia são os shared props, no seu stack vai ser outro nome. É o código mais executado do sistema e o menos revisado, porque ele não pertence a nenhuma feature. Uma query desnecessária ali custa mais que uma query lenta numa página que ninguém abre.
Relação em cache é pra exibir, nunca pra decidir. Ler de memória pra montar a tela, tudo bem. Ler de memória pra autorizar, gatear ou trocar de contexto, não: se alguma coisa escreveu no meio do request, você decide com dado velho e falha sem barulho.

Pra fechar, com honestidade

O ganho real aqui não foi de 27 pra 15 queries, foi trocar uma curva por uma constante. E eu só achei isso porque a hipótese fácil (cache) não colou e eu fui obrigado a medir de verdade.

Ficou dívida à vista, e eu deixei escrita no próprio teste em vez de fingir que não existe: uma página com escopo de time ainda faz quatro checagens de membership por request, duas delas em middlewares que rodam colados e poderiam dividir uma leitura só. O teste trava em quatro com uma regra clara, esse número pode diminuir, nunca aumentar. Se um dia virar cinco, é porque alguém enfiou mais uma checagem no pipeline sem perceber, e eu quero saber no mesmo dia.

Se o seu app tem "aquela lentidão que ninguém explica", meu palpite é que ela não está na página que você está olhando. Vai no seu middleware de props compartilhados, liga o log de query e conta. Me conta o que você achou.

Politica de privacidade e promessa que o codigo precisa cumprir

Alessandro Nunes — Sat, 25 Jul 2026 14:37:18 +0000

Eu estava configurando login com Google, GitHub e Apple no meu SaaS, e pra publicar o app no Google você precisa de uma home pública com link pra termos de uso e política de privacidade. Os meus eram cinco seções de template genérico, daqueles que servem pra qualquer produto e por isso não servem pra nenhum. Sentei pra reescrever querendo uma coisa só: passar autoridade pro revisor.

O que aconteceu foi melhor, e bem mais desconfortável. Quando o documento passou a descrever o que o sistema realmente faz, ele começou a acusar o que o sistema não faz. Política honesta é auditoria de código disfarçada de burocracia, e eu não tinha percebido isso em nenhum dos SaaS que já escrevi.

O que o documento acusou

A política dizia que os dados ficam 30 dias depois do cancelamento e depois são excluídos em definitivo. Bonito, padrão de mercado, e eu tinha certeza de que era verdade porque o meu Team usa SoftDeletes. Fui conferir: não existe um único forceDelete no código de produção inteiro. Um Time excluído há dois anos continua no banco, inteirinho. O soft delete que eu achava que era metade da solução era na verdade o problema, porque ele me dava a sensação de ter implementado retenção quando eu só tinha implementado "não apagar".

E aí veio a parte que me fez rir de nervoso. Fui olhar o outro lado, a exclusão de usuário:

// app/Http/Controllers/Settings/ProfileController.php
Auth::logout();
$user->delete();   // User não usa SoftDeletes. Isso é hard delete, agora.

Ou seja, a mesma frase da política estava errada nas duas pontas ao mesmo tempo, e em direções opostas: o Time ficava pra sempre, o usuário sumia na hora, e nenhum dos dois tinha a tal janela de 30 dias que eu prometia por escrito.

Depois foi a vez dos logs. A política falava em guardar registro de acesso por 12 meses, citando o art. 15 do Marco Civil, que é a coisa certa a se dizer. O meu config estava assim:

// config/activitylog.php
'delete_records_older_than_days' => null,   // null = pra sempre

E esse log grava IP e user agent de toda ação. O art. 15 é prazo mínimo de guarda, nunca foi licença pra guardar eternamente, então eu estava violando o meu próprio documento pra pior.

O terceiro achado foi exportação de dados. A política dizia que o dono do time exporta os dados dele pelo painel, e não existe rota pra isso. O que existe é um endpoint na API que exporta um usuário final, que é outra coisa completamente: é ferramenta pro meu cliente atender os titulares dele, não pra mim atender ele. Eu tinha confundido as duas.

A cláusula falsa que ninguém mentiu pra escrever

Agora a parte que interessa mais que os achados, no mesmo espírito do teste verde que me enganou por meses no post anterior.

Aquela frase sobre exportação de dados no painel foi escrita na mesma sessão, poucas horas antes de eu descobrir que era falsa. Ninguém mentiu. A IA leu o código, viu um DataExportsController, viu que ele exporta dados, e deduziu que existia exportação. É uma dedução razoável, escrita com confiança, e completamente errada. Se eu não tivesse pedido pra conferir cláusula por cláusula contra o código, ela ia pra produção com cara de verdade.

É exatamente o mesmo inimigo do post passado, com outra roupa. Lá, a IA copiava o padrão errado porque ele era o mais visível no código. Aqui, ela escreveu o que era plausível porque plausível é o que ela otimiza. Imitação convincente é o modo de falha, não a mentira. E texto jurídico é o pior lugar possível pra isso acontecer, porque ninguém revisa política de privacidade com o mesmo rigor que revisa um pull request. O documento passa batido justamente por ser chato.

Identidade em config, não no texto

Duas coisas viraram código e valem pra qualquer projeto.

A primeira é boba e resolve uma dor real: tirar a identidade da empresa e os prazos de dentro do texto. Virou um config/legal.php com razão social, CNPJ, endereço, foro, emails e os prazos de retenção e de resposta. O texto legal só interpola :taxId, :retentionDays, :privacyEmail. Mudar de endereço agora é uma linha de env em vez de uma caçada em dois idiomas, e o prazo publicado passa a ter um lugar único de verdade.

Teve um detalhe pequeno aí que eu gostei mais do que devia. O default vazio renderiza "inscrita no CNPJ sob o nº ." e ninguém enxerga isso numa revisão, porque o olho pula frase quebrada em texto jurídico. Então o default virou [CNPJ] literal, que é impossível de publicar sem querer.

O gate, porque regra sem gate é sugestão

A segunda é a que fecha o ciclo. Se o texto interpola :taxId e a chave não existir na config, o Laravel não dá erro: ele renderiza :taxId literal, cru, no meio da política. O leitor vê, eu não. É falha silenciosa, que é o tipo que eu mais odeio.

Então o texto legal ganhou um teste que varre todas as strings, extrai cada token e falha se ele não tiver par:

// tests/Feature/LegalPagesTest.php
// Token sem par não dá erro, renderiza literal. Este teste transforma isso em falha.
foreach ($matches[1] as $token) {
    $this->assertContains(
        $token,
        $known,
        "landing.{$key} interpola :{$token}, que não é compartilhado em config/legal.php",
    );
}

Junto com ele, um teste que percorre as 29 seções dos dois documentos nos dois idiomas e falha se qualquer uma resolver pra vazio. É a mesma tese do post anterior aplicada num lugar que eu nunca tinha pensado em testar: se importa, vira teste que quebra o build. Política de privacidade importa, então vira teste como qualquer outra regra que eu levo a sério.

O que fez o documento parar de parecer genérico

Uma coisa que eu não esperava: o que dá autoridade não é o documento ser bem escrito, é ele bater com o que o app faz.

O meu produto tem dois papéis ao mesmo tempo. Eu sou controlador dos dados da conta do meu cliente (cadastro, login, cobrança), e operador dos dados dos usuários finais dele, que chegam pelo widget que ele instala no produto dele. São regimes jurídicos diferentes, com responsabilidades diferentes, no mesmo banco de dados. Nenhum template tem essa distinção, porque template não sabe o que o seu produto faz.

Colocar isso em seção própria foi o que mudou o texto de "genérico bonito" pra "esse cara sabe do que está falando". E é justamente a primeira coisa que o jurídico de um cliente B2B maior vai procurar.

As 3 regras que eu tiro disso

Escreva a política contra o código, não contra um template. Cada cláusula é uma afirmação verificável sobre o seu sistema. Se você não consegue apontar o arquivo que cumpre a frase, a frase é ficção.
Prazo publicado é prazo exigível. No minuto que você escreve "30 dias" ou "12 meses", isso deixou de ser aspiração e virou dívida. Ou o agendador cumpre, ou o número sai do texto.
Texto jurídico também merece gate. É o lugar onde falha silenciosa mais sobrevive, porque ninguém revisa com carinho e o failure mode não é erro, é o usuário lendo :taxId no meio da sua política.

Pra fechar, com honestidade

Eu não publiquei nada disso ainda. As três falhas viraram issue no meu repo, e a da retenção é bloqueante: enquanto Time excluído ficar pra sempre no banco, o documento promete o que o código não faz, e publicar assim é trocar um problema de template por um problema de LGPD. A poda de log é a mais barata das três, config mais uma linha no agendador, e ainda assim estava lá.

As frases falsas eu corrigi na hora pra descreverem o processo real de hoje, que no caso da exportação é um pedido manual por email. É menos bonito que "exporte pelo painel" e tem a vantagem de ser verdade.

Se você tem um SaaS rodando agora, faz um teste: abre sua política de privacidade e escolhe uma frase, qualquer uma, que prometa prazo. Vai no código procurar quem cumpre. Me conta o que você achou.

Testes de arquitetura como guardrail pra IA

Alessandro Nunes — Sat, 11 Jul 2026 13:52:24 +0000

Eu construo SaaS sozinho e programo com IA o dia inteiro, ela é rápida, entrega feature, resolve bug às 2 da manhã, mas ela tem um defeito que ninguém te conta no começo: ela não respeita a sua arquitetura. Ela lê o padrão, concorda com você, e cinco prompts depois copia o jeito errado que já existe no código, porque o objetivo dela é "fazer funcionar", não "manter o padrão".

Eu descobri isso do jeito mais concreto possível: mandei fazer uma auditoria no meu próprio SaaS e o resultado foi que 89 pontos do código chamavam uma classe do jeito que o meu próprio manual de arquitetura proíbe, contra só 6 no jeito certo, o errado tinha virado a maioria, e cada vez que eu pedia uma feature nova, a IA olhava, via que "todo mundo faz assim", e fazia igual.

A lição não é "pare de usar IA", é que o que importa de verdade você não protege com documentação, protege com um teste que quebra o build, esse post é sobre a técnica que está segurando a minha barra, e sobre o furo dela que me ensinou mais que o acerto.

Documentação não segura a IA

Eu tenho um CLAUDE.md e ADRs (registros de decisão de arquitetura) caprichados. A IA lê, e ignora quando dá, não por má vontade: é que um arquivo de texto é um pedido, não uma barreira, e no modo "só entrega logo", pedido perde pra imitação toda vez.

O que a IA não ignora é um teste vermelho no CI, ela não consegue passar por cima de um build quebrado, então a regra que eu adotei é simples:

Se uma decisão de arquitetura importa de verdade, ela vira um teste automatizado. Se ela não vale um teste, ela não vale um parágrafo no CLAUDE.md, é só preferência.

Regra que importa vira teste que quebra o build

No Laravel isso é barato com o arch testing do Pest. Você descreve a regra em linguagem quase natural:

// tests/Arch/ArchitectureTest.php

// Controllers não tocam no banco direto: quem faz isso é a camada de dados
arch('controllers não usam a facade DB')
    ->expect('App\Http\Controllers')
    ->not->toUse('Illuminate\Support\Facades\DB');

// Toda Action tem que morar no lugar certo e ter o sufixo certo
arch('actions seguem a convenção')
    ->expect('App\Actions')
    ->toBeClasses()
    ->toHaveSuffix('Action');

Isso já mata uma classe inteira de "criatividade" da IA: ela não consegue enfiar uma query no controller sem o build reclamar. Escreveu, ficou vermelho, ela mesma corrige.

O pulo do gato: a baseline que só encolhe

O problema real não é começar limpo. É que você já tem código bagunçado (seu ou gerado por IA) e não dá pra consertar tudo hoje. Se você liga a regra agora, o build fica vermelho em 200 lugares e você desliga a regra, aí não vale nada.

A solução que eu uso (e que um revisor externo elogiou como rara) é uma baseline que só pode encolher. Você congela a lista de violações que já existem, mas escreve o teste de um jeito que essa lista nunca cresce e ainda te obriga a limpar:

// Dívida herdada. A regra de ouro: essa lista SÓ diminui.
const LEGACY = [
    'App\Http\Controllers\Tickets\TicketsController',
    // ... o que já infringe hoje
];

test('sem violação nova, e a dívida velha só encolhe', function () {
    $violacoes = encontrarViolacoes(); // varre o código e devolve os infratores

    // 1) Código NOVO não pode infringir: nada fora da baseline
    $novas = array_diff($violacoes, LEGACY);
    expect($novas)->toBeEmpty(
        'Código novo quebrando o padrão: ' . implode(', ', $novas)
    );

    // 2) O truque: se você consertou um arquivo, ele TEM que sair da baseline.
    //    Esqueceu de tirar? Teste vermelho. Isso força a lista a encolher.
    $jaCorrigidas = array_diff(LEGACY, $violacoes);
    expect($jaCorrigidas)->toBeEmpty(
        'Remova da baseline (já corrigido): ' . implode(', ', $jaCorrigidas)
    );
});

A segunda asserção é o coração de tudo. Sem ela, uma baseline vira um tapete pra empurrar sujeira pra baixo. Com ela, cada limpeza é obrigatória de registrar, e o número só cai. É a diferença entre "dívida técnica documentada" e "dívida técnica que se paga sozinha com o tempo".

O invariante mais importante ganha um guarda em produção

Tem uma regra que eu não confio nem no teste: isolamento entre clientes (multi-tenancy). Um where esquecido não dá erro: vaza dado de um cliente pro outro, calado. Pra esse caso, além do escopo automático, eu tenho um guard que estoura uma exceção em produção se o escopo de tenant não foi aplicado numa query que deveria ter. Cinto e suspensório. É o tipo de coisa onde "provavelmente está certo" não é aceitável.

O teste verde que me enganou

Agora a parte que interessa mais que os acertos.

Lembra dos 89 call-sites errados? Eu tinha um arch test pra Actions. Ele estava verde o tempo todo, enquanto 89 lugares faziam o proibido.

Como? Porque o teste checava a coisa errada. Ele garantia que certos métodos estavam na baseline, e não o estilo de invocação, que era justamente onde a IA driftava. O guardrail existia, passava no CI, me dava uma falsa sensação de segurança, e guardava a porta errada. E como o estilo errado era o mais visível no código, a IA copiava ele por imitação a cada feature nova. O teste verde estava, na prática, abençoando o drift.

A lição doeu e é a melhor que eu tenho pra te dar: verde não quer dizer certo, quer dizer que aquilo que eu de fato testei está ok. Se você nunca viu o teste ficar vermelho, você não sabe o que ele guarda.

As 3 regras que eu tiro disso

Se importa, vira teste que quebra o build. CLAUDE.md e ADR a IA lê e contorna sob pressão. Vermelho no CI ela não contorna.
Baseline que só encolhe. Você não precisa consertar tudo hoje, mas o débito não pode crescer, e limpar tem que ser obrigatório de registrar.
Escreva o caso que falha primeiro. Antes de confiar num guardrail, quebre o padrão de propósito e veja o teste ficar vermelho. Um guardrail que nunca viu vermelho provavelmente está guardando a porta errada. Foi exatamente o meu caso.

Pra fechar, com honestidade

Meu SaaS está no meio dessa migração agora, enquanto escrevo isso. Não é código perfeito, é código real, com guardrails reais, um deles furado, sendo consertado à luz do dia. Nos próximos posts eu vou mostrando cada etapa da limpeza: como eu deduplico dois controllers que a IA clonou, como converto o padrão de Actions domínio a domínio, e como eu fecho o furo daquele teste pra ele parar de mentir pra mim.

Se você também constrói com IA e sente que o código foge do controle, esse é o caminho que está funcionando pra mim. Me conta o seu.