PR Pequeno na Era da IA: guia para não empilhar mudanças

1. O que mudou com IA no fluxo de desenvolvimento

O paradoxo da aceleração

IA acelera a execução. O problema é que ela não avisa quando você está acumulando mudanças demais numa só entrega.

Antes da IA, você escrevia código na velocidade que conseguia pensar. O esforço natural criava um freio: poucas pessoas abriam PRs com 2.000 linhas porque escrever 2.000 linhas levava dias.

Com IA, você pede uma refatoração e recebe 12 arquivos modificados em dois minutos. Esse gap entre velocidade de produção e velocidade de revisão é o problema central.

Por que o padrão "PR grande quando necessário" parou de funcionar

A justificativa clássica do PR grande é: "quando o contexto todo precisa entrar junto." Isso fazia sentido quando você controlava o escopo. Hoje o agente controla o escopo, e ele não tem incentivo para conter o tamanho.

Se você der uma tarefa grande a um agente sem dizer para fatiar, ele vai entregar tudo encadeado. Ele entrega tudo junto porque é mais simples do que fatiar. A complexidade fica no seu review, não no trabalho dele.

2. A conta real do PR grande

Bug escondido no diff

Revisar diff de 400 linhas e revisar diff de 1.800 são tarefas diferentes em complexidade cognitiva, além do tempo. Você consegue manter contexto ativo para uns poucos arquivos. Depois disso, você para de entender as interdependências e começa a aprovar por confiança, sem leitura real.

O bug que escapa num PR grande raramente está numa linha isolada. Está na interação entre três mudanças em arquivos diferentes que parecem desconexas.

Merge e conflito caros

PRs grandes ficam abertos mais tempo. Tempo aberto significa mais chances de conflito com main.

Resolver conflito em 400 linhas significa entender o estado da branch no momento da divergência e o estado atual de main e a intenção das mudanças nas duas. Qualquer um dos três que você errar, você quebra algo.

Revert em bloco

Você identifica que algo quebrou em produção. O culpado está no PR que entrou ontem.

PR pequeno: você reverte uma mudança cirúrgica. Em 5 minutos o sistema voltou ao estado anterior e você pode investigar.

PR grande: você reverte 1.800 linhas. Isso inclui mudanças que funcionavam e que você vai ter que reaplicar depois. E que podem conflitar de novo.

Time parado

Review não é um evento. É um contexto. Você precisa carregar a intenção do PR na cabeça para revisar com qualidade.

PR de 1.800 linhas não entra em 15 minutos de revisão. Ele pede 45 minutos de concentração, e a maioria dos times não tem esse slot disponível sempre.

O resultado prático: "LGTM" por cansaço. Review que tecnicamente aconteceu mas não detectou nada.

3. Antes de abrir o PR: o checklist

[ ] Qual é a única coisa que esse PR faz?
    → Se a resposta tiver "e" ou "além disso", divide.
 
[ ] O reviewer consegue entender a intenção sem explicação oral?
    → Título e descrição precisam contar a história.
 
[ ] Qual é o critério de "funcionando" para esse PR?
    → Se não tiver resposta clara, o review vai ser subjetivo.
 
[ ] Existem mudanças aqui que poderiam entrar independente?
    → Refatorações, renomes, ajustes de configuração — entram primeiro, separados.
 
[ ] O PR passa nos testes automatizados antes de abrir?
    → Nunca terceirize a verificação básica para o reviewer.

O teste dos 15 minutos

Se você não consegue explicar o que o PR faz em 15 minutos de review, ele é grande demais.

A métrica relevante é complexidade, não linhas. Um PR de 500 linhas que renomeia um módulo pode passar em 10 minutos. Um PR de 80 linhas que toca a lógica de autenticação pode precisar de 40.

4. Como estruturar work com IA para não empilhar mudanças

Fatie antes de pedir

A decisão de fatiar não acontece na hora de abrir o PR. Acontece na hora de dar a tarefa ao agente.

Em vez de:

"Refatora o módulo de autenticação para usar o novo padrão de tokens."

Use:

"Identifica todos os arquivos que precisam mudar para migrar o módulo de auth para o novo padrão de tokens. Não muda nada ainda."

Depois, com o mapa em mãos:

"Cria uma branch separada para cada grupo de mudanças: (1) só os tipos e interfaces, (2) a camada de serviço, (3) os endpoints."

Use branches de preparação

Mudanças estruturais (renomes, reorganização de pastas, extração de função) entram numa branch primeiro. Depois que estão em main, as mudanças de comportamento entram por cima.

Isso isola o barulho da refatoração do conteúdo que o reviewer precisa avaliar com atenção.

Desconfie de diff grande de agente

Se um agente devolveu mais de 300 linhas modificadas, pause antes de commitar.

Pause para confirmar que você entende o que está no diff. Você vai defender esse código no review. Se você não consegue, o agente foi longe demais.

A pergunta que vale: você entende o que mudou e por quê?

Princípio geral

PR pequeno exige clareza de intenção antes de tamanho.

Um PR que você consegue descrever numa frase vai receber review real. Um PR que precisa de dois parágrafos de contexto vai receber "LGTM" por cansaço.

Com IA no fluxo, você produz mais, e isso exige mais disciplina no fatiamento. O agente vai sempre entregar o maior escopo que você deixar. Sua responsabilidade é não deixar.

@developer.israel · AI Engineering · Práticas com Claude Code