Date: 2026-09-10

​
Revisão de código e recuperação segura

Nesta lição, vais aprender a pedir revisões de código baseadas em evidências e a recuperar alterações sem perder trabalho local.

​
A revisão é uma tarefa baseada em evidências

Uma revisão de código útil identifica defeitos que podem ser demonstrados a partir do código, do diff, dos testes ou do comportamento em execução. Deve dar prioridade às conclusões pelo impacto e evitar encher a resposta com preferências de estilo. A Nova pode rever:
  • Alterações não submetidas na árvore de trabalho.
  • Alterações preparadas para commit.
  • Um commit ou intervalo específico.
  • O diff de um pull request fornecido através de uma integração disponível.
  • Ficheiros selecionados ou um subsistema.
  • Código sensível para segurança, numa perspetiva defensiva.
Não tens de assumir que existe um comando /review integrado. Pede diretamente à Nova, invoca uma competência de revisão se estiver instalada ou cria um comando com barra do projeto em .compass/commands para um fluxo de trabalho repetível da equipa.

​
Um pedido de revisão eficaz

Define o âmbito e as prioridades da revisão:
Para um subsistema:
Para uma implementação que a Nova acabou de concluir:

​
Fluxo de revisão

Normalmente, a Nova deve:
  1. Inspecionar o estado do repositório para compreender ficheiros preparados, não preparados e não rastreados.
  2. Ler um resumo antes de pedir um diff grande.
  3. Examinar os ficheiros alterados com contexto envolvente suficiente.
  4. Seguir os locais de chamada, contratos e testes afetados.
  5. Executar verificações focadas e não destrutivas quando aumentarem a confiança.
  6. Comunicar as conclusões antes de resumos ou elogios.
Uma conclusão relevante deve incluir:
  • A gravidade ou o impacto prático.
  • O caminho e a linha exatos.
  • O motivo pelo qual o comportamento atual está errado.
  • Um cenário realista que desencadeie a falha.
  • A menor correção credível.
Se não encontrares um defeito, indica-o e identifica qualquer risco não testado em vez de inventares problemas.

​
Usa o agente de verificação para uma análise independente

A Nova inclui um perfil especializado de verificação para revisões só de leitura, inspeção de segurança defensiva, reprodução de falhas e validação de testes direcionados. É útil quando um agente de implementação já alterou o código e uma segunda análise isolada reduz o viés de confirmação. O resultado da verificação deve fornecer um veredito PASS, FAIL, PARTIAL ou BLOCKED, com evidências concretas. A sessão principal continua a ter de avaliar as conclusões antes de agir sobre elas.

​
Disciplina do diff

Uma revisão deve separar:
  • Alterações introduzidas pela tarefa atual.
  • Alterações preexistentes do utilizador.
  • Saída gerada.
  • Ficheiros não rastreados que possam conter segredos ou estado local.
Nunca faças reset, clean ou checkout sobre uma árvore de trabalho com alterações apenas para facilitar a revisão. Inspeciona-a e preserva o trabalho do utilizador.

​
Reverter uma conversa

A Nova suporta:
Isto remove a interação mais recente entre utilizador e assistente do contexto da conversa. Não reverte ferramentas já executadas. Edições de ficheiros, comandos de shell, commits, pushes, emails enviados, eventos de calendário ou alterações remotas mantêm-se em vigor. Este comando serve para corrigir a direção da conversa, não o estado operacional.

​
Restaurar ficheiros de pontos de controlo

Quando os pontos de controlo do fluxo de trabalho estão ativos, a Nova pode pré-visualizar um plano de recuperação limitado a ficheiros:
Restaura apenas um ficheiro com cópia de segurança depois de aprovares:
A restauração a partir de pontos de controlo é deliberadamente opcional e limitada. Não executa uma reversão automática ampla do espaço de trabalho.

​
Recuperação baseada em Git

O Git fornece o melhor rasto de auditoria para trabalho preparado ou com commit, mas os comandos de recuperação variam quanto ao caráter destrutivo. Antes de reverteres algo:
  1. Inspeciona o estado e o diff relevante.
  2. Identifica o trabalho não submetido que tens de preservar.
  3. Prefere um novo commit de reversão para histórico partilhado.
  4. Evita force pushes e reescrever o histórico, salvo se for explicitamente autorizado e seguro.
  5. Nunca uses um reset destrutivo como atalho para não compreenderes a alteração.
A Nova deve pedir confirmação para operações que descartem trabalho ou alterem histórico publicado.

​
Rever após a recuperação

A recuperação só fica concluída quando verificares o estado resultante. Volta a executar os testes direcionados, inspeciona o diff e confirma que apenas os ficheiros pretendidos foram alterados. Se a operação original afetou um sistema externo, verifica esse sistema de forma independente; uma reversão local pode não reparar efeitos remotos.

​
Recapitulação

Uma boa revisão demonstra problemas com evidências, preserva alterações preexistentes e comunica apenas conclusões acionáveis. A recuperação segura começa por inspecionar o estado e termina por verificar o resultado.

​
Prática segura

Pede à Nova para rever um diff preparado ou não submetido sem editar nada. Confirma que distingue as alterações da tua tarefa de quaisquer alterações preexistentes e que apresenta caminhos e linhas para cada conclusão. Anterior: Gestão de contexto e sessões | Seguinte: NOVA.md e regras do projeto