Engenharia de Software

Engenharia de Pull Requests: boas práticas aprendidas contribuindo para o AI-DLC da AWS Labs

Escopo, evidências, comunicação, testes e aprendizado em revisões de código.

Iury Coelho

10 de ago. de 202613 min de leitura

Uma mudança não está pronta apenas porque o código foi escrito. Ela está pronta quando o time possui contexto e evidências suficientes para compreender, revisar e assumir responsabilidade pelo que será entregue.

Revisão de código não é caça a estilo. É uma decisão de engenharia antes do merge.

Mas essa decisão não acontece somente quando alguém abre a aba Files changed. Ela começa na forma como o problema é explicado, passa pelo tamanho da mudança, pela qualidade dos testes e pela clareza da conversa entre autor e reviewers.

Durante minhas contribuições ao projeto open source awslabs/aidlc-workflows, tive Pull Requests incorporados ao projeto e acompanhei revisões detalhadas, com mais de uma rodada de ajustes em alguns casos.

O principal aprendizado não foi uma técnica específica. Foi perceber que um bom review depende de disciplina dos dois lados:

o autor precisa tornar a mudança compreensível e verificável;
o reviewer precisa explicar riscos e expectativas com clareza;
o feedback precisa ser tratado como investigação, não como disputa;
documentação e testes precisam acompanhar o comportamento real;
a aprovação deve considerar o estado mais recente do Pull Request.

Este artigo reúne as práticas que mais se destacaram nessas contribuições.

1. Pull Request é uma conversa de engenharia

Um Pull Request conecta diferentes perspectivas:

produto;
arquitetura;
segurança;
testes;
documentação;
operação;
manutenção futura.

Por isso, ele não deveria ser apenas um pacote de arquivos aguardando aprovação.

Um PR profissional precisa permitir que outra pessoa responda, sem depender de uma reunião paralela:

Qual problema está sendo resolvido?
Por que essa abordagem foi escolhida?
O que mudou para o usuário ou para o sistema?
Como a solução foi validada?
Quais limitações ou riscos permanecem?

Quando esse contexto não está presente, o reviewer precisa reconstruir a intenção a partir do código. Isso aumenta o tempo de revisão e também o risco de interpretar a mudança de forma incorreta.

O Google Engineering Practices apresenta o Code Review como um mecanismo para melhorar continuamente a saúde do código, sem exigir que cada mudança seja perfeita. Essa ideia ajuda a equilibrar qualidade e progresso: o objetivo é melhorar o sistema com segurança, não transformar cada PR em uma revisão infinita de toda a aplicação.

2. Uma boa revisão começa com uma mudança revisável

O guia Small CLs, do Google Engineering Practices explica que mudanças pequenas e simples tendem a ser revisadas mais rapidamente e com maior profundidade, além de serem menos propensas a introduzir bugs e mais fáceis de integrar.

Mas “pequena” não significa apenas ter poucas linhas.

Uma mudança revisável normalmente:

possui uma intenção principal;
evita misturar feature, refactor e documentação sem necessidade;
explica o que está fora do escopo;
inclui testes e documentação relacionados;
apresenta uma sequência de commits compreensível;
pode ser validada sem reconstruir todo o projeto mentalmente.

A pergunta mais útil não é:

Quantas linhas foram modificadas?

É:

Quantas decisões diferentes o reviewer precisa compreender para aprovar esta mudança?

Um PR com poucas linhas pode alterar uma regra importante. Outro, maior, pode ser uma atualização mecânica. O tamanho deve ser avaliado junto com o risco e a quantidade de decisões envolvidas.

3. O autor deve preparar o review

O trabalho do autor não termina quando o código compila.

Um bom Pull Request prepara o caminho para a revisão. A descrição pode incluir:

contexto do problema;
comportamento anterior;
comportamento esperado;
decisão adotada;
alternativas consideradas;
testes executados;
screenshots, logs ou exemplos;
impacto em documentação;
limitações conhecidas;
verificações que ainda dependem do CI ou de outro ambiente.

Um modelo simples:

## Problema

O que estava acontecendo?

## Mudança

O que foi alterado e por quê?

## Como validar

- Testes automatizados:
- Verificação manual:
- Evidências:

## Riscos e limitações

- Risco residual:
- O que não foi validado:
- Follow-ups:

Uma das melhores práticas que observei nas discussões foi a transparência sobre validação.

Em vez de afirmar genericamente que “todos os testes passaram”, é melhor registrar:

quais comandos foram executados;
em qual ambiente;
quais testes direcionados passaram;
quais testes não puderam ser executados;
se algum resultado depende da execução oficial do CI.

Evidência profissional também inclui dizer claramente o que ainda não foi verificado.

4. O reviewer deve explicar impacto, não apenas apontar linhas

O guia What to look for in a code review, do Google Engineering Practices orienta o reviewer a avaliar design, funcionalidade, complexidade, testes, nomenclatura, comentários, estilo, documentação e o contexto mais amplo da mudança.

Um comentário útil responde a três perguntas:

O que foi identificado?
Por que isso importa?
O que precisa acontecer antes do merge?

Glossário de comentários

issue: existe um problema;
suggestion: há uma melhoria possível;
question: o reviewer precisa de contexto;
nitpick: detalhe não bloqueante;
blocking: precisa ser resolvido antes do merge;
non-blocking: pode ser tratado depois.

Exemplo:

issue (blocking): este comando depende de o usuário estar em outro diretório,
mas a documentação não informa essa mudança de contexto.

Ao seguir os passos literalmente, o comando falha. Antes do merge, indique
explicitamente em qual diretório ele deve ser executado.

Compare com:

Isso está errado.

O primeiro comentário cria uma base objetiva para a correção. O segundo transfere para o autor o trabalho de descobrir o problema e a expectativa do reviewer.

O padrão Conventional Comments ajuda a diferenciar tipos de feedback:

issue: existe um problema;
suggestion: há uma melhoria possível;
question: o reviewer precisa de contexto;
nitpick: detalhe não bloqueante;
blocking: precisa ser resolvido antes do merge;
non-blocking: pode ser tratado depois.

O valor desses rótulos não está na formalidade. Está em reduzir ambiguidade.

5. Nem todo comentário deve bloquear o merge

Quando o time não diferencia gravidade, qualquer comentário pode virar uma negociação longa.

Uma classificação simples pode ajudar:

Nível	Significado	Bloqueia?
P0	risco crítico imediato	sim
P1	bug ou risco relevante	sim
P2	problema importante	depende
P3	melhoria	normalmente não
Nit	preferência local	não

Essa nomenclatura não é universal. Cada organização pode usar outra.

O importante é o reviewer deixar claro:

qual é o impacto;
se o comentário bloqueia;
qual mudança é esperada;
se um follow-up é aceitável.

Isso evita dois extremos:

tratar toda sugestão como obrigatória;
ignorar um risco real porque ele apareceu misturado a comentários de estilo.

6. Feedback não deve virar defesa da primeira solução

Uma das práticas mais valiosas que observei foi reproduzir os findings antes de responder.

O fluxo pode ser:

flowchart TD A["Finding do reviewer"] --> B["Reproduzir o cenário"] B --> C["Criar teste que demonstra o problema"] C --> D["Corrigir a causa"] D --> E["Executar nova validação"] E --> F["Responder ao reviewer com evidências"]

Uma resposta forte não precisa ser longa, mas deve ser verificável:

## Reprodução

Consegui reproduzir o comportamento no commit indicado.

## Causa

A mudança não considerava o cenário em que...

## Correção

Ajustei...

## Validação

- Teste adicionado:
- Regressões executadas:
- Limitação ainda existente:

Essa prática muda o tom da conversa.

Em vez de:

“Acho que isso não acontece.”

A resposta passa a ser:

“Reproduzi o cenário, identifiquei a causa e adicionei uma verificação para impedir a regressão.”

Também é importante admitir quando a primeira solução estava incompleta. Em revisões maduras, mudar de direção depois de uma boa evidência não é fraqueza. É engenharia.

7. Três lições de contribuições já incorporadas ao projeto

Selecionei três Pull Requests já mergeados porque eles representam aprendizados diferentes e complementares.

7.1 PR #642 — revisar a jornada completa do usuário

No PR #642, a proposta adicionava às instruções de instalação um passo que estava faltando: clonar o repositório e acessar a branch correta.

A primeira mudança resolvia o problema principal, mas o review identificou outros pontos dentro do mesmo fluxo:

alguns comandos ainda pressupunham um diretório diferente;
uma seção de referência rápida podia ser acessada sem o contexto da instalação;
as instruções precisavam permanecer consistentes entre vários guias.

A lição não é apenas sobre documentação.

Revise o caminho que a pessoa percorre, não apenas o parágrafo modificado.

Uma alteração pode estar correta isoladamente e ainda falhar quando alguém segue o processo completo.

Boas perguntas para esse tipo de review:

De onde o usuário começa?
Em qual diretório ele está?
A instrução depende de uma etapa anterior?
Uma pessoa pode acessar esta seção diretamente?
O mesmo fluxo aparece em outros documentos?

7.2 PR #644 — cada rodada de review deve aumentar a qualidade

No PR #644, uma parte do processo que dependia de cálculo em texto foi transformada em uma execução previsível e testável.

O Pull Request passou por várias rodadas de review. Os comentários encontraram problemas diferentes ao longo do tempo:

casos de arredondamento;
parâmetros aceitos sem o efeito esperado;
entradas inválidas;
documentação ausente;
testes que precisavam acompanhar as regras;
conflitos surgidos porque a branch principal continuou evoluindo.

O aprendizado mais importante foi o processo:

reproduzir cada finding;
corrigir a causa;
acrescentar testes;
revisar novamente a documentação;
validar o novo head depois de rebase;
confirmar que arquivos gerados continuavam sincronizados.

A aprovação deve considerar a versão atual do PR, não apenas a versão que iniciou a conversa.

Esse caso também mostrou que Code Review não é uma etapa única. Em mudanças relevantes, cada rodada pode revelar uma nova camada: primeiro o comportamento principal, depois os casos de borda, depois a integração com o estado mais recente do repositório.

7.3 PR #645 — não escreva uma garantia maior do que o sistema oferece

No PR #645, a proposta corrigia uma divergência entre documentação e o local real de determinados artefatos.

Durante o review, algumas frases foram consideradas amplas demais. A documentação dizia, em essência, que algo “nunca” acontecia em determinado local, mas havia uma exceção legítima. Também descrevia reutilização onde o comportamento real era de atualização e sobrescrita.

Em outra rodada, o changelog foi revisado porque parecia descrever uma mudança de runtime que, na prática, nunca havia existido daquela forma.

A boa prática aprendida foi:

Antes de fortalecer uma afirmação, siga o comportamento real do sistema.

Palavras como estas merecem cuidado:

sempre;
nunca;
somente;
garante;
impede;
reutiliza;
não altera comportamento.

Documentação e changelog fazem parte da entrega. Eles precisam descrever exatamente o que mudou, sem diminuir a importância da contribuição e sem prometer mais do que ela realiza.

Esse PR também mostrou uma boa decisão de escopo: um problema relacionado, mas maior, foi separado em uma issue própria em vez de ampliar indefinidamente a mudança atual.

Um bom review melhora o PR sem transformar cada finding em obrigação de resolver todo o sistema.

8. O que essas revisões tinham em comum

Apesar de tratarem de problemas diferentes, as melhores práticas se repetiram.

Clareza de intenção

O reviewer conseguia comparar a proposta com o comportamento esperado.

Evidência concreta

Os comentários eram acompanhados de caminhos, exemplos, comandos ou cenários reproduzíveis.

Distinção entre bloqueador e melhoria

Os reviews deixavam claro o que precisava mudar antes do merge e o que poderia virar follow-up.

Respostas baseadas em reprodução

As correções eram explicadas a partir do comportamento observado, não apenas de opinião.

Honestidade sobre limites

Quando um teste completo não podia ser executado localmente, isso era registrado.

Revisão do conjunto

Código, testes, documentação, changelog e arquivos gerados eram tratados como partes da mesma mudança.

Validação depois de rebase

O PR era reavaliado quando a branch base mudava, porque o contexto de integração também muda.

9. IA pode ajudar, mas os padrões precisam estar no projeto

Em desenvolvimento assistido por IA, boas práticas não deveriam depender apenas de instruções repetidas em cada conversa.

O Amazon Q Developer permite manter regras em arquivos Markdown dentro de:

Estrutura do projeto

project-root/
- .amazonq/
  - rules/
    - 00-project-context.md
    - 01-architecture.md
    - 02-coding-standards.md
    - 03-security.md
    - 04-testing.md
    - 05-pull-requests.md
    - 06-documentation.md
    - 07-observability.md
    - 08-database.md
    - 09-api-design.md
    - 10-ai-dlc-workflow.md
- src/
- tests/
- docs/
- README.md
- ...

Essas regras podem ser usadas como contexto nas conversas do projeto, conforme a documentação oficial sobre project rules.

Exemplo:

# Pull Requests

- Mantenha uma intenção principal por PR.
- Explique o comportamento anterior e o comportamento esperado.
- Registre testes executados e limitações de ambiente.
- Diferencie comentários bloqueantes de sugestões.
- Findings reproduzidos devem gerar teste de regressão quando aplicável.
- Não declare uma garantia maior do que a implementação demonstra.

Isso ajuda agentes e pessoas a trabalharem com os mesmos princípios.

Mas há uma distinção importante:

Regras orientam. Checks automatizados verificam. Reviewers exercem julgamento.

Uma regra pode pedir testes. O CI confirma se eles passam. Uma regra pode pedir documentação. O reviewer avalia se ela está correta e suficiente.

A abordagem do AI-DLC reforça essa combinação entre assistência da IA, artefatos persistentes e validação humana.

10. Checklist prático

Para quem abre o Pull Request

O problema está explicado.
A mudança possui uma intenção principal.
O comportamento anterior e o esperado estão claros.
Testes e evidências foram incluídos.
Limitações foram declaradas.
Documentação e changelog foram avaliados.
O PR está atualizado com a branch base.

Para quem revisa

Li a descrição antes de iniciar pelo diff.
Avaliei comportamento, não apenas estilo.
Expliquei o impacto dos findings.
Diferenciei bloqueadores de sugestões.
Considerei o fluxo completo do usuário.
Verifiquei testes e documentação.
Evitei ampliar o escopo sem necessidade.

Para responder ao feedback

Reproduzi o problema.
Corrigi a causa, não apenas o exemplo.
Adicionei ou atualizei testes.
Registrei o que foi validado.
Declarei o que não pude executar.
Atualizei a descrição do PR quando a solução mudou.

Conclusão

Um bom Pull Request não é aquele que recebe aprovação rapidamente ou que não recebe comentários.

É aquele que permite uma decisão de merge consciente.

As contribuições ao awslabs/aidlc-workflows reforçaram para mim que boas revisões dependem de:

escopo claro;
descrição verificável;
comunicação respeitosa;
feedback com impacto e expectativa explícitos;
reprodução antes da correção;
testes que preservam o aprendizado;
documentação fiel ao comportamento;
honestidade sobre limitações;
revisão do head atual;
capacidade de separar correções obrigatórias de evoluções futuras.

Code Review profissional não é uma disputa entre autor e reviewer. É uma investigação colaborativa para reduzir incerteza antes do merge.

Quando essa cultura existe, o review deixa de ser uma cerimônia de aprovação e se transforma em uma das melhores ferramentas de aprendizado, qualidade e compartilhamento de conhecimento de um time.