Quando o PR Parece Bom, Mas Ainda Soa Errado
Se você já está publicando com IA há mais de algumas semanas, provavelmente conhece essa sensação.
Você abre um pull request. O código está limpo o bastante. A nomenclatura está decente. Os testes existem. Nada parece obviamente quebrado. E, ainda assim, alguma coisa ali incomoda.
Talvez a fronteira esteja um pouco borrada. Talvez o contract esteja implícito em vez de declarado. Talvez o happy path esteja coberto, mas a regra de negócio de verdade ainda more na cabeça de alguém. Você sente o risco, mesmo sem conseguir apontar uma linha catastrófica.
Esse é o novo problema de review.
A maioria dos times ainda passa desenvolvimento assistido por IA por um fluxo antigo: escrever um prompt, gerar um diff, abrir o PR e pedir para um engenheiro sênior inspecionar o código com atenção suficiente para capturar invariants violadas, edge cases ausentes, deriva arquitetural e risco escondido.
Esse modelo fazia sentido quando humanos escreviam quase toda a implementação por conta própria. Faz muito menos sentido quando um modelo consegue gerar a implementação, a primeira suíte de testes, o schema e até a estrutura inicial de contracts em uma passada.
A partir daí, review de código linha por linha deixa de ser o lugar de maior alavancagem para gastar atenção sênior.
A pergunta real já não é mais: “Esta função parece razoável?”
A pergunta real é: “Definimos corretamente o comportamento, a fronteira e a invariant antes de a função existir?”
Essa é a inversão de fluxo que a IA cria. Code review não desaparece. Mas o centro de gravidade sobe no fluxo. Na era da IA, code review vira specification review.
Por Que Essa Mudança Parece Tão Diferente
Por muito tempo, a maioria dos times de engenharia tratou especificações como material de apoio.
O código era a coisa real. O doc comment era só uma pista. O ADR era contexto, se você tivesse tempo de ler. O schema era “só validação”. O arquivo Gherkin era algo opcional, se alguém se desse ao trabalho de mantê-lo em dia.
Essa hierarquia está quebrando.
Se um LLM consegue transformar uma especificação em artefatos de implementação com rapidez e repetição, então a especificação deixa de ser secundária. Ela vira o artefato-fonte do qual o resto do sistema é derivado.
E isso muda onde os erros são mais baratos de capturar.
Se a especificação é vaga, o modelo consegue produzir uma implementação do jeito errado, mas lindamente estruturada. Ele entrega código limpo, testes plausíveis e uma falsa sensação de confiança. Mesmo um code review forte ainda pode deixar passar o problema real, porque o bug não está na sintaxe. O bug está na intenção.
É isso que torna este momento tão traiçoeiro e tão importante. A IA facilita produzir saída convincente. Também torna muito mais perigoso ser descuidado com aquilo que você pediu.
Se a especificação é precisa, delimitada e testável, tudo fica mais fácil. A implementação fica mais fácil. A validação fica mais fácil. O review fica mais fácil. O CI fica mais forte.
É por isso que o melhor esforço de review humano está se deslocando de auditar manualmente cada branch para tornar mais preciso o artefato que define o comportamento dessa branch em primeiro lugar.
Uma Especificação Não É um Documento Gigante de Requisitos
Quando as pessoas ouvem a palavra “especificação”, muitas vezes imaginam um documento inchado que ninguém quer escrever e em que ninguém confia seis semanas depois.
Não é isso que importa aqui.
Em um fluxo prático assistido por IA, uma especificação é qualquer artefato que defina o comportamento pretendido com precisão suficiente para permitir geração e enforcement.
Isso pode ser:
- um ADR em Markdown que descreve uma boundary rule
- um schema Zod que define o formato da entrada externa
- uma assinatura de função com um doc comment afiado
- um cenário Gherkin que captura comportamento observável
- um bloco de contract com pré-condições e pós-condições
- um modelo de reducer ou uma tabela de transição de estado
Nada disso precisa ser pesado. Só precisa ser claro o bastante para que as ferramentas consigam fazer algo útil com isso.
Esse é o limiar que importa. Uma especificação útil não é apenas legível para humanos. Ela é acionável pelo sistema ao redor da codebase.
Como o Review de Verdade Começa a Ficar
No modelo antigo, um engenheiro sênior gasta energia em perguntas como:
- esta implementação está limpa?
- o autor deixou passar algum edge case?
- estes testes são fortes o bastante?
- este import viola uma fronteira?
Essas perguntas ainda importam. Elas só já não são as primeiras perguntas de maior alavancagem.
Em um fluxo orientado por especificação, as perguntas mais valiosas passam a ser:
- o contract está realmente correto?
- o schema define a fronteira real?
- as regras de negócio estão completas?
- o ADR está preciso o bastante para enforcement?
- essas propriedades listadas expressam a semântica real?
Essas são perguntas melhores de review porque uma boa resposta melhora vários artefatos de uma vez.
Se você torna um ADR vago mais preciso, melhora a regra arquitetural, a orientação de implementação e o enforcement no CI em um único movimento.
Se você corrige um schema fraco, melhora validação em tempo de execução, inferência de tipos e qualidade de geração de código em um único movimento.
Se você afia um contract, melhora implementação, testes e resistência a mutação em um único movimento.
Essa é a diferença de alavancagem. Você já não está mais inspecionando saídas uma por uma. Está revisando a coisa que molda essas saídas.
Por Que o Code Review Tradicional Começa a Trincar
O code review tradicional parte da suposição de que humanos são os autores primários e que o revisor está verificando a qualidade de um processo de pensamento humano a partir do código final.
Com IA, essa suposição enfraquece a cada semana.
Um modelo consegue produzir cinquenta linhas plausíveis em segundos. Consegue produzir mais cinquenta com a mesma rapidez. E mais cinquenta depois disso. Se todo o seu processo depende de um revisor capturar manualmente a deriva semântica enterrada dentro desse fluxo, a superfície de review cresce mais rápido do que a atenção humana jamais vai crescer.
Isso cria um equilíbrio ruim:
- a geração de código acelera
- os diffs ficam maiores ou mais frequentes
- a fadiga de review sobe
- a confiança semântica cai
- os times começam a compensar com vibes, intuição e “looks good to me”
Isso não é estratégia de escala. É risco acumulado com boa formatação.
O movimento melhor é reduzir o quanto de review subjetivo você precisa, para começar. Coloque mais significado em especificações determinísticas e revisáveis. Depois deixe a máquina verificar se o código continua alinhado a esse significado.
CI É o Que Torna Isso Real
Essa inversão de fluxo só funciona se a especificação estiver ligada a enforcement.
Caso contrário, você só está renomeando documentação e torcendo para que as pessoas a respeitem mais.
O ponto é tornar a especificação operacional.
Isso significa:
- decisões de arquitetura compilam em regras de dependência
- schemas definem fronteiras seguras em tempo de execução e no sistema de tipos
- contracts geram checagens executáveis
- listas de propriedades dirigem geração de testes
- semânticas críticas viram bloqueios de merge
Quando isso acontece, CI deixa de ser um sistema de build passivo e vira o mecanismo que mantém a implementação alinhada com a intenção.
É também por isso que especificações vivas finalmente se tornam realistas para times normais. Historicamente, a documentação apodrecia porque ninguém tinha tempo de manter texto e código sincronizados à mão.
A IA muda a economia de escrever e atualizar esses artefatos. CI muda a economia de impô-los.
Você precisa dos dois. IA sem enforcement entrega deriva polida. Enforcement sem boas specs entrega confusão rígida.
Hard Guards, Soft Reviews
Essa também é a parte da filosofia da Autotomy que me parece cada vez mais certa.
A ideia é simples: coloque as regras inegociáveis em hard guards, depois deixe o review humano focar nas partes que realmente exigem julgamento.
Isso significa que tipos, schemas, contracts, regras de dependência e deterministic checks lidam com os modos de falha conhecidos. Eles rodam sempre. Não se cansam. Não se distraem com um diff bem formatado. Não se importam se o código veio de um engenheiro em nível staff ou de um modelo de linguagem.
Então a camada de review fica menor e melhor.
Em vez de gastar atenção sênior em coisas que o sistema poderia ter rejeitado automaticamente, você a gasta em tradeoffs, semântica, interfaces e arquitetura. Você pergunta se a fronteira está correta, se o contract é honesto, se a substituição realmente satisfaz a interface, se o sistema está ficando mais fácil ou mais difícil de mudar.
Essa última parte importa muito.
Um dos efeitos colaterais mais saudáveis do trabalho orientado por especificação é que ele empurra você para pontos de corte mais limpos. Se um module pode ser substituído desde que satisfaça o contract e passe nas checagens, você para de tratar cada implementação como sagrada. Começa a projetar para substituição segura em vez de preservação dolorosa.
É uma mudança sutil, mas muda a forma como os times lidam com crescimento. A codebase deixa de parecer algo que só dá para remendar com cuidado por dentro. Passa a parecer um sistema com costuras explícitas.
Isso É Boa Notícia para Engenheiros Seniores
Essa mudança não torna o julgamento de engenharia sênior menos valioso. Ela o torna mais focado e mais importante.
O engenheiro sênior deixa de ser mais valioso como um motor humano de diff sintático. Passa a ser mais valioso onde ambiguidades são resolvidas, invariants são escolhidas, interfaces são moldadas e tradeoffs ficam explícitos.
Isso significa mais tempo gasto com:
- escrever ADRs precisos
- definir contracts e schemas
- revisar mudanças semânticas em vez de estilísticas
- decidir quais propriedades merecem enforcement
- transformar arquitetura em regras que podem bloquear merge
Esse é um uso muito melhor de atenção cara.
A máquina é muito boa em preencher detalhe de implementação. Engenheiros seniores continuam muito melhores em decidir o que precisa continuar verdadeiro quando o sistema é pressionado, alterado e escalado.
Você Não Precisa de um Rewrite Gigante de Processo
Isso pode soar maior do que realmente é.
Você não precisa lançar uma iniciativa de métodos formais. Não precisa parar de publicar. Não precisa enterrar o time em processo.
Comece com uma mudança estreita: trate uma classe de especificação como um artefato de primeira classe submetido a review.
Uma sequência prática se parece com isto:
- exigir doc comments precisos e schemas nas fronteiras críticas
- tratar mudanças em ADR como itens de review sênior
- gerar testes e contracts a partir desses artefatos
- impor deriva arquitetural e de contract no CI
- rebaixar comentários de review só de estilo em favor de review semântico
Isso basta para mudar a cultura.
Quando os times sentem que especificações melhores reduzem o atrito de review mais adiante, o modelo começa a se reforçar sozinho. Os reviews ficam mais afiados. Os diffs ficam menos assustadores. A confiança melhora.
A Virada Estratégica Real
Os times que vencem com IA não serão os times que apenas geram código mais rápido.
Serão os times que movem a atenção humana para a parte mais estreita e de maior alavancagem do fluxo.
Essa parte é a especificação.
Quando a especificação vira o artefato principal, o código deixa de ser a única coisa que vale review linha por linha. Ele vira uma saída de um sistema mais disciplinado.
Essa é a mudança real.
Implementação ainda importa. Muito. Mas, cada vez mais, a decisão de review mais importante acontece antes de a implementação existir.
E é por isso que, na era da IA, code review vira specification review.