Um bom handoff é, quase todo, uma lista de becos sem saída

Três horas de sessão: você tentou a abordagem com streaming e abandonou, descartou duas bibliotecas e descobriu que a suíte de testes mente num caso específico. Aí a janela enche, a sessão compacta e, vinte minutos depois, o Claude sugere a abordagem com streaming.

Isso não é falha de memória. É decisão de projeto, e está documentado. A documentação do Claude Code lista exatamente o que o resumo da compactação preserva: os seus pedidos e a sua intenção, os conceitos técnicos centrais, os arquivos lidos ou modificados com os trechos de código importantes, os erros e como foram corrigidos, as tarefas pendentes e o trabalho atual. E completa: o resumo substitui a conversa literal — a saída completa das ferramentas e o raciocínio intermediário desaparecem.

Todo beco sem saída que você percorreu vive no raciocínio intermediário. Ele nunca virou arquivo, nunca virou diff, nunca virou erro corrigido — então não existe nada em disco que registre aquilo. A compactação preserva o que aconteceu. As suas tentativas descartadas nunca aconteceram. Essa assimetria é o problema do handoff inteiro.

/resume não é handoff

A objeção óbvia: por que escrever alguma coisa, se existe claude --resume? Porque o resume resolve outro problema. A documentação é clara: uma sessão retomada restaura o histórico completo, incluindo as chamadas de ferramenta e os resultados delas. Ou seja, você reabre exatamente a janela entupida da qual estava tentando fugir — e ela compacta de novo pouco depois. Isso é continuação, não consolidação.

Mais três limites que vale conhecer antes de tratar o resume como rede de segurança:

• O escopo é o diretório. A busca por session ID cobre o diretório do projeto atual e os git worktrees dele, mais nada. Retome da pasta errada e você recebe No conversation found with session ID.
• Tem prazo de validade. Os transcripts ficam em ~/.claude/projects/<project>/<session-id>.jsonl com retenção padrão de 30 dias (cleanupPeriodDays). Aquela depuração difícil do trimestre passado já foi apagada.
• O arquivo não é um documento. A própria documentação avisa: o formato das entradas é interno ao Claude Code e muda entre versões, então script que lê esses arquivos direto pode quebrar em qualquer release. transcript é log de append, não é conhecimento.

E o /export, que renderiza a conversa como texto legível? Esse existe explicitamente pra uma pessoa ler. Colar 40 mil tokens de transcript renderizado numa sessão nova é o pior dos dois mundos: você paga o preço cheio do ruído e o Claude ainda tem que redescobrir todas as conclusões.

O formato do arquivo

Um arquivo por tarefa, num caminho que você realmente vai abrir — eu uso notes/handoff-<tarefa>.md. Seis seções, nessa ordem, porque é a ordem em que alguém que chega frio precisa delas:

# Handoff — <tarefa> · <data> · sessão <nome>

## OBJETIVO
Uma frase. E como a gente sabe que terminou (o comando, o teste, a verificação).

## ESTADO
- Pronto:
- Em andamento:  ← diga o arquivo exato e o que está editado no meio
- Aberto:

## DECISÕES
- Escolhi X em vez de Y porque Z.

## DESCARTADO — não tentar de novo
- Tentei A → falhou com <erro ou motivo exato>.
  Só vale tentar de novo se <o que teria que mudar>.

## FATOS DE BASE
Arquivos tocados · o comando que prova que funciona · todo ID, URL, versão
e número de que o trabalho depende.

## PRÓXIMO
O único próximo comando ou edição, executável sem me perguntar nada.

DESCARTADO não é apêndice bonitinho. É a única seção que nada no seu ferramental vai reconstruir pra você, e é a razão de o arquivo existir. Tudo que está acima dela, uma sessão nova redescobre lendo o código em dez minutos. Essa seção ela só redescobre repetindo os seus erros.

O prompt que escreve o arquivo

Cole isso na sessão que está morrendo:

Escreva um handoff em notes/handoff-<tarefa>.md para que uma sessão nova, com
zero histórico de conversa, consiga assumir este trabalho. Use exatamente
estas seções:

OBJETIVO — uma frase, e como saberemos que terminou.
ESTADO — Pronto / Em andamento (diga o arquivo exato e o que está pela metade)
  / Aberto.
DECISÕES — cada escolha que fechamos, com o motivo. Não tem motivo? Diga isso.
DESCARTADO — toda abordagem que tentamos e abandonamos, o erro ou motivo exato
  da falha, e o que teria que mudar para valer a pena tentar de novo. Não
  comprima esta seção. Ela é o ponto do arquivo.
FATOS DE BASE — arquivos tocados, o comando que prova que funciona, e todo ID,
  URL, versão e número de que o trabalho depende.
PRÓXIMO — o único próximo comando ou edição, executável sem me perguntar nada.

Regras: sem elogio, sem recapitular a conversa, sem conselho, sem sugestão que
eu não pedi. Se você não souber dizer se algo foi decidido ou apenas discutido,
coloque em Aberto e marque como "não confirmado". Cada linha tem que ser algo
que realmente aconteceu nesta sessão, não algo que você está inferindo agora.

Essa última regra faz trabalho de verdade. Peça a um modelo pra resumir uma sessão e ele vai gentilmente tapar os buracos com reconstrução plausível — é assim que um handoff vira ficção sem ninguém perceber. Nomear a restrição mantém o arquivo auditável.

Depois, na sessão nova:

Leia notes/handoff-<tarefa>.md. Não comece a trabalhar ainda. Me diga em três
linhas: o objetivo, a próxima ação, e qualquer coisa em DESCARTADO que você
teria tentado.

A terceira linha é o teste. Se o Claude apontar algo que ele estava a ponto de tentar, o arquivo já se pagou. Se ele não apontar nada, a sua seção DESCARTADO está vaga demais pra ter efeito.

O truque que quase ninguém conhece

Você não precisa estar dentro da sessão pra gerar o handoff dela. A documentação do Claude Code mostra um caminho headless: mandar um prompt pra uma sessão existente pelo ID e capturar a resposta como JSON estruturado.

claude -p --resume <session-id> --output-format json \
  "Devolva só o corpo do arquivo de handoff. <o prompt acima, sem o caminho>" \
  | jq -r '.result' > notes/handoff-bug-checkout.md

Essa é a saída de emergência pra sessão que você já fechou, ou pra aquela que você abandonou de raiva às 1h da manhã. Qualquer coisa dentro da janela de 30 dias ainda está alcançável. Pegue o ID no seletor do /resume — Ctrl+A abre a lista pra todos os projetos da máquina.

Dois vizinhos que valem ficar no kit. O /branch copia a conversa até aqui pra um novo session ID e deixa a original intacta — é a ferramenta certa quando você quer tentar a abordagem arriscada em vez de anotar que ela falhou. E um hook de SessionEnd consegue arquivar o transcript automaticamente, se você preferir não pensar nisso nunca.

Por que isso é habilidade, não macete

O texto da Anthropic sobre engenharia de contexto dá nome ao padrão por trás disso: anotação estruturada, em que o agente escreve notas guardadas fora da janela e as lê de volta depois de um reset. O exemplo mais afiado que eles dão é o Claude jogando Pokémon — depois de um reset de contexto, o agente lê as próprias notas e continua sequências de treino de várias horas. No mesmo texto, sobre a parte difícil de compactar: primeiro maximize o recall, garantindo que o prompt de compactação capture toda informação relevante do histórico, e só então itere pra melhorar a precisão. Recall primeiro, precisão depois. É exatamente por isso que o DESCARTADO manda o modelo não comprimir nada ali.

Se a mesma seção aparecer em handoff depois de handoff, pare de copiar na mão. O Claude Code permite adicionar uma seção "Compact Instructions" no CLAUDE.md pra dirigir o que toda compactação automática preserva — é ali que mora um "sempre mantenha a lista de abordagens descartadas". Quando isso vira estrutura, você para de pagar por isso toda vez.

O ângulo de EM

Esse é o mesmo artefato que você já deve a um ser humano. Um colega que assume a sua branch pela metade precisa do objetivo, do estado, das decisões e dos becos sem saída — nessa ordem. Escreva handoffs pro Claude por um mês e as suas descrições de pull request e os seus updates de daily também ficam melhores, porque você passou o mês treinando justamente o que a maioria dos engenheiros pula: escrever o que tentou e por que parou.

E se você está em processo pra vaga remota nos EUA ou na Europa, isso não é habilidade comportamental de enfeite. Time distribuído roda em estado escrito, e "aqui está o que eu descartei e por quê" é o sinal mais claro que existe de que você consegue trabalhar com gente oito horas de fuso longe.

Faça isso hoje

Pegue a sua sessão aberta mais longa — aquela bagunçada que você fica retomando — e rode o prompt de handoff nela agora. Depois leia só a seção DESCARTADO. Se ela voltar vazia ou vaga, você acabou de aprender uma coisa incômoda: três horas de opções eliminadas estavam a ponto de evaporar. Salve o arquivo, dê /clear e recarregue com a checagem de três linhas. Quatro minutos, e é o seguro mais barato do seu setup inteiro.

Fontes

• Claude Code docs — Manage sessions
• Claude Code docs — How Claude Code works
• Claude Code docs — Explore the context window
• Anthropic Engineering — Effective context engineering for AI agents