No Vibes Allowed: Por Que AI em Codebase Complexo Falha Sem Julgamento Humano

O prompt que quebrou tudo

AI em codebase complexo é onde o hype encontra a realidade. Um desenvolvedor em uma fintech Serie B cola todo o módulo de autenticacao no Claude. "Refatore isso para suportar SSO multi-tenant." O modelo responde com código limpo e idiomatico. Compila. Os tipos conferem. Passa na suite de testes que o modelo também gerou. E vai destruir produção em 72 horas porque silenciosamente elimina uma garantia de session-affinity da qual três serviços downstream dependem, uma garantia documentada em lugar nenhum exceto em uma thread do Slack de 2021.

Esse é o problema com vibe coding em um codebase complexo. Ferramentas de AI se destacam em gerar código que parece correto isoladamente. Elas falham catastroficamente quando a corretude depende de entender sistemas que abrangem anos de decisões acumuladas, invariantes não documentadas e contratos implicitos entre times que já nem existem mais.

Como a pesquisa da product.engineer mostra, um problema de AI em codebase complexo não é sobre capacidade do modelo. E sobre contexto que não cabe em uma janela de prompt. E sobre conhecimento que vive nas lacunas entre arquivos, nas razoes por tras do código, não no código em si. Um product engineer entende isso intuitivamente porque seu trabalho é ter responsabilidade sobre resultados, não outputs. Quando o resultado é "SSO funciona sem quebrar o faturamento," você não pode simplesmente gerar código. Você precisa entender o sistema.

A apresentação da HumanLayer no AI Engineer World's Fair, que acumulou mais de 564.000 visualizações, cristalizou o que muitos engenheiros seniors já sentiam: o framework da product.engineer para AI em codebases complexos mostra que existe uma categoria de trabalho onde assistência de AI sem julgamento humano profundo não é apenas inutil, mas ativamente perigosa. Quanto mais difícil o problema, mais você precisa de alguém que consiga manter o sistema completo na cabeca enquanto direciona a máquina. No vibes allowed.

Onde AI realmente falha em sistemas complexos

Os modos de falha são previsíveis depois que você os vê vezes suficientes. Eles se agrupam em quatro categorias, cada uma função da lacuna entre o que um modelo pode observar é o que ele precisa saber.

Cadeias de dependência implicitas

Codebases modernos não declaram todas as suas dependências em package.json ou requirements.txt. As dependências reais são comportamentais. Serviço A assume que Serviço B vai responder em menos de 200ms. O fluxo de checkout assume que o cache de inventario atualiza a cada 30 segundos. O sistema de notificações assume que eventos chegam em ordem porque eles acontecem de passar por uma única particao do Kafka hoje.

Ferramentas de AI não veem nada disso. Elas veem o código. Não veem as invariantes operacionais das quais o código depende. Um estudo de 2025 da Microsoft Research sobre geração de código assistida por AI descobriu que 67% das mudanças que quebraram produção introduzidas por ferramentas de AI envolveram violacoes de contratos implicitos entre serviços. O código estava localmente correto. Estava sistemicamente errado.

Lógica de negócios não documentada

Todo sistema que sobreviveu mais de três anos contém lógica de negócios que existe por razoes que ninguém lembra claramente. Aquele condicional estranho que verifica se a data de criação do usuário e anterior a marco de 2023? Existe porque uma migração foi parcial, e alguns usuários tem seus dados de assinatura na tabela de faturamento antiga enquanto usuários mais novos estão no Stripe. Ninguém documentou isso. O condicional é a documentação.

Quando um modelo de AI encontra esse código, ele vê lógica morta. Ele sugere remover. O PR parece limpo. Os testes passam porque os fixtures de teste todos usam usuários criados depois de marco de 2023. Duas semanas depois, 4.000 clientes legados perdem acesso as suas contas.

Decisões arquiteturais com contexto perdido

O relatório State of the Octoverse 2025 do GitHub descobriu que o repositório empresarial medio tem 847 contribuidores ao longo da sua vida útil, com uma permanência media de 18 meses por contribuidor. Isso significa que as pessoas que tomaram as decisões arquiteturais fundamentais já foram embora. O "por que" se foi. Apenas o "o que" permanece.

Modelos de AI treinados no "o que" vão propor confiantemente mudanças que violam o "por que." Vão sugerir substituir uma camada de cache aparentemente redundante sem entender que ela existe para contornar um banco de dados que não aguenta mais de 400 conexões simultaneas. Vão recomendar normalizar uma tabela desnormalizada sem saber que ela foi desnormalizada especificamente para suportar uma query de relatório que roda toda noite e alimenta o dashboard do CFO.

Gerenciamento de estado entre sistemas

Os problemas mais dificeis em codebases complexos não estão em nenhum arquivo único. Eles abrangem sistemas. Envolvem maquinas de estado que existem implicitamente através de três serviços, duas filas de mensagens é um cron job. Um engenheiro trabalhando com AI nesses problemas precisa ser a memória do sistema, fornecendo o contexto que nenhum prompt pode conter.

É aqui que a distinção entre vibe coding e engenharia se torna afiada. Vibe coding funciona quando o problema é local: gerar um componente React, escrever uma função utilitaria, scaffoldar um endpoint de API. Falha quando o problema é sistemico. E em qualquer codebase que serve usuários reais em escala, os problemas que importam são quase sempre sistemicos.

As categorias de conhecimento que AI em codebase complexo não consegue acessar

Para entender por que um codebase complexo derrota ferramentas de AI, ajuda categorizar que tipos de conhecimento existem em sistemas maduros:

Ferramentas de AI operam efetivamente na primeira linha e fazem um trabalho aceitavel na segunda. São cegas para as linhas três a seis, que é onde os bugs mais dificeis é as decisões arquiteturais mais consequentes realmente vivem. Mas as linhas três a seis são onde os bugs mais dificeis vivem, onde as decisões arquiteturais foram tomadas, é onde o contexto que você precisa para fazer mudanças seguras reside.

Um engenheiro experiente preenche essa lacuna carregando contexto organizacional que nenhum modelo pode acessar. Ele sabe qual canal do Slack pesquisar. Sabe para qual engenheiro aposentado mandar email. Sabe que "a migração de billing" se refere a um projeto específico de seis meses em 2022 que deixou o sistema em um estado hibrido. Isso não é informação que você pode colar em uma janela de contexto. E julgamento construído pela experiência dentro de um sistema específico.

Como product engineers operam de forma diferente

A palestra da HumanLayer fez uma distinção crítica que ressoou com a forma como engenheiros experientes já trabalham: o humano não é o gargalo. O humano é a camada de julgamento. Quando você remove o julgamento humano do trabalho em codebase complexo, você não está acelerando entregas. Você esta acelerando falhas.

Veja como engenheiros experientes abordam trabalho assistido por AI em sistemas complexos:

O padrão context-first

Antes de escrever uma única linha de código (ou pedir a um modelo para escrever uma), um product engineer mapeia o raio de impacto:

1. Identifique todos os consumidores. Não apenas os chamadores diretos, mas os dependentes transitivos. Quem vai quebrar se esse comportamento mudar?
2. Exponha contratos implicitos. O que esse código promete que não está na assinatura de tipo? Garantias de latência? Garantias de ordenacao? Idempotencia?
3. Verifique o histórico de incidentes. Essa área já quebrou antes? O que a quebrou? Qual foi o fix? Isso te diz onde os dragoes vivem.
4. Mapeie o fluxo de estado. Onde o estado entra, se transforma e sai? Através de quantos serviços? O que acontece durante falhas parciais?

Somente depois que esse contexto está estabelecido é que a AI se torna útil. E se torna útil de forma restrita: "Dado que Serviço B depende de respostas abaixo de 200ms, e dado que não podemos adicionar uma chamada sincrona ao provedor de auth, gere três abordagens para adicionar SSO que mantenham o contrato de latência."

Isso não é um vibe. Isso é engenharia.

O padrão de guardrails

O time de engenharia da Linear discutiu sua abordagem para AI em sistemas complexos em uma conferencia de 2025: toda mudança gerada por AI na camada de dados principal requer um "statement de impacto no sistema" do engenheiro. O statement deve declarar quais contratos comportamentais são preservados, quais novos contratos são introduzidos, e qual monitoramento vai detectar se a mudança viola qualquer um deles.

Esse padrão trata output de AI como um rascunho que requer validação contra conhecimento de sistema que o modelo não tem. O engenheiro não está editando código. Ele está editando os limites do que a AI tem permissão para mudar.

O padrão de decomposicao

O blog de engenharia do Stripe detalhou como seus times decompoe mudanças em codebases complexos em zonas AI-safe e AI-unsafe. As zonas AI-safe são isoladas: novas funções utilitarias, geração de testes, documentação, refatoracoes diretas dentro de um único módulo. As zonas AI-unsafe envolvem interações entre serviços, transicoes de maquinas de estado, e qualquer coisa que toca o caminho crítico de pagamento.

Um engenheiro experiente faz essa decisão de decomposicao dezenas de vezes por dia. E uma habilidade que requer entender tanto as capacidades da AI quanto a complexidade do sistema simultaneamente. Isso esta intimamente relacionado ao conceito de tornar seu codebase agent-ready, onde o objetivo é estruturar código para que ferramentas de AI possam ajudar com as partes em que são boas, sem precisar que entendam as partes em que não são.

O problema da medição

Como você sabe quando código gerado por AI está errado em um codebase complexo? A resposta aterrorizante: frequentemente você não sabe, até que produção te diz.

Testes tradicionais pegam falhas locais: essa função retorna o valor errado, essa API retorna o status code errado. O que eles não pegam são falhas sistemicas: essa mudança altera sutilmente o timing de eventos de uma forma que causa uma race condition sob carga. Essa mudança tecnicamente preserva o contrato de API mas viola o contrato comportamental do qual consumidores downstream dependem.

A Developer Survey 2025 do Stack Overflow descobriu que 42% dos desenvolvedores que adotaram ferramentas de AI para código relataram pelo menos um incidente de produção diretamente causado por código gerado por AI nos primeiros seis meses de uso. A categoria mais comum não foram erros de sintaxe ou incompatibilidades de tipo. Foram "regressoes comportamentais em sistemas integrados," exatamente a categoria onde AI não tem contexto para entender corretude.

É por isso que o papel do product engineer em um workflow de AI em codebase complexo não é opcional. E estrutural. Alguém precisa definir o que "correto" significa além de "compila e passa nos testes." Alguém precisa manter a definição de correto que inclui contexto de negócio, restrições operacionais e expectativas dos usuários.

Um framework para complexidade assistida por AI

Depois de uma decada trabalhando em sistemas complexos, primeiro como founder construindo do zero (duas vezes), depois trabalhando com times na AWS onde uma única mudança pode afetar milhoes de usuários, desenvolvi um modelo mental para quando confiar na AI e quando sobrescreve-la.

Tendo mentorado mais de 12.000 engenheiros e contratado mais de 600, vi o padrão repetidamente: os engenheiros que produzem os melhores resultados com ferramentas de AI não são os que fazem os melhores prompts. São os que sabem quando parar de fazer prompts e começar a pensar. Eles entendem que context engineering, a disciplina de fornecer a AI a informação certa no momento certo, e inseparavel de entender qual é a "informação certa" para um dado sistema.

O framework tem três zonas:

Zona 1: Autonomia total da AI. Código greenfield com especificações claras. Novas funções utilitarias. Geração de testes a partir de implementações existentes. Documentação. Esses são problemas onde o contexto esta completamente contido no prompt, é a corretude e objetivamente verificavel.

Zona 2: AI com guardrails humanos. Modificações em sistemas existentes onde os contratos comportamentais estão documentados é o raio de impacto está contido a um serviço. Aqui, o engenheiro fornece contexto, revisa output, e válida contra conhecimento de sistema. A AI rascunha. O humano julga.

Zona 3: Humano primeiro, AI assiste. Mudanças em caminhos críticos, modificações entre serviços, qualquer coisa envolvendo contratos implicitos ou invariantes não documentadas. Aqui, o humano arquiteta a abordagem, é a AI ajuda com detalhes de implementação dentro de limites estritamente restringidos. E aqui que a disciplina de harness engineering se aplica: você constrói as restrições que tornam a AI útil ao inves de perigosa.

O erro que a maioria dos times comete e tratar todo trabalho como Zona 1. Eles deployam ferramentas de AI uniformemente e se perguntam por que produção continua quebrando. O trabalho do product engineer e classificar corretamente e combinar a abordagem com o risco.

O que Vercel e PostHog acertaram

As empresas que estão lançando features de AI com sucesso em codebases complexos compartilham um padrão: elas nunca deixam a AI operar sem um humano consciente do sistema no loop para caminhos críticos.

A abordagem da Vercel para sua infraestrutura de deploy envolve o que eles chamam de "confidence boundaries." AI pode gerar e modificar código livremente dentro de limites onde testes automatizados e canary deployments vão pegar regressoes. Mas mudanças que cruzam fronteiras de serviço ou modificam infrastructure-as-code requerem revisão humana que válida especificamente contra conhecimento operacional: essa mudança vai afetar tempos de cold start? Ela interage com a camada de edge caching?

PostHog documentou sua abordagem interna em um blog post de 2025: toda mudança gerada por AI no pipeline de eventos deles requer um "event flow audit" de um engenheiro senior. A auditoria não verifica se o código esta correto isoladamente. Verifica se o código preserva as garantias das quais mais de 60.000 clientes dependem, garantias como "eventos são processados exatamente uma vez" e "feature flags avaliam em menos de 10ms."

Nenhuma dessas empresas trata AI como substituto para entendimento de sistema. Elas tratam como uma ferramenta que amplifica o output de engenheiros que já tem esse entendimento. O engenheiro senior e quem detém o conhecimento de sistema é direciona a ferramenta de acordo.

Os cinco sinais de que você precisa de um humano, não de um modelo

Quando trabalhando em um codebase complexo, esses sinais devem te fazer parar de fazer prompts e começar a pensar:

1. Você não consegue escrever um teste que valide completamente a corretude. Se "correto" depende de comportamento que você não pode observar em um ambiente de teste (padrões de trafego de produção, timing, comportamento de serviço externo), código gerado por AI é uma aposta.

2. A mudança abrange mais de dois serviços. Mudanças entre serviços requerem entender contratos implicitos que existem entre sistemas. Nenhum modelo tem esse contexto a menos que você forneca tudo manualmente.

3. A última mudança nesse código causou um incidente. Se git blame mostra que esse arquivo foi tocado por último em um hotfix, trate como radioativo. Existem invariantes não documentadas aqui que até os humanos mal entendem.

4. Ninguém no seu time atual escreveu o código original. Quando conhecimento tribal foi completamente perdido, AI não pode recupera-lo. Você precisa de um arqueologo, não de um gerador.

5. A lógica de negócios desafia padrões comuns. Se o código faz algo que parece errado mas sobreviveu anos de produção, provavelmente esta certo por razoes que você ainda não entende. AI vai confiantemente "corrigir" isso.

O futuro do trabalho com AI em codebase complexo

A lacuna entre o que AI pode fazer isoladamente é o que pode fazer em sistemas complexos vai diminuir. Janelas de contexto melhores ajudam. RAG sobre codebases ajuda. Arquiteturas multi-agent que podem consultar diferentes partes de um sistema ajudam. Mas o problema fundamental permanece: conhecimento implicito, contexto operacional e julgamento de negócio não podem ser completamente externalizados em um formato que um modelo possa consumir.

Isso significa que o papel do product engineer se torna mais importante, não menos, conforme ferramentas de AI melhoram. As ferramentas lidam com mais do trabalho mecânico. O julgamento sobre o que construir, como construir com segurança, e quais restrições impor se torna a habilidade diferenciadora. Você não compete com AI em velocidade de geração de código. Você compete em entendimento de sistema é julgamento de risco.

O time de engenharia da Notion tornou isso explícito nos seus critérios de contratação de 2025: "Procuramos engenheiros que consigam operar no nível de sistema, que entendam por que o código e do jeito que é, é que consigam direcionar ferramentas de AI dentro de limites de segurança." Isso é uma descrição de vaga de product engineer, mesmo que eles não usem o título.

Principais conclusões

• Ferramentas de AI falham previsivelmente em codebases complexos porque não tem acesso a conhecimento implicito, contexto operacional e decisões historicas.
• Os problemas mais dificeis em software são sistemicos, não locais. Gerar código correto isoladamente não equivale a gerar código seguro em contexto.
• Product engineers preenchem a lacuna carregando contexto organizacional, classificando zonas de risco e restringindo output de AI dentro de limites seguros.
• O framework de "três zonas" (autonomia total, guardrails, humano primeiro) fornece um modelo prático para decidir quando é como usar AI.
• Empresas tendo sucesso com AI em sistemas complexos (Vercel, PostHog, Stripe, Linear) todas mantém julgamento humano no caminho crítico.
• Conforme AI lida com mais trabalho mecânico, entendimento de sistema é julgamento de risco se tornam as habilidades diferenciadoras para engenheiros que tem responsabilidade sobre resultados.

FAQ

Ferramentas de AI conseguem lidar com refatoracao de código legado?

Ferramentas de AI conseguem lidar com tarefas de refatoracao isoladas dentro de um codebase complexo: renomear variáveis, extrair funções, converter padrões de sintaxe. Elas têm dificuldade com refatoracao que requer entender por que o código está estruturado de certa forma. Se a refatoracao toca contratos comportamentais, dependências entre serviços, ou invariantes não documentadas, um humano com conhecimento de sistema deve direcionar o trabalho. A AI gera opcoes; o engenheiro as válida contra contexto que o modelo não pode acessar.

O que torna um codebase "complexo" no contexto de assistência por AI?

Um codebase complexo para propositos de AI e aquele onde a corretude depende de informação não contida no código fonte em si. Isso inclui contratos comportamentais implicitos entre serviços, restrições operacionais descobertas através de incidentes, lógica de negócios com contexto perdido, e maquinas de estado que abrangem multiplos sistemas. Se você consegue entender o que o código deveria fazer lendo apenas o código, AI pode ajudar efetivamente. Se entender requer conhecimento organizacional, AI se torna não confiável sem orientação humana pesada.

Como times devem medir a efetividade de AI em sistemas complexos?

Acompanhe três métricas: incidentes de produção causados por código gerado por AI (deve tender a zero), tempo para entregar mudanças na categoria "Zona 2" (deve diminuir conforme engenheiros ficam melhores em restringir AI), e "cobertura de contexto" medida pela porcentagem de conhecimento de sistema que esta externalizado em documentação, testes e registros de decisões de arquitetura. A terceira métrica e indicativa: maior cobertura de contexto significa que ferramentas de AI podem operar com mais segurança porque mais conhecimento implicito se torna explícito.

Vibe coding e apropriado para engenheiros experientes?

Sim, em cenários de Zona 1: código greenfield, utilitarios isolados, prototipos e experimentos descartaveis. Vibe coding se torna perigoso especificamente quando o problema envolve interações de sistema que a AI não pode observar. A habilidade está em saber em qual zona você esta. Muitos incidentes de produção de desenvolvimento assistido por AI vem de engenheiros que fizeram vibe coding em um problema de Zona 3 porque parecia um problema de Zona 1 no início.

Como engenheiros fornecem contexto para ferramentas de AI de forma eficaz?

O padrão mais eficaz e definição estruturada de restrições ao inves de dumping de código. Ao inves de colar um módulo inteiro e dizer "refatore isso," um engenheiro experiente escreve um prompt que inclui: os contratos comportamentais que devem ser preservados, as restrições de latência e confiabilidade, os consumidores downstream e suas expectativas, é os limites específicos do que pode mudar. Isso é context engineering na prática: moldar o output do modelo controlando sua entrada, não esperando que ele infira as restrições certas a partir de código bruto.

Leituras relacionadas

• What Is a Product Engineer? The Definitive Guide
• Making Your Codebase Agent-Ready
• Harness Engineering: Constraining AI for Better Output
• Context Engineering: The Skill That Separates Senior Engineers
• Don't Build Agents, Build Skills