📨 O que é um handoff
Um bloco curto que dá ao próximo agente o estado completo da sessão: objetivo, status atual, decisões, o que evitar, próximo passo. Cabe em 1 mensagem.
Anatomia de um handoff
- Objetivo: o que estamos tentando fazer
- Status: onde paramos agora
- Decisões: o que já foi decidido (com why)
- Evitar: abordagens que falharam
- Próximo passo: ação concreta imediata
📄 Template HANDOVER.md
# HANDOVER
## Objetivo
Implementar endpoint POST /api/orders com idempotência.
## Status atual
- Schema validado em src/schemas/order.ts
- Handler escrito em src/api/orders/post.ts
- Teste idempotência falhando em tests/orders.test.ts:42
## Active files
- src/api/orders/post.ts (em edição)
- src/schemas/order.ts (estável)
- tests/orders.test.ts (com 1 falha)
## Decisões
- Idempotency key vem do header X-Idempotency-Key (why: padrão Stripe)
- TTL de 24h na cache (why: alinhado com TTL do CDN)
## Evitar
- Já tentei usar Redis (não temos infra). Use Postgres advisory locks.
- Não mexer em src/legacy/orders.ts (será removido em outro PR)
## Próximo passo
Fazer o teste tests/orders.test.ts:42 passar. Hipótese: lock não está
liberando após erro. Verificar try/finally.Regra: CLAUDE.md/AGENTS.md guardam regras perenes. HANDOVER.md guarda estado efêmero da sessão. Atualiza HANDOVER.md, não AGENTS.md.
🛠️ Skill session-handoff
Em vez de escrever o handoff manualmente, peça pro agente fazer. Skill compartilhável (funciona em Claude e Codex via Agent Skills standard).
---
name: session-handoff
description: Cria HANDOVER.md sintetizando a sessão atual quando o usuário pedir handoff, encerrar, ou trocar de agente
allowed-tools: [Read, Write]
---
# Session Handoff
Quando invocada:
1. Revise histórico da conversa
2. Identifique: objetivo, decisões com why, active files, próximo passo
3. Escreva HANDOVER.md no formato padrão (max 60 linhas)
4. Mostre o conteúdo final pra eu copiar/colar no outro agenteVocê diz "/session-handoff" ou "faz um handoff" — agente lê histórico, produz HANDOVER.md. Você copia, cola no outro terminal, segue trabalhando.
🚨 Quando fazer handoff
Os sinais práticos pra trocar de agente:
🚨 Sinais de troca
- 1Agente repete a mesma "correção" 3 vezes
- 2Loop óbvio (mesmas hipóteses retornando)
- 3
/usagemostra >70% do context - 4Você quer testar abordagem totalmente nova
- 5Status page mostra incidente no fornecedor
✓ Quando NÃO trocar
- 1Agente está progredindo (mesmo lento)
- 21ª tentativa, ainda iterando
- 3Context abaixo de 50%
- 4Problema é falta de info, não de raciocínio
🎯 Handoff Claude → Codex pra desbloquear
O cenário do vídeo do Nate Herk: Claude trava num bug → handoff pro Codex → Codex resolve em 10 segundos. Não é mágica — é abordagem diferente.
Detecta o loop
3 tentativas erradas seguidas no Claude. Para. Não insiste.
Gera handoff
"Faça session handoff" — Claude escreve HANDOVER.md.
Cola no Codex com frase mágica
"Não confie nas tentativas anteriores. Reproduza o erro, isole a causa, proponha correção. Não corrija antes de me mostrar a hipótese."
Avalia hipótese, libera fix
Frequentemente Codex chega na causa real em 30s. Ataque diferente, ponto cego diferente.
🔄 Round-trip iterativo
Uso avançado: Claude e Codex alternando no mesmo arquivo, cada um atacando seu forte. O padrão "stylist + restorer" do vídeo:
Caso real
- Claude desenha HTML em dark mode bonito
- No processo, perde clareza de valor (informação fica escondida)
- Handoff pro Codex: "restaure clareza de valor sem perder o styling do Claude"
- Codex devolve hierarquia visual + headlines mais claros
- Volta pro Claude pra polimento final
Resultado: arquivo melhor que qualquer um faria sozinho.
⚠️ Cuidado overwrite
Antes de cada handoff: git commit -am "wip: claude pass". Sem commit, o próximo agente pode sobrescrever sem você conseguir voltar. Próximo módulo (T3 3.4) fecha esse loop.
📚 Resumo
Próximo:
2.4 ★ Prompts e dicas prontas (Bônus)