Itere em passos pequenos

Field Note

Sexta-feira, 15h. O plano estava aprovado: cinco etapas para migrar a tela de relatórios para a API nova. A pessoa disse "pode executar tudo" e foi para uma reunião. Na volta, 31 arquivos alterados, a suíte de testes com nove falhas e um resumo otimista dizendo que "faltam pequenos ajustes". Quais das nove falhas vieram da etapa 1? Quais da etapa 4? Não dá para saber. Não existe ponto intermediário para onde voltar. Existe só o tudo, e o tudo está vermelho.

Conceito

Iterar em passos pequenos é cortar o trabalho em fatias que podem ser rodadas, revisadas e revertidas uma de cada vez. A ideia é velha em engenharia de software. Com agente, ela fica mais importante, porque o agente produz código mais rápido do que você revisa. Pedido monolítico maximiza a chance de receber muita coisa errada de uma vez só.

Fatia vertical, não camada. Uma fatia boa atravessa o sistema e termina funcionando: um endpoint novo com um campo, o teste e a tela mostrando esse campo. Uma fatia ruim é "primeiro todo o banco, depois toda a API, depois toda a tela". Na fatia por camada, nada funciona até a última etapa, e qualquer erro só aparece no fim.

Cada fatia tem três coisas:

1. Um objetivo que cabe numa frase.
2. Uma verificação que roda (teste, build, comando, tela).
3. Um ponto de retorno (checkpoint e commit).

Checkpoints, conferidos na doc oficial. O Claude Code cria um checkpoint automático a cada prompt seu que inicia um turno, com snapshot dos arquivos antes da mudança. Ele guarda os snapshots dos 100 checkpoints mais recentes da sessão, e os checkpoints ficam salvos com a conversa, então dá para usar /rewind mesmo depois de retomar a sessão.

/rewind, ou Esc duas vezes com o campo de texto vazio, abre o menu. Você escolhe um prompt anterior e uma ação:

• Restore code and conversation: volta código e conversa para aquele ponto.
• Restore conversation: volta a conversa e mantém o código atual.
• Restore code: volta os arquivos e mantém a conversa.
• Summarize from here: resume a conversa daquele ponto em diante, liberando contexto.
• Summarize up to here: resume o que veio antes e mantém o recente.
• Never mind: sai sem mudar nada.

O que o checkpoint não cobre. A doc lista limitações que importam muito aqui:

• Mudanças feitas por comandos de shell (rm, mv, cp) não são rastreadas.
• Edições feitas por subagentes, em geral, não voltam com rewind. Use git.
• Edições suas fora do Claude Code ou de outra sessão não são capturadas.
• Mensagem que você manda na fila e entra no meio de um turno não ganha checkpoint próprio.
• Não substitui controle de versão. A doc diz isso com todas as letras.

Por isso a regra prática desta lição é: checkpoint para desfazer rápido dentro da sessão, commit para marcar cada fatia aprovada.

Feedback específico. Entre uma fatia e outra, o feedback que funciona aponta o que está errado e onde. "Ficou ruim" gera outra tentativa no escuro. "O total está somando o frete duas vezes, veja calcTotal em report.ts" gera uma correção. E vale a regra que já apareceu: depois de duas correções sem efeito no mesmo ponto, /clear e um pedido melhor.

Testar um caminho alternativo. Se quiser tentar outra direção sem perder a atual, /branch cria um ramo da conversa naquele ponto. O original fica disponível pelo /resume.

Quando usar

• Qualquer plano com mais de uma etapa.
• Mudança que mexe em código que outras partes usam.
• Quando a verificação é lenta: fatias pequenas mostram o erro antes de ele se espalhar.
• Quando você vai sair e deixar rodando. Peça que ele pare e espere depois de cada fatia.

Quando não usar

• Mudança atômica que não faz sentido pela metade (renomear um símbolo em todo o projeto de uma vez, com teste rodando no fim).
• Correção de uma linha. Fatiar o que já é pequeno só cria cerimônia.
• Quando cada fatia exige uma rodada de revisão tão cara que o custo passa do benefício. Aí aumente a fatia, não pule a verificação.

Faça agora

A prática é entregar uma Sequência de três checkpoints, com evidência de cada um.

1. Pegue o plano aprovado da lição anterior, ou uma tarefa que dê para dividir em três partes. Branch separada.
2. Peça a divisão:

Divida este plano em três fatias verticais. Cada fatia precisa terminar com o sistema funcionando e ter uma verificação que roda. Para cada uma, diga o objetivo em uma frase e o comando de verificação. Não implemente ainda.

3. Execute só a primeira fatia:

Implemente apenas a fatia 1. Rode a verificação dela e me mostre a saída. Pare e espere minha revisão antes de seguir.

4. Revise o que mudou com /diff e leia a saída da verificação. Se aprovado, faça o commit da fatia (você ou ele, com mensagem que diga qual fatia é).
5. Repita para as fatias 2 e 3.
6. Em pelo menos uma das fatias, provoque um desvio de propósito ou aproveite um que aconteceu, e use /rewind com Restore code and conversation para voltar. Anote o que voltou e o que não voltou.
7. Registre os três commits (hash e mensagem) e a evidência de verificação de cada um.

Armadilhas

• "Pode executar tudo." É o pedido monolítico com outro nome. Peça parada explícita entre fatias.
• Fatiar por camada. Nada funciona até o fim, e o erro só aparece no fim.
• Confiar no rewind para comando de shell. Arquivo apagado com rm não volta pelo menu. Commit volta.
• Pular o commit "porque tem checkpoint". Checkpoint é da sessão e tem retenção limitada. Commit é do projeto.
• Feedback vago. "Não gostei" não diz onde mexer. Aponte arquivo, função e comportamento esperado.
• Seguir quando a direção piora. Se a fatia 2 está desfazendo a fatia 1, pare. Volte ao plano.

Material para levar

Registro da sequência:

Tarefa:
Branch:

Fatia 1
  Objetivo (uma frase):
  Verificação (comando):
  Saída observada:
  Commit (hash e mensagem):

Fatia 2
  Objetivo:
  Verificação:
  Saída observada:
  Commit:

Fatia 3
  Objetivo:
  Verificação:
  Saída observada:
  Commit:

Rewind usado em qual fatia:
O que voltou:
O que não voltou e precisou de git:

Regras de bolso:

Fatia boa termina funcionando
Uma frase de objetivo, um comando de verificação
Pare entre fatias, revise com /diff, faça commit
Checkpoint desfaz rápido, commit marca o que foi aprovado
Shell e subagente não voltam pelo rewind
Duas correções sem efeito: /clear e pedido novo