Verificando acesso...

MÓDULO 2.3

⚡ Session handoff entre agentes

Travou em Claude? Handoff em 60s pro Codex e desbloqueio. Template HANDOVER.md e fluxo round-trip.

1

📨 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
2

📄 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.

3

🛠️ 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 agente

Você diz "/session-handoff" ou "faz um handoff" — agente lê histórico, produz HANDOVER.md. Você copia, cola no outro terminal, segue trabalhando.

4

🚨 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/usage mostra >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
5

🎯 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.

1

Detecta o loop

3 tentativas erradas seguidas no Claude. Para. Não insiste.

2

Gera handoff

"Faça session handoff" — Claude escreve HANDOVER.md.

3

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."

4

Avalia hipótese, libera fix

Frequentemente Codex chega na causa real em 30s. Ataque diferente, ponto cego diferente.

6

🔄 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

  1. Claude desenha HTML em dark mode bonito
  2. No processo, perde clareza de valor (informação fica escondida)
  3. Handoff pro Codex: "restaure clareza de valor sem perder o styling do Claude"
  4. Codex devolve hierarquia visual + headlines mais claros
  5. 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

Handoff = bridge de contexto entre agentes
HANDOVER.md tem 5 seções fixas
Skill session-handoff automatiza
Trocar de agente em loop / context alto / incidente
"Não confie nas tentativas anteriores" é frase mágica
Round-trip exige commit entre passes

Próximo:

2.4 ★ Prompts e dicas prontas (Bônus)