Claude Code travou no meio da tarefa: como retomar sem perder o que já foi feito

Você estava no meio de uma tarefa grande, o terminal fechou e a conversa inteira sumiu da tela

Aquele frio na barriga de achar que perdeu horas de trabalho é real, mas na maioria das vezes é só susto

O Claude Code salva cada conversa localmente como sessão atrelada ao diretório do projeto, gravada enquanto você trabalha, e é exatamente isso que permite retomar de onde parou

O risco maior nem é a perda em si

É retomar ERRADO: abrir uma sessão nova, recontar a história do jeito que você lembra e mandar o agente refazer coisa que já estava pronta

Bora resolver isso na ordem certa?

Terminal fechado, máquina reiniciada ou conexão caiu: qual comando usar em cada caso

Sintoma: a sessão desapareceu da tela e você está encarando um terminal limpo, sem saber onde parou

Causa: o processo do agente morreu junto com o terminal, mas a conversa é gravada em disco, atrelada ao diretório do projeto

Ou seja: o que morreu foi a janela, não necessariamente o histórico

Solução: volte pro MESMO diretório do projeto e retome a sessão mais recente dali

cd /caminho/do/seu/projeto
claude --continue

A forma curta é claude -c, se você é do tipo que odeia digitar 🙂

Agora, se você tinha várias frentes abertas e não quer a mais recente, e sim aquela específica:

claude --resume

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Esse abre um seletor interativo das sessões salvas

E ele também aceita nome ou ID direto:

claude --resume <nome-ou-id>

Já dentro do Claude Code, o comando /resume faz o mesmo papel de voltar pra uma conversa anterior (aceita nome ou ID)

E se eu não estiver mais no diretório do projeto?

Aí entra a diferença que resolve o caso da máquina reiniciada, quando você abre o terminal em qualquer lugar

Passando o ID da sessão, o claude --resume <session-id> funciona de QUALQUER diretório

A régua é essa: continue é por diretório, resume é por identificação específica

Como prevenir: dê nome pras suas sessões

Dá pra nomear com a flag --name ou com o comando /rename dentro da sessão, substituindo o título gerado automaticamente

/rename refatora-autenticacao

Parece bobo, mas quando o seletor abrir com um monte de conversa parecida, é o nome que vai te salvar de retomar a errada

Antes de mandar continuar, avalie o que já foi feito no código

Sintoma: você retoma, o histórico volta bonitinho, mas bate a dúvida: aquela última edição chegou a ser aplicada nos arquivos ou morreu no meio?

Causa: a conversa voltou, o estado do repositório é outra história

São duas coisas diferentes e é aqui que a galera se ferra: manda "continua aí" sem olhar o código e o agente reescreve o que já existia

Solução: olhe o estado real antes de pedir qualquer coisa nova

O Claude Code captura checkpoints do estado do código antes de cada prompt do usuário, e isso vem ligado por padrão

O /rewind volta código e conversa pra um checkpoint, ou resume só parte da conversa

/rewind

O menu lista cada prompt enviado na sessão, e as opções incluem restaurar o código, restaurar código e conversa, ou restaurar só a conversa

E tem um detalhe que resolve nossa vida na retomada: os checkpoints são salvos junto com a conversa, então dá pra rodar /rewind mesmo DEPOIS de retomar a sessão

Os limites do checkpoint (leia isso antes de confiar cegamente)

Tome cuidado aqui, porque é onde mora a surpresa desagradável

• o checkpointing rastreia apenas as edições feitas pelas ferramentas de edição de arquivo do Claude
• arquivo mexido por comando de terminal fica de fora: os rm, mv, cp da vida não entram no checkpoint e não podem ser desfeitos pelo rewind
• ao restaurar código, caminhos rastreados que sejam symlink ou hard link são pulados, com aviso do tipo Restored the code, but skipped N files
• as opções de restaurar código só aparecem quando o checkpoint selecionado tem mudanças de arquivo rastreadas pra reverter; sem edição capturada, o menu oferece apenas restaurar conversa, resumir ou cancelar

Então o rewind não é máquina do tempo universal, é histórico do que o agente editou pelas ferramentas dele

Como prevenir: abra o menu e INSPECIONE antes de escolher qualquer restauração

Um clique errado ali desfaz trabalho bom junto com o ruim

Por que reexplicar tudo do zero costuma piorar a retomada

Sintoma: em vez de retomar, a pessoa abre uma sessão nova e cola um resumo do que ela ACHA que aconteceu

"a gente tinha feito o login, acho que faltava o middleware, e tinha um bug no formulário"

Causa: esse resumo humano é uma versão empobrecida da verdade

O transcrito da sessão guarda todas as mensagens, chamadas de ferramenta e resultados

Seu resumo de memória guarda o que sobrou na sua cabeça, e o modelo vai trabalhar em cima dessa versão torta

A própria documentação oficial afirma que, como as conversas ficam salvas localmente, uma tarefa que atravessa várias sentadas não exige reexplicar o contexto

Solução: retome a sessão e trate o contexto como recurso, não como texto pra encher

Primeiro, veja quanto da janela está ocupado:

/context

Ele mostra o uso atual da janela de contexto em grade colorida, com sugestões de otimização e avisos de capacidade

Se estiver apertado, compacte com FOCO em vez de recomeçar:

/compact Focus on the API changes

O /compact libera contexto resumindo a conversa até ali e aceita instrução de foco pro resumo

Só lembra que a compactação exige uma conversa existente com pelo menos duas trocas anteriores pra resumir, então em sessão recém-nascida ele não tem o que fazer

Quando começar limpo faz sentido de verdade

Nem sempre retomar é o certo, beleza?

• /clear pra começar do zero numa tarefa NOVA, mantendo a memória do projeto
• /branch dentro da sessão (ou --fork-session combinado com --continue ou --resume) quando você quer testar um caminho alternativo: a cópia recebe ID próprio e a original mantém ID e histórico intactos

Bifurcar é ótimo pro clássico "e se a gente tentasse de outro jeito", sem sujar a linha principal

Como prevenir: uma sessão por frente de trabalho

A documentação oficial recomenda nomear sessões com /rename e tratá-las como branches, cada frente com seu contexto persistente

Se você conhece branch no Git, é a mesma cabeça: contexto separado por assunto, não uma sessão gigante fazendo tudo

A sessão não aparece no seletor: onde os transcritos ficam no disco

Sintoma: você roda o --resume, o seletor abre, e a conversa que você quer simplesmente não está na lista

Causa: quase sempre você está olhando outro projeto, outro diretório de configuração ou outra máquina

Solução: vá no disco conferir

Os transcritos de sessão ficam gravados no diretório .claude, assim:

~/.claude/projects/<projeto>/<sessão>.jsonl

Dentro deles vão todas as mensagens, chamadas de ferramenta e resultados

E o nome da pasta do projeto não é aleatório: é o diretório de trabalho absoluto com todo caractere não alfanumérico trocado por hífen

Ou seja, /Users/me/proj vira -Users-me-proj

No Windows, ~/.claude corresponde a %USERPROFILE%\.claude

E se a variável de ambiente CLAUDE_CONFIG_DIR estiver definida, os caminhos de ~/.claude passam a viver dentro dela:

$CLAUDE_CONFIG_DIR/projects/<projeto>/*.jsonl

Já me confundi por bem menos que isso, então confere a variável antes de achar que a sessão evaporou

O que mais mora ali

• saídas grandes de ferramentas e transcritos de subagentes ficam em subpastas da sessão: projects/<projeto>/<sessão>/subagents/ e projects/<projeto>/<sessão>/tool-results/
• o history.jsonl guarda todo prompt digitado, com timestamp e caminho do projeto, e é ele que alimenta o recall pela seta pra cima

Levando a sessão pra outra máquina

Pra retomar sessão entre máquinas, é preciso levar o arquivo .jsonl da sessão e restaurá-lo dentro de um diretório sob ~/.claude/projects/ na outra máquina, antes de chamar o resume

Ou seja: copiar ~/.claude/projects/<projeto>/<session-id>.jsonl e só depois abrir o agente lá

Alerta sério: transcritos e histórico NÃO são criptografados em repouso, e as permissões de arquivo do sistema operacional são a única proteção

Se uma ferramenta ler um .env ou um comando imprimir uma credencial, esse valor fica gravado no .jsonl da sessão

Pensa nisso duas vezes antes de sair copiando transcrito pra Drive, Slack ou pendrive…

E se nada disso resolver, tem os dois de sempre: /doctor roda uma checagem de instalação e configuração e pode corrigir problemas encontrados, e /debug diagnostica problemas de execução

O que uma sessão refeita do zero custa na prática

Agora a parte que dói no bolso

Quando testei um projeto inteiro rodando via API, no vídeo abaixo, eu tinha colocado 2 dólares de crédito na conta antes de começar

O painel de uso já mostrava 3 centavos de dólar de uma execução de teste anterior

E o projeto inteiro ficou em torno de 11 a 12 centavos de dólar

Esses valores são do teste que eu descrevo no vídeo, não é tabela de preço de ninguém, beleza?

Mas a leitura vale: cada vez que você joga fora a sessão e recomeça contando tudo de novo, você paga pra reprocessar contexto que já estava salvo no disco

Em sessão longa, retomar é mais barato E mais fiel que recontar de cabeça

Se economia é o assunto, a outra alavanca óbvia é escolher o modelo certo pra cada tarefa, que muda bastante a conta no fim do mês

No vídeo eu também mostro a parte que virou hábito aqui: ao terminar a primeira versão do projeto, pedi ao próprio modelo pra criar um arquivo de documentação na raiz, com visão geral, stack, estrutura de pastas, banco de dados, autenticação, como rodar, convenções e regras importantes

Chamei aquilo de aperto de mão entre sessões: quem chega depois lê o documento e consegue retomar o projeto

E funcionou de um jeito que me surpreendeu: troquei de ferramenta no meio do projeto, saí do Claude Code pra outro agente, e usei esse arquivo pra fazer a retomada

Pedi pro novo agente explicar como o projeto funcionava, e ele descreveu o sistema corretamente com base no arquivo de contexto e nos arquivos do projeto

Depois segui implementando recursos novos e, no MESMO prompt, pedi que o arquivo de contexto fosse atualizado com as funcionalidades novas

É isso que evita o documento apodrecer a cada mudança

Confissão honesta: o certo seria eu ter lido e conferido o arquivo gerado pra ver se ficou completo, em vez de assumir que o modelo acertou tudo

E vale o contexto: o projeto do teste era inicial e pequeno, então aquela camada toda de proteção contra estrago valia mais como HÁBITO do que como necessidade naquele caso

O que registrar no repositório para a próxima retomada já vir com contexto

Sintoma: toda sessão nova começa com você repetindo as mesmas cinco regras do projeto

"usa pnpm, não usa npm", "o teste roda com tal comando", "branch é nesse padrão"

Causa: esse contexto mora na sua cabeça, não no repositório

Então ele morre junto com a sessão, toda vez

Solução: escreve isso em arquivo de memória

O comando /memory lista os locais dos arquivos de memória (CLAUDE.md, CLAUDE.local.md) nos escopos de usuário e de projeto, incluindo entradas de arquivos que ainda não existem

Os escopos, na prática:

• ./CLAUDE.md na raiz do projeto: versionado e compartilhado com o time
• ./CLAUDE.local.md: anotações pessoais do projeto, e esse deve entrar no .gitignore pra não ser compartilhado
• ~/.claude/CLAUDE.md: vale pra todas as suas sessões

O que a documentação oficial manda colocar lá

• comandos que o Claude não teria como adivinhar
• regras de estilo que fogem do padrão
• instruções de teste e runner preferido
• etiqueta do repositório (nome de branch, convenção de PR)
• decisões de arquitetura específicas do projeto
• peculiaridades do ambiente, tipo variáveis obrigatórias

E o que ela manda deixar de FORA

• qualquer coisa que o Claude descobre lendo o código
• convenções padrão da linguagem
• documentação detalhada de API
• informação que muda com frequência
• explicações longas ou tutoriais
• descrição arquivo por arquivo do codebase

Repara no espírito da lista: o arquivo é pra dizer o que NÃO está óbvio no código, não pra virar um segundo README gigante

Esse mesmo arquivo é o que sustenta trabalho mais autônomo depois, tipo deixar o agente rodando tarefas sozinho, porque aí o contexto não depende de você estar por perto pra explicar

Como prevenir: /rename nas sessões pra achar cada frente depois, e /export quando a conversa precisar sair da máquina

O /export abre um menu pra copiar a conversa atual pra área de transferência ou salvá-la como arquivo de texto

(e vale lembrar do alerta lá de cima: o que estava no transcrito vai junto no export)

Conclusão: o que fazer da próxima vez que a sessão morrer

Sessão morta quase nunca é trabalho perdido, é trabalho mal retomado

A sequência enxuta é essa:

1. volte pro diretório do projeto (o --continue depende disso, e é o erro mais comum: rodar de outra pasta e achar que sumiu)
2. retome com claude --continue se for a última daquele diretório, ou claude --resume quando você tem várias frentes abertas
3. sem estar no diretório certo? claude --resume <session-id> funciona de qualquer lugar
4. antes de pedir qualquer coisa nova, olhe o estado real com /rewind e o espaço de contexto com /context (pular esse passo é o que faz o agente refazer coisa pronta)
5. contexto apertado, /compact com instrução de foco; tarefa realmente nova, /clear

E o próximo passo concreto, pra hoje: dá /rename nas sessões que estão abertas e escreve o primeiro CLAUDE.md do projeto

Porque a melhor retomada é aquela que não depende da sua memória…

até o próximo post! 😀