Em times de engenharia maduros, code review não é um ritual burocrático nem um “check de qualidade” superficial. Ele é a última linha de defesa entre uma boa intenção e um incidente em produção. Ainda assim, um antipadrão persiste mesmo em times experientes: Pull Requests grandes, extensos, multifoco, frequentemente com 900 ou 1000 linhas de código.
O problema não é apenas estético. PRs grandes aumentam exponencialmente a carga cognitiva do revisor, reduzem a efetividade da revisão e fazem com que detalhes críticos passem despercebidos. O resultado aparece dias ou semanas depois, em forma de bugs evitáveis, retrabalho e perda de confiança no processo.
Ao longo da carreira, muitos engenheiros chegam à mesma conclusão: um bom PR trata de um único assunto e não é extensivo. Essa definição não é opinião pessoal nem preferência cultural; ela é sustentada por estudos empíricos, práticas consolidadas de engenharia e princípios básicos de sistemas complexos.
Tudo começa no planejamento
A capacidade de quebrar bem um PR nasce antes da primeira linha de código ser escrita. Ela começa no momento em que o desenvolvedor pega um card para trabalhar. Antes de pensar em implementação, é fundamental entender exatamente o que precisa ser feito, qual problema de produto está sendo resolvido e qual impacto aquela mudança terá no sistema e no negócio.
Quando esse entendimento não acontece, o código tende a crescer de forma desordenada. O desenvolvedor começa a “aproveitar o embalo” para corrigir coisas adjacentes, refatorar partes não relacionadas ou antecipar problemas futuros. O resultado é um PR que tenta resolver tudo de uma vez, e acaba não sendo revisado corretamente em nada.
Planejamento técnico não é burocracia. Ele é um exercício de clareza. Se não conseguimos planejar a execução de um único card, dificilmente conseguiremos planejar uma frente inteira, um sistema ou um trimestre de entregas. Isso não é apenas sobre código, é sobre maturidade de carreira.
Um card não é um Pull Request
Um erro comum é assumir que um card do backlog deve resultar em um único PR. Na prática, isso quase nunca é verdade para mudanças não triviais. Um card descreve um objetivo de produto; o PR é apenas uma unidade técnica de entrega.
Durante o refinamento, um card pode ter sido estimado em oito pontos. No entanto, ao planejar a execução técnica, o desenvolvedor percebe que a mudança envolve novas integrações, alterações estruturais ou impactos em múltiplas camadas do sistema, elevando o esforço real para treze pontos. Nesse momento, o correto não é “dar um jeito” e seguir em frente, mas sinalizar, ajustar a estimativa e replanejar.
Separar o “o quê” do “como” é o que permite quebrar uma feature em PRs pequenos, coerentes e revisáveis. Esse planejamento prévio também facilita encadear commits de forma lógica e produzir uma sequência de PRs que fazem sentido isoladamente.
O custo cognitivo de PRs grandes
Existe evidência empírica forte mostrando que revisões grandes são menos eficazes. Um dos maiores estudos já realizados sobre code review, conduzido pela SmartBear em parceria com a Cisco, analisou mais de 2.500 revisões e milhões de linhas de código.
O estudo mostra que revisões acima de 400 linhas reduzem drasticamente a taxa de detecção de defeitos. O ponto ótimo está entre 200 e 400 linhas de código, revisadas em sessões de até 60 ou, no máximo, 90 minutos. Nesse intervalo, revisores conseguem identificar entre 70% e 90% dos defeitos existentes. Acima disso, a eficácia despenca.
Referência: https://www.drivehq.com/file/df.aspx/publish/pranaslu/WordPressFiles/BestPracticesForPeerCodeReview.pdf
Esse dado é fundamental porque desmonta o argumento de que “é só revisar com mais atenção”. Atenção humana é um recurso limitado. Revisão de código é uma atividade de alta carga cognitiva, e ignorar isso é projetar um processo fadado ao erro.
PR pequeno não é sobre velocidade de merge
Um ponto importante de nuance é que PRs pequenos não existem para “mergear mais rápido”. Um estudo publicado na conferência MSR 2022, analisando mais de 800 mil PRs em múltiplas linguagens, mostra que o tamanho do PR não tem correlação direta com o tempo até o merge.
Referência: https://arxiv.org/abs/2203.05045
Isso é relevante porque desloca a discussão do eixo errado. PRs pequenos não são uma otimização de fluxo administrativo; eles são uma otimização de qualidade, entendimento e redução de risco. O ganho está na revisão, não no merge.
O software como uma esteira de produção
Sistemas comerciais evoluem como uma esteira de produção, ou como uma pilha de camadas sendo empilhadas progressivamente até gerar valor de negócio. Cada camada tem responsabilidades, dependências e riscos distintos.
Camadas mais próximas da interface lidam com APIs HTTP, gRPC, consumers, contratos e camadas de anticorrupção. Camadas de negócio concentram regras, validações, pipelines e casos de uso. Camadas estruturais lidam com banco de dados, integrações externas e mudanças de schema. Camadas físicas envolvem novos serviços, bancos, clusters e consumo de recursos.
Quanto mais abaixo na pilha, maior o número de dependências e maior o custo de erro. Por isso, a ordem de implementação importa. Se a camada de negócio depende de um provedor externo, não faz sentido começar pelo domínio sem antes garantir que a integração existe, está testada e é estável.
Esse é um ponto natural de quebra de PR. Um PR para integração com o provedor externo, outro para adaptar a camada de negócio. Cada PR resolve um problema claro, é revisável e reduz o risco sistêmico.
Quebrar PRs é uma habilidade de Maturidade.
Guia de práticas de engenharia do Google reforça esse ponto de forma direta. Eles recomendam mudanças pequenas, autocontidas, que resolvam uma única coisa. Segundo o próprio guia, cerca de 100 linhas costuma ser um tamanho razoável para uma mudança, enquanto mil linhas geralmente é grande demais.
Referência: https://google.github.io/eng-practices/review/developer/small-cls.html
O guia também destaca que grandes mudanças devem ser divididas antes da implementação, não depois. Dividir um PR depois de pronto é caro, desgastante e frequentemente mal feito. Engenheiros experientes pensam na decomposição antes de escrever código.
Essa habilidade não é apenas técnica. Ela reflete capacidade de abstração, entendimento de dependências, visão sistêmica e maturidade profissional. É por isso que a capacidade de planejar, fatiar e entregar incrementalmente costuma diferenciar engenheiros Staff de níveis mais juniores.
Conclusão
Quebrar bem uma feature em múltiplos PRs não é sinal de lentidão nem de excesso de zelo. É sinal de engenharia madura. PRs pequenos aumentam a qualidade da revisão, reduzem bugs, facilitam rollback, melhoram a comunicação do time e tornam o sistema mais evolutivo.
Mais importante ainda, eles forçam clareza de pensamento. Se não conseguimos explicar uma mudança em um PR pequeno, provavelmente ainda não entendemos bem o problema que estamos tentando resolver.
No fim, a arte de quebrar PRs é a arte de pensar bem antes de codar. E isso, inevitavelmente, é o que sustenta sistemas grandes, times escaláveis e carreiras de longo prazo.
