Exemplos de checkpoints
Exemplos reais de utilização eficaz de checkpoints no Claude Code.
6 min
Checkpoints e retrocesso
InicianteGrátis11 minatualizado 2026-10-21
Os checkpoints permitem guardar o estado da conversa e retroceder para pontos anteriores da sua sessão no Claude Code. Isto é muito útil para explorar abordagens diferentes, recuperar de erros ou comparar soluções alternativas.
Visão geral
Os checkpoints permitem guardar o estado da conversa e retroceder para pontos anteriores, possibilitando experimentação segura e a exploração de várias abordagens. São instantâneos do estado da sua conversa, incluindo:
- Todas as mensagens trocadas
- Alterações feitas aos ficheiros
- Histórico de utilização de ferramentas
- Contexto da sessão
Os checkpoints são muito úteis ao explorar abordagens diferentes, recuperar de erros ou comparar soluções alternativas.
Conceitos-chave
| Conceito | Descrição |
|---|---|
| Checkpoint | Instantâneo do estado da conversa, incluindo mensagens, ficheiros e contexto |
| Retrocesso | Regresso a um checkpoint anterior, descartando as alterações posteriores |
| Ponto de bifurcação | Checkpoint a partir do qual se exploram várias abordagens |
Aceder aos checkpoints
Pode aceder aos checkpoints e gerí-los de duas formas principais:
Usar o atalho de teclado
Prima Esc duas vezes (Esc + Esc) para abrir a interface de checkpoints e navegar pelos checkpoints guardados.
Usar o comando slash
Use o comando /rewind (aliases: /checkpoint, /undo) para um acesso rápido:
Terminal
# Open rewind interface
/rewind
# Or use the alias
/checkpointOpções de Retrocesso
Ao retroceder, é apresentado um menu com seis opções:
- Restaurar código e conversa -- Reverte tanto os ficheiros como as mensagens para esse ponto de controlo
- Restaurar conversa -- Retrocede apenas as mensagens, mantendo o código atual tal como está
- Restaurar código -- Reverte apenas as alterações nos ficheiros, mantendo o histórico completo da conversa
- Resumir a partir daqui -- Comprime a conversa, a partir deste ponto em diante, num resumo gerado por IA, libertando espaço na janela de contexto. As mensagens anteriores ao ponto selecionado mantêm-se intactas. Nenhum ficheiro no disco é alterado. As mensagens originais são preservadas na transcrição da sessão. Pode, opcionalmente, indicar instruções para focar o resumo em tópicos específicos.
- Resumir até aqui -- A contraparte no sentido inverso: comprime tudo o que está antes do ponto selecionado num resumo gerado por IA, mantendo intactas as mensagens a partir deste ponto. Juntamente com "Resumir a partir daqui", obtém uma compactação bidirecional e direcionada da janela de contexto. Nenhum ficheiro no disco é alterado, e as mensagens originais são preservadas na transcrição da sessão.
- Deixar para lá -- Cancela e regressa ao estado atual
Nota: Depois de restaurar a conversa ou de escolher Resumir a partir daqui, o prompt original da mensagem selecionada é repuesto no campo de entrada, para que possa reenviá-lo ou editá-lo. Ao escolher Resumir até aqui, fica no fim da conversa com o campo de entrada vazio.
/cleardeixou de ser uma fronteira rígida (v2.1.191+): o/rewindpode retomar a partir de um ponto de controlo criado antes de executar/clear. Limpar a conversa já não descarta de forma permanente o estado que a precedia: pode retroceder para além da limpeza, se precisar outra vez desse código ou contexto anterior.
Pontos de Controlo Automáticos
O Claude Code cria pontos de controlo automaticamente:
- Em cada prompt do utilizador - É criado um novo ponto de controlo a cada entrada do utilizador
- Persistentes - Os pontos de controlo são guardados com a conversa, pelo que o
/rewindcontinua a funcionar depois de retomar uma sessão - Limpeza automática - Os pontos de controlo são eliminados automaticamente após 30 dias
Isto significa que pode retroceder sempre para qualquer ponto anterior da conversa, desde há alguns minutos até vários dias antes.
Casos de Utilização
| Cenário | Fluxo de trabalho |
|---|---|
| Explorar abordagens | Guardar → Experimentar A → Guardar → Retroceder → Experimentar B → Comparar |
| Refatorização segura | Guardar → Refatorizar → Testar → Se falhar: Retroceder |
| Testes A/B | Guardar → Desenhar A → Guardar → Retroceder → Desenhar B → Comparar |
| Recuperação de erros | Notar o problema → Retroceder até ao último estado bom |
Utilizar Pontos de Controlo
Ver e Retroceder
Prima Esc duas vezes ou use /rewind para abrir o navegador de pontos de controlo. Verá a lista de todos os pontos de controlo disponíveis, com carimbos de data e hora. Selecione qualquer ponto de controlo para retroceder até esse estado.
Detalhes do Ponto de Controlo
Cada ponto de controlo mostra:
- Data e hora em que foi criado
- Ficheiros que foram modificados
- Número de mensagens na conversa
- Ferramentas que foram utilizadas
Exemplos Práticos
Exemplo 1: Explorar Abordagens Diferentes
Terminal
User: Let's add a caching layer to the API
Claude: I'll add Redis caching to your API endpoints...
[Makes changes at checkpoint A]
User: Actually, let's try in-memory caching instead
Claude: I'll rewind to explore a different approach...
[User presses Esc+Esc and rewinds to checkpoint A]
[Implements in-memory caching at checkpoint B]
User: Now I can compare both approachesExemplo 2: Recuperar de erros
Terminal
User: Refactor the authentication module to use JWT
Claude: I'll refactor the authentication module...
[Makes extensive changes]
User: Wait, that broke the OAuth integration. Let's go back.
Claude: I'll help you rewind to before the refactoring...
[User presses Esc+Esc and selects the checkpoint before the refactor]
User: Let's try a more conservative approach this timeExemplo 3: Experimentação segura
Terminal
User: Let's try rewriting this in a functional style
[Creates checkpoint before experiment]
Claude: [Makes experimental changes]
User: The tests are failing. Let's rewind.
[User presses Esc+Esc and rewinds to the checkpoint]
Claude: I've rewound the changes. Let's try a different approach.Exemplo 4: Abordagens de ramificação
Terminal
User: I want to compare two database designs
[Takes note of checkpoint - call it "Start"]
Claude: I'll create the first design...
[Implements Schema A]
User: Now let me go back and try the second approach
[User presses Esc+Esc and rewinds to "Start"]
Claude: Now I'll implement Schema B...
[Implements Schema B]
User: Great! Now I have both schemas to choose fromRetenção de checkpoints
O Claude Code gere automaticamente os seus checkpoints:
- Os checkpoints são criados automaticamente a cada prompt do utilizador
- Os checkpoints antigos são retidos durante um máximo de 30 dias
- Os checkpoints são limpos automaticamente para evitar um crescimento ilimitado do armazenamento
Padrões de fluxo de trabalho
Estratégia de ramificação para exploração
Ao explorar várias abordagens:
Terminal
1. Start with initial implementation → Checkpoint A
2. Try Approach 1 → Checkpoint B
3. Rewind to Checkpoint A
4. Try Approach 2 → Checkpoint C
5. Compare results from B and C
6. Choose best approach and continuePadrão de Refatorização Segura
Ao efetuar alterações significativas:
Terminal
1. Current state → Checkpoint (auto)
2. Start refactoring
3. Run tests
4. If tests pass → Continue working
5. If tests fail → Rewind and try different approachBoas práticas
Como os checkpoints são criados automaticamente, pode concentrar-se no seu trabalho sem se preocupar em guardar o estado manualmente. No entanto, tenha estas práticas em atenção:
Utilizar checkpoints de forma eficaz
✅ Faça:
- Reveja os checkpoints disponíveis antes de retroceder
- Use o retrocesso quando quiser explorar direções diferentes
- Mantenha os checkpoints para comparar abordagens diferentes
- Compreenda o que cada opção de retrocesso faz (restaurar o código e a conversa, restaurar a conversa, restaurar o código ou resumir)
❌ Não faça:
- Depender apenas dos checkpoints para preservar o código
- Esperar que os checkpoints detetem alterações externas no sistema de ficheiros
- Usar os checkpoints como substituto dos commits do git
Configuração
Os checkpoints são um comportamento predefinido integrado no Claude Code e não requerem qualquer configuração para serem ativados. Cada prompt do utilizador cria automaticamente um checkpoint.
Duas definições regem o comportamento dos checkpoints - se os instantâneos são ou não capturados e durante quanto tempo são mantidos:
Terminal
{
"fileCheckpointingEnabled": true,
"cleanupPeriodDays": 30
}| Definição | Predefinido | Efeito |
|---|---|---|
fileCheckpointingEnabled | true | Cria uma cópia dos ficheiros antes de cada edição para que /rewind os possa restaurar. Requer a versão 2.1.119 ou superior. Aparece em /config como Rewind code (checkpoints). Equivalente na variável de ambiente: CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING |
cleanupPeriodDays | 30 | Número de dias durante os quais o histórico de sessões e os checkpoints são mantidos |
O Claude Code mantém as cópias dos 100 checkpoints mais recentes; os mais antigos são eliminados mesmo dentro do período de retenção.
Atualização da versão 2.1.117:cleanupPeriodDayspassa agora a regular a retenção de muitas caches em disco, e não apenas dos checkpoints (uma seleção abaixo; as transcrições de sessões,file-history/,plans/,debug/,paste-cache/e outras também estão abrangidas):
- Checkpoints de sessões
- ~/.claude/tasks/ - listas de tarefas persistentes
- ~/.claude/shell-snapshots/ - cópias do ambiente de shell capturadas
-~/.claude/backups/- versões anteriores de~/.claude.json(são mantidas as cinco mais recentes)
Uma única definição elimina agora estas pastas de forma uniforme, ao fim do mesmo número de dias.
Limitações
Os checkpoints têm as seguintes limitações:
- Alterações feitas por comandos Bash NÃO são registadas - Operações como
rm,mvoucpno sistema de ficheiros não são capturadas nos checkpoints - Alterações externas NÃO são registadas - As alterações feitas fora do Claude Code (no seu editor, no terminal, etc.) não são capturadas
- Não substituem o controlo de versões - Use o git para alterações permanentes e auditáveis na sua base de código
- As edições feitas por subagentes NÃO são restauradas - Os ficheiros editados por um subagente não são registados, pelo que
/rewindos deixa como estão; a exceção é uma skillcontext: forkem primeiro plano, cujas edições são restauradas como as da sessão principal
Atualização da versão 2.1.216: /rewind já não restaura nem elimina ficheiros através de ligações simbólicas ou ligações físicas em caminhos registados. Se um caminho registado for resolvido através de uma ligação simbólica ou física, o rewind ignora-o em vez de seguir a ligação, e indica quantos caminhos ignorou por este motivo.
Resolução de problemas
Checkpoints em falta
Problema: O checkpoint esperado não foi encontrado
Solução:
- Verifique se os checkpoints foram limpos
- Verifique o espaço em disco
- Certifique-se de que
cleanupPeriodDaysestá definido com um valor suficientemente alto (predefinido: 30 dias)
Falha no rewind
Problema: Não é possível retroceder para o checkpoint
Solução:
- Certifique-se de que não existem alterações não confirmadas em conflito
- Verifique se o checkpoint está corrompido
- Tente retroceder para outro checkpoint
Integração com o Git
Os checkpoints complementam o git, mas não o substituem:
| Funcionalidade | Git | Checkpoints |
|---|---|---|
| Âmbito | Sistema de ficheiros | Conversa + ficheiros |
| Persistência | Permanente | Baseada na sessão |
| Granularidade | Commits | Qualquer ponto |
| Velocidade | Mais lenta | Instantânea |
| Partilha | Sim | Limitada |
Use os dois em conjunto:
- Use checkpoints para experimentação rápida
- Use commits do git para alterações finalizadas
- Crie um checkpoint antes de operações git
- Faça commit dos estados de checkpoint bem-sucedidos no git
Guia de início rápido
Fluxo de trabalho básico
- Trabalhe normalmente - O Claude Code cria checkpoints automaticamente
- Quer voltar atrás? - Prima
Escduas vezes ou use/rewind - Escolha um checkpoint - Selecione um da lista para retroceder
- Selecione o que restaurar - Escolha entre restaurar código e conversa, restaurar apenas a conversa, restaurar apenas o código, resumir a partir daqui, resumir até aqui, ou cancelar
- Continue a trabalhar - Volta a esse ponto
Atalhos de teclado
Esc+Esc- Abre o navegador de checkpoints/rewind- Forma alternativa de aceder aos checkpoints/checkpoint,/undo- Aliases de/rewind
Saber quando retroceder: monitorização do contexto
Os checkpoints permitem voltar atrás, mas como saber quando deve fazê-lo? À medida que a conversa cresce, a janela de contexto do Claude enche-se e a qualidade do modelo degrada-se em silêncio. Pode estar a entregar código de um modelo com menos capacidade sem se aperceber.
O cc-context-stats resolve este problema ao acrescentar zonas de contexto em tempo real à barra de estado do Claude Code. Indica onde se encontra na janela de contexto, desde Plan (verde, seguro para planear e programar), passando por Code (amarelo, evite começar novos planos), até Dump (laranja, termine e retroceda). Quando a zona muda, sabe que é altura de criar um checkpoint e recomeçar em vez de continuar com resultados degradados.
Conceitos relacionados
- Funcionalidades avançadas - Modo de planeamento e outras capacidades avançadas
- Gestão de memória - Gestão do histórico da conversa e do contexto
- Comandos slash - Atalhos invocados pelo utilizador
- Hooks - Automação orientada a eventos
- Plugins - Pacotes de extensões
Recursos adicionais
- Documentação oficial sobre checkpoints
- Guia de funcionalidades avançadas - Pensamento alargado e outras capacidades
Resumo
Os checkpoints são uma funcionalidade automática do Claude Code que permite explorar diferentes abordagens em segurança, sem receio de perder trabalho. Cada prompt do utilizador cria automaticamente um novo checkpoint, para que possa retroceder a qualquer ponto anterior da sua sessão.
Principais vantagens:
- Experimente com confiança várias abordagens
- Recupere rapidamente de erros
- Compare diferentes soluções lado a lado
- Integre-se em segurança com sistemas de controlo de versões
Lembre-se: os checkpoints não substituem o git. Use os checkpoints para experimentação rápida e o git para alterações permanentes no código.
Última atualização: 18 de outubro de 2026
Versão do Claude Code: 2.1.302
Fontes:
- https://code.claude.com/docs/en/checkpointing
- https://code.claude.com/docs/en/settings
- https://github.com/anthropics/claude-code/releases/tag/v2.1.117
- https://code.claude.com/docs/en/model-config
- https://code.claude.com/docs/en/commands
- https://code.claude.com/docs/en/claude-directory
Modelos compatíveis: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5
Exemplos e recursos deste módulo
Componentes para esta tarefa
Escolhemos à mão os agentes, skills e comandos que resolvem este tipo de trabalho: Agentes e skills para depuração e diagnóstico de erros.
Guia da comunidade open-source (MIT) · tradução e manutenção Doutor AI.
Precisa de uma solução à medida?
Não sabe por onde começar a usar IA no seu negócio? Receba uma avaliação gratuita e um plano à medida - sem compromisso.
Poupe horas todas as semanas com IA, sem complicações
O Doutor AI dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe.
Ver planos