Pontos de Controle (Checkpoints): A Rede de Segurança a Qualquer Momento

📚 Navegação da Série: O capítulo anterior 36 Comandos de Barra organizou a lista de comandos iniciados com /, onde o /rewind também apareceu. Este capítulo é dedicado inteiramente a ele — os Pontos de Controle (Checkpoints) são instantâneos automáticos do código gerados pelo Claude Code antes de cada edição, permitindo retornar a um estado anterior. Abordaremos como eles são salvos automaticamente, como reverter, o que pode ou não ser recuperado e como eles se dividem com o git.

Dizem que os checkpoints são o seu "remédio para arrependimento", e que com essa segurança você pode dar total liberdade para o Claude agir — mas a verdade é que usar isso como git é receita para problemas.

Imagine alguém que acabou de começar a usar o Claude Code, ouviu falar do /rewind e relaxou, deixando o Claude alterar mais de dez arquivos de uma vez e executar alguns comandos rm e mv para organizar os diretórios. Na terceira iteração, percebe que a direção está errada e digita /rewind calmamente esperando voltar ao estado inicial — o código retorna em parte, mas os arquivos apagados pelo rm não voltam de forma alguma. O desespero bate na hora: "Não disseram que dava para desfazer?"

Dá para desfazer, mas apenas as alterações em arquivos feitas pelas ferramentas de edição do Claude, não as marcas deixadas no disco por comandos bash executados diretamente, e muito menos um histórico permanente como o do git. Os checkpoints funcionam como uma "desfazer local no escopo da sessão", ideal por ser rápido, automático e reverter inclusive o histórico da conversa; no entanto, eles possuem limites claros e não conseguem atuar fora do seu escopo.

Este capítulo foca em dois objetivos: ensinar a gerenciar o fluxo de "salvamento automático e reversão" e definir com precisão os limites — o que pode ser desfeito, o que é permanente, quando confiar nos checkpoints e quando recorrer ao git. Compreender esses limites garante que o recurso funcione como uma rede de segurança real, e não uma ilusória.

Ao ler este capítulo, você obterá:

• A definição clara de checkpoints e quando o sistema os salva automaticamente (sem intervenção manual).
• As duas formas de abrir o menu de reversão (comando /rewind e clique duplo na tecla Esc com entrada vazia) e o que significa cada opção de reversão.
• Uma tabela comparativa de "O que pode ser revertido vs. O que é permanente" — código e conversa voltam, mas efeitos colaterais de bash e estados externos não.
• A divisão clara de tarefas entre checkpoints e git: quando usar cada um e por que um não substitui o outro.
• Um exercício prático guiado com resultado esperado: force um "erro de desenvolvimento" e reverta-o usando checkpoints.

---

01 O que são Checkpoints: O Sistema Salva Instantâneos sem Você Notar

Para ir direto ao ponto: um checkpoint é um instantâneo do código antes de qualquer edição tirado de forma automática pelo Claude Code — a cada prompt enviado, o sistema salva o estado atual; se precisar reverter, basta usar /rewind para retornar ao ponto desejado.

Vimos uma introdução a esse recurso no Capítulo 7, sabendo que o /rewind serve como segurança para erros. Agora vamos nos aprofundar. Lembre-se do fluxo de trabalho com o Claude: você envia um comando → a IA executa o ciclo "pensar → agir → observar" e altera arquivos → você avalia e envia o próximo comando (ciclo detalhado no Capítulo 3). O que os checkpoints fazem é salvar o estado atual do código exatamente antes do início da execução de cada novo comando.

Analogia: A barra de linha do tempo de um gravador de vídeo digital (DVR). O aparelho grava a programação continuamente, mas insere marcadores de capítulos sempre que há uma mudança de programa. Se quiser rever um trecho, você não precisa avançar manualmente desde o início; basta arrastar o cursor diretamente para o marcador do capítulo. Os checkpoints funcionam de forma semelhante: cada prompt enviado funciona como um marcador na linha do tempo; executar /rewind é arrastar a fita de volta a esse marcador. A diferença é que — enquanto o DVR apenas reproduz a imagem, o checkpoint restaura o código e a conversa para aquele exato momento, permitindo seguir um caminho diferente.

A documentação oficial define a função desse recurso:

Ao trabalhar com o Claude, o checkpointing captura automaticamente o estado do código antes de cada edição. Essa rede de segurança permite executar tarefas complexas de grande escala com confiança, sabendo que você sempre pode retornar a um estado anterior do código.

Note a palavra chave — automaticamente. Esse é o grande diferencial dos checkpoints e a maior diferença de usabilidade em relação ao git: você não precisa fazer nada. No git, você precisa se lembrar de fazer o git commit, e se esquecer, as alterações não serão registradas; com os checkpoints, o Claude salva tudo silenciosamente em segundo plano, sem exigir atenção.

A documentação lista quatro cenários típicos de uso, acompanhados de exemplos reais:

• Explorar caminhos alternativos: se a implementação A não ficou boa, reverta ao ponto de partida para testar o caminho B, mantendo o ponto de partida original intacto, sem receio de "estragar o código e não conseguir voltar".
• Recuperar de erros: a IA alterou um arquivo e os testes falharam, e você quer evitar reescrever ou apagar as linhas manualmente — restaure o checkpoint anterior para limpar as alterações.
• Refatorar funcionalidades: pedir para o Claude reescrever um módulo inteiro para teste; se o resultado não agradar, retorne ao ponto anterior à refatoração, como se nada tivesse acontecido, incentivando a experimentação.
• Liberar espaço de contexto: após uma longa sessão de depuração, você deseja manter a explicação inicial, mas descartar as tentativas malsucedidas do meio — use a opção de "resumir" (explicada na seção 3).

O ponto comum nesses cenários: "quero agir com ousadia, mas tenho receio de quebrar o código e não conseguir voltar" — os checkpoints removem esse receio.

💡 Resumo em uma frase: Checkpoints são Resumos de código gerados automaticamente antes de cada edição; a cada prompt enviado, um marcador é inserido na linha do tempo, permitindo retornar o código e a conversa para esse momento via /rewind — tudo de forma automática, sem necessidade de salvamento manual.

---

02 Quando os Checkpoints são Salvos, Onde Ficam e Quanto Tempo Duram?

Como os checkpoints são gerados de forma "automática", é importante conhecer as regras desse automatismo — quando são criados, onde são salvos e por quanto tempo permanecem disponíveis. A documentação detalha esses pontos:

Gatilho de Criação: Um Checkpoint por Prompt

A regra é direta: a cada prompt enviado pelo usuário, o Claude Code gera um novo checkpoint. A documentação afirma:

Cada prompt do usuário cria um novo checkpoint.

Dessa forma, a frequência dos marcadores na linha do tempo acompanha o ritmo da conversa — se você enviar dez instruções, terá dez pontos possíveis de retorno. É por isso que o menu de reversão listará exatamente os prompts enviados na sessão: cada instrução serve tanto como início de ação quanto como ponto de restauração.

Ao mapear esse fluxo, fica fácil ver como os checkpoints são registrados ao longo da conversa:

A imagem ilustra: a cada instrução enviada, antes de iniciar o processamento, o Claude gera um checkpoint (pontos azuis); se no prompt 3 ocorrer algum erro, executar /rewind permite voltar ao checkpoint 1, revertendo tanto o código quanto as conversas geradas nos passos 2 e 3.

Onde são Salvos: Na Pasta ~/.claude

Os instantâneos não ficam apenas na memória volátil, eles são gravados no disco. O documento sobre o diretório do Claude indica:

file-history/<session>/ — Instantâneos de arquivos editados pelo Claude, usados para restauração de checkpoints.

Isso significa que os dados de histórico de arquivos de cada sessão são gravados em ~/.claude/file-history/<session>/. Não há necessidade de manipular esses arquivos manualmente, mas saber de sua existência ajuda a entender o consumo de disco do programa e a segurança das cópias.

Persistência: Sobrevivem ao Fechamento da Sessão

Por serem gravados em disco, os checkpoints persistem mesmo se a sessão for encerrada. A documentação afirma:

Os checkpoints persistem entre sessões, permitindo acessá-los mesmo em conversas retomadas.

Isso significa que você pode fechar a sessão com Ctrl+D hoje e, amanhã, ao retomar com claude --resume (ou --continue), todo o histórico de checkpoints continuará disponível para uso com /rewind. O histórico é mantido associado à sessão e respeita o tempo de limpeza configurado em cleanupPeriodDays.

Tempo de Armazenamento: Limpeza Automática em 30 Dias (Ajustável)

Os arquivos não são mantidos para sempre, seguindo uma rotina de expiração:

Limpeza automática após 30 dias (configurável).

Essa configuração é controlada pela diretiva cleanupPeriodDays no arquivo settings.json (analisada no Capítulo 31). A documentação de configurações indica que o padrão é 30 dias para limpar dados de sessões inativas, aceitando valores a partir de 1 dia (valores zerados são rejeitados). Para a maioria dos usuários, o padrão de 30 dias é ideal. Alterações permanentes de longo prazo devem ser registradas no git, sem depender de checkpoints para manter históricos de meses.

A pasta file-history em ~/.claude armazena todos os pontos de retorno que garantem o funcionamento do /rewind. O processo ocorre sem demandar atenção do usuário, o que reforça a facilidade do salvamento automático.

Tabela de resumo das propriedades:

Propriedade	Funcionamento	Ação Requerida
Criação	Um checkpoint automático a cada prompt	Nenhuma, gerado de forma transparente
Local de salvamento	Salvo sob ~/.claude/file-history/<session>/	Apenas consulta, sem necessidade de edição
Persistência	Mantido após fechar o console	Permite restaurar em sessões retomadas
Expiração	Removido conforme cleanupPeriodDays (padrão de 30 dias)	Recomendado manter o padrão; usar git para histórico permanente

💡 Resumo em uma frase: Checkpoints são salvos a cada prompt enviado no diretório ~/.claude/file-history/, persistem ao encerrar a sessão e expiram conforme a diretiva cleanupPeriodDays (30 dias); o gerenciamento é feito de forma automática pelo sistema.

---

03 Como Restaurar: /rewind, Tecla Esc e Opções de Reversão

Com os pontos salvos em segundo plano, veja como utilizá-los para restauração. Existem dois caminhos principais: o comando /rewind ou pressionar duas vezes a tecla Esc com entrada vazia.

Os Dois Atalhos

O primeiro método utiliza o comando de barra:

/rewind

O segundo método é mais rápido — com a caixa de entrada vazia, pressione duas vezes a tecla Esc:

(Com entrada vazia, pressione Esc Esc)

Ambas as ações abrem o menu de rollback (rewind menu). A documentação indica:

Execute /rewind, ou pressione Esc duas vezes com a entrada de texto vazia para exibir o menu de rollback.

Relembramos uma orientação importante já vista no Capítulo 14:

Se a caixa de entrada contiver texto, pressionar Esc duas vezes limpará o texto em vez de abrir o menu. O texto apagado é salvo no histórico de comandos e pode ser recuperado pressionando ↑ após sair do menu.

Isso significa que: se houver texto na entrada, o clique duplo em Esc funcionará como "limpar texto". Para abrir o menu de rollback, certifique-se de que a entrada está vazia. Caso tenha dúvidas, digite /rewind, que abrirá o menu independentemente do estado da entrada de texto.

Entendendo as Opções do Menu de Reversão

Ao abrir o menu, o sistema listará os prompts enviados na sessão atual (os marcadores da linha do tempo). Após escolher para qual prompt deseja retornar, você deve selecionar como aplicar a reversão. Existem opções diferentes de comportamento:

Opção do Menu	Ação Executada	Cenário de Uso
Restaurar código e conversa	Código e conversa ambos retornam ao ponto selecionado	Para descartar completamente as rodadas anteriores, como se nunca tivessem ocorrido
Restaurar conversa	Apenas o histórico de conversa retorna; o código permanece inalterado	Quando o código gerado está correto, mas o diálogo se perdeu e você quer ajustar a conversa
Restaurar código	Apenas as alterações de código são revertidas; a conversa é mantida	O código gerado falhou e você quer testar outra lógica mantendo as explicações e o contexto do diálogo
Resumir a partir daqui	Comprime esta conversa e as seguintes em um resumo de contexto	Para descartar discussões e testes malsucedidos mantendo apenas a conclusão
Resumir até aqui	Comprime as conversas anteriores a este ponto em um resumo de contexto	Para resumir discussões preliminares e focar nos detalhes mais recentes do desenvolvimento
Cancelar	Fecha o menu sem aplicar alterações	Retornar ao terminal

A separação entre restaurar código ou conversa é muito útil no dia a dia:

• Restaurar apenas o Código: imagine que você e o Claude conversaram por cinco rodadas para definir a lógica de uma integração. Ele aplicou o código, mas o resultado quebrou nos testes. Você quer remover o código falho, mas deseja manter a conversa contendo os detalhes explicativos para não precisar redigitar tudo. Selecionando "Restaurar código", o código retorna ao estado anterior à alteração, a conversa permanece disponível no histórico e a IA mantém a compreensão do problema para tentar uma nova implementação.
• Restaurar apenas a Conversa: no cenário oposto, o código gerado pelo Claude está excelente, mas as perguntas adicionais feitas por você após a alteração desviaram o rumo do diálogo, poluindo o contexto. Selecionando "Restaurar conversa", o histórico é limpo até o ponto desejado, mas as alterações feitas no código são preservadas, permitindo retomar a conversa a partir de um ponto limpo.

Essas duas opções funcionam como ajustes de precisão independentes para o código e a conversa. A opção mais utilizada no cotidiano é "Restaurar código", permitindo descartar uma implementação incorreta mantendo o escopo da discussão intacto.

É importante não confundir "Restaurar" com "Resumir". Embora estejam no mesmo menu, executam ações distintas:

• Restaurar (Restore): altera os dados no disco e na sessão, revertendo arquivos e históricos. Funciona como uma "viagem no tempo".
• Resumir (Summarize): não altera os arquivos físicos, apenas consolida blocos de conversa em resumos para poupar limite de contexto da sessão. Funciona como uma "limpeza de rascunhos".

A documentação enfatiza essa distinção:

As opções de restauração alteram o estado: elas revertem alterações de código, histórico de conversa ou ambos. As opções de resumo apenas consolidam trechos do diálogo em resumos gerados por IA, sem modificar arquivos em disco.

Ou seja, a opção de resumo funciona como uma versão direcionada do comando /compact (analisado no Capítulo 19). Enquanto o /compact resume todo o histórico da sessão, o menu de rollback permite escolher um ponto específico para resumir apenas um lado do diálogo (antes ou depois do ponto selecionado).

Dica prática: ao selecionar "Restaurar conversa" ou "Resumir a partir daqui", a mensagem do prompt que estava selecionada é copiada de volta para a caixa de entrada, permitindo editá-la e reenviá-la de forma rápida. (A opção "Resumir até aqui" mantém a entrada de texto vazia).

Dúvidas Comuns na Restauração

"O menu de rollback está vazio ou tem poucas opções" — é o comportamento esperado em sessões novas. Como o sistema cria checkpoints a cada prompt do usuário, se você iniciou a sessão há pouco tempo, haverá poucos pontos para retornar. A lista de pontos cresce conforme a conversa avança.

"Reverti para um ponto anterior por engano, perdi meus checkpoints mais recentes?" — os arquivos permanecem gravados no histórico em disco. No entanto, dependendo de como a sessão reconstrói a árvore de histórico, a navegação pode ser afetada. Como boa prática recomendada: antes de executar alterações complexas ou reversões de grande escala, crie um commit no git (git commit), garantindo um ponto de restauração permanente e seguro no controle de versão.

💡 Resumo em uma frase: Use /rewind ou Esc Esc com entrada vazia para abrir o menu; escolha o ponto de retorno e defina se deseja reverter código, conversa ou ambos; lembre-se que restaurar reverte arquivos e histórico, enquanto resumir apenas comprime textos de contexto.

---

04 Limites do Recurso: O que Pode e o que Não Pode ser Revertido

Esta é a seção mais importante para evitar perda de dados. Os checkpoints monitoram exclusivamente alterações de arquivos feitas pelas ferramentas de edição do Claude (como Edit/Write). Qualquer alteração feita por outros caminhos não será capturada.

Analogia do DVR: ele grava apenas o sinal de vídeo que chega na TV, não os acontecimentos da sala de estar. Se você derrubar um copo de água na mesa ou enviar uma mensagem no celular enquanto assiste ao vídeo, pausar ou retroceder a gravação não limpará a mesa nem trará a mensagem de volta. Os checkpoints registram os arquivos editados pelo Claude; eles não gerenciam comandos bash que afetam o sistema operacional ou serviços externos.

A documentação detalha as limitações do recurso, organizadas na tabela abaixo:

Tipo de Alteração	Pode ser Revertida?	Justificativa
Arquivos editados por ferramentas do Claude (Edit/Write)	✅ Sim	É o escopo principal de monitoramento dos checkpoints
Histórico de conversas na sessão	✅ Sim	O menu de rollback permite restaurar trechos de diálogos
Arquivos modificados por comandos bash (rm, mv, cp, etc.)	❌ Não	O sistema de checkpoints não monitora alterações de comandos shell
Arquivos não editados na sessão atual	❌ Não	O monitoramento se restringe a arquivos tocados na sessão ativa
Alterações feitas fora do Claude Code (IDE, outro editor)	❌ Não	Modificações externas não são capturadas pelo sistema
Alterações de outras sessões paralelas do Claude Code	❌ Não	Cada sessão mantém seu próprio histórico de monitoramento
Ações externas (chamadas de API, alterações em banco, push, etc.)	❌ Não	Escopo fora do controle de arquivos locais do projeto

A limitação mais crítica envolve comandos bash, que a documentação oficial destaca:

O checkpointing não rastreia arquivos modificados por comandos bash. Por exemplo, se o Claude Code executar rm file.txt, mv old.txt new.txt ou cp source.txt dest.txt, essas modificações não poderão ser revertidas pelo rollback. Apenas edições diretas feitas pelas ferramentas de escrita do Claude são monitoradas.

Isso explica por que arquivos apagados por um comando rm da IA não são restaurados pelo /rewind. Importante: O Claude interage com os arquivos de duas formas — editando o conteúdo via ferramentas internas (capturado pelo checkpoint) ou rodando comandos no shell (não capturado). Ambos alteram o projeto, mas apenas o primeiro caminho tem suporte a rollback.

Como identificar qual caminho o Claude está utilizando no momento? Observe as chamadas de ferramentas exibidas no terminal durante a execução (pressione Ctrl+O para exibir os logs detalhados):

• Chamadas como Edit, Write ou MultiEdit — são monitoradas, permitindo reversão segura via /rewind.
• Chamadas de Bash executando comandos como rm, mv, cp ou redirecionamentos de escrita (>) — não são monitoradas, impedindo a reversão pelo checkpoint.

Fique atento a essas chamadas ao delegar tarefas que envolvam manipulação de arquivos. Se a IA precisar rodar comandos shell de escrita ou remoção, crie um commit no git antes de autorizar a execução.

Sobre alterações externas:

O checkpointing monitora apenas arquivos editados na sessão ativa. Alterações manuais feitas por você fora do Claude Code ou edições vindas de outras sessões paralelas não serão capturadas, a menos que toquem nos mesmos arquivos modificados na sessão.

Iddo significa que alterações feitas na sua IDE ou em outro console não são registradas pelo checkpoint desta sessão.

Regra geral de segurança: ações que envolvam remoção de arquivos, movimentação de diretórios, conexões de banco de dados ou requisições externas não devem depender de /rewind para segurança. Use commits do git e backups apropriados. Os checkpoints são ideais apenas para reverter lógicas de código implementadas incorretamente pelas ferramentas de escrita da IA.

Tabela de cenários práticos de recuperação:

Ocorrência no Projeto	Recuperável com /rewind?	Ação Recomendada de Correção
O Claude escreveu código incorreto em um arquivo	✅ Sim	Executar /rewind e selecionar o ponto de rollback
O Claude removeu um arquivo com rm no bash	❌ Não	Restaurar pelo git (git checkout) ou backup
O Claude executou um script que alterou dados de teste no banco	❌ Não	Restaurar backup do banco de dados ou usar transações
O Claude fez um push incorreto para o repositório remoto	❌ Não	Executar rollback de commit no git (git revert / git push -f)
Modificação acidental feita por você na IDE	❌ Não	Usar o comando "Desfazer" do editor ou git

As falhas que não podem ser revertidas pelo checkpoint compartilham o mesmo fator: são alterações que ocorrem fora do monitoramento de escrita da sessão do Claude Code. Se a alteração afeta algo fora dos arquivos de código editados diretamente pela IA, o checkpoint não conseguirá atuar.

💡 Resumo em uma frase: Checkpoints atuam apenas sobre conversas e arquivos alterados pelas ferramentas internas do Claude; alterações por comandos bash (rm/mv), modificações externas de editores ou ações de rede não são revertidas — se a alteração ocorre fora do controle de escrita local da IA, o /rewind não terá efeito.

---

05 Divisão de Tarefas com o Git: Segurança Local vs. Histórico Permanente

Compreendendo os limites dos checkpoints, a frase "não use checkpoints como substituto do git" ganha clareza. Os dois recursos coexistem e atendem a necessidades diferentes no fluxo de desenvolvimento.

A documentação oficial define essa relação de forma direta:

Considere os checkpoints como um "Desfazer local" e o Git como um "Histórico permanente".

Analogia: Anotações em um rascunho de papel vs. Documento oficial arquivado. Checkpoints funcionam como o rascunho onde você escreve e apaga livremente com borracha — é rápido, informal, serve para testes imediatos e o papel é descartado após o término da tarefa (limpeza em 30 dias). O git funciona como o livro de atas oficial onde os registros são arquivados de forma permanente — contém assinaturas, histórico auditável, ramificações de equipe e persistência eterna. Você não deixa de arquivar atas porque tem rascunhos, nem usa atas oficiais para fazer rabiscos rápidos de teste. Ambos são necessários.

A documentação orienta a divisão:

• Mantenha o uso de controle de versão (como Git) para commits, branches e histórico de longo prazo;
• Os checkpoints complementam, mas não substituem o controle de versão adequado.

Comparativo direto de propriedades:

Propriedade	Checkpoints (Claude Code)	Git (Controle de Versão)
Ativação	Automática (a cada prompt)	Manual (via comando git commit)
Granularidade	Fina (um checkpoint por mensagem)	Grossa (definida pelo escopo do commit)
Arquivos de bash	❌ Não monitora alterações de bash	✅ Restaura qualquer arquivo com commit salvo
Persistência	Temporária (removido em 30 dias)	Permanente (mantido na história do repositório)
Colaboração	❌ Apenas local do usuário	✅ Compartilhável via servidores remotos
Melhor para	Reverter pequenos testes e lógicas no prompt	Marcos de entrega, histórico geral e trabalho em equipe

O git também não monitora alterações de banco de dados ou APIs, mas garante a restauração completa de qualquer arquivo de código que tenha sido comitado.

Diretriz prática de escolha:

• Desenvolvimento rápido e iterações curtas → use checkpoints. Teste uma lógica, reverta com /rewind se falhar e tente de novo. O fluxo é rápido e evita encher o git com commits temporários de teste.
• Marcos de entrega e funcionalidades concluídas → use git commit. Assim que um módulo estiver concluído e com testes passando, salve no controle de versão para garantir o registro permanente.
• Garantir reversão contra comandos bash perigosos → use git. Como checkpoints não capturam remoções via bash, manter commits atualizados é a única forma de garantir a recuperação de arquivos deletados por engano.

O fluxo recomendado consiste em: usar checkpoints para experimentar lógicas com liberdade e, assim que alcançar um estado funcional estável, registrar um commit no git. Essa combinação une o desfazer rápido dos checkpoints com a estabilidade de longo prazo do git. O maior risco é confiar apenas nos checkpoints, passar horas sem comitar e perder o histórico de rollback se a sessão for corrompida. Mantenha o hábito de realizar commits frequentes.

A integração do Claude Code com o Git (geração de mensagens de commit, criação de branches) é detalhada no Capítulo 43 (Git Workflow). Lembre-se: os checkpoints servem como apoio local, enquanto o git garante a história permanente do projeto.

Se você deseja testar caminhos alternativos mantendo a sessão atual intacta sem misturar dados, utilize a flag de bifurcação de sessão em vez do resumo:

claude --continue --fork-session

Isso criará uma nova ramificação da conversa em paralelo, preservando a sessão original (detalhes no Capítulo 34).

💡 Resumo em uma frase: Checkpoints atuam como desfazer local temporário (rápido, fino, automático), enquanto o git fornece o histórico permanente (permanente, colaborativo, seguro contra bash); use checkpoints para testes rápidos de prompts e git para registrar entregas e proteger contra exclusões.

---

06 Prática: Simulando uma Alteração Incorreta e Revertendo com Checkpoints

Para consolidar o conhecimento, siga este exercício rápido de 5 minutos para testar o fluxo de alteração de arquivo, reversão com /rewind e validação de limites de comandos bash. Você precisará apenas do terminal.

Passo 1: Criar um diretório de teste e inicializar o git

mkdir ~/rewind-demo && cd ~/rewind-demo
git init
printf 'hello\n' > note.txt
git add note.txt && git commit -m "init: nota inicial"

Resultado esperado: O arquivo note.txt é criado contendo o texto hello e registrado no repositório git local.

Passo 2: Iniciar o Claude Code e solicitar uma edição

Inicie a ferramenta:

claude

Solicite a alteração do arquivo (isso criará o primeiro checkpoint):

Altere o arquivo note.txt para conter três linhas: apple, banana, cherry. Use a ferramenta de escrita do Claude.

Resultado esperado: O Claude exibe a alteração proposta via ferramenta de escrita. Aprove a alteração para que o conteúdo do arquivo note.txt seja atualizado.

Passo 3: Realizar uma segunda alteração

Solicite outra modificação para simular o erro:

Agora remova as três linhas e escreva apenas: esta versao nao deve ser mantida

Resultado esperado: O arquivo note.txt é modificado para conter apenas a frase do erro. O histórico agora possui dois prompts registrados.

Passo 4: Abrir o menu de rollback e reverter

Com a caixa de entrada vazia, pressione Esc duas vezes (ou digite /rewind):

(Com entrada vazia, pressione Esc Esc)

Resultado esperado: O menu de rollback é exibido listando as duas instruções anteriores. Selecione a opção correspondente ao prompt do Passo 2 (antes da escrita das frutas) e selecione "Restaurar código e conversa".

Passo 5: Validar a restauração

Consulte o conteúdo do arquivo na sessão (ou usando comandos do terminal):

! cat note.txt

Resultado esperado: O conteúdo de note.txt retornou para a palavra hello (o estado inicial). Ambas as alterações foram removidas e o histórico de conversa foi limpo até o ponto inicial, confirmando a ação do rollback.

Passo 6: Testar os limites com comandos bash

Solicite à IA para remover o arquivo usando o comando bash rm:

Remova o arquivo note.txt executando o comando bash rm.

Aprove a execução do comando bash. Após a exclusão, execute /rewind, selecione o ponto anterior e tente restaurar o código. Em seguida, consulte a pasta:

! ls

Resultado esperado: O arquivo note.txt não foi recuperado e a pasta permanece vazia. Isso confirma que comandos bash de remoção não são recuperados por checkpoints. Para restaurar o arquivo, utilize o git:

git checkout note.txt

O arquivo note.txt contendo a palavra hello será restaurado a partir del commit do repositório local.

O exercício demonstra a utilidade de reverter edições de escrita de forma simples e a importância de usar o git como segurança contra ações de comandos shell.

💡 Resumo em uma frase: A prática demonstra que edições de escrita são revertidas na hora com /rewind, mas arquivos deletados por comandos bash (rm) dependem do git para serem recuperados.

---

07 Resumo

Neste capítulo, detalhamos o funcionamento dos checkpoints do Claude Code, compreendendo-os como uma ferramenta de desfazer local e rápida, integrada ao fluxo de prompts, que atua em conjunto com o git.

Pontos chaves abordados no capítulo:

Tópico	Detalhe de Funcionamento	Aplicação Prática
O que são	Instantâneos de código gerados antes de cada prompt	Salvamento automático que serve como rede de segurança para testes locais
Como acionar	Comando /rewind ou Esc Esc com entrada de texto vazia	Abre o menu de rollback na sessão
Modos de reversão	Restaurar código, conversa ou ambos	Permite reverter alterações de arquivos mantendo o contexto de conversa, ou vice-versa
Limitações	Rastreia apenas escritas de ferramentas internas da IA	Comandos bash (rm/mv), alterações externas e conexões não são recuperados
Integração com Git	Checkpoint é o desfazer local, Git é a história permanente	Use checkpoints para experimentar lógicas e comite entregas no git para segurança de longo prazo

Agora você é capaz de: gerenciar com segurança o andamento do código e das conversas na sessão do Claude Code, reverter implementações malsucedidas mantendo o histórico de diálogo correspondente, identificar os limites de segurança dos checkpoints e manter um fluxo de desenvolvimento alinhado com commits frequentes no git. Isso garante a segurança do projeto contra alterações incorretas.

Compreendendo o funcionamento dos checkpoints, completamos mais uma etapa no controle operacional das ferramentas.

---

O próximo capítulo, 38 "Manual de Referência de Plugins", abordará como agrupar Skills, Hooks, agentes e configurações em pacotes instaláveis e compartilháveis. Veremos a estrutura de arquivos e os campos de manifesto necessários para criar seus próprios plugins ou instalar soluções prontas de terceiros. Nos vemos no próximo capítulo!

---

Leituras Recomendadas

• Tarefas Paralelas: Executando Múltiplas Sessões do Claude Code
• MCP: Integrando o Claude com Ferramentas do Sistema
• Integração com o VS Code