Uma das maiores preocupações ao usar agentes de IA para editar código é o medo de perder o controle: "e se o Claude Code fizer uma mudança que quebra tudo e eu não conseguir voltar atrás?" A resposta para essa preocupação são os checkpoints no Claude Code. Este guia ensina a criar pontos de restauração em cada passo da sua sessão, garantindo que você sempre possa voltar no tempo com segurança total. Combinando Git com boas práticas de sessão, você elimina o risco de trabalhar com agentes de IA.
Sumário
O que é um checkpoint no Claude Code?
Um checkpoint é um ponto de salvamento do estado do seu projeto em um momento específico. Se algo der errado depois — uma edição que quebra a build, um refatoração que introduz bugs, uma mudança que você mudou de ideia — você volta ao checkpoint e retoma de lá como se nada tivesse acontecido.
No ecossistema do Claude Code, o checkpoint é implementado com Git. Mas a mentalidade é diferente do Git tradicional. No Git normal, commits são unidades lógicas e semânticas: "adiciona feature X", "corrige bug Y". No checkpoint para Claude Code, os commits são pontos de restauração frequentes e descartáveis: "antes de pedir a refatoração do módulo auth", "antes de pedir os testes do componente Button".
A diferença fundamental: commits normais você quer preservar. Checkpoints você cria sabendo que pode descartá-los depois com um git reset ou git rebase. Eles existem para dar segurança, não para documentar história.
Git como ferramenta de checkpoint
O Git é a ferramenta mais robusta para checkpoints no Claude Code por três razões:
- Instantâneo completo: Um checkpoint Git salva o estado de todo o projeto, não apenas dos arquivos editados.
- Restauração atômica: Voltar a um checkpoint restaura exatamente o estado anterior, sem efeitos colaterais.
- Zero dependência: Git já está instalado em qualquer ambiente de desenvolvimento, incluindo Windows com WSL.
Comandos essenciais de checkpoint
O padrão é simples: antes de cada comando de edição, checkpoint. Depois do resultado, avalie. Se ruim, reverta. Se bom, próximo checkpoint.
Fluxo de trabalho completo com checkpoints
Vamos a um exemplo real de sessão com checkpoints. Imagine que você precisa refatorar um componente React, adicionar testes e depois ajustar o CSS.
Note o padrão: checkpoint, comando, avaliação, checkpoint. Em nenhum momento você fica sem um ponto de restauração. Se o comando 3 quebrar tudo, você volta ao checkpoint do comando 2 sem perder os testes.
Checkpoint automático com scripts
Para não precisar digitar git add -A && git commit -m "chk: ..." manualmente a cada comando, crie um alias ou script no seu shell do Windows.
Alias no PowerShell
Alias no Git Bash / WSL
Com o alias, o fluxo de checkpoint fica tão rápido que você não pensa duas vezes antes de criar um. E a regra de ouro se mantém: se você pensou em criar um checkpoint, crie. O custo de um checkpoint extra é quase zero; o custo de não ter um pode ser horas de retrabalho.
Para ambientes com Git integrado com agentes de IA, scripts de checkpoint podem ser ainda mais sofisticados, incluindo verificação automática de build e testes antes de confirmar o checkpoint.
Recuperação de erros: voltando no tempo
Saber criar checkpoints é metade do trabalho. A outra metade é saber recuperar-se de erros usando esses checkpoints. Existem três cenários comuns:
Cenário 1: Último comando deu errado
Use quando o último comando do Claude Code produziu um resultado insatisfatório. Isso desfaz todas as mudanças do último checkpoint, deixando o projeto exatamente como estava antes.
Cenário 2: Múltiplos comandos deram errado
Use quando você percebe que uma sequência de comandos produziu resultados ruins. Por exemplo, três comandos de refatoração que introduziram bugs em cascata.
Cenário 3: Checkpoint específico
Use quando você quer voltar a um ponto específico, não necessariamente o último. Por exemplo, se o checkpoint 3 foi bom, o 4 e 5 foram ruins, e você quer voltar ao 3.
Cuidado: git reset --hard descarta mudanças não commitadas. Sempre crie um checkpoint antes de reverter. Se você tem trabalho não salvo no diretório de trabalho, use git stash antes do reset.
Checkpoints em ambiente multiagente
Em setups com múltiplos agentes rodando em paralelo, a estratégia de checkpoint precisa ser coordenada. Cada agente opera em seu próprio diretório ou branch, e os checkpoints são independentes.
No Orquestra, cada terminal de agente pode ter seu próprio checkpoint. Você pode ter um Claude Code fazendo checkpoints no módulo de front-end enquanto um Codex faz checkpoints no módulo de back-end. Se o Codex quebrar algo, você reverte apenas o checkpoint do Codex sem afetar o trabalho do Claude Code.
Para projetos que usam orquestração de agentes, a independência de checkpoints é um dos maiores benefícios: cada agente pode experimentar livremente, porque o checkpoint do outro agente está sempre lá como rede de segurança.
Perguntas frequentes
O que é um checkpoint no Claude Code?
Um checkpoint no Claude Code é um ponto de salvamento do estado do projeto antes de executar uma edição. Na prática, é um commit Git feito antes de cada comando de edição, permitindo reverter mudanças que não saíram como esperado.
Checkpoint e commit Git são a mesma coisa?
No contexto do Claude Code, sim. O checkpoint é implementado como um commit Git. A diferença é a intenção: checkpoints são descartáveis e frequentes (um por comando), enquanto commits são permanentes e representam unidades lógicas de trabalho.
Quantos checkpoints devo criar por sessão?
O ideal é um checkpoint por comando de edição. Se você der 5 comandos ao Claude Code, faça 5 checkpoints. Isso garante que você possa reverter qualquer passo individual sem perder o progresso dos demais.
Checkpoints consomem espaço em disco?
Sim, mas o impacto é mínimo. Commits no Git são delta compressions — cada checkpoint novo ocupa apenas a diferença. Mil checkpoints em um projeto típico ocupam menos de 50 MB. O Git faz limpeza automática com git gc.
Posso usar checkpoints com múltiplos agentes simultaneamente?
Sim. Com o Orquestra, cada agente tem seu próprio terminal e pode criar checkpoints independentes. Você pode ter um Claude Code fazendo checkpoints no front-end enquanto um Codex faz checkpoints no back-end, sem conflito.
Posts relacionados
Pronto para orquestrar seus agentes?
Baixe o Orquestra para Windows 11 e comece a coordenar seus agentes de IA em um canvas infinito. Grátis por 7 dias.