Date: 2026-09-10

​
Explorar, planear, programar, verificar e fazer commit

Nesta lição, vais aplicar um fluxo de trabalho de engenharia que reduz suposições: primeiro compreendes o estado atual, depois alteras apenas o necessário e por fim verificas o resultado.

​
Um fluxo de trabalho disciplinado

A Nova é mais fiável quando o trabalho no repositório segue cinco etapas explícitas:
  1. Explorar a implementação atual.
  2. Planear quando a incerteza ou o risco o justificam.
  3. Programar a menor alteração coerente.
  4. Verificar com evidência adequada à alteração.
  5. Fazer commit apenas quando pedido explicitamente.
Estas etapas não têm de se tornar cinco conversas separadas. Uma correção clara e de baixo risco pode atravessá-las numa só interação. O princípio é não saltar a análise nem a verificação.

​
1. Explorar

Começa por localizar o comportamento, as respetivas dependências e os testes. A Nova deve preferir pesquisas focadas de nomes de ficheiros e código e, depois, ler secções específicas em vez de analisar todo o repositório. Exemplo:
Um resultado de exploração útil distingue:
  • Factos observados no código e na configuração.
  • Inferências que ainda precisam de confirmação.
  • A causa principal dos sintomas a jusante.
  • Convenções existentes que uma correção deve seguir.
  • Testes ou evidência de runtime em falta.

​
2. Decidir se deves planear

O planeamento é adequado para alterações de arquitetura, migrações, alterações incompatíveis, sistemas de alto risco ou trabalho que abrange módulos acoplados onde uma sequência errada causaria retrabalho. A Nova distingue a execução direta do fluxo de planeamento sujeito a aprovação. Normalmente, classifica o pedido pela complexidade e pelo risco; também podes pedir um plano explicitamente:
Um plano formal é registado e acompanhado pelo ambiente de execução. Depois de aprovado, a Nova executa tarefas sequencialmente e regista a conclusão. Se o âmbito mudar de forma material, o plano deve ser atualizado em vez de abandonado em silêncio. Usa /resume plan [planId] para listar ou reativar planos de implementação incompletos numa sessão interativa. Para correções simples, a execução direta é preferível. Criar um plano para corrigir uma gralha numa linha acrescenta formalidade sem reduzir o risco.

​
3. Programar

A implementação deve seguir os padrões estabelecidos pelo projeto. Antes de editar, a Nova deve analisar:
  • A função ou componente completo que vai mudar.
  • Importações, tipos e interfaces públicas.
  • Implementações próximas que resolvem problemas semelhantes.
  • Testes e fixtures existentes.
  • Manifestos de dependências antes de introduzir uma biblioteca.
Um prompt de implementação forte é específico sobre os invariantes:
A Nova deve evitar formatação não relacionada, refatorações oportunistas, abstrações especulativas e comentários que apenas repetem o código.

​
4. Verificar

A verificação deve visar os critérios de sucesso observáveis. Consoante o projeto, pode incluir:
  • Testes unitários ou de integração focados.
  • Linting e verificação de tipos.
  • Um build de produção.
  • Verificação no browser de um fluxo de UI real e dos seus estados de carregamento, erro, vazio e sucesso.
  • Análise de diff em trabalho apenas de documentação.
  • Estado de Git para confirmar a superfície exata da alteração.
Um comando que passa é evidência apenas do que realmente verifica. A Nova não deve afirmar que uma UI está correta apenas porque a verificação de tipos passou, nem que o runtime está correto apenas porque o diff está limpo. Quando uma verificação falhar, determina se a falha foi introduzida pela alteração, já existia ou depende de um serviço externo indisponível. Não ocultes falhas nem as apresentes como sucesso.

​
5. Rever e fazer commit

Antes de fazer commit, analisa a árvore de trabalho e o diff preparado. Procura ficheiros não relacionados, artefactos gerados, credenciais, binários demasiado grandes e alterações de configuração acidentais. A Nova não precisa de um commit para considerar uma implementação concluída. Faz commit apenas quando o pedires. Quando o agente interativo trata desse pedido, o fluxo é:
  1. Analisar o estado do Git.
  2. Preparar as alterações relevantes.
  3. Rever o diff preparado.
  4. Gerar uma mensagem de commit convencional.
  5. Executar o commit sem contornar hooks.
  6. Fazer push apenas se pedires push.
Os comandos integrados /commit e nova commit são mais restritos: exigem alterações já preparadas, geram uma mensagem convencional a partir de git diff --staged e criam o commit. Não preparam ficheiros nem fazem push. As alterações existentes de outros utilizadores não devem ser repostas nem substituídas como atalho.

​
Recuperar de erros

A Nova suporta /rollback last para remover a última interação da conversa do contexto ativo. Isto não desfaz efeitos secundários. A recuperação de checkpoints é independente, opcional, limitada a ficheiros e sujeita a aprovação:
O Git continua a ser a forma autorizada de analisar o histórico do repositório, mas resets ou checkouts destrutivos que descartam trabalho exigem cuidado e aprovação explícitos.

​
Recapitulação

  • Explora e identifica a causa principal antes de alterar código.
  • Planeia apenas quando o risco, o acoplamento ou a incerteza o justificarem.
  • Verifica o comportamento e o âmbito da alteração antes de fazeres commit.

​
Prática segura

Escolhe uma pequena falha conhecida num repositório de teste e começa por pedir uma investigação sem edição:
Só pede uma implementação depois de reveres a evidência e definires que verificações devem passar. Anterior: A tua primeira sessão com a Nova · Seguinte: Gestão de contexto e sessões