🎯 Handoff vs resumo genérico
Muita gente confunde os dois e acaba escrevendo o errado. O resumo genérico é uma narrativa humana — conta o que aconteceu. O handoff é um documento operacional — instrui a próxima sessão a continuar. Propósitos diferentes, estruturas diferentes.
❌ Resumo genérico (inútil para Claude)
- • Narrativa em primeira pessoa
- • Sem caminhos, sem comandos
- • "Amanhã continuo" = vazio
- • Reflexões misturadas com ações
✓ Handoff (executável pela nova sessão)
Migrar validação de Joi→Zod em /src/api/users.
# Estado
Branch: refactor/zod-validation · 2/5 rotas feitas
# Próxima ação
Editar /src/api/users/update.ts aplicando o schema em /src/schemas/user.ts.
- • Seções fixas e previsíveis
- • Caminhos absolutos
- • Próxima ação em 1 linha
- • Zero subjetividade
🧠A diferença mental
Pergunte-se antes de escrever: "quem vai ler isso — eu amanhã ou o Claude de amanhã?". A resposta define o formato.
Você precisa da narrativa emocional? Vai no diário. O Claude precisa executar a próxima tarefa? Vai no handoff. Nunca misture.
📐 Template oficial (7 seções)
O handoff tem 7 seções fixas. Sempre na mesma ordem. Se você seguir o esqueleto, não precisa decidir o que incluir — só preenche os campos.
Esqueleto das 7 seções
Exemplo preenchido
# Objetivo
Adicionar autenticação OAuth Google ao endpoint /api/login.
# Estado atual
- Branch: feature/google-oauth
- Node 20.11, pnpm 9.1
- Servidor dev rodando em http://localhost:3001 (PID 4182)
- .env.local configurado com GOOGLE_CLIENT_ID e SECRET
# O que foi feito
- Dependência "next-auth" instalada
- Rota /api/auth/[...nextauth].ts criada
- Schema User atualizado com providerId em /prisma/schema.prisma
# Arquivos importantes
- /home/dev/app/src/app/api/auth/[...nextauth].ts
- /home/dev/app/prisma/schema.prisma
- /home/dev/app/.env.local (NÃO commitar)
# Decisões tomadas
- next-auth v5 beta porque v4 não suporta App Router
- providerId no User (não em tabela separada) porque 1 provider por user
# O que falta
1. Rodar "npx prisma migrate dev" para aplicar schema
2. Adicionar middleware de proteção em /src/middleware.ts
3. Testar fluxo end-to-end
# Próxima ação
Rodar `npx prisma migrate dev --name add-oauth-provider` e validar que a migração aplica sem erros.✅ Checklist: o que incluir sempre
Algumas informações nunca podem faltar — porque a nova sessão começa do zero, sem acesso ao seu terminal ou histórico mental.
Informações obrigatórias em qualquer handoff
| Tipo | Formato exigido | Exemplo bom |
|---|---|---|
| 📁 Caminhos | Absolutos (nunca relativos) | /home/dev/app/src/utils/api.ts |
| 🔢 Processos | PID + comando que iniciou | PID 4182 · pnpm dev --port 3001 |
| 🌐 URLs | Completa + porta | http://localhost:3001/api/health |
| ⌨️ Comandos | Literal, com flags | pnpm test -- --watch users.test.ts |
| 📦 Versões | Exata quando for crítica | next@15.0.2 · prisma@5.18 |
| 🌿 Branch / commit | Nome + último hash | feature/oauth · a1b2c3d |
💡Regra do "pronto para copiar"
Se a nova sessão precisa digitar alguma coisa, ela deve poder copiar do handoff diretamente. "Rode o servidor" é péssimo. pnpm dev --port 3001 é excelente. Reduz a zero a chance de digitação errada.
❌ O que NÃO colocar
Cada token no handoff dilui a atenção. Há coisas que parecem úteis mas pioram o resultado — elas roubam o foco da próxima ação.
✗ Fora do handoff
- ✗Retrospectivas — "foi difícil porque...", "gastamos tempo com..."
- ✗Emoções — "frustrante", "finalmente consegui", "ótimo progresso"
- ✗Justificativas longas — parágrafos explicando por que uma decisão foi certa
- ✗"O que aprendi" — reflexões pessoais sobre a sessão
- ✗Histórico de tentativas falhas — "primeiro tentei A, depois B, depois C"
- ✗Agradecimentos ou cumprimentos
✓ Equivalente útil (se precisar)
- ✓"Foi difícil" → decisão: "escolhi X porque Y falhou"
- ✓"Finalmente consegui" → feito: "ação + arquivo"
- ✓Justificativa longa → formato ADR: 1 linha "X porque Y"
- ✓"Aprendi Zod" → vai num notes.md, não no handoff
- ✓Tentativas falhas → só menciona se for bloqueio ativo
- ✓Emocional → pula completamente
Antes e depois: a mesma decisão
"Passamos bastante tempo debatendo se deveríamos usar TypeScript ou ficar com JavaScript. No começo eu achava JavaScript bastaria, mas depois de ver os problemas de tipagem no módulo de payments, percebi que TypeScript seria melhor. Foi uma boa decisão porque já evitou 2 bugs nos testes. Acho que vai escalar bem."
# Decisão
- TypeScript (não JS) porque tipos em /src/payments evitaram bugs de validação
🪄 Prompt mágico — código pronto
Escrever handoff manualmente dá trabalho. A solução é um prompt pronto que você cola no final da sessão — o Claude gera o documento seguindo sua estrutura. Cole, revise 30 segundos, salva.
Prompt oficial de handoff
copie e cole no fim da sessãoCrie um handoff estruturado com:
1. Objetivo do projeto
2. Estado atual (branch/ambiente/processos rodando)
3. Arquivos ou dados importantes (caminhos absolutos)
4. Decisões tomadas (com o porquê)
5. O que já foi concluído
6. Problemas pendentes
7. Próxima ação recomendada (1 linha)🔍Por que esse prompt funciona
- →Estrutura enumerada: o modelo segue a ordem literal — sem improviso
- →"caminhos absolutos": instrução explícita previne paths relativos
- →"com o porquê": força ADR-style em decisões, não só a decisão
- →"1 linha": força síntese extrema na próxima ação
Ajustes por tipo de projeto
| Tipo | Adicione ao prompt |
|---|---|
| 🌐 Web/fullstack | "Inclua portas abertas e variáveis .env críticas (sem valores)" |
| 📊 Data/ETL | "Inclua esquema de tabelas lidas/escritas e IDs de jobs" |
| 📝 Documentação | "Inclua arquivos editados em bullet com 1 linha cada" |
| 🧪 Pesquisa/experimento | "Inclua hipóteses testadas e seus resultados (sem comentário)" |
💡Revise os 30 segundos
O Claude pode gerar handoff com pequenos desvios — caminho relativo, ação na 2ª linha, justificativa longa. Leia de cabo a rabo antes de salvar. 30 segundos aqui economizam 20 minutos amanhã.
💾 Onde guardar o handoff
Handoff perfeito não serve se some quando você fecha o terminal. Existem 3 lugares válidos — e um lugar fatal que muita gente tenta.
Clipboard — uso imediato
Copia o handoff direto, abre nova sessão, cola. Ideal quando a continuação é AGORA.
Risco: perde se copiar outra coisa antes. Use só para retomada imediata.
Arquivo handoff.md no projeto
Salva no repositório, versiona, sobrevive a reboots. Ideal para retomadas em dias diferentes.
Bônus: vira histórico útil quando o projeto tem pausas longas.
Pasta /handoffs/ versionada
Um handoff por dia/milestone, arquivados. Exemplo: /handoffs/2026-04-21-oauth.md.
Ideal para projetos longos ou times com múltiplas mãos.
"Na memória do Claude" — erro fatal
Pedir "lembre disso para amanhã" não funciona. Não existe memória persistente entre sessões. O Claude vai ESQUECER.
→ Se você não salvar em lugar que VOCÊ controla, o handoff não existe.
🏆A regra de ouro
Se some quando você fecha o terminal, é lugar errado. Handoff precisa viver em disco — arquivo, commit, qualquer coisa que você possa abrir amanhã sem depender do ambiente da sessão.
📋Resumo do Módulo
Próximo módulo:
3.2 — 🗂️ Memória Externa: Arquivos de Apoio
CLAUDE.md, skills, decisions.md — onde vai cada tipo de informação.