Handoff Document no Claude Code: sessões longas sem perder qualidade

Tem um momento no Claude Code que todo mundo que usa de verdade conhece: a janela de contexto começa a encher, você manda /compact, segue trabalhando, enche de novo, compacta de novo — e, sem perceber, o agente vai ficando pior. Esquece um combinado, repete um trabalho, erra um caminho de arquivo que ele mesmo criou meia hora atrás.

Esse desgaste tem nome: context rot. E existe uma técnica simples que resolve melhor que ficar compactando: o handoff document.

O que é um handoff document

É um arquivo Markdown que registra o que aconteceu na sessão — as decisões, os arquivos mexidos, o que já funciona, o que ainda falta — e prepara a próxima sessão pra continuar de onde parou.

A sacada está numa observação que quem usa muito o Claude Code já sentiu na pele: o agente é mais afiado no começo de cada sessão. A janela está limpa, o foco está inteiro no que importa. Conforme a conversa cresce e você compacta várias vezes, a qualidade escorrega.

Em vez de espremer ao máximo uma sessão cansada, o handoff faz o contrário: você materializa o estado do projeto num documento e abre uma sessão nova, descansada, alimentada por esse resumo. O próximo Claude lê o handoff no início — o melhor momento dele — e segue em frente.

Por que isso vence o /compact em projeto longo

O /compact é útil, ninguém está dizendo o contrário. Pra um respiro pontual, dentro de uma tarefa só, ele resolve. O problema é usá-lo como estratégia num projeto de vários dias.

A diferença em uma frase:

• /compact resume a conversa, mas você continua na mesma sessão — e cada compactação seguida vai acumulando ruído e perdendo detalhe.
• Handoff document encerra a sessão e abre uma limpa, com um resumo que você controlou — escolhendo o que deve ser lembrado.

Repare na palavra: você controlou. No compact, é o Claude que decide o que cortar. No handoff, você dirige — diz exatamente o que o projeto precisa carregar pra frente. Isso muda tudo num trabalho longo.

Se economizar contexto é uma dor recorrente sua, vale combinar essa técnica com as ideias de gastar menos tokens no Claude e com o Summarize cirúrgico que mostrei no guia do /rewind.

O prompt do handoff

A hora de gerar o handoff é antes de estourar o contexto, com a sessão ainda lúcida. Quando sentir que a janela está enchendo, pare e cole algo assim:

Vamos encerrar esta sessão. Antes, gere um handoff document em Markdown
para a próxima sessão continuar de onde paramos. Inclua:

- Objetivo do projeto e o estado atual (o que já funciona).
- Decisões importantes que tomamos e o porquê.
- Arquivos criados ou alterados, com o caminho exato.
- O que tentamos e NÃO deu certo (pra não repetir).
- Os próximos passos, em ordem de prioridade.

Regras: seja exaustivo em contexto, mas conciso na prosa (use bullets).
Não invente nada que não aconteceu nesta sessão. Inclua código real,
não pseudocódigo. O documento tem que ser autossuficiente: alguém que
leia só ele deve conseguir continuar o trabalho.

Salve o resultado num arquivo versionável do projeto — HANDOFF.md na raiz, ou docs/handoff.md. Como entra no Git, ele acompanha o código e fica disponível pra qualquer sessão futura (sua ou de outra pessoa do time).

Na sessão seguinte, abre simples:

Leia o HANDOFF.md e continue de onde paramos.

As regras que separam um handoff bom de um inútil

Um handoff mal feito é pior que não ter nenhum, porque dá uma falsa sensação de continuidade. Quatro princípios mantêm o documento confiável:

• Não invente. O Claude tende a "completar" lacunas. Deixe explícito que ele só pode registrar o que de fato aconteceu na sessão. Um handoff com passos imaginários manda a próxima sessão pro buraco errado.
• Código e caminhos reais. Nada de pseudocódigo ou "o arquivo de config". Quer o nome exato, o trecho real. O próximo Claude vai agir em cima disso.
• Autossuficiência. O teste é simples: alguém que leia só o handoff, sem ter visto a conversa, consegue continuar? Se não, falta contexto.
• Exaustivo em fato, enxuto em prosa. Cubra tudo o que importa — mas em listas e bullets, não em parágrafos longos. Denso de informação, leve de ler.

Leve pro próximo nível: vira Skill

Colar o mesmo prompt toda vez cansa — e quando cansa, você para de fazer. A solução é transformar o handoff numa Skill do Claude Code.

Você guarda o procedimento como uma Skill e, no fim da sessão, chama ela em vez de colar o prompt inteiro. O documento sai em segundos, sempre no mesmo padrão. O hábito vira automático, e é aí que a técnica realmente compensa.

Se você nunca criou uma, o passo a passo está no guia de como criar sua própria Skill — leva poucos minutos e essa é uma das melhores primeiras Skills que dá pra ter.

Quando usar (e quando não precisa)

Seja honesto com o tamanho da tarefa:

• Tarefa curta, uma sentada só? Não precisa de handoff. Toque o trabalho e, no máximo, dê um /compact se a janela apertar.
• Projeto de vários dias, várias sessões? Aí o handoff brilha. Cada sessão termina entregando a próxima pronta, e você nunca recomeça do zero nem arrasta uma janela podre por dias.

A ideia central é essa: não lute pra manter viva uma sessão cansada. Capture o estado num documento que você controla, comece limpo, e deixe o Claude fazer o que ele faz de melhor — começar afiado. Em projetos longos, handoff documents ganham do compact com folga.

Por onde continuar

• Quer automatizar o handoff? Comece por como criar sua própria Skill.
• Combine com gastar menos tokens no Claude pra esticar ainda mais cada sessão.
• Pra delegar trabalho pesado sem sujar a conversa principal, veja os subagentes no Claude Code.

---

Fonte/inspiração: dica de IA — Como usar Handoff Documents no Claude Code. O conceito e os princípios do handoff vêm de lá; a redação, o prompt, os exemplos e a estrutura são deste blog.