Como é que acompanhamos as revisões de PR na era da IA?

1. Delimite cada PR a apenas uma coisa

A forma mais rápida de matar o ritmo de uma revisão é um PR que faz três coisas ao mesmo tempo. Os revisores não devem ter de desenvencilhar mentalmente quais as alterações que pertencem à correção do bug e quais pertencem à refatorização que introduziu sorrateiramente.

• Uma correção de bug, um campo, uma funcionalidade, e não as três no mesmo PR.

• Um PR focado de cerca de 1.000 linhas que resolve um problema claro é perfeitamente aceitável. Um PR de 300 linhas com três preocupações diferentes não o é. Se ultrapassar largamente as 1.000 linhas, é um sinal claro de que deve dividi-lo.

• Utilize PRs empilhados (stacked) para alterações maiores.

• Faça uma autoanálise antes de abrir: alguém consegue rever isto de uma só vez? Faz exatamente uma única coisa? Estaria confortável em integrá-lo (merge)?

2. Não peça revisão até estar realmente pronto

Os Rascunhos (Drafts) existem por uma razão. Retirar um PR do estado de rascunho é um sinal para a equipa de que fez o seu trabalho de casa e que isto merece o tempo de outra pessoa. Se esse sinal não for fiável, todo o sistema de revisão falha.

Só o deve retirar do estado de rascunho se puder responder sim a tudo isto:

• Fez uma auto-revisão

• Todos os testes passam, incluindo os testes de ponta a ponta (e2e)

• Zero comentários não resolvidos (incluindo os do Devin)

• Testou localmente no que toca a alterações de UI/UX

• Para alterações que podem ser cobertas por testes automatizados, verificou que estão 100% cobertas

• Todas as tarefas do CI estão verdes (exceto as irritantes pré-visualizações do Vercel)

Se responder "não" a alguma, deixe-o como rascunho. Rascunhos a solicitar revisão poluem a fila de espera e atrasam os PRs que estão efetivamente prontos.

3. Limite os seus PRs abertos a um máximo de 5 (incluindo rascunhos)

Os PRs abertos representam inventário em espera. Eles acarretam custos de mudança de contexto, risco de conflitos de integração (merge conflicts) e dívida de revisão. Se tiver mais de cinco abertos em simultâneo, as contas não batem certo. Está a produzir mais rápido do que a equipa consegue absorver.

Se tiver 5 PRs abertos, entre rascunhos e não rascunhos combinados, não comece nada de novo. Vá antes rever os PRs dos seus colegas de equipa ou conclua os seus trabalhos mais antigos.

4. Coloque uma voz humana na descrição do seu PR

A descrição não tem de ser totalmente escrita por si. A IA serve perfeitamente para estruturar e resumir as diferenças no código (diff). O problema com o que se vê atualmente são as descrições massivas geradas por IA que parecem uma lista genérica de verificação com a qual ninguém realmente interagiu. Falta-lhes o elemento humano de que o revisor realmente necessita.

• Uma nota do autor de apenas uma frase sobre a solução de compromisso (trade-off) escolhida, ou o porquê de esta correção ser importante agora, é muito mais valiosa do que um bloco longo do tipo "Pontos Chave da Revisão" / "Lista de Verificação de Revisão Humana".

• Se estiver a lançar código que ainda não é utilizado em lado nenhum, explique o motivo.

• Se a IA rascunhou a descrição, edite-a para a reduzir e adicione o contexto que só você possui.

5. Prove que a correção funciona

Um PR que diz "corrige o bug X" sem provas adicionais está a pedir ao revisor que acredite por mera fé. Não faça com que eles tenham de fazer isso.

• Capturas de ecrã (screenshots), gravações de ecrã, painéis de controlo de antes/depois; tudo o que mostre que o bug foi eliminado e que nada mais sofreu regressão.

• O controlo de qualidade funcional (QA) é obrigatório para alterações de UX/UI, não é opcional.

6. Alterações de SQL e desempenho necessitam de validação real

A simples revisão de código não consegue confirmar se a reescrita de uma consulta (query) se mantém sob carga de produção. Ler um diff de uma consulta e dizer "parece correto" não é validar. Para PRs que mexam com caminhos de consulta ou reescritas:

• EXPLAIN ANALYZE num conjunto de dados com o mesmo perfil de produção

• Métricas de latência de antes/depois ou capturas de ecrã dos painéis de controlo

• Lançamento faseado por feature-flags para alterações de alto risco

7. A IA é um acelerador, não um cérebro

A IA consegue gerar código rapido. Não consegue decidir se esse código deve existir. O raciocínio ainda tem de vir de si.

• Pense na arquitetura primeiro. Defina a abordagem, pense nos casos limite (edge cases), escreva uma nota curta e depois faça o pedido à IA (prompt).

• Depois de o agente gerar o código, leia-o de facto. Uma auto-revisão deteta chamadas Prisma no local errado, diretrizes do agente que foram ignoradas, estruturas frágeis, etc.

• Antes de abrir o PR, pergunte-se: em que é que isto mexe? Tem algum impacto para o utilizador? Implicações de desempenho ou segurança? Qual é o raio de destruição se estiver incorreto?

8. Valide os PRs de segurança antes de os abrir

Confirme que a vulnerabilidade realmente se aplica à forma como utilizamos o código. Os PRs do tipo "Corrigir vulnerabilidade X" que mexem em caminhos sensíveis podem introduzir mais riscos do que o relatório original.

9. Direcione os PRs para o revisor certo

O revisor errado desperdiça o tempo de duas pessoas: o do revisor, que não consegue dar feedback relevante, e o do autor, que tem de esperar por uma segunda ronda com a pessoa adequada.

• PRs muito específicos de um domínio (encaminhamento Salesforce/CRM, migrações de perfis de equipa, etc.) pertencem ao proprietário desse domínio, e não à equipa de Foundation para darem uma aprovação automática a uma suite de testes gerada por IA.

• Alterações a caminhos estruturais (core/foundation), tais como infraestrutura de consultas, hasTeamAccess, etc., merecem um alinhamento rápido com a equipa proprietária antes da abertura do PR.

10. As conversas sobre arquitetura acontecem cedo

Aplicar correções provisórias na mesma área três vezes é um sinal, não uma coincidência. Se está a contornar a mesma limitação novamente, a atitude correta é uma conversa e uma potencial reescrita, não mais um remendo.

Fale com Foundation / Responsável de Engenharia antes de implementar. Foi assim que os módulos de infraestrutura surgiram, e a consistência gera dividendos com o tempo.

11. Um caminho mais simples para correções triviais

Nem tudo necessita de uma revisão por parte de Foundation. Devemos gastar a largura de banda de revisão onde ela é mais valiosa.

Pequenos ajustes em mensagens do tipo "toast", dimensionamento de botões, alterações mecânicas de nomes, correções de textos, funcionalidades padrão – tudo isto pode passar por revisão de IA e/ou revisões ao nível da equipa. Reserve a revisão de Foundation para alterações que realmente precisem dela.

12. Não abra PRs em nome de outros

Se o Engenheiro X está a fazer o trabalho, é o Engenheiro X que abre o PR. Caso contrário, os comentários chegam à pessoa errada, as perguntas ficam sem resposta e o PR fica bloqueado.