A decisao de merge

Toda mudanca de codigo termina com uma decisao: fazer merge ou nao. No mundo pre-IA, essa decisao era respaldada pelo modelo mental do revisor - ele escreveu codigo similar, conhecia o sistema, conseguia raciocinar sobre risco pela experiencia.

Com codigo gerado por IA, esse modelo mental frequentemente nao existe. O revisor nao escreveu o codigo. Pode nao ter contexto completo da area sendo alterada. O codigo parece limpo, passa nos testes e o diff e grande. A decisao recai em instinto, pressao de tempo ou carimbo automatico.

Um bom relatorio de verificacao substitui instinto por sinais estruturados. Nao uma nota de aprovado/reprovado. Nao uma lista de ajustes de estilo. Uma decomposicao em camadas que diz o que mudou, o que pode ser arriscado e o que nao pode ser verificado - para que voce tome a decisao de merge com evidencia em vez de esperanca.

Separando o que voce sabe do que voce suspeita

A propriedade mais importante de um relatorio de verificacao e a separacao entre fatos e julgamentos.

Fatos sao o que mudou. Uma assinatura de funcao foi modificada. Tratamento de erros foi adicionado. Um export foi removido. Uma nova dependencia foi importada. Sao observacoes estruturais do diff. Sao deterministicos - o mesmo diff sempre produz os mesmos fatos. Nao podem estar errados, nao podem ser manipulados e nao dependem da opiniao de nenhum modelo.

Julgamentos sao o que pode ser arriscado. O export removido pode quebrar tres consumidores downstream. O novo tratador de erros captura excecoes mas as engole silenciosamente. A mudanca de assinatura pode violar o contrato da API. Sao inferencias - requerem interpretacao e podem estar erradas. Um bom relatorio torna essa distincao explicita. Todo julgamento deve carregar evidencia (o que no diff o motivou) e um indicador de confianca (quao certa e a analise).

Incognitas sao o que nao pode ser verificado. Nenhum tratamento de concorrencia observado para acesso a estado compartilhado. Sem cobertura de testes para o novo branch. Sem validacao no novo parametro de entrada. Esses nao sao achados - sao lacunas. O relatorio esta dizendo: "Eu procurei isso e nao encontrei. Voce deveria verificar." Essa categoria e onde os problemas mais perigosos se escondem, porque representam codigo ausente, nao codigo errado.

Quando um relatorio mistura essas tres categorias - ou pior, apresenta tudo como igualmente certo - o revisor nao consegue calibrar sua atencao. Ele ou trata tudo como aviso (ruido) ou nada como aviso (perigo).

Sinais de risco que realmente importam

Nem todas as mudancas carregam o mesmo risco. Uma mudanca de formatacao e uma mudanca de autenticacao nao merecem a mesma atencao de revisao. Um bom relatorio pontua risco com base no que realmente importa para seguranca em producao.

Severidade diz quao ruim pode ser. Uma mudanca que toca autenticacao, processamento de pagamentos ou fronteiras de acesso a dados e de alta severidade independente de quao pequeno o diff e. Uma mudanca que afeta performance ou observabilidade e de severidade menor. A classificacao deve seguir as consequencias de errar, nao o tamanho da mudanca.

Confianca diz quao certa a analise e. Um achado respaldado por evidencia forte no diff (um null check removido, um tipo de retorno alterado) e de alta confianca. Um achado que requer suposicoes sobre comportamento em runtime e de confianca menor. Quando o revisor ve um achado de alta severidade e alta confianca, sabe exatamente onde focar. Quando ve um achado de baixa confianca, sabe que deve verificar pessoalmente antes de agir.

Categorias dizem o dominio. E uma preocupacao de seguranca? Uma mudanca de contrato de dados? Uma modificacao de tratamento de erros? Uma questao de corretude logica? Categorizacao permite que diferentes revisores foquem em sua expertise. O engenheiro de seguranca olha achados de autenticacao. O engenheiro de dados olha mudancas de contrato. Ninguem precisa ler tudo.

Raio de impacto: o sinal que a maioria das ferramentas perde

Uma mudanca de tres linhas em uma funcao utilitaria pode quebrar cinquenta arquivos. Uma mudanca de duzentas linhas em um componente isolado nao afeta mais nada. Tamanho do diff e um proxy terrivel para risco.

Raio de impacto - quantos outros arquivos dependem do codigo alterado - e um dos sinais mais fortes para decisoes de merge. Se o arquivo alterado e importado por trinta outros modulos, mesmo uma mudanca pequena exige revisao cuidadosa. Se o arquivo alterado e um script standalone sem dependentes, o risco esta contido.

As mudancas mais perigosas sao diffs pequenos em arquivos altamente conectados. Parecem inofensivas no PR mas tem impacto desproporcional. Sem informacao de raio de impacto, revisores nao tem como saber.

Alinhamento com spec: o codigo fez o que deveria?

Quando um agente de IA implementa uma feature a partir de um spec ou descricao de tarefa, existem duas perguntas: ele escreveu codigo correto, e ele implementou a coisa certa?

A maioria dos processos de revisao so aborda a primeira pergunta. Verificam se o codigo e bem estruturado, trata erros e nao introduz problemas de seguranca. Nao verificam se a implementacao realmente corresponde ao que foi pedido.

Alinhamento com spec fecha essa lacuna. Dados o documento de requisitos e o diff, um bom relatorio pode dizer: quais requisitos foram atendidos, quais foram parcialmente atendidos, quais foram contraditos e quais nao foram tocados. Isso e particularmente valioso com codigo gerado por IA, onde o agente pode implementar com confianca algo que diverge do spec de maneiras que nao sao obvias ao ler o codigo.

Como e um sinal de merge-ready

Um relatorio que apoia boas decisoes de merge da ao revisor um caminho rapido para a resposta certa:

Quando nao ha com que se preocupar: sem achados, baixo raio de impacto, todos os specs atendidos. O revisor pode fazer merge com confianca. Gastou segundos, nao minutos. Isso e o que "compressao de revisao" realmente significa - nao pular revisao, mas tornar mudancas seguras rapidas de aprovar.

Quando ha algo a investigar: um ou dois achados com evidencia e niveis de confianca. O revisor sabe exatamente quais arquivos e linhas olhar e por que. Gasta tempo na preocupacao especifica em vez de varrer o diff inteiro procurando problemas.

Quando a mudanca nao esta pronta: achados de alta severidade, tratamento de erros ausente, requisitos de spec contraditos ou alto raio de impacto com cobertura de testes insuficiente. O revisor tem evidencia para devolver com feedback especifico e acionavel. Nao "isso nao parece certo" mas "essa mudanca remove escalacao de erros em um arquivo do qual trinta outros modulos dependem."

Em todos os tres casos, o relatorio substitui a pergunta "devo fazer merge?" por "aqui esta a evidencia, aqui esta o risco, aqui esta o que eu nao consegui verificar." A decisao de merge ainda e sua. Mas agora e informada.

O relatorio como artefato

Para times com requisitos de compliance, o relatorio nao e apenas um auxilio de decisao. E evidencia.

Quando um auditor pergunta "como voces verificam codigo gerado por IA antes de ir para producao?", a resposta deveria ser demonstravel. Um relatorio estruturado - com fatos, achados, niveis de confianca, alinhamento com spec e lacunas identificadas - armazenado junto ao PR, e um registro verificavel. Mostra o que foi verificado, o que foi sinalizado e o que o time decidiu fazer a respeito.

Essa e a diferenca entre "revisamos todo o codigo" (que auditores cada vez mais nao aceitam pelo valor de face) e "aqui esta o artefato de verificacao para cada mudanca que foi para producao" (que eles podem inspecionar).

O relatorio fecha o ciclo entre todos os problemas que esta secao cobre: aborda o gargalo de revisao (triagem estruturada), a preocupacao de IA revisando IA (fundamentado em evidencia, nao consenso), o problema das lacunas (incognitas explicitas), o ciclo de revisao continua (relatorio em cada checkpoint) e a questao de privacidade de codigo (gerado localmente, armazenado no seu repositorio).