Como retomar um projeto parado há meses com o Claude Code

Tem coisa pior que pegar código dos outros: pegar o SEU código de meses atrás e não reconhecer nada 😅

Aquele arquivo pela metade tinha um motivo, aquela função comentada ia virar alguma coisa, e o próximo passo estava óbvio na sua cabeça na sexta-feira em que você fechou o terminal

A diferença pro projeto legado de terceiro é essa: aqui existe rastro SEU em disco

Sessões antigas, histórico de prompts, commits, working tree do jeitinho que você largou

O código é seu, só a intenção que se perdeu… e é ela que a gente vai reconstruir com o Claude Code, na ordem certa: recuperar o rastro, mapear em leitura, só depois editar

O que você precisa antes de abrir o projeto:

Três coisas, e nenhuma delas é PC da Nasa 😀

• Terminal aberto no diretório do projeto: o rastro de sessão é POR diretório, então abrir o Claude Code na pasta errada é o mesmo que não ter rastro nenhum
• O repositório git como você deixou: branch, mudanças não commitadas, commits recentes
• A noção do que existe em disco: é aqui que a maioria se surpreende

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

Os transcripts de sessão ficam em ~/.claude/projects/<project>/<session-id>.jsonl, onde <project> é o caminho do diretório de trabalho com os caracteres não alfanuméricos trocados por hífen

No Windows, ~/.claude resolve pra %USERPROFILE%\.claude

E tem prazo: o Claude Code guarda esses transcripts localmente por 30 dias por padrão e apaga os arquivos mais antigos que isso

Quem manda nesse prazo é a configuração cleanupPeriodDays: o padrão é 30, o mínimo é 1, e definir 0 falha com erro de validação

Do lado dos prompts, o arquivo ~/.claude/history.jsonl guarda tudo o que você digitou, com timestamp e caminho do projeto, e é ele que alimenta o recall de prompts com a seta pra cima entre sessões

Tome cuidado! Esses arquivos não são criptografados em repouso: a única proteção são as permissões de arquivo do sistema operacional

Se algum comando seu imprimiu uma credencial na tela, ou o Claude leu um .env, aquilo foi gravado no arquivo da sessão

E se você quiser zerar o rastro de um projeto de vez, existe o claude project purge, que apaga transcripts, auto memory e entradas de histórico daquele projeto

Três cenários de projeto parado (e qual caminho seguir em cada um):

Antes de sair rodando comando, vale saber em qual dos três você está, porque o caminho muda

Cenário 1: a sessão antiga ainda está em disco:

Você parou há menos tempo que o período de retenção configurado

Esse é o cenário bom: retomar a sessão com --resume ou --continue reabre a conversa sob o mesmo ID e restaura o histórico completo, incluindo chamadas de ferramenta e resultados, além do modelo que estava em uso e do agente configurado

Ou seja, você não volta só pro texto: volta pro raciocínio

Cenário 2: os transcripts já foram apagados:

Passou da janela, o Claude Code limpou e acabou a conversa antiga

Mas não acabou o rastro: sobram o git (branch, working tree suja, commits recentes), o history.jsonl com os prompts que você digitou e, claro, o próprio código

Aqui a reconstrução é por leitura, não por memória

Cenário 3: você nunca usou o Claude Code nesse projeto:

Projeto antigo de verdade, escrito na unha

Não existe transcript nem history.jsonl daquele projeto, mas o git continua lá, então o passo 3 vale igual: é ele que mostra onde o trabalho parou

Depois é /init pra ter um CLAUDE.md de partida e o subagente Explore pra mapear o que existe antes de encostar em qualquer arquivo

Passo a passo para retomar o projeto com o Claude Code:

A sequência abaixo funciona nos três cenários, você só entra nela em pontos diferentes

1. Recuperar a sessão antiga:

Abra o terminal NO diretório do projeto e rode:

claude --resume

Ele abre uma lista pra você escolher qual sessão retomar, que é exatamente o que você quer numa retomada: faz tempo que você parou e provavelmente não lembra qual conversa era a boa

Se você tem certeza de que a última sessão daquele diretório é a certa, o atalho é:

claude --continue

Ele retoma a sessão mais recente daquele diretório, sem perguntar nada

Se não existir nenhuma, ele imprime No conversation found to continue e sai

E se você já estiver dentro de uma sessão em execução, dá pra trocar por ali mesmo com /resume, informando o ID, o nome ou escolhendo no seletor

Erro comum deste passo: rodar o comando com o terminal em outra pasta

Como o rastro é por diretório, a lista vazia (ou o No conversation found to continue) costuma ser só isso: diretório errado, não sessão perdida

2. Ramificar antes de mexer:

Antes de deixar o Claude editar qualquer coisa em cima de uma conversa antiga, faça uma cópia:

claude --resume --fork-session

Combinar --continue ou --resume com --fork-session cria uma cópia da conversa em uma sessão nova e deixa a original intacta

É o seu ponto de retorno caso a retomada vá pro lado errado

Erro comum deste passo: pular ele

A conversa antiga é o único registro de como você pensava o projeto naquela época, então preserve

3. Ler o estado do git que o Claude já enxerga:

O Claude Code tem acesso ao estado do git do projeto: branch atual, mudanças não commitadas e histórico recente de commits

E olha, na prática é o working tree sujo que entrega onde você parou

Pergunte direto:

Olhe a branch atual, o que está sem commit e os últimos commits.
Me diga em que ponto esse trabalho parou e o que parece estar pela metade.

Erro comum deste passo: aceitar a resposta como verdade absoluta

O git conta o QUE mudou, não o PORQUÊ

Trate isso como hipótese e confirme lendo o código nos próximos passos

4. Gerar o CLAUDE.md de partida:

Se o projeto não tem um CLAUDE.md, rode:

/init

O /init faz o Claude Code ler a estrutura do projeto e gerar um CLAUDE.md inicial, que depois você refina com /memory

Vale entender o porquê disso importar tanto numa retomada: esse arquivo é lido no início de TODA sessão

O carregamento é hierárquico: o Claude Code carrega o arquivo do diretório de trabalho e de cada diretório pai no lançamento, e os de subdiretórios sob demanda, quando lê arquivos ali

Então o que você escrever nele hoje é o que o seu eu do futuro vai receber de graça na próxima abertura

Erro comum deste passo: achar que o /init sozinho já resolve

Ele é ponto de partida, não retrato fiel

5. Mapear o que está pela metade com o Explore:

Antes de editar, mapeie

O Explore é um subagente somente leitura, otimizado pra buscar e analisar codebases, acionado justamente quando é preciso entender o código sem alterá-lo

A chamada especifica um nível de profundidade: quick, medium ou very thorough

Use o subagente Explore em profundidade very thorough para listar
o que está incompleto neste projeto: TODOs, funções sem uso,
testes quebrados e módulos que ninguém importa.

A sacada é que a exploração fica FORA da conversa principal, então você mapeia o projeto inteiro sem entupir o contexto da sessão em que vai trabalhar

Subagentes são arquivos Markdown com frontmatter YAML e, no Claude Code, moram em .claude/agents/

É a mesma lógica de quando uma skill não funciona no seu projeto: configuração é por projeto, e o que existe na pasta é o que vale ali

Erro comum deste passo: mandar o Explore "dar uma olhada" sem escopo

Peça uma lista do que está incompleto, não um resumo bonito do projeto

6. Deixar o Claude propor o próximo passo sem editar nada:

Agora sim, o plan mode

Ele faz o Claude ler arquivos e propor um plano sem editar nada até você aprovar

Pra entrar, use Shift+Tab, que cicla entre default, acceptEdits e plan

Se for pra um prompt único, dá pra prefixar com /plan

/plan Com base no que está pela metade, proponha qual é o próximo passo
e em que ordem retomar.

Gostou de quase tudo mas quer mudar uma parte? Ctrl+G abre o plano no seu editor de texto pra edição direta antes de o Claude prosseguir

E Shift+Tab de novo sai do plan mode sem aprovar nada

Erro comum deste passo: aprovar o plano no impulso porque parece plausível

O projeto é seu: o plano tem que bater com a intenção original, não só com o que o código sugere hoje

7. Registrar o entendimento reconstruído:

Essa é a parte que quase todo mundo pula, e é a que faz a PRÓXIMA pausa não doer

Rode:

/memory

Com ele você refina o CLAUDE.md e também navega pela pasta de auto memory, que é markdown puro: dá pra ler, editar ou apagar

E aqui vale a distinção, porque são dois mecanismos diferentes que atravessam sessões:

• CLAUDE.md: as instruções que VOCÊ escreve
• auto memory: as notas que o próprio Claude escreve a partir de correções e preferências suas

Separar os dois na cabeça evita confusão do tipo "eu nunca escrevi isso aqui" 😀

Erro comum deste passo: escrever no CLAUDE.md o que o código já diz

Registre o que o código NÃO diz: por que aquela parte parou, o que era pra ser e qual é o próximo passo combinado

8. Trabalhar com rede:

Retomada tem chute errado, e tudo bem

Cada prompt enviado cria um checkpoint, e o Claude tira snapshot dos arquivos antes de cada alteração

O menu abre com duplo Esc ou com:

/rewind

E ele oferece restaurar só a conversa, só o código, ambos, ou resumir a partir da mensagem selecionada

Duas coisas pra guardar: os checkpoints são salvos junto com a conversa, então dá pra fechar o terminal, retomar depois e ainda assim rebobinar

E tem limite: checkpoints só rastreiam mudanças feitas pelas ferramentas de edição do Claude

Alterações via comandos Bash ou processos externos NÃO são capturadas

Erro comum deste passo: confiar no /rewind pra desfazer um script que rodou no Bash

Esse aí é com o git mesmo

Problemas comuns ao retomar e como resolver:

"No conversation found to continue":

Sintoma: você roda claude --continue e o terminal cospe a mensagem e sai

Causa: ou o terminal está em outro diretório (o rastro é por diretório), ou aquela sessão já passou do período de retenção e o arquivo foi apagado

Solução: confira a pasta e rode claude --resume pra ver a lista do que sobrou

Se não sobrou nada, siga do passo 3 em diante: git mais /init mais Explore reconstroem bastante coisa

Como prevenir: ajuste cleanupPeriodDays pra um valor maior que o padrão de 30 dias, sabendo que o mínimo é 1 e que 0 é rejeitado com erro de validação

O contexto estoura no meio da retomada:

Sintoma: você mal começou a entender o projeto e a conversa já está pesada

Causa: retomada é leitura em massa, e sessão retomada volta com o histórico completo, incluindo chamadas de ferramenta e resultados

Solução: diagnostique com /context, que mostra o uso atual por categoria, com sugestões de otimização, e indica quais arquivos CLAUDE.md e de auto memory foram carregados

Depois controle o que sobrevive à compactação rodando /compact com um foco, ou adicionando uma seção de instruções de compactação no CLAUDE.md

Como prevenir: empurre a exploração pro subagente Explore, que mantém a leitura fora da conversa principal

E não confunda contexto cheio com Claude Code lento: são diagnósticos diferentes

Medo de rodar /clear e perder a conversa antiga:

Sintoma: a sessão está poluída, você quer limpar, mas trava com medo de perder o histórico da época

Causa: confusão entre limpar contexto e apagar registro

Solução: o /clear zera o contexto da conversa, porém a conversa anterior permanece em disco e pode ser retomada pelo seu session ID

Anote o ID antes e siga tranquilo

Como prevenir: pegue o hábito de ramificar com --fork-session quando for experimentar em cima de uma conversa que você quer preservar

O CLAUDE.md descreve um projeto que não existe mais:

Sintoma: o Claude insiste em uma estrutura, um script ou uma convenção que você abandonou justamente antes de parar

Causa: o arquivo é lido no início de toda sessão, então uma descrição velha vira instrução velha, sessão após sessão

Solução: rode /init pra o Claude reler a estrutura atual e depois refine com /memory, apagando o que não vale mais

Aproveite e passe o olho na pasta de auto memory pelo mesmo comando: é markdown editável, e nota antiga também envelhece

Como prevenir: ao encerrar uma sessão de retomada, atualize o CLAUDE.md antes de fechar o terminal

Conclusão:

A lógica da retomada cabe em três movimentos, e a ordem é o que importa

Primeiro recuperar o rastro (--resume, --continue, git, history.jsonl), depois mapear em modo leitura (Explore e plan mode) e só então editar

E fechar registrando: o CLAUDE.md é o que transforma esse esforço todo em algo que a próxima pausa não vai cobrar de novo

Próximo passo concreto pra hoje: escolha UM projeto seu que está parado, abra o terminal na pasta dele, rode claude --resume e não saia da sessão sem deixar o CLAUDE.md atualizado com o que estava pela metade e qual é o próximo passo

Se quiser cavar mais fundo em cada comando, a documentação de sessões do Claude Code tem os detalhes

Até o próximo post! 😀