Revisão Pré-Commit (Auto-Revisão Pré-Landing)
Antes de enviar mudanças significativas, percorra esta lista de verificação. Pegue os problemas antes que a CI os pegue — ou pior, antes que os usuários o façam.
Quando Usar
Execute esta habilidade quando qualquer um destes for verdadeiro:
- Alterou >100 linhas de código
- Modificou >5 arquivos
- Toca na infraestrutura principal (executor, armazenamento, loops principais de despacho)
- Introduziu novas abstrações ou APIs públicas
- Incerteza sobre casos extremos ou escolhas de design
Portão rápido:
git diff --stat HEAD | tail -5 # Quanto mudou?
git diff --name-only HEAD | wc -l # Quantos arquivos?
Pular Se
- Mudança trivial (≤50 linhas, ≤3 arquivos)
- Apenas atualizações de documentação ou lições
- Mudanças apenas de teste (testes são sua própria revisão)
- Correção simples de uma linha com escopo óbvio e limitado
- Refatoração mecânica sem mudanças de lógica
A Lista de Verificação
1. Casos Extremos
- [ ] Entradas nulas/vazias tratadas?
- [ ] Condições de limite testadas (off-by-one, listas vazias, zero)?
- [ ] Acesso concorrente ou condições de corrida considerados?
- [ ] Problemas de Unicode/codificação se processando texto?
2. Caminhos de Erro
- [ ] Todas as exceções capturadas no nível correto (não muito amplo)?
- [ ] Mensagens de erro informativas (o que falhou, por que, o que fazer)?
- [ ] Modos de falha falham graciosamente, não silenciosamente?
- [ ] Nenhum `except:` vazio ou erros engolidos?
3. Cobertura de Testes
- [ ] Caminhos críticos têm testes?
- [ ] Casos extremos identificados acima têm testes?
- [ ] Testes realmente executam e passam?
- [ ] Nenhum stub de teste deixado como `pass` ou `...`?
4. Documentação
- [ ] Docstrings/comentários correspondem ao comportamento atual?
- [ ] README atualizado se a interface pública mudou?
- [ ] Mensagem de commit captura o que mudou e por quê?
- [ ] Documentos de arquitetura relevantes ainda precisos?
5. Qualidade de Código
- [ ] Nomes claros e consistentes com o código ao redor?
- [ ] Nenhum code smell óbvio (God functions, números mágicos, caminhos embutidos)?
- [ ] Segue os padrões existentes no arquivo/pacote?
- [ ] Análise estática / typecheck passa?
Teste de Fumaça de Uma Linha
# Execute antes de enviar (adapte à sua pilha):
make format && make typecheck && pytest -x -q && echo "✅ Limpo para enviar"
Se qualquer etapa falhar, corrija antes de enviar. Não envie vermelho.
Anti-Padrões
| Anti-Padrão | Correção |
|---|---|
| "A CI vai pegar" | CI é um último recurso, não um substituto para seu próprio julgamento. Pegue primeiro. |
| "Vou adicionar testes depois" | Depois não chega. Escreva o teste agora ou aceite a lacuna permanentemente. |
| "Funcionou quando testei manualmente" | Testes manuais não são reproduzíveis. Escreva um teste automatizado para que sessões futuras também possam verificar. |
| "A mensagem de erro é um TODO" | Mensagens de erro TODO são enviadas como mensagens de erro TODO. Escreva a mensagem real agora. |
| "Posso ver pelo código que ele trata este caso" | Se não for testado, uma refatoração futura quebrará invisivelmente. |
Por Que Isso Importa
Agentes autônomos são treinados para produzir saídas boas o suficiente para evitar correção. Sem um portão de revisão estruturado, os commits autônomos de código contornam a verificação humana que normalmente pega regressões e casos extremos. Esta habilidade atua como esse portão — cinco lentes alvo executadas em sequência para que nada óbvio escape.
O benefício se acumula: cada passagem de revisão que pega um problema real é uma rodada de CI economizada, um bug de usuário evitado e um PR de reversão não necessário.
Relacionados
- Habilidade de Auto-Envio (Self-Push) — verificação de qualidade/preguiça que complementa esta revisão estrutural
- Habilidade de Revisão Multi-Lente (Multi-Lens Review) — revisão paralela mais profunda para mudanças de alto risco