DEV Community: Vinícius Mendonça

BDD e Gherkin na era da IA: por que escrever em linguagem natural ficou mais importante, não menos

Vinícius Mendonça — Fri, 05 Jun 2026 11:45:35 +0000

Numa manhã qualquer, você pega o card: "Implementar cancelamento de pedido". Você faz tudo certo: passa o contexto para a IA, mapeia os estados do pedido, revisa com cuidado o código que voltou e os testes passam. Você não foi preguiçoso, foi um bom desenvolvedor usando uma boa ferramenta.

Três dias depois, o comercial relata: "Não estamos conseguindo cancelar um pedido que já foi enviado". E faz sentido o sistema barrar, porque no mercado pedido enviado não se cancela, e foi o que você e a IA assumiram. O que ninguém te contou é que a sua empresa tem um acordo com a transportadora que permite interceptar a entrega, então aqui pode. Essa regra não estava no card nem no prompt, vivia com o time de operação.

E aí está o problema: ninguém errou. A regra existia, mas no lugar errado, na cabeça de algumas pessoas e nunca num formato que o card, o prompt ou o código pudessem consultar. Faltou alguém transformar uma regra de negócio difusa num acordo explícito antes da primeira linha de código.

Esse é o ponto cego que a IA não fechou e que talvez tenha até alargado, porque, embora ela tenha ficado absurdamente boa em resolver o "como", que é traduzir uma intenção clara em implementação, continua dependendo de um humano para definir "o que o sistema deve fazer" e "por quê". E é exatamente aí que mora o BDD, uma prática que muita gente deu como morta na última década e que, na minha leitura, acabou de ficar mais relevante do que nunca.

BDD?

Antes de defender qualquer coisa, preciso garantir que estamos falando da mesma coisa. Se você nunca trabalhou com BDD, ele é uma prática para alinhar, em linguagem natural, como o software deve se comportar em um cenário.

Existem três coisas bem diferentes que costumam ser tratadas como uma só debaixo do nome "BDD", e essa confusão é responsável por boa parte da má fama da prática. Vamos separá-las.

BDD (Behavior-Driven Development), formulado por Dan North por volta de 2006 como uma evolução do TDD, nunca foi sobre técnica e sim sobre conversa. A ideia central era atacar o problema mais caro do desenvolvimento de software (que nunca foi escrever código): escrever o código errado com perfeição técnica, porque dev, QA e negócio entenderam a mesma frase de três formas diferentes. BDD propôs que essas três pessoas sentassem juntas e descrevessem o comportamento esperado do sistema em exemplos concretos, numa linguagem que todas entendessem.

Gherkin é só a notação que saiu dessa conversa, aquele formato Dado / Quando / Então (Given / When / Then) que estrutura um exemplo de comportamento em linguagem quase natural.

Cucumber (e seus primos, SpecFlow/Reqnroll no .NET, Behave no Python, JBehave no Java, Godog no Go) é a ferramenta que pega o texto Gherkin e amarra cada linha a um pedaço de código de teste, transformando a especificação em algo executável.

Quase toda crítica ao "BDD" na verdade é uma crítica ao Cucumber mal usado, e confundir os três é o que fez muita gente jogar a água fora com o bebê dentro.

Guarde essas definições porque elas são a chave do argumento. Quando a discussão vira "IA já escreve os testes, então para que BDD?", quem fala isso está olhando só para o Cucumber, que é a camada mais barata e mais automatizável das três e o valor do BDD nunca esteve aí.

Por que o BDD "morreu"?

O BDD ganhou uma fama ruim, mas confesso que era merecida em boa parte. Eu já vi, e provavelmente você também, o cemitério clássico.

Times que adotaram Cucumber porque era moderno, escreveram trezentos cenários Gherkin que ninguém de negócio nunca leu, e transformaram cada .feature em um teste de integração disfarçado, só que mais verboso e mais frágil.

O Given virava um setup de banco gigante, o When chamava direto um método interno, e o Then fazia assert em campo de DTO, de modo que ninguém do produto chegava perto daquilo, porque era teste automatizado (com um custo de cerimônia) que não pagava nenhum benefício.

Quando o BDD é só isso, ele realmente não vale a pena, e a IA escrever esses testes por você só torna o desperdício mais rápido.

Gherkin que só o desenvolvedor lê não é BDD, e sim um framework de teste de aceitação com sintaxe esquisita. Se a pessoa de negócio ou de suporte nunca lê o Gherkin, você pagou o preço do BDD sem comprar o produto.

Mas na verdade, o diagnóstico de que "o BDD morreu" era parcial, porque ele matou o BDD como tecnologia, aquele que vira framework de teste, mas não tocou no BDD como alinhamento, já que o problema de três pessoas entenderem a mesma regra de três jeitos nunca foi resolvido por ferramenta nenhuma, apenas adiado. E a IA, ao acelerar brutalmente a produção de código, trouxe esse problema adiado de volta para a mesa, agora com urgência.

E aqui vale notar uma ironia que muda a conta. O que matou o BDD da primeira vez foi o custo de manter as step definitions, o código que amarra cada linha do Gherkin ao sistema, e que alguém precisava escrever e atualizar à mão. Só que esse é exatamente o tipo de código mecânico e repetitivo que a IA faz bem e barato. Ou seja, a mesma IA que devolveu urgência ao problema que o BDD resolve também derrubou o custo da parte que fez o BDD fracassar e é por isso que "já tentamos isso e não deu certo" não serve mais como argumento.

O que a IA automatizou e o que ela escancarou

Vou tentar ser "pé no chão" aqui. A IA generativa e agêntica é excelente em pegar uma intenção bem especificada e produzir a implementação, de forma que se você der a ela um comportamento claro, ela escreve o controller, o service, o repositório e o teste. A camada "como o código faz isso" desabou de preço.

Só que ela é tão boa nisso que criou um novo risco, o de produzir a coisa errada com altíssima velocidade e qualidade técnica, já que a IA preenche lacunas: você pede "cancelar pedido" e ela inventa uma regra plausível para o caso de pedido já enviado, porque tem que escrever alguma coisa ali.

A regra inventada parece razoável, passa no teste que a própria IA escreveu, afinal o teste valida a regra que ela inventou e não a que o negócio queria, e, aqui está o ponto, sobrevive até à sua revisão, porque, para reprovar a regra inventada, você precisaria conhecer a verdadeira, e ela não estava escrita em lugar nenhum. Revisão de código só pega o que o revisor conhece, e o que ninguém documentou, ninguém revisa.

Esse é o ponto que quero martelar: a IA não tem o contexto de negócio, ela tem o contexto da internet. E ela não inventa do nada: o contexto da internet diz que pedido já enviado não cancela direto, porque abre uma logística reversa, que gera uma devolução, que dispara uma nota fiscal de entrada e precisa de aprovação fiscal. Essa é a regra mais comum do mercado, e é exatamente por isso que a IA a assume com tanta confiança.

Só que na sua empresa a regra é o oposto, porque pedido enviado pode, sim, ser cancelado, já que a transportadora recebe uma notificação e simplesmente não entrega. Essa regra, a sua, não está em nenhum dataset de treino, está na cabeça da Maria da operação, e o trabalho de extrair isso da cabeça dela e transformar em algo executável é, palavra por palavra, a definição original de BDD.

A IA derrubou o custo de escrever código e, com isso, elevou o custo relativo de especificar o código certo. Onde antes a especificação ruim só atrasava, agora ela se materializa em produção em minutos, porque o gargalo se mudou da implementação para a intenção.

Gherkin como contrato que disciplina o código gerado

Aqui o Gherkin reaparece, e não por nostalgia. Repare na coincidência: a gente passou vinte anos lapidando um formato para alinhar humanos com humanos, e ele acabou sendo quase perfeito como entrada para uma IA.

Pense no que um bom cenário Gherkin é: uma descrição de comportamento, estruturada, em linguagem natural, com exemplos concretos e condições de borda explícitas. É exatamente o tipo de prompt que faz uma IA gerar bom código, e ao mesmo tempo, o exato artefato que permite verificar o que ela gerou.

Veja a diferença entre alimentar a IA com um prompt solto e alimentá-la com um cenário acordado:

# A regra que saiu da conversa entre tech lead, QA e o pessoal de negócio
Funcionalidade: Cancelamento de pedido

  Cenário: Pedido pago e ainda não enviado é cancelado direto
    Dado um pedido no estado "PAGO"
    E que ainda não foi despachado
    Quando o cliente solicita o cancelamento
    Então o pedido deve ir para o estado "CANCELADO"
    E o estorno do pagamento deve ser iniciado

  Cenário: Pedido já enviado é cancelado notificando a transportadora
    Dado um pedido no estado "ENVIADO"
    Quando o cliente solicita o cancelamento
    Então o pedido deve ir para o estado "CANCELADO"
    E o estorno do pagamento deve ser iniciado
    E a transportadora deve ser notificada para não entregar

Primeiro, este Gherkin é um prompt muito melhor do que "crie um endpoint que cancela pedido", porque carrega a regra de negócio que a IA jamais adivinharia.

Segundo, ele é um critério de verificação independente, porque quando a IA gera a implementação, esses cenários automatizados via Cucumber dizem objetivamente se o código fez o que o negócio acordou e não o que a IA imaginou.

A ordem inverte: o humano define o comportamento em Gherkin, a IA implementa e o cenário verifica. O teste deixa de ser derivado do código e vira o contrato que veio antes dele.

Quando a IA escreve o código e o teste do código, ela está marcando a própria prova. O cenário de BDD, definido antes e pela pessoa que entende o domínio, é a única nota que ela não consegue fraudar.

E note que isso não é um exercício de cerimônia, porque o Given/When/Then aqui não é firula, e sim a estrutura mínima para que a regra fique sem ambiguidade tanto para o humano quanto para a máquina.

Gherkin como documentação viva para o suporte

Tem um terceiro uso do Gherkin que, na minha experiência, sozinho já justifica a prática, e que ficou ainda mais valioso agora que o código nasce rápido e some na velocidade dos commits. O cenário Gherkin é a melhor documentação de regra de negócio que existe, porque é a única que não pode mentir sobre o que afirma.

Um cenário Gherkin automatizado é diferente de uma página de documentação mantida manualmente à parte, porque se a regra muda no código e o cenário não é atualizado, o build quebra. Como a documentação e o comportamento estão amarrados pelo CI, não dá para a documentação ficar desatualizada sem alguém ser obrigado a encarar isso, já que a esteira não deixa passar.

Imagine o atendente do suporte recebendo um chamado: "cliente quer cancelar um pedido que já foi enviado, isso é possível?". Em vez de abrir o código, ou pior, perguntar no Teams "alguém sabe a regra de cancelamento?", ele abre a página de features Gherkin e lê:

  Cenário: Pedido já enviado é cancelado notificando a transportadora
    Dado um pedido no estado "ENVIADO"
    Quando o cliente solicita o cancelamento
    Então o pedido deve ir para o estado "CANCELADO"
    E o estorno do pagamento deve ser iniciado
    E a transportadora deve ser notificada para não entregar

Está tudo lá, em português, sem palavrão técnico e com a garantia de que essa é a regra que de fato roda em produção, porque, se não fosse, o build estaria vermelho.

O suporte para de adivinhar, o comercial consegue entender o comportamento sem ler C#, e o dev novo, no onboarding, lê as features como se fossem o manual do domínio, que é exatamente o que elas são.

Documentação que não está amarrada à execução é ficção bem-intencionada. O valor único do Gherkin automatizado é que tudo o que ele afirma o sistema é obrigado a manter verdadeiro, sob pena de não buildar.

Esse benefício sempre existiu, mas ficou mais precioso na era da IA por um motivo específico, porque, quando o código é gerado e regenerado rápido, a memória institucional sobre "por que isso funciona assim" se perde mais fácil ainda. O cenário Gherkin é o que sobrevive à rotatividade do código.

Como isso se parece na prática (e onde a IA entra no fluxo)

Tudo até aqui foi conceito. Mas na prática? O fluxo que faz sentido para mim num time que usa IA pesado no dia a dia:

A conversa continua sendo humana, porque dev, QA e negócio, os "três amigos" do BDD clássico, discutem o comportamento e os casos de borda, e isso a IA não faz por você, já que ela não tem acesso à Maria da operação.

O que a IA pode fazer aqui é ajudar a rascunhar cenários a partir de uma descrição e, principalmente, provocar: "e se o pedido tiver dois itens e só um deles já foi despachado? e se estiver em separação no estoque, conta como enviado ou não?". Ela é ótima como geradora de casos de borda para você aceitar ou rejeitar, mas péssima como autora final da regra.

O Gherkin acordado vira o prompt estruturado, e quando você entrega os cenários para a IA gerar a implementação, o código sai mais certo de primeira porque a intenção estava clara.

Os cenários automatizados via Cucumber viram o portão de qualidade, de forma que o código gerado só passa se satisfizer o comportamento que o humano definiu, e a IA não marca a própria prova.

E os mesmos arquivos .feature ficam no repositório como documentação viva, lidos por suporte, produto e devs novos.

Repare que em nenhuma etapa a IA foi descartada, já que ela acelera a conversa, escreve o grosso do código e até sugere bordas. O que ela não faz é substituir a definição humana do que é certo, e o BDD é justamente o método de capturar essa definição num formato que serve à máquina e à pessoa ao mesmo tempo.

Um exemplo para concretizar a ideia

Imagine um produto que cobra por mensagem enviada, e a tarifa depende de uma janela de tempo, de modo que a mensagem enviada até 24h depois da última resposta do usuário entra numa tarifa, e se passar disso entra em outra, mais cara. É regra de negócio pura, dessas que não têm nada a ver com código e tudo a ver com o contrato da operadora.

Um dev experiente refatora esse trecho com bastante ajuda de IA. O código sai limpo, bem testado, passa em tudo e sobe, mas começa a divergir centavo a centavo na fatura, daquele jeito que ninguém percebe no dia e só nota no fechamento do mês, quando o financeiro pergunta por que o número não bate.

O problema não está no código, que faz exatamente o que foi escrito. É que a janela tinha uma exceção. Digamos que mensagem que responde a um template não conta o tempo do mesmo jeito, que ninguém falou para a IA, e ela, coerente como sempre, preencheu a lacuna com a interpretação mais óbvia, errada para aquele contrato específico. O teste passava porque validava a regra que a IA inventou, que era a prova marcada pelo próprio aluno.

Agora imagine o mesmo caso com BDD na frente. Se aquela regra tivesse virado cenário antes do código, com a janela, a exceção do template e a tarifa de cada caso, a IA teria a regra certa na entrada e o cenário teria reprovado a interpretação errada na saída. O centavo divergente nunca chegaria à fatura, e quando o cliente questionasse a cobrança, o suporte abriria a pasta de features e leria a regra em português, sabendo que é a que roda em produção, porque senão o build não teria deixado subir.

Conceitos bons, contexto errado. A IA não errou o código, ela acertou o código de uma regra que ninguém tinha escrito. Foi a falta do contrato em linguagem natural, não a IA, que custou o fechamento do mês.

Antes de sair escrevendo Gherkin

Esse artigo é sobre por que o BDD voltou a importar, e não um tutorial de como escrever cenários, mas aqui vai o aviso mais importante para quem se animou: a maneira como você escreve o Gherkin decide se ele vai te entregar tudo que prometi acima ou virar mais um teste de integração disfarçado que ninguém de negócio lê.

O erro 1 é escrever Gherkins imperativos, descrevendo a mecânica da tela, com "clico no botão X", "preencho o campo Y", "navego para a página Z". Isso é frágil, porque quebra quando a UI muda, é ilegível para quem não é dev, e perde justamente o valor de documentação:

# Imperativo: amarrado à tela, quebra quando a UI muda, e o negócio não lê
Cenário: Cancelar pedido enviado
  Dado que estou logado como atendente
  E que abri a tela de detalhes do pedido 1234
  Quando clico no botão "Cancelar" do menu lateral
  E confirmo no modal clicando em "Sim, cancelar"
  Então devo ver o texto "Pedido cancelado" no topo da página

O caminho é o Gherkin declarativo, que descreve o comportamento e a regra de negócio, e não o passo a passo da interface:

# Declarativo: descreve a regra, sobrevive a qualquer mudança de tela
Cenário: Pedido já enviado é cancelado notificando a transportadora
  Dado um pedido no estado "ENVIADO"
  Quando o cliente solicita o cancelamento
  Então o pedido deve ir para o estado "CANCELADO"
  E a transportadora deve ser notificada para não entregar

O primeiro fala de botões, modais e textos na tela, enquanto o segundo fala da regra de negócio, sendo a mesma frase que a Maria da operação e o atendente de suporte conseguem ler e confirmar.

A pergunta guia, que vale colar na parede do time, é simples: "se a implementação mudar, essa frase precisa mudar?". Se precisar, então você escreveu mecânica e não comportamento, e o melhor é reescrever pensando em quem vai ler, que é a pessoa de negócio que precisa confirmar a regra e o atendente de suporte que vai consultar o cenário para responder o cliente. Se esses dois não entendem a frase, ela está técnica demais.

Para se aprofundar de verdade, deixo dois pontos de partida que valem mais que dez posts genéricos, que são o texto original do Dan North, Introducing BDD, onde a prática nasce justamente como uma conversa sobre comportamento, e o guia Writing better Gherkin da própria Cucumber, que detalha o estilo declarativo e como manter cenários curtos e centrados no negócio.

Gherkin bem escrito é em linguagem de negócio e suporte, não de UI nem de código. A regra é dizer o que o sistema faz, nunca como ele faz na tela. Se o seu cenário quebra quando você troca um botão de lugar, ele não é documentação de comportamento, e sim teste de interface fantasiado.

O trabalho que sobrou para você

A pergunta de abertura, "a IA escreve código, então para que BDD?", carrega um erro de mira, porque compara a IA com a camada errada do BDD, a do Cucumber, que sempre foi a mais barata e a mais descartável.

O coração do BDD nunca foi automatizar teste, e sim alinhar humanos sobre o que o sistema deve fazer e registrar esse acordo num formato que não pode mentir. A IA não tocou nesse coração, apenas tornou mais barato tudo ao redor dele, e com isso deixou o coração mais exposto do que nunca, porque, agora que escrever código não é mais o gargalo, especificar o código certo virou o trabalho que sobra, justamente o trabalho que a IA não faz por você.

Gherkin, esse formato velho de quase vinte anos, virou três coisas de uma vez na era da IA, que são o prompt que faz a IA gerar o código certo, o contrato que verifica se ela gerou mesmo, e a documentação viva que o suporte lê sabendo que é verdade. Não foi descartado, foi promovido.

E se essa ideia de "a especificação é a fonte de verdade, o código é gerado contra ela" soou maior do que um cenário de cancelamento de pedido, é porque ela é mesmo. Levado ao extremo, esse princípio é o que o mercado passou a chamar de Spec-Driven Development (SDD), onde não só o comportamento, mas também arquitetura, bordas e restrições viram especificação versionada que o agente de IA consome para gerar código, teste e documentação. O BDD é a porta de entrada natural para esse mundo, mas como aplicar SDD numa aplicação de verdade é assunto que merece um artigo só dele, que pretendo escrever em breve.

Se você esquecer tudo desse artigo menos uma coisa, lembre disso: a IA tirou de você o trabalho de escrever o código, mas não tirou, e não vai tirar, o trabalho de decidir qual código é o certo. BDD sempre foi sobre esse segundo trabalho, e ele acabou de ficar o mais valioso dos dois.

Gostou do artigo? Comente abaixo sobre o que ele te fez pensar e que práticas você deseja aplicar. Além disso, comente sobre o que faltou no artigo que é informação importante sobre o assunto.

Evolução natural de software: por que padrões de arquitetura não são exatamente uma boa decisão de começo

Vinícius Mendonça — Mon, 01 Jun 2026 18:06:50 +0000

Você abre o repositório de um projeto novo na sexta de manhã. Está vazio: um README.md, um .gitignore, um arquivo de solução em branco. O ticket diz que o time tem três meses pra entregar a primeira versão de um produto que ainda está sendo desenhado pelo time de negócio, e que precisa de uma API REST com "uns oito endpoints, pode ser que vire mais".

Você respira, abre um post recente no LinkedIn elogiando Clean Architecture, lê de novo a parte sobre use cases e ports & adapters, estrutura de pastas para DDD, e antes de entender o domínio já decidiu a como vai organizar o código do projeto.

Vinte minutos depois, o projeto tem Domain, Application, Infrastructure, Presentation, três bibliotecas de classe, um pacote do MediatR adicionado, AutoMapper e um arquivo IRepository<T> ainda vazio porque você não decidiu se vai usar Dapper ou EF Core. Você sente que fez a coisa certa. O projeto, na sua cabeça, agora tem "fundação".

Venho aqui defender a tese contrária. A decisão de arquitetura que você acabou de tomar é, com altíssima probabilidade, a errada. Não porque Clean Architecture seja ruim, mas porque foi tomada antes de o problema existir. E o custo dessa decisão vai aparecer daqui a seis meses (não amanhã) exatamente quando ela ficar cara demais pra ser desfeita sem dor.

A tese central é simples de falar: padrão de arquitetura nasce da necessidade, não da estética. O resto do artigo é só a defesa dessa tese, com casos, código, e algumas ressalvas pra que ninguém ache que eu estou pregando contra rigor técnico.

Padrões de arquitetura bem conhecidos

Vale citar alguns nomes que dominam a discussão pública hoje, e que provavelmente ocorreram pra você quando leu o parágrafo de abertura. Nenhum deles é propriedade de uma linguagem: você encontra todos em .NET, Java, Node, Python, Go, Kotlin ou qualquer outra.

Clean Architecture, formalizada por Robert C. Martin em 2012, organiza o sistema em camadas concêntricas onde as dependências sempre apontam pra dentro. Regras de negócio ficam no centro, frameworks na borda, e a inversão de dependência garante que o domínio nunca conhece o detalhe técnico. Ela brilha em sistemas com lógica de negócio densa (seguros, banking, saúde), times grandes, integrações externas pesadas, e onde testabilidade alta é requisito de regulação.

Hexagonal, proposta por Alistair Cockburn em 2005, tem a mesma intuição central: isolar o núcleo da aplicação do mundo externo, atravessando essa fronteira por meio de ports & adapters. Resolve o mesmo problema de Clean com vocabulário diferente, e brilha quando há troca frequente de infraestrutura (banco, fila, broker) ou múltiplos canais de entrada (REST, gRPC, CLI, fila).

Vertical Slice, popularizada por Jimmy Bogard por volta de 2018, é filosoficamente o oposto de Clean: em vez de compartilhar abstrações entre camadas, organiza o sistema por feature, e duplica de propósito quando dois slices parecem fazer coisas parecidas. Brilha em sistemas com muitas funcionalidades pouco acopladas e times grandes trabalhando em paralelo, e fracassa miseravelmente quando as features dependem demais umas das outras, virando um projeto "shared" gigante que ninguém ousa tocar.

Repare que esses três nomes são padrões de arquitetura de dentro de uma aplicação: camadas, dependências, organização de pastas. Mas existe uma segunda escala, que também entra nessa discussão, que decide como o sistema se divide em partes que rodam separadas: um monolito, um monolito modular, vários microsserviços, etc.

As duas escalas são a mesma pergunta vista de distâncias diferentes, e a tese desse artigo vale igual nas duas. Vou transitar entre elas ao longo do texto de propósito, porque o erro é o mesmo dos dois lados.

Cada uma dessas opções é boa no contexto certo. Esse contexto é o tema do artigo.

Qual usar?

Aqui está a pergunta natural depois de apresentar esses exemplos: qual deles você deve usar no seu próximo projeto?

A minha resposta, sem retórica de palestra, é: nenhuma.

Calma, não é que arquitetura não importa. É que a decisão de qual arquitetura usar, feita no dia zero, antes de entender o problema, antes de validar o produto, antes de ter dor real, é quase sempre a decisão errada.

Overengineering nasce justamente desse impulso de "fazer bonito desde o começo". A escolha precoce de arquitetura é, na maior parte dos casos, uma decisão estética disfarçada de decisão técnica.

E a primeira coisa que precisamos separar pra que essa tese não vire desculpa pra fazer porcaria é:

Código limpo e arquitetura limpa são coisas diferentes

Existem duas coisas que costumam ser tratadas como uma só, e essa confusão é responsável por boa parte do overengineering que eu vejo.

Código limpo é sobre a qualidade do código em si: como você escreve cada função, cada classe, cada bloco lógico. Nomes claros, funções pequenas, responsabilidades bem definidas, ausência de gambiarras "espertas".

É uma disciplina linha a linha, e na minha opinião deveria ser obrigatório sempre. Não importa se o projeto é um MVP de hackathon, um sistema interno de oito endpoints, ou um produto bem-sucedido em produção. Código limpo não tem desconto.

Arquitetura limpa é sobre como o sistema está organizado, e isso acontece nas duas escalas que eu mencionei: de perto, como você arruma o código dentro de uma aplicação (camadas, dependências, slices, que é onde entram Clean, Hexagonal e Vertical Slice); e de longe, como você divide o sistema em partes que rodam separadas (monolito, monolito modular, minisserviços, microsserviços).

É uma disciplina estrutural, e é contextual nas duas pontas: depende do problema, do time, do momento. E o mesmo erro se repete nas duas escalas, criar cinco camadas pra um CRUD é o mesmo equívoco que quebrar em quinze microsserviços um produto que cabia tranquilo num monolito.

Código limpo é inegociável. Arquitetura limpa é contextual. Não confundir os dois é o primeiro passo pra parar de se enganar.

Quando alguém diz "ah, então eu posso fazer qualquer coisa de qualquer jeito, né?", essa pessoa está confundindo os dois eixos. O código sempre tem que ser limpo. A arquitetura é uma decisão de engenharia que responde a um custo, e que portanto só faz sentido se houver um custo correspondente pra pagar.

O que é overengineering?

Overengineering é fazer mais engenharia do que o problema pede. Não é sobre fazer bem feito. É sobre fazer demais.

Criar use cases, boundaries, entities e adapters quando você só precisa de meia dúzia de operações básicas gera código mais complexo, onboarding mais difícil, velocidade desnecessariamente menor nas entregas (especialmente nas primeiras) e camadas que não resolvem nenhuma dor real. O time fica preso na arquitetura, no "como", em vez de focar no problema.

Tanta "robustez" deixa o sistema frágil pela complexidade desnecessária. Esse é o paradoxo central do overengineering, e é o motivo de ele ser tão difícil de combater: ele se parece com profissionalismo.

Sintomas clássicos (com código)

O melhor jeito de reconhecer overengineering é olhando código. Vou pegar dois sintomas que aparecem com frequência embaraçosa em projetos novos.

Sintoma 1: CQRS num CRUD simples

Imagine o cenário mais comum do mundo: você precisa de um endpoint pra cadastrar cliente. Recebe um JSON com nome, e-mail e CPF, salva no banco, devolve o ID. Eis como muita gente faria isso "profissionalmente" hoje:

// 6 artefatos para inserir um Cliente
public record CreateClienteCommand(string Nome, string Email, string Cpf);

public class CreateClienteCommandValidator : AbstractValidator<CreateClienteCommand>
{
    public CreateClienteCommandValidator() { /* regras */ }
}

public class CreateClienteCommandHandler
{
    private readonly IClienteRepository _repo;
    private readonly IMapper _mapper;

    public async Task<CreateClienteResult> Handle(CreateClienteCommand cmd, CancellationToken ct)
    {
        var cliente = _mapper.Map<Cliente>(cmd);
        await _repo.AddAsync(cliente, ct);
        return _mapper.Map<CreateClienteResult>(cliente);
    }
}

public record CreateClienteResult(Guid Id, string Nome, string Email);

public class ClienteMappingProfile : Profile { /* perfis */ }

// + Controller, DTO de entrada, registro no container DI, etc.

Seis artefatos pra fazer um INSERT. Em alguns sistemas (grandes, com 200 use cases, validação rica, comportamento cross-cutting via pipeline), esse é o caminho certo, e eu não estou atacando CQRS. Mas se você tem oito endpoints de uma área administrativa interna, isso é overengineering puro.

Veja a versão suficiente:

[ApiController]
[Route("api/clientes")]
public class ClientesController : ControllerBase
{
    private readonly AppDbContext _db;
    public ClientesController(AppDbContext db) => _db = db;

    [HttpPost]
    public async Task<IActionResult> Create(CreateClienteRequest req)
    {
        if (string.IsNullOrWhiteSpace(req.Nome) || string.IsNullOrWhiteSpace(req.Email))
        {
            return BadRequest();
        }

        var cliente = new Cliente
        {
            Id = Guid.NewGuid(),
            Nome = req.Nome,
            Email = req.Email,
            Cpf = req.Cpf
        };

        _db.Clientes.Add(cliente);
        await _db.SaveChangesAsync();

        return CreatedAtAction(nameof(Create), new { id = cliente.Id }, cliente);
    }
}

Menos de 20 linhas. Separação entre Request e Entity continua existindo. Nomes continuam claros. Tratamento de erro continua explícito. Nenhuma mágica. Simplicidade não é bagunça. É o ponto principal desse texto.

Esse não é um exemplo de laboratório, eu já vivi ele. Numa época em que eu era tech lead, a gente pegou um projeto pequeno pra um cliente grande: um piloto, antes de pousar, solicitava por um app que o caminhão de reabastecimento já estivesse esperando o avião na vaga. No fundo era um CRUD, criar um pedido de uma ponta, listar os pedidos da outra. Designamos um dev, falamos "é simples, qualquer coisa me chama" e, confesso, não acompanhei como devia, então a culpa boa parte foi minha.

Quando eu olhei, o que era pra ser um INSERT tinha virado CQRS, use cases, command handlers, banco de leitura separado do de escrita. Estourou o prazo, o front ficou de lado e nem ficou bom pro usuário, e o pior veio depois: o dev saiu pra outro projeto e o substituto, fazendo o handover, vinha me procurar meio desesperado dizendo que não conseguia entender se o que estava no card era verdade, de tão emaranhado que estava o código.

Conceitos bons, contexto errado. É exatamente assim que a armadilha pega gente competente.

Sintoma 2: Strategy sem dor real

Outro exemplo: cálculo de frete. Acima de R$ 200, é grátis; abaixo, R$ 20. Lado A, o que muita gente entrega:

public interface IFreteStrategy
{
    decimal Calcular(decimal valor);
}

public class FreteGratisStrategy : IFreteStrategy
{
    public decimal Calcular(decimal v) => 0m;
}

public class FreteFixoStrategy : IFreteStrategy
{
    public decimal Calcular(decimal v) => 20m;
}

public class FreteFactory
{
    public IFreteStrategy Criar(decimal v) =>
        v > 200m ? new FreteGratisStrategy() : new FreteFixoStrategy();
}

Quatro classes, uma interface, uma factory. Pra duas regras fixas. Lado B, a versão honesta:

public class PedidoService
{
    public decimal CalcularFrete(decimal valorPedido)
        => valorPedido > 200m ? 0m : 20m;
}

Uma linha. Strategy é ótimo quando você tem muitas estratégias (Correios, transportadora X, transportadora Y, retirada em loja, frete internacional). Pra duas regras fixas, o ternário é o código profissional, e o Strategy é arquitetura tentando se justificar.

Por que caímos na armadilha

Vale entender por que pessoas competentes, com boa intenção, repetem esse padrão. Eu vejo cinco motivos, e nenhum deles é incompetência.

O senior traumatizado. Quem já apanhou de sistema mal arquitetado tende a superprojetar o próximo, e o trauma vira excesso. É uma reação compreensível, e por isso difícil de notar em si mesmo.
Currículo e status. "Eu uso Clean + CQRS + Event Sourcing" soa melhor numa entrevista do que "eu fiz um monolito modular bem feito". A linguagem técnica que vende é a da sofisticação, mesmo quando a entrega que cria valor é a da simplicidade.
Conteúdo da internet. Posts e cursos vendem sofisticação, porque ninguém viraliza fazendo CRUD simples. O algoritmo recompensa diagrama bonito, e diagrama bonito quase nunca é o do sistema que está em produção dando dinheiro.
Medo de errar pra menos. Parece mais seguro projetar pro futuro do que pro presente, porque "se o sistema crescer e eu não tiver feito assim, eu fui amador". A inversão dessa lógica (se o sistema crescer e eu tiver feito assim sem precisar, eu desperdicei meses) raramente é considerada.
(e talvez o pior) Confusão com profissionalismo. Tem dev que acha que código simples é amador. É exatamente o contrário: escrever simples é o que dá trabalho.

Overengineering raramente vem de má intenção. Vem do impulso de fazer bonito desde o começo, e esse impulso é, paradoxalmente, anti-profissional.

Eu gosto de uma analogia simples pra explicar isso. Imagine alguém com medo de ter câncer no futuro: pesquisa na internet, toma um monte de vitamina, suplemento, remédio, tudo pra se blindar de uma doença que talvez nunca venha. E, no meio dessa preocupação com o futuro distante, esquece de medir a glicose, ignora os sinais do dia a dia, e desenvolve diabetes.

Foi cuidar do problema hipotético e deixou passar o real, o que estava ali na frente, dando sinal. Arquitetura é a mesma coisa: não se blinde contra a escala que talvez nunca chegue ao ponto de não enxergar a dor que o sistema já está sentindo hoje.

Casos reais

Os sintomas acima foram da arquitetura "de perto", dentro do código. Agora subo um nível pra escala "de longe", a de dividir o sistema em serviços, porque é exatamente o mesmo erro com outro figurino, e o caso a seguir mostra as duas coisas acontecendo juntas.

Só que aqui o custo do exagero é bem maior, e vale torná-lo concreto, porque ele costuma ser invisível no dia da decisão. No CRUD, o preço do overengineering eram seis classes a mais. Ao quebrar um sistema em microsserviços antes da hora, o preço é outro: o que era uma chamada de função vira uma chamada de rede, que pode falhar, ter latência e precisar de retry. O que era uma transação de banco vira consistência eventual, e agora você precisa lidar com estados intermediários e outbox, saga, compensação.

Depurar um fluxo deixa de ser um stack trace e passa a exigir tracing distribuído pra entender por onde a requisição passou. Um deploy simples vira coreografia de versões e contratos entre serviços. Nada disso é exótico: é o custo-base de qualquer sistema distribuído, e você paga ele inteiro mesmo que o problema não tivesse pedido distribuição nenhuma.

Eu vou contar uma história, sem nomear a empresa, relatado por um amigo próximo. Uma startup que cresceu rápido. Em 2019, time pequeno, urgência de entregar. O pessoal leu meia dúzia de posts no LinkedIn, achou bonito, e decidiu aplicar Clean Architecture desde o dia zero. Em tudo. Inclusive em serviços de quatro endpoints. E como já estavam "fazendo bonito", quebraram o sistema em microsserviços na mesma pegada.

Em 2024, o que sobrou:

20+ microsserviços para um produto que precisava de quatro
90+ dias de onboarding pra cada dev novo
No mínimo, 6 serviços diferentes pra responder uma única requisição
Repositórios duplicados, sem que ninguém saiba qual é o "oficial"

Repare que a Clean Architecture e os microsserviços foram a mesma decisão, tomada pelo mesmo motivo estético, no mesmo dia zero. E isso é caro, porque desfazer overengineering é tão caro quanto fazer. Overengineering bem-intencionado é o mais perigoso, porque te custa caro duas vezes: uma quando você implementa, outra quando você precisa desfazer.

Antes que pareça que esse é um problema só de startup que não sabe se virar, vale olhar três casos públicos, em ordem crescente de tamanho. Todos giram em torno da mesma decisão de dividir ou não dividir o sistema em serviços, que é onde o custo do exagero fica mais visível.

Basecamp / DHH roda um produto multi-milionário em monolito Rails há mais de vinte anos, e o DHH escreveu textos famosos defendendo a tese do "Majestic Monolith". O argumento dele é direto: a complexidade dos microsserviços só compensa quando há escala humana e técnica que justifiquem o custo.

Stack Overflow atendia bilhões de requisições por mês em um monolito enxuto, sem microsserviços, sem service mesh, sem nada do que costuma se vender em conferência. Nick Craver tem posts famosos descrevendo essa arquitetura, e a parte mais chocante é o quanto ela é, de fato, simples.

Amazon Prime Video, em 2023, publicou um artigo que virou meme da internet, então vale contar direito, porque quase todo mundo cita errado. Não foi "a Amazon abandonou microsserviços". Foi um time específico, o de análise de qualidade de vídeo (VQA), num único serviço, o de monitoramento de streams ao vivo. Esse serviço tinha sido montado com orquestração serverless (Step Functions, Lambdas, frames passando por S3 entre etapas) e bateu num teto de escala a 5% da carga esperada, ficando caríssimo.

A solução foi juntar as etapas num único processo em container (ECS), e isso cortou 90% do custo. A própria AWS depois fez questão de dizer que a lição não é "monolito é melhor que microsserviço", e sim "escolha a topologia certa pro problema certo". Que é exatamente a tese aqui: a empresa que mais entende de microsserviços no mundo recuou num pedaço onde a distribuição custava mais do que entregava.

Repare o padrão: empresas que podem se dar ao luxo da sofisticação escolhem a simplicidade quando ela serve. Quem geralmente cai na cilada do overengineering é quem ainda não tem escala, mas quer agir como se tivesse.

A evolução natural de software

Se a tese for "comece simples", a pergunta justa é: como o projeto evolui sem virar bagunça? A resposta é uma palavra antiga, fácil de citar, difícil de praticar.

YAGNI, ou You Ain't Gonna Need It, é uma das regras originais do Extreme Programming, formulada por Kent Beck nos anos 90. Não implemente nada baseado em uma necessidade futura especulada. Implemente quando a necessidade for concreta, atual, demonstrável.

O motivo de YAGNI funcionar é menos óbvio do que parece. Implementar antes da necessidade não tem só o custo de construir agora; tem três custos:

Construir agora: tempo e dinheiro gastos numa coisa que pode nunca ser usada.
Manter: essa coisa que existe e ninguém usa continua aparecendo em revisão de código, em métrica de cobertura, em refactoring de dependência. Ela pesa.
Remover ou refatorar: quando o futuro vier diferente, e ele sempre vem diferente, você vai precisar tirar essa coisa do caminho, e isso custa mais do que ter resistido à tentação no início.

Esse "o futuro sempre vem diferente" não é força de expressão. Eu trabalho muito com integrações com o WhatsApp, e quem lida com a Meta sabe: num ano eles anunciam que aquele é o jeito definitivo de enviar e cobrar mensagens, você capricha numa estrutura robusta pensando nos próximos três anos, e seis meses depois eles mudam tudo de novo. Toda a engenharia que você antecipou pro futuro vira retrabalho. E isso tem preço, literalmente.

De uns anos pra cá eu passei a ter um CEO que liga a hora do desenvolvedor direto ao caixa: quantas horas esse produto custou, quanto a empresa precisa vender pra ter lucro com ele. Quando você enxerga assim, fica claro que tem hora que a gente gasta tempo entregando uma qualidade que o momento não pedia e esse tempo é dinheiro vazando justamente pelo time de engenharia.

YAGNI não é desculpa pra fazer mal feito. Faça bem feito, mas só o que é necessário agora.

Aqui cabe a ressalva mais importante do artigo, porque é a objeção honesta que todo sênior experiente vai levantar: "mas tem decisão que é cara demais pra desfazer depois". Verdade, e é uma distinção que muda tudo.

A Amazon usa a metáfora das portas de mão dupla e de mão única. A maioria das decisões é porta de mão dupla: se der errado, você volta. Trocar um ternário por um Strategy, extrair um serviço, introduzir uma camada, dá pra reverter num PR. Pra essas, YAGNI manda: decida tarde, decida barato, erre barato.

Mas algumas são porta de mão única, caras ou impossíveis de reverter depois que clientes e dados dependem delas: o contrato público da sua API, o modelo de dados central, a escolha de quebrar a base em vários bancos, a fronteira entre dois serviços que viram repositórios e times separados. Nessas poucas, vale pensar duas vezes e investir um pouco mais de cuidado no dia zero.

O erro não é pensar no futuro. O erro é tratar toda decisão como se fosse de mão única, e portanto enrijecer tudo "por garantia". A disciplina é justamente saber separar as duas: seja agressivamente simples nas decisões reversíveis, que são a esmagadora maioria, e reserve o peso da deliberação pras raras que não dá pra voltar atrás. Overengineering é, no fundo, tratar porta de mão dupla como se fosse de mão única.

Cada decisão arquitetural deve responder a uma dor real. Nenhuma deveria ser feita somente pelo amor à arte.

Quando arquitetura limpa vale a pena

Tudo isso pode soar como uma cruzada contra Clean, Hexagonal, Vertical Slice e microsserviços, e não é. Arquitetura limpa é cara no início e barata no longo prazo, mas só quando o longo prazo existe.

Vale quando...	Não vale quando...
O domínio é complexo e central (banking, seguros, saúde, regulação)	Você está validando produto ou MVP
O time é grande e muitas pessoas tocam no código	Não tem certeza sobre o escopo
O sistema vai existir por anos	Ainda não entendeu as regras de negócio
Há muitas integrações externas	Não sabe se o sistema vai crescer
Testabilidade é requisito (regulação, contrato)	O domínio ainda está sendo descoberto

Se você lê a coluna da direita e reconhece o seu projeto atual, pare de tentar resolver com estrutura o que ainda é problema de descoberta. Estrutura não substitui entendimento de domínio; ela apenas torna a confusão mais cara de desfazer.

Como decidir na prática

Tudo que eu disse até aqui é conceitual. Aqui vai o aterramento: como decidir, na segunda-feira de manhã, no projeto de vocês.

O mínimo profissional

Quando eu defendo "comece simples", não estou defendendo "comece sem nada". Existe um conjunto de fundações que entra em qualquer projeto, independente do tamanho, e que não tem desculpa pra ficar pra depois:

Código limpo e idiomático
Estrutura mínima por feature
Versionamento decente (Git, com mensagens que outro humano consegue ler)
Testes do que dói (talvez não cobertura total, mas o suficiente pra dormir tranquilo)
Logs estruturados
Observabilidade básica
Configuração externalizada
CI/CD mínimo

Nada disso é Clean, Hexagonal, Vertical Slice ou microsserviços. É fundação básica de profissionalismo. Não tem desculpa pra começar projeto sem isso, e ter isso já te dá uma posição muito mais saudável do que ter Clean Architecture sem ter testes.

Quando subir de nível

Duas perguntas guiam isso, e elas são complementares: uma olha pra frente ("estou pronto?"), a outra olha pro presente ("o sistema já está pedindo?").

A primeira é o teste de prontidão, antes de adotar qualquer arquitetura mais elaborada (Clean, Hexagonal, microsserviços).

O domínio está claro?
O escopo é estável, ou ainda há pivotagem provável?
O time vai crescer ao ponto de precisar de fronteiras?

E principalmente: existe um problema concreto que essa arquitetura resolve, que você consiga descrever em uma frase?
Se você não consegue, não está pronto, e "ainda não" é diferente de "nunca".

A segunda pergunta é sobre os sintomas. Você não precisa adivinhar a hora, o sistema avisa:

mexer numa feature simples passou a tocar cinco arquivos espalhados
onboarding de dev novo demora demais; os times vivem em conflito de merge
os testes ficaram lentos ou frágeis; trocar de tecnologia virou épico de backlog
a regra de negócio está espalhada por controllers, services e helpers

Dois ou três desses juntos ao mesmo tempo? Pare de adiar, porque a partir daí o custo de não investir supera o de investir, e a sua "simplicidade sustentável" virou negligência. E note que evoluir não é reescrever do zero: você isola o módulo que dói, extrai o serviço que precisa existir, introduz a camada onde ela ganha o seu sustento, um passo de cada vez.

A regra final

Se você esquecer tudo desse artigo menos uma coisa, lembre disso:

Resolva o problema de hoje com a estrutura mais simples que você consegue manter limpa. Quando o problema mudar, a estrutura te avisa e você a evolui.

É o sistema que te diz "tá na hora de evoluir". Não é um livro, não é uma palestra, não é a moda do mês. É a dor real do dia a dia. Escute essa dor.

Gostou do artigo? Comente abaixo sobre o que ele te fez pensar e que práticas você deseja aplicar. Além disso, comente sobre o que faltou no artigo que é informação importante sobre o assunto

Memory Cache: o bug invisível que só aparece quando sua aplicação precisa escalar horizontalmente

Vinícius Mendonça — Tue, 26 May 2026 14:20:32 +0000

Você implementou um endpoint que busca a timeline de uma conversa, viu que a query era pesada demais pra rodar em todo request, então injetou um cache de memória no controller, configurou expiração de cinco minutos e seguiu a vida.

Nos testes e na homologação tudo se comporta como esperado: o primeiro request paga o custo, os seguintes voltam instantaneamente e o gráfico de latência fica bonito.

Aí o serviço entra em produção em um cluster Kubernetes com três réplicas, porque a empresa cresceu, porque o time finalmente migrou o monolito velho para um ambiente que escala horizontalmente, ou simplesmente porque o Tech Lead não quis mais depender de uma única instância.

E começam a chegar relatos estranhos:

o atendente atualiza a tela e vê a mensagem nova
atualiza de novo, e a mensagem some
atualiza pela terceira vez, e ela volta

Não é bug de UI, não é race condition no banco, não é nada que apareça nos logs do request específico que o suporte mandou.

Logo você entende que o problema é o cache de memória. Este que durante anos foi invisível e funcional, virou a primeira coisa que precisava sair do caminho.

A história é específica de um stack (no nosso caso, .NET com IMemoryCache virando IDistributedCache apontado pro Redis), porém o problema é completamente independente de linguagem: qualquer aplicação que use cache em processo, seja em Node com um Map global ou um lru-cache, em Python com functools.lru_cache ou um dicionário de módulo, em Java com ConcurrentHashMap ou Caffeine, em Go com sync.Map ou um cache em struct, vai encontrar exatamente o mesmo bug ao passar de uma instância única para múltiplas réplicas.

Este artigo é sobre por que ele funcionava antes, por que ele quebra agora, e por que a resposta nem sempre é "trocar cache local por Redis", embora muitas vezes seja.

Por que Memory Cache funcionava antes

IMemoryCache é a abstração padrão do .NET pra cache local, ou seja, o dicionário vive dentro da memória do próprio worker que está atendendo o request. Independentemente de qual stack estejamos falando, há equivalentes utilizados para o mesmo fim.

[HttpGet("conversations/{id}/timeline")]
public async Task<IActionResult> GetTimeline(
    Guid id,
    [FromServices] IMemoryCache cache,
    [FromServices] ITimelineRepository repository)
{
    var key = $"timeline:{id}";
    if (cache.TryGetValue(key, out var cached))
        return Ok(cached);

    var timeline = await repository.LoadAsync(id);
    cache.Set(key, timeline, TimeSpan.FromMinutes(5));
    return Ok(timeline);
}

Quando o aplicativo roda como uma única instância (um App Service single-instance, uma VM, um container solitário), todos os requests passam pelo mesmo processo, leem do mesmo dicionário e a consistência é óbvia: se o request A escreveu uma chave, o request B vai ler aquela chave, porque os dois estão no mesmo lugar.

Esse padrão funcionava por uma combinação de coisas: o monolito era stateful por acidente (todos os requests passavam pelo mesmo processo), o load balancer não existia ou era irrelevante e o cache nunca precisou ser confiável porque na prática nunca foi distribuído. Funcionava porque a topologia escondia o problema, não porque o código estava correto.

Cache local não é "errado". Há usos muito úteis para ele e não é pra sair jogando tudo no Redis e correr o risco de aumentar consideravelmente o preço de uso dessa ferramenta. Mas como bons arquitetos de software, devemos decidir onde é útil utilizá-lo e onde é necessário distribuir o cache

O que quebra quando escala horizontalmente?

Quando o mesmo serviço passa a rodar como N réplicas atrás de um load balancer, dois fatos novos entram em cena.

cada pod tem sua própria memória, então o cache do pod A é literalmente um objeto diferente do cache do pod B, sem comunicação entre eles.
o roteamento de request, por padrão, distribui carga entre os pods sem nenhuma afinidade (a menos que você configure sticky session, o que traz outros problemas nesse sentido), ou seja, o próximo request do mesmo usuário pode cair em qualquer pod.

A consequência é que o ciclo "lê do cache, cache miss, popula o cache, responde" passa a acontecer N vezes (uma por pod), o que já é desperdício. Mas pior do que isso, quando o estado muda (uma nova mensagem chega na conversa, por exemplo) e o código invalida a chave do cache, ele só invalida no pod que recebeu o request de escrita, deixando os outros N pods servindo dados velhos até o expiration natural.

Se o seu serviço vai rodar com mais de uma réplica, qualquer estado em memória que afeta a resposta visível ao usuário (cache, contador, rate limiter, sessão) é um bug latente. Não é uma questão de "se", é uma questão de quando o tráfego vai expor a divergência.

A solução padrão: tirar o cache de memória

A leitura do problema já sugere o caminho da solução: se a inconsistência aparece porque cada pod tem seu próprio cache, a saída é parar de guardar o cache dentro do pod e passar a guardar num lugar único, externo, que todos os pods enxergam. Em vez de cada réplica manter seu próprio dicionário em memória, todas as réplicas falam com um servidor de cache compartilhado, que vira a única fonte de verdade pra aquela camada.

O servidor mais usado pra esse papel é o Redis, um banco de dados que utiliza a memória RAM de onde está hospedado, otimizado pra operações simples (get, set com TTL, delete, incrementos, listas, conjuntos) e com latência absurdamente baixa, principalmente quando roda na mesma rede do serviço que o consome.

Não é a única opção (Memcached, Hazelcast, NCache, ou caches gerenciados pelo provedor de nuvem como Azure Cache for Redis e AWS ElastiCache resolvem o mesmo problema), mas é o padrão de fato na maioria das stacks modernas, ao ponto de "vou colocar um Redis" virar quase sinônimo de "vou colocar um cache distribuído".

Na prática, o que muda no código é a abstração que você injeta: em vez de IMemoryCache (cache local, em processo), você usa IDistributedCache (cache externo, com implementação plugada pra Redis via Microsoft.Extensions.Caching.StackExchangeRedis). O contrato da interface é parecido o suficiente pra que a tradução, no primeiro olhar, pareça quase mecânica:

public async Task<TimelineDto> ExecuteAsync(
        Guid conversationId,
        CancellationToken cancellationToken)
    {
        var key = BuildKey(conversationId);

        var cached = await _cache.GetStringAsync(key, cancellationToken);
        if (cached is not null)
        {
            return JsonSerializer.Deserialize<TimelineDto>(cached)!;
        }

        var timeline = await _databaseRepository.FetchAsync(conversationId, cancellationToken);

        await _cache.SetStringAsync(
            key,
            JsonSerializer.Serialize(timeline),
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5)
            },
            cancellationToken);

        return timeline;
    }

    private static string BuildKey(Guid conversationId)
        => $"conversations:{conversationId}:timeline";

A configuração no Program.cs (ou no equivalente da sua linguagem) é igualmente direta:

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration.GetConnectionString("Redis");
});

Com isso, todos os pods passam a ler e escrever no mesmo Redis: quando o pod A escreve a chave conversations:123:timeline, o pod B consegue ler exatamente o mesmo valor, e quando o pod A invalida a chave, ela some pra todo mundo ao mesmo tempo. A inconsistência intermitente desaparece, porque ela só existia enquanto o estado vivia escondido dentro de cada processo.

Redis é um processo separado que roda em algum lugar (um container no mesmo cluster Kubernetes, um serviço gerenciado da nuvem, uma VM dedicada). Ele precisa de connection string, secret pra autenticação, e idealmente alguma estratégia de alta disponibilidade (Redis Sentinel, Redis Cluster, ou o modo HA do serviço gerenciado). Não é "instalar uma biblioteca"; é adicionar uma dependência de infra ao seu sistema.

ATENÇÃO: Quando o Redis fica fora do ar, todos os requests que dependem dele falham ou ficam lentos. Em cache local, perder o cache só significava recalcular; em cache distribuído, perder o Redis pode significar derrubar a feature inteira se não houver fallback. Vale planejar o comportamento de degradação antes do primeiro incidente.

Esse é o caminho clássico, ensinado em qualquer tutorial sério de aplicação cloud-native, e na grande maioria das vezes é exatamente o que você deve fazer. Mas existe uma pergunta anterior que, se feita honestamente, evita você arrastar Redis pra dentro de features que nem precisam dele.

A pergunta que vem antes do Redis

A reação natural quando se entende o problema é fazer a troca imediata do cache local pelo distribuído e seguir a vida. Funciona, resolve a inconsistência e é a recomendação padrão pra cenários multi-réplica em praticamente qualquer stack.

Mas antes de fazer essa troca imediatamente, vale uma pergunta que economiza código, dependência e custo operacional: o cache ainda é necessário?

Boa parte dos caches locais espalhados num monolito legado são oportunistas, ou seja, foram colocados ali porque na época a query embaixo era cara, ou porque o ORM antigo não tinha change tracking decente, ou simplesmente porque o desenvolvedor preferiu garantir uma camada extra.

Quando você migra a feature pra uma stack moderna, com queries mais enxutas, índices revisados e um modelo de dados mais alinhado ao caso de uso, é comum descobrir que a query da nova versão já está rápida o suficiente pra dispensar o cache de cara.

Antes de migrar cache local pra cache distribuído, meça a feature sem cache. Se a latência da query na nova versão está dentro do esperado, não introduza Redis só porque o legado tinha cache. Migração mecânica imediata (quando você só migra a lógica sem analisar melhorias) é justamente onde nascem dependências fantasma.

Essa avaliação não é gratuita: você precisa olhar a query, entender o padrão de acesso (quantas vezes por minuto, quantos usuários simultâneos, qual o custo no banco), e só então decidir. Mas a economia de não arrastar uma dependência adicional pra uma feature que não precisa dela compensa o tempo gasto na medição.

Quando o cache distribuído é o caminho certo

Quando a evidência indica que o cache continua sendo necessário (a query é cara, o padrão de acesso é repetitivo, o hot path aparece em produção), aí sim o caminho é cache distribuído apontado pra um serviço externo, geralmente Redis, compartilhado entre os pods. A consistência entre réplicas para de ser um acidente do acaso pra virar uma garantia da arquitetura.

Manter Redis como dependência mesmo em features pequenas não é exagero, desde que o cluster já exista no ambiente. O custo marginal de mais uma chave é desprezível; o custo de introduzir um cache compartilhado só na primeira feature que precisa é alto, porque envolve infra, secret, observabilidade e processo de deploy.

Armadilhas que sobrevivem à migração

Trocar cache local por cache distribuído resolve o problema da inconsistência entre pods, mas herda armadilhas próprias do cache compartilhado, das quais três merecem atenção redobrada em qualquer stack.

cache stampede: situação em que uma chave expira e dezenas de requests simultâneos batem no banco ao mesmo tempo pra repopular, derrubando o serviço quando a query é cara. Em cache local, o impacto é limitado ao pod, mas em cache compartilhado, o impacto é global, porque todos os pods vão fazer cache miss ao mesmo tempo. A defesa clássica é um lock distribuído na repopulação (Redis tem SET NX justamente pra isso), ou alguma variação de stale-while-revalidate que mantenha o valor velho enquanto o novo é calculado. Vale escolher a estratégia conscientemente, não esperar o incidente acontecer.
serialização: cache distribuído armazena bytes, então tudo precisa virar JSON ou algum formato binário. Objetos com referência cíclica, tipos polimórficos sem discriminador ou campos de data sem timezone explícito são fontes inesgotáveis de bug, e bug de serialização raramente aparece em homologação porque os dados de teste costumam ser bem-comportados. Esse problema é especialmente capcioso em linguagens dinâmicas (Python, Node, Ruby), onde a estrutura do objeto serializado pode mudar entre deploys sem que haja um compilador para te avisar.
invalidação cross-feature: quando duas features escrevem em entidades que se sobrepõem (por exemplo, "atualizar uma mensagem" mexe na timeline da conversa e no resumo do contato), você precisa decidir explicitamente quem invalida o quê, sob pena de servir dados inconsistentes entre telas. Em cache local, esse problema era escondido pela curta vida útil do processo; em cache compartilhado, ele vira responsabilidade clara de quem está escrevendo.

Cache não é compensação pra modelo de dados ruim. Se você está cacheando uma view porque a join embaixo é insustentável, o trabalho real é arrumar a join, não esticar o expiration.

Concluindo

A pergunta que importa, antes de escolher a tecnologia, é se o cache continua resolvendo um problema real depois que o resto da arquitetura mudou.
Quando continua, cache distribuído é a resposta certa. Quando não continua, código a menos é a resposta melhor.

Adicionalmente, sobre os cuidados com o uso do Redis, recomendo o seguinte artigo, feito pelo Milton Câmara, parceiro de profissão e de empresa :) Redis além do tutorial. Com os problemas que ninguém te conta

Gostou do artigo? Comente abaixo sobre o que ele te fez pensar e que práticas você deseja aplicar. Além disso, comente sobre o que faltou no artigo que é informação importante sobre o assunto