Phase 14 - Lesson 40

Handoff de Múltiplas Sessões

A sessão vai terminar. O trabalho não. O pacote de handoff é o artefato que transforma "o agente trabalhou por uma hora" em "a próxima sessão é produtiva no primeiro minuto". Construa-o intencionalmente, não como uma reflexão tardia.

Tipo: Construção Linguagens: Python (stdlib) Pré-requisitos: Phase 14 · 34 (Repo Memory), Phase 14 · 38 (Verification), Phase 14 · 39 (Reviewer) Tempo: ~50 minutos

Objetivos de Aprendizado

  • Identificar os sete campos que todo pacote de handoff precisa.
  • Gerar um handoff a partir dos artefatos da bancada de trabalho sem escrever prosa manualmente.
  • Reduzir logs de feedback grandes para um resumo do tamanho de um handoff.
  • Tornar a primeira ação da próxima sessão determinística.

O Problema

A sessão termina. O agente diz "ótimo, fizemos progresso". A próxima sessão começa. O próximo agente pergunta "onde paramos?". A resposta do primeiro agente desapareceu. O próximo agente redescobre, executa novamente os mesmos comandos, faz novamente as mesmas perguntas ao humano e perde trinta minutos recuperando os últimos trinta segundos da sessão anterior.

O custo de um handoff ruim é pago a cada sessão durante a vida útil da tarefa. A solução é um pacote gerado automaticamente no final da sessão: o que mudou, por quê, o que foi tentado, o que falhou, o que restou e o que fazer primeiro na próxima vez.

O Conceito

flowchart LR
  State[agent_state.json] --> Generator[generate_handoff.py]
  Verdict[verification_report.json] --> Generator
  Review[review_report.json] --> Generator
  Feedback[feedback_record.jsonl] --> Generator
  Generator --> Handoff[handoff.md + handoff.json]
  Handoff --> Next[Próxima Sessão]

Sete campos que todo handoff carrega

Campo Pergunta que ele responde
summary Um parágrafo sobre o que foi feito
changed_files O diff em um relance
commands_run O que realmente foi executado
failed_attempts O que foi tentado e por que não funcionou
open_risks O que pode dar problema na próxima sessão, com gravidade
next_action O primeiro passo concreto que a próxima sessão dará
verdict_pointer Caminho para os relatórios de verificação + revisão

O campo next_action é o principal sustentáculo. Um handoff com tudo exceto next_action é um relatório de status, não um handoff.

Handoffs são gerados, não escritos

Um handoff escrito à mão é um handoff que acaba sendo ignorado em um dia difícil. O gerador lê os artefatos da bancada de trabalho e emite o pacote. O trabalho do agente é deixar a bancada de trabalho em um estado que o gerador possa resumir, não escrever o resumo.

Duas formas: legível por humanos e legível por máquinas

handoff.md é o que o humano lê. handoff.json é o que o próximo agente carrega. Ambos vêm dos mesmos artefatos de origem. Se eles divergirem, o JSON vence.

Redução do log de feedback

O feedback_record.jsonl completo pode conter centenas de entradas. O handoff carrega apenas as últimas K, além de cada entrada com um código de saída diferente de zero. A próxima sessão carrega o log completo se for necessário, mas o pacote permanece pequeno.

Construa

code/main.py implementa:

  • Um carregador que reúne o estado, o veredicto, a revisão e o feedback em um único WorkbenchSnapshot.
  • Uma função generate_handoff(snapshot) -> (markdown, payload).
  • Um filtro que escolhe as últimas K entradas de feedback mais todas as saídas diferentes de zero.
  • Uma execução de demonstração que escreve handoff.md e handoff.json ao lado do script.

Execute:

python3 code/main.py

Saída: um corpo de handoff impresso, além de ambos os arquivos no disco.

Padrões de produção na prática

Codex CLI, Claude Code e OpenCode trazem, cada um, uma história de compactação diferente; o pacote de handoff estruturado fica por cima de todos os três.

As estratégias de compactação variam; o esquema do pacote não. O POST /v1/responses/compact do Codex CLI é um blob AES opaco no lado do servidor (caminho rápido para modelos da OpenAI); o fallback é um "resumo de handoff" local anexado como uma mensagem de papel do usuário _summary. O Claude Code executa uma compactação progressiva em cinco estágios com 95% do contexto. O OpenCode faz ocultação de mensagens com base em carimbo de data/hora mais um resumo de LLM com 5 títulos. Três mecanismos diferentes, mesma necessidade: serializar o que sobrevive à compressão em um artefato portátil. O pacote é esse artefato.

Handoff de nova sessão não é compactação. A compactação estende uma sessão; o handoff encerra uma de forma limpa e inicia a próxima. O enquadramento da Hermes Issue #20372 (abril de 2026) está correto: quando a compressão in-place começa a se degradar, o agente deve gravar um handoff compacto, encerrar a sessão e retomar em um novo contexto. O pacote é o que torna essa transição barata. O erro é continuar compactando até que a qualidade colapse; a correção é planejar um handoff limpo e antecipado.

Um handoff ativo por branch e tópico. A coordenação multiagente falha mais com handoffs desatualizados do que com saídas ruins de modelos. Sempre inclua branch, last_known_good_commit e um status de active | superseded | archived. Handoffs antigos são arquivados; apenas o ativo direciona a próxima sessão. Esta é a diferença entre handoff-como-notas e handoff-como-estado.

Encerre antes de 50-75% do contexto, não no limite. O playbook de padrão escrito à mão (CLAUDE.md + HANDOVER.md) relata melhores resultados quando a sessão termina com 50-75% do orçamento de contexto, em vez de 95%. O gerador de pacotes funciona de forma limpa antes que os artefatos de compressão poluam o estado de origem. Barato de escrever enquanto o contexto está intacto; caro quando o modelo já está perdendo o rumo.

Use

Padrões de produção:

  • Hook de fim de sessão. O runtime aciona o gerador quando o usuário fecha o chat. O pacote vai para outputs/handoff/<session_id>/.
  • Template de PR. O markdown do gerador também é o corpo de um PR. Os revisores o leem sem precisar abrir cinco outros arquivos.
  • Handoff entre agentes. Construa com um produto (Claude Code), continue com outro (Codex). O pacote é a língua franca.

O pacote é pequeno, regular e barato de produzir. A economia de custo se acumula a cada sessão.

Envie

outputs/skill-handoff-generator.md produz um gerador ajustado para os caminhos de artefato de um projeto, um hook de fim de sessão que o executa e um esquema handoff.json que o próximo agente lê na inicialização.

Exercícios

  1. Adicione um campo assumptions_to_validate que exiba todas as suposições que o construtor registrou, mas que o revisor não avaliou acima de 1.
  2. Reduza o resumo do feedback de forma diferente para execuções com falha versus execuções bem-sucedidas. Defenda a assimetria.
  3. Inclua uma lista de "perguntas para o humano". Qual é o limite para uma pergunta entrar no pacote em vez de ser enviada em uma mensagem de chat?
  4. Torne o gerador idempotente: executá-lo duas vezes produz o mesmo pacote. O que precisa ser estável para que isso se mantenha?
  5. Adicione uma seção de "pré-requisitos da próxima sessão" listando exatamente os artefatos que a próxima sessão deve carregar antes de agir.

Termos-Chave

Termo O que as pessoas dizem O que realmente significa
Pacote de handoff "Resumo da sessão" Artefato gerado que carrega os sete campos, tanto em markdown quanto em JSON
Próxima ação "O que fazer primeiro" O único passo concreto que inicia a próxima sessão
Redução de feedback "Resumo do log" Os últimos K registros mais cada saída diferente de zero
Relatório de status "O que fizemos" Um documento sem o next_action; útil, mas não um handoff
Ponteiro do veredicto "Recibo" Caminho para os relatórios de verificação + revisão para rastreabilidade

Leituras Adicionais

0 lifetime access. Curriculum based on AI Engineering from Scratch by Rohit Ghumare (MIT, used under attribution).