🔀 Handoff Inteligente

Um handoff é um documento estruturado escrito para a PRÓXIMA sessão do Claude executar. Um resumo é uma narrativa humana sobre o que aconteceu. Propósitos diferentes.

Sem essa distinção, você acaba escrevendo textos bonitos que o Claude não consegue executar. Handoff é ferramenta operacional, não relatório.

Handoff = instrução para a próxima sessão. Resumo = registro para humanos. Handoff tem seções fixas, caminhos absolutos, próxima ação clara.

Sete seções fixas: Objetivo, Estado atual, O que foi feito, Arquivos importantes, Decisões tomadas (com porquê), O que falta, Próxima ação (1 linha).

Estrutura fixa = cérebro desligado na hora. Você não decide mais "o que incluir" — só preenche os campos. Reduz fricção.

A seção mais importante é a última: "Próxima ação". Se não couber em 1 linha, o handoff está grande demais.

Caminhos absolutos (nunca relativos), IDs de processos em background, URLs de serviços, comandos exatos que funcionaram, versões de dependências críticas.

A nova sessão não tem contexto. "Rodar o servidor" é ambíguo; npm run dev --port 3001 é executável.

Tudo que for ação → comando literal. Tudo que for local → path absoluto. Ambiguidade custa minutos de re-descoberta.

Fora do handoff: retrospectivas ("foi difícil porque..."), emoções, justificativas longas, "o que aprendi", agradecimentos, história de tentativas que falharam.

Cada token irrelevante dilui a atenção. Handoff inflado é handoff ignorado — o Claude novo vai focar no meio, não na próxima ação.

Se não for executável ou bloqueante, não entra. Reflexões vão em outro arquivo (ou em lugar nenhum).

Um único prompt que você cola no final da sessão e o Claude gera o handoff pronto. Inclui as 7 seções e pede caminhos absolutos explicitamente.

Handoff manual tem atrito. Prompt pronto vira automático. Cole, revise 30 segundos, salva.

O módulo traz o prompt completo para copiar + dicas de ajuste por tipo de projeto.

Três lugares possíveis: clipboard para uso imediato (cola na próxima), arquivo handoff.md no projeto (persistente), NUNCA "na memória do Claude" (não existe).

"Guardar na memória" é o erro fatal: Claude não lembra entre sessões. O handoff precisa estar em lugar que VOCÊ controle.

Regra: se some quando você fecha o terminal, é lugar errado.

Arquivo CLAUDE.md na raiz do projeto. O Claude Code carrega automaticamente no início da sessão e re-injeta após compaction.

É o único lugar que sobrevive sem você tomar ação. Tudo que é regra permanente do projeto vai aqui — não na conversa.

Automático + persistente + re-injetado. Três garantias que o histórico da conversa não tem.

A Anthropic recomenda CLAUDE.md com menos de 200 linhas: "Target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence."

Mais de 200 linhas diminui a aderência do próprio modelo ao que você escreveu — instruções competem por atenção. O limite é oficial.

Se passou de 200 linhas: extrair para skills, delegar para arquivos específicos, cortar obsoleto.

4 níveis de escopo: managed policy (/etc/claude-code/), user (~/.claude/), project (./CLAUDE.md) e local (./CLAUDE.local.md).

Colocar no nível errado quebra compartilhamento (time vs pessoal) e controle de versão (local é gitignored por padrão).

Regra do projeto → project. Preferência pessoal do dev → local. Regra de todos os seus projetos → user.

Skills carregam sob demanda (até 5k tokens cada, budget combinado de 25k). CLAUDE.md carrega sempre. São complementares, não substitutos.

Colocar workflow raro no CLAUDE.md infla o contexto de TODA sessão. Colocar regra permanente em skill faz o Claude esquecer.

Frequência alta + curta → CLAUDE.md. Frequência baixa + longa → skill. Decisão baseada em uso real.

Arquivos markdown pequenos no projeto: decisions.md (ADRs curtos), todo.md (lista volátil de tarefas), ARCHITECTURE.md (visão geral).

CLAUDE.md aponta para eles ("leia decisions.md antes de X"); o Claude só carrega quando precisa. Mantém o core leve.

Templates curtos (20-50 linhas) separados por tópico batem arquivo único gigante.

Fatos permanentes sobre você → memória (user CLAUDE.md). Decisões e estado do projeto → arquivo versionado. Workflows invocáveis → skill.

Cada tipo de informação tem o lugar ótimo. Misturar gera duplicação, inconsistência e desperdício de tokens.

Teste rápido: "isso muda por projeto?" → arquivo. "Isso muda por usuário?" → memória. "Isso é um procedimento?" → skill.

Fluxo mínimo: abrir Claude Code no mesmo diretório, usar /clear se sessão anterior ainda está viva, colar o handoff como primeira mensagem.

Ordem importa: abrir no diretório certo faz o CLAUDE.md carregar sozinho. Começar em diretório errado perde metade do contexto "gratuito".

CLAUDE.md se carrega sozinho. Handoff você cola. Skills serão chamadas sob demanda. Três camadas.

Um prompt curto que antecede o handoff: "Vou continuar um projeto. Leia o handoff abaixo e me confirme que entendeu antes de agir". Evita ações impulsivas.

Sem essa framing, o Claude novo pode começar a executar antes de validar que entendeu. Pedir confirmação antes corta retrabalho.

Framing "ler + confirmar + agir" em 3 etapas explícitas é melhor que "continua aí".

Depois de colar o handoff, peça: "em 2 linhas, o que vamos fazer?". Se a resposta divergir, o handoff estava ambíguo ou incompleto.

Esse check curto detecta mal-entendidos em 10 segundos. Pular ele significa descobrir o erro 20 minutos depois de código errado.

Validação cedo, curta, barata. Re-fraseamento do modelo é termômetro de entendimento.

Quando a sessão chega a ~95% da capacidade, o Claude Code compacta automaticamente: limpa tool outputs primeiro, depois resume mensagens.

Se você não controlar a sessão, ela se auto-gerencia — mas de forma genérica. Um handoff manual antes do auto-compaction preserva melhor o contexto.

Auto-compaction é rede de segurança, não estratégia. Melhor é você atuar antes.

Após compaction: CLAUDE.md é re-lido do disco, skills invocadas são re-anexadas (até 5k tokens cada), user requests importantes ficam no resumo.

Saber o que sobrevive muda onde você coloca as coisas importantes. Regra permanente no CLAUDE.md = imune. Regra no chat = some.

Tudo que é "re-lido do disco" é resiliente. Tudo que vive só no histórico é descartável.

O erro clássico: fazer /clear e depois perguntar "continua onde paramos?". O Claude não lembra. Pior: vai INVENTAR uma continuação plausível.

Esse é o bug humano mais frequente da Trilha 3. Você perde uma tarde inteira corrigindo código inventado antes de perceber.

Após /clear: ou você cola o handoff, ou começa do zero. Não existe "continuar por telepatia".