Claude Code: Checkpoints e Rollback
Última atualização: 2026-08-31
Checkpoints são a rede de segurança do Claude Code — auto-snapshots antes de operações críticas, rollback a qualquer momento se problemas surgirem.
💡 Dica: Checkpoints não são apenas commits git — são snapshots em granularidade de sessão registrando o estado de cada operação para rollback preciso a qualquer passo.
📋 Pré-requisitos: Capítulo 19 - Manual de Referência CLI
1. O Que Você Vai Aprender
- Mecanismo de checkpoints e auto-snapshots
- Criação manual de checkpoints
- Rollback para qualquer passo
- Relação entre checkpoints e git
- Estratégias de rede de segurança
2. Mecanismo de Checkpoints
(1) Como Funciona
| Condição de Gatilho | Auto-Cria | Descrição |
|---|---|---|
| Início de sessão | ✅ | Registra estado inicial |
| Antes de modificação de arquivo | ✅ | Registra estado pré-modificação |
| Antes de execução de comando | ✅ | Registra estado pré-comando |
| Solicitação manual | ✅ | /checkpoint |
▶ Exemplo 1: Ver Lista de Checkpoints
TEXT
📖 Somente leitura
> /checkpoints
#1 [14:20:00] Session start | 0 files changed
#2 [14:22:15] Modified jwt.ts | 2 files changed
#3 [14:25:30] Modified auth.ts | 1 file changed
#4 [14:30:15] Added tests | 3 files changed
#5 [14:35:00] Current state | 6 files changed
3. Checkpoints Manuais
(1) Criar Checkpoint
TEXT
📖 Somente leitura
> /checkpoint
✅ Checkpoint #6 created
> /checkpoint "Pre-migration state"
✅ Checkpoint #6 created with description
(2) Melhores Práticas — Quando Criar
| Momento | Motivo |
|---|---|
| Antes de grandes mudanças | Refatoração, migração, etc. |
| Conclusão de marco | Um ponto de funcionalidade finalizado |
| Operações incertas | Antes de modificações experimentais |
| Antes de sair | Salvar progresso atual |
▶ Exemplo 2: Antes de Grandes Mudanças
TEXT
📖 Somente leitura
> /checkpoint "Pre-migration state"
✅ Checkpoint #6 created
> Migrate auth from Session to JWT
Claude Code: Modifying 12 files... 3 tests failed ❌
# Alice decide fazer rollback e tentar diferente
> /rollback 6
✅ Rolled back to checkpoint #6 (pre-migration state)
4. Operações de Rollback
(1) Métodos de Rollback
| Comando | Descrição |
|---|---|
/rollback |
Rollback para checkpoint anterior |
/rollback <n> |
Rollback para checkpoint especificado |
/undo |
Desfazer operação mais recente |
git checkout . |
Reverter todas as mudanças não commitadas |
▶ Exemplo 3: Rollback Passo a Passo
TEXT
📖 Somente leitura
> /checkpoints
#1 [14:20] Start
#2 [14:22] Added UserService
#3 [14:25] Added tests
#4 [14:30] Refactored UserService (failed)
#5 [14:35] Attempted fix (still failing)
# Apenas reverter refatoração falha, manter adições bem-sucedidas
> /rollback 3
✅ Rolled back to checkpoint #3
Kept: UserService + tests
Reverted: Refactor + fix attempt
# Refatorar com abordagem diferente
> Refactor UserService with different approach
5. Checkpoints vs Git
(1) Comparação
| Dimensão | Checkpoint | Git |
|---|---|---|
| Granularidade | Nível de operação | Nível de commit |
| Persistência | Apenas na sessão | Permanente |
| Armazenamento | Memória/temp | Repositório |
| Compartilhamento | Não compartilhável | Pushável |
| Rollback | Preciso ao passo | Preciso ao commit |
(2) Estratégia Cooperativa
TEXT
📖 Somente leitura
# Melhor prática: Checkpoint + git dupla garantia
# 1. Git commit antes da sessão
git add -A && git commit -m "before: claude session"
# 2. Usar checkpoints para rollback dentro da sessão
/checkpoint "Milestone complete"
/rollback 3
# 3. Git commit após a sessão
git add -A && git commit -m "feat: user auth module"
# 4. Se sessão inteira falhar, git rollback
git reset --hard HEAD~1
6. Rede de Segurança em Múltiplas Camadas
TEXT
📖 Somente leitura
Level 1: /undo — Desfazer operação mais recente
Level 2: /rollback — Rollback para checkpoint
Level 3: git checkout — Reverter mudanças não commitadas
Level 4: git reset — Rollback para qualquer commit
Level 5: git reflog — Recuperar commits perdidos
❓ Perguntas Frequentes
P: Por quanto tempo checkpoints são retidos? R: Apenas dentro da sessão atual. Sair perde checkpoints, mas commits git são permanentes.
P: Rollback perde todo o progresso? R: Não. Rollback para checkpoint específico apenas reverte mudanças após aquele ponto; mudanças anteriores são preservadas.
P: Posso fazer rollback de um único arquivo? R: Rollback de checkpoint é por passo. Rollback de arquivo único:
git checkout -- <file>.
P: Após rollback, o Claude Code lembra a conversa anterior? R: Sim. O histórico de conversa é preservado mas o estado dos arquivos é revertido. O Claude Code sabe o que você fez e o que reverteu.
📖 Resumo
- Checkpoints auto-criam antes de operações críticas; manual via
/checkpoint /rollback <n>para rollback preciso ao passo especificado- Checkpoints são em nível de sessão; git é permanente; use ambos juntos
- Rede de segurança em múltiplas camadas: undo → rollback → git checkout → git reset → reflog
- Sempre crie checkpoints antes de grandes mudanças
📝 Exercícios
- Básico (⭐): Crie checkpoint, faça mudanças, faça rollback, verifique arquivo restaurado.
- Intermediário (⭐⭐): Execute 3 passos de modificação, rollback ao passo 2, verifique passo 1 preservado e passo 3 revertido.
- Avançado (⭐⭐⭐): Desenhe rede de segurança em múltiplas camadas combinando checkpoints e git para recuperação de qualquer operação.
