Depurar por evidência e revisar por risco

Laboratório: revisão por categorias de risco

Mão na massa 8 min de leitura 40 min de prática Você leva: Checklist de review calibrado do seu time

Rodar uma revisão assistida em oito categorias sobre um pull request real e classificar o que voltou em verdadeiro positivo, falso positivo e ruído.

Revisão assistida serve para ampliar o alcance: uma pessoa cansada às seis da tarde não lembra de checar autorização, concorrência e observabilidade em todo diff. O assistente lembra sempre — e erra com frequência. O laboratório é sobre calibrar isso.

A chave é revisar por categoria de risco, não em geral. "Revise este código" produz comentários de estilo. Um pedido categoria por categoria produz achados que o formatter não pegaria.

Revisão em oito categorias

Revise o diff abaixo como engenheiro sênior do time.

Objetivo da mudança: [uma frase]
Critérios de aceite: [lista]
Contexto: [cole o CONTEXT.md]

Revise nesta ordem, uma seção por categoria:
1. Correção — a mudança faz o que o objetivo diz?
2. Autenticação e autorização — quem pode chamar isso?
3. Exposição de dados — algo sensível vaza em resposta, log ou erro?
4. Injeção e entrada não confiável
5. Concorrência — o que acontece com duas execuções simultâneas?
6. Performance sob volume real — [informe a escala]
7. Observabilidade — dá para diagnosticar isso em produção às 3h?
8. Testes — o que passaria se a regra estivesse errada?

Para CADA achado, obrigatório:
- trecho exato
- cenário concreto de falha (entrada → resultado errado)
- severidade: bloqueante / recomendado / dúvida
- confiança: alta / média / baixa
- correção mínima

Regras:
- Não comente estilo coberto pelo formatter.
- Se não houver achado numa categoria, escreva "nada encontrado" e siga.
- Se você não conseguir descrever o cenário de falha, NÃO reporte o achado.

Diff:
[cole sanitizado]

A penúltima regra é o filtro mais eficiente: a maior parte dos falsos positivos morre na hora de escrever o cenário concreto de falha.

Mão na massa40 min

Calibrar a revisão assistida no código do seu time e produzir um checklist que reflita os erros que vocês realmente cometem.

Use um pull request já revisado e aprovado por gente. Assim você tem gabarito: sabe o que os humanos acharam e pode comparar.

Escolha um PR já mergeado, de tamanho médio, e sanitize o diff.
Rode o prompt das oito categorias.
Classifique cada achado: verdadeiro positivo / falso positivo / verdadeiro mas irrelevante.
Compare com os comentários que os humanos deixaram no PR original.
Anote o que os humanos pegaram e o assistente não — essa é a lista mais valiosa.
Anote em quais categorias a taxa de falso positivo foi alta no seu código.
Escreva o checklist calibrado com o que sobrou.

Deu certo quando

Cada achado foi classificado em uma das três categorias.
Existe uma lista do que só os humanos pegaram.
As categorias com muito falso positivo estão identificadas.
O checklist final tem menos de 15 itens — cabe numa revisão real.

Se travar: Se quase tudo voltou como falso positivo, provavelmente o diff foi colado sem contexto suficiente. Autorização e concorrência são as categorias que mais dependem de saber o que existe fora do diff — cole a interface ou o middleware relevante.

Você leva daquiChecklist de review calibrado

Diferente de um checklist genérico da internet: este contém os erros que o seu time comete e as categorias em que a IA acerta no seu código.

# Checklist de review — [time/projeto]
Calibrado em [data] sobre [n] pull requests

## Sempre verificar (assistido)
- [ ] Autorização: todo endpoint novo tem verificação explícita
- [ ] Query com valor de usuário usa bind
- [ ] Nenhum catch vazio
- [ ] Nenhuma consulta dentro de laço
- [ ] [item específico do seu domínio]

## Só humano pega (nossa experiência)
- [ ] A regra bate com o requisito escrito
- [ ] A decisão é reversível? Se não, alguém mais viu?
- [ ] Faz sentido no fluxo que o usuário realmente percorre
- [ ] [item que a IA errou nos nossos testes]

## Categorias em que a IA gera muito ruído aqui
- [ex: performance — sugere índice sem ver o EXPLAIN]
- [ex: segurança — marca como injeção o que usa allowlist]

## Regra do time
Nenhum pull request é aprovado por ferramenta. O parecer é de uma pessoa,
que pode usar a ferramenta para ampliar o alcance da leitura.

Onde guardar: No repositório, como CONTRIBUTING.md ou template de pull request.

A lista "só humano pega" é a mais importante

É ela que responde por que a revisão humana continua obrigatória. Quase todos os itens dela têm a mesma natureza: dependem de saber o que o sistema deveria fazer, e isso não está no diff.

Em uma frase

Exigir cenário concreto de falha em cada achado elimina a maior parte do ruído antes de você ler.

← Aula anterior Próxima aula →

Comentários e dúvidas

Inscreva-se grátis para comentar, tirar dúvidas, marcar seu progresso e emitir o certificado ao fim do curso.

Inscrever-se grátis com Google

Ainda não há comentários nesta aula.