Lição 3 de 6: Memória entre sessões

Esta lição é sobre memória de longo prazo entre sessões, não sobre código que roda. Cada nova sessão começa com a janela de contexto vazia; o que sobrevive a um reset é só o que ficou gravado em arquivo no repositório.

O que /resume faz, e o que ele não resolve

/resume é um built-in do Claude Code. Ele reabre uma sessão passada: a documentação descreve claude --continue pra retomar a sessão mais recente e claude --resume pra escolher de uma lista. O importante é o que ele restaura: a conversa anterior, o transcript salvo localmente. E a conversa não dura: ela vive presa àquela sessão, e some quando a janela é resetada ou compactada.

A disciplina: assuma interrupção

A regra mental que organiza tudo aqui: assuma que sua janela de contexto pode ser resetada a qualquer momento.A disciplina de presumir que a janela de contexto pode ser resetada a qualquer momento (fechar o app, /clear, compactação no limite). O que sobrevive ao reset é só o que está gravado em arquivo no repositório. Você fecha o app, roda /clear, a sessão compacta sozinha ao bater no limite: em todos os casos, a próxima sessão começa do zero. A Anthropic mediu esse mesmo problema num regime mais extremo (agentes que trabalham horas sem ninguém olhando), e a solução de lá transfere pro seu caso interativo:

Eles rodavam dezenas de sessões autônomas; você roda poucas e está no loop o tempo todo. Mas a parte que transfere é a mesma: a janela some, e o que sobrevive é o que ficou em arquivo. Em escala menor, isso vira três arquivos que uma sessão nova lê pra recuperar onde você estava:

A regra de operação que vem junto, também do experimento da Anthropic: uma feature por vez, e "marque features como passando só depois de testar com cuidado." Marcar feito antes de verificar de ponta a ponta envenena o próprio registro: a próxima sessão confia num item que não está pronto.

O que conta como "verificar de ponta a ponta" depende do que você constrói. Num SaaS, é o teste rodar verde, o build passar, ou você abrir a tela e ver a função acontecer (emitir um recibo de teste e o PDF sair, por exemplo). Numa ferramenta de dados, é conferir o número contra a fonte oficial, ver se a data bate, confirmar que o dado não veio alucinado. Se você ainda não escreve teste, "vi funcionar com meus próprios olhos, no caso real" já é uma verificação válida; o que não vale é marcar feito por suposição.

Onde isso mora: no plano, não num arquivo solto

Tentação: criar docs/session-log.md separado. Evite: um log à parte fica órfão e ninguém consulta. O plano da fatia (aquele pedaço pequeno de trabalho que você planejou no M2) já é arquivo vivo que você e o Claude consultam, e o log de progresso só faz sentido junto com o plano que estava ativo. Progresso no plano = contexto na hora em que importa.

Quando a fatia fecha (commit final), o plano vai pra plans/archive/ com o log e a checklist dentro. Seis meses depois, quando você (ou alguém que pegou o projeto) volta naquele commit, lê: "tentei X primeiro, descobri Y, mudei pra Z", e a decisão fica explicável.

Passo 1 — Adicione log de progresso e checklist ao plano ativo

Cole no Claude, no fim de uma sessão de trabalho real:

Atualiza `plans/<plano-ativo>.md` com duas seções, se ainda não existirem.

Primeiro, uma checklist de features da fatia atual, cada item com status. Se ainda não existe a seção `## Features`, crie listando as features da minha fatia como pendente; depois marque feito só as que verifiquei nesta sessão:

## Features
- [ ] <feature 1> — pendente
- [ ] <feature 2> — pendente
(...)

Marca `[x]` e `feito` SÓ as features que eu verifiquei de ponta a ponta nesta sessão (vi funcionar no caso real ou conferi o dado contra a fonte; ou, se você escreve teste, o teste rodou verde e o build passou). Não marca nada por "parece pronto".

Depois, um log de progresso datado no fim do arquivo:

## Progresso

### <data-ISO>
**O que mudou:** 3-5 bullets concretos (arquivos, decisões, erros encontrados).
**O que tentei e não funcionou:** se aplicável, 1-3 bullets, com o porquê curto.
**Onde parei:** 1 frase precisa + a próxima ação clara.
**Pro próximo Claude:** 1-2 frases de contexto que uma sessão nova precisaria saber sem ter lido esta (ex: "decidi Drizzle, não Prisma; razão em DECISIONS.md").

Mostra o diff antes de gravar.

Aprove. O valor está em você ler antes de comitar: o log é curado por você, não despejado pelo Claude. Resumo que você não leu vira ruído: depois de três meses você não confia no que está lá porque não escreveu, então não consulta, então o arquivo morre.

Passo 2 — Um init que a próxima sessão lê pra se situar

A próxima sessão começa vazia. Dê a ela um ponto de entrada único, em vez de você reexplicar tudo toda vez. Se você não mexe com scripts, fique na opção simples: uma seção ## Início rápido no topo do plano que diz "comece lendo isto". Ela funciona igual. O script (bin/init.sh) serve a quem prefere que um comando suba o ambiente sozinho; se não é seu caso, ignore.

Cria `bin/init.sh` (ou, se preferir mais simples, uma seção "## Início rápido" no topo de `plans/<plano-ativo>.md`) que uma sessão nova lê pra recuperar o estado. Conteúdo:

1. Como rodar o projeto, SE houver um comando (ex: `npm run dev`, `streamlit run`, `python app.py`). Se o projeto ainda não roda com um comando, pula este item.
2. Onde está o estado: "leia a seção ## Progresso (último datado) e ## Features (o que falta) deste plano."
3. A regra de operação: uma feature por vez; marca `feito` só depois de verificar de ponta a ponta.

Mantém curto (10-15 linhas). Se for script, roda `chmod +x bin/init.sh`. Mostra o diff antes.

Aprove. Numa sessão nova, seu primeiro prompt vira leia o ## Início rápido do plano ativo (ou bin/init.sh) e me diga onde paramos, e o Claude reconstrói o estado a partir do arquivo, não da sua memória.

Passo 3 — Transforme o ritual num comando /diario

O log do Passo 1 é um hábito de fim de sessão, e hábito que depende só da sua disciplina uma hora falha. Codifique o ritual num comando customizado: um arquivo Markdown em .claude/commands/ com as instruções do que fazer, que o Claude executa quando você digita /diario. (É o mesmo formato das skills que você criou no M3: um arquivo de texto com um passo a passo pro Claude seguir. Se não lembra do M3, não tem problema: o prompt abaixo monta o arquivo pra você.)

Cria `.claude/commands/diario.md`: um comando que eu disparo com /diario no fim de uma sessão. Conteúdo do comando:

---
description: Escreve o log de progresso da sessão no plano ativo
---
Atualiza a seção ## Progresso de `plans/<plano-ativo>.md` com uma entrada datada (data ISO):
- O que mudou nesta sessão (arquivos, decisões).
- O que não funcionou, se aplicável.
- Onde parei + próxima ação.
- Pro próximo Claude: contexto que uma sessão nova precisaria.

E atualiza a checklist ## Features: marca `feito` SÓ o que eu verifiquei de ponta a ponta nesta sessão (vi funcionar, teste passou, ou conferi o dado contra a fonte).

Mostra o diff antes de gravar. Não comita sozinho.

Mostra o diff antes de criar o arquivo do comando.

Aprove. Agora o ritual é /diario no fim da sessão: um comando, não um gesto que você precisa lembrar de digitar por extenso.

Passo 4 — Conheça a auto memory (MEMORY.md) e o /memory

Os três arquivos acima são memória que você mantém. Existe uma segunda camada, que o Claude mantém sozinho: a auto memory.

A divisão de trabalho que importa pra você:

Os dois não competem. A auto memory guarda o que se repete no projeto inteiro (o comando de build, a versão de uma lib, um erro que já te mordeu antes); o log no plano guarda o estado de uma fatia específica de trabalho. Rode /memory uma vez agora pra ver o que o Claude já anotou sobre seu projeto. Num projeto que você usa há um tempo, costuma já ter algo; num recém-criado, pode estar vazio ainda, e tudo bem: ela se preenche conforme você corrige o Claude.

Passo 5 — Faça o commit

Faça commit de `plans/<plano-ativo>.md` (log + checklist), `bin/init.sh` (se criou) e `.claude/commands/diario.md`. Mensagem: `docs(plans): log de progresso + checklist de features`. Mostra os comandos antes.

Aprove. A auto memory (~/.claude/projects/...) não entra no commit: ela é local por design; não tente versioná-la.

Takeaways

• /resume é built-in e reabre uma sessão passada (o transcript). Mas transcript não é memória durável: some no próximo reset. O que sobrevive é o que está em arquivo no repo.
• Assuma interrupção: a próxima sessão começa vazia. Mantenha log de progresso + checklist de features + um init que ela lê pra se situar.
• Uma feature por vez; marque feito só depois de verificar de ponta a ponta: viu funcionar no caso real, conferiu o dado contra a fonte, ou o teste passou. Marcar antes envenena o registro.
• Auto memory (MEMORY.md) é ligada por padrão, o Claude a mantém sozinho, é local por repo. O log no plano é o que você mantém e versiona. Os dois se complementam.

Você terminou quando

Quatro coisas:

1. plans/<plano-ativo>.md tem uma seção ## Progresso com pelo menos uma entrada datada e uma ## Features com status por item
2. Existe um init (bin/init.sh ou seção "## Início rápido") que uma sessão nova lê pra recuperar o estado
3. /diario existe em .claude/commands/ (ou você tem o ritual de fim de sessão rodando)
4. Você rodou /memory ao menos uma vez e sabe onde a auto memory mora; tudo commitado (menos a auto memory, que é local)