O documento de handoff: memória de agente entre sessões

Em 21 de março de 2026, meu site em produção estava servindo páginas com 14 segundos de carregamento depois que uma limpeza de cache expôs um gargalo de performance. Investiguei a causa raiz em duas sessões, identifiquei o caminho de código lento, elaborei um plano de correção e capturei tudo em um documento de handoff.

Um documento de handoff carrega um diagnóstico através das fronteiras entre sessões, para que o agente que implementa herde o entendimento já corrigido em vez de rederivar as mesmas conclusões erradas. Diferentemente de tickets que dizem o que fazer, handoffs registram o que foi tentado, o que estava errado e por que abordagens anteriores falharam. O handoff da página de market sobreviveu a três correções ao longo de quatro dias e guiou uma implementação que reduziu o carregamento de página de 14 segundos para 108 milissegundos.

O primeiro rascunho desse handoff estava errado. Ele mirava no caminho de código errado. Uma revisão de código detectou que as páginas lentas medidas eram servidas por market_hub(), não por _fetch_market_data() como o handoff presumia. O handoff foi revisado.

O segundo rascunho propunha partials HTMX desnecessários para Apple Maps e contagens de tier. Uma revisão detectou que o Apple Maps assina URLs localmente (sem requisição externa para adiar) e que as contagens de tier deveriam vir de uma única query de agregação. O handoff foi revisado novamente.

O terceiro rascunho propunha tornar o endpoint de clima assíncrono, mas não especificava que o cliente HTTP síncrono existente ainda bloquearia o event loop mesmo por trás de HTMX. O handoff foi revisado uma terceira vez.

Quatro dias depois, uma sessão diferente leu o handoff revisado três vezes e implementou a correção. Austin passou de 14.290ms para 108ms. A implementação mirou no caminho de código correto, usou a abordagem de query correta e pulou os partials HTMX desnecessários. Cada correção das três revisões já estava incorporada.

O documento de handoff carregou um diagnóstico ao longo de quatro dias e múltiplas sessões. Sem ele, a sessão de implementação teria começado do zero, feito as mesmas suposições erradas, proposto as mesmas otimizações desnecessárias e precisado das mesmas correções. O handoff comprimiu quatro dias de investigação em um documento que o agente implementador leu em segundos. Isto é context window management aplicado a um problema específico: como transferir um diagnóstico entre fronteiras de sessão sem perder as correções que o tornam preciso.

O que um handoff contém

Um documento de handoff não é um ticket. Um ticket diz o que fazer. Um handoff diz o que foi tentado, o que foi aprendido, o que estava errado e o que fazer a seguir. A diferença é memória institucional.

O handoff da página de market continha:

O diagnóstico. Medições de TTFB em cold render para seis páginas de market, variando de 381ms (Tokyo, market pequeno) a 14.290ms (Austin, 500+ empresas). As medições provaram que o problema escalava com a contagem de empresas, o que apontava para o formato da query como o gargalo.

As causas raiz, priorizadas. Quatro causas raiz ordenadas por impacto: formato da query (primária), API de clima bloqueante (secundária), full-table scan em um caminho de código diferente (terciária) e cabeçalhos de cache ausentes (já parcialmente tratada). Cada causa raiz incluía caminhos de arquivo, números de linha e o padrão de código específico causando a lentidão.

As rotas erradas. O primeiro rascunho mirou em _fetch_market_data() em vez de market_hub(). O handoff registrou esse erro e a correção, para que a sessão de implementação não rederivasse a mesma conclusão errada. Ele também registrou os partials HTMX descartados e por que foram descartados: Apple Maps não tem requisição externa, contagens de tier pertencem à query de agregação.

O plano de implementação. Cinco passos com exemplos de SQL, critérios de aceitação e instruções de verificação. Passo 1: substituir paginação no lado do Python por uma query de banco de dados. Passo 2: adicionar partial HTMX de clima com cliente async. Passo 3: fazer cache do caminho de código secundário. Passo 4: adicionar cabeçalhos de cache de borda. Passo 5: remedir as mesmas seis URLs.

O post context window management explica por que esse nível de especificidade importa: cada ambiguidade no handoff é uma decisão que o agente implementador precisa rederivar, consumindo orçamento de contexto e arriscando a mesma conclusão errada.

As armadilhas de contexto. O contexto compartilhado do template inclui uma busca autenticada de saldo de moedas em cada página, inclusive páginas que nunca a renderizam. O handoff anotou isso como uma preocupação de correção de cache: s-maxage sem cabeçalhos Vary adequados poderia servir dados de autenticação obsoletos para usuários anônimos.

Por que tickets falham

Um ticket para o mesmo trabalho diria: “Páginas de market estão lentas. Otimizar a query do market hub.” A sessão de implementação precisaria:

1. Descobrir qual caminho de código serve as páginas de market (não óbvio sem ler o router)
2. Fazer profiling do caminho de código para encontrar o gargalo
3. Considerar várias abordagens de otimização
4. Implementar uma
5. Descobrir que a abordagem tem um efeito colateral (correção de cache com dados de autenticação)
6. Revisar a abordagem

Os passos 1-3 já tinham sido feitos nas sessões de investigação. O handoff carrega esse trabalho adiante. Um ticket o descarta.

O modo de falha não é preguiça. O modo de falha é perda de contexto entre fronteiras de sessão. Uma sessão de agente de IA começa com uma janela de contexto limpa. Ela não lembra o que a sessão anterior descobriu. Este é o mesmo problema que context is architecture aborda em nível de sistema: o que você coloca na janela de contexto determina a qualidade da saída. Um ticket fornece um objetivo. Um handoff fornece um objetivo mais o entendimento acumulado necessário para alcançá-lo corretamente.

O histórico de revisões importa

O histórico de revisões do handoff é tão valioso quanto seu conteúdo atual. O handoff da página de market registrou três revisões com timestamps e motivos:

• Capturado: 2026-03-21T17:24 (investigação original)
• Revisado: 2026-03-21T18:20 (correções de revisão de código: caminho de código errado, HTMX desnecessário)
• Revisado: 2026-03-25T06:30 (implementação completa, correção de query publicada)

O histórico de revisões diz à sessão de implementação: “este diagnóstico foi questionado e corrigido. A versão atual incorpora essas correções.” Um handoff sem revisões pode estar errado. Um handoff com três revisões foi submetido a teste de estresse.

As rotas erradas fazem parte do valor. Um handoff que diz “consideramos e rejeitamos HTMX de /_map porque o Apple Maps assina URLs localmente” poupa a sessão de implementação de propor a mesma otimização, tê-la revisada e tê-la rejeitada. O handoff antecipa a rejeição.

Quando escrever um handoff

Nem toda tarefa precisa de um handoff. Uma correção de bug que leva uma sessão não precisa de persistência entre sessões. Um handoff é valioso quando:

A investigação é cara. Fazer profiling de um gargalo de performance, rastrear uma vulnerabilidade de segurança, depurar uma interação multi-sistema. Se a investigação exigiu esforço significativo, o handoff preserva esse esforço.

A implementação vai acontecer em uma sessão diferente. Se você termina a investigação hoje mas vai implementar amanhã, o handoff faz a ponte. Sem ele, a sessão de amanhã começa do zero.

O diagnóstico não é óbvio. Se a correção correta exige entender por que três alternativas aparentemente razoáveis estão erradas, o handoff captura esse entendimento. O sistema compound context explica como handoffs se encaixam na acumulação mais ampla de conhecimento de projeto. Um ticket que diz “corrija a query” não explica por que a query precisa de uma correção específica.

Várias pessoas (ou agentes) podem trabalhar nela. O handoff é um documento de entendimento compartilhado. Qualquer sessão que o leia herda o contexto completo da investigação.

Handoffs como compound context

Um handoff é um depósito no sistema compound context. Cada handoff captura tempo de diagnóstico e o converte em um artefato reutilizável. A sessão de implementação saca o diagnóstico a um custo próximo de zero.

Com o tempo, handoffs se acumulam em um histórico de investigação. O handoff da página de market referencia o incidente de limpeza de cache, as medições do nightcheck, o guard destrutivo de API e o sistema de revisão de código. Cada um deles é, em si, produto de sessões anteriores. O handoff os conecta em uma narrativa que uma nova sessão pode seguir.

O handoff não substitui o entendimento. A sessão de implementação ainda precisa ler o código, escrever a correção e verificar o resultado. O handoff substitui a redescoberta. A sessão não precisa descobrir o que já é conhecido. A Ralph agent architecture usa handoffs como o principal mecanismo de persistência entre sessões para seu loop de execução noturna. O AI engineering hub documenta como handoffs se encaixam na infraestrutura mais ampla de hooks, skills e sistemas de memória que fazem o desenvolvimento assistido por agente compor com o tempo.

FAQ

Qual deve ser o tamanho de um handoff?

Longo o suficiente para capturar o diagnóstico, as rotas erradas e o plano de implementação. Curto o suficiente para que um agente possa lê-lo em um único carregamento de contexto. O handoff da página de market tinha 103 linhas. A maioria dos handoffs tem de 50 a 150 linhas.

Onde você armazena handoffs?

No diretório de memória do projeto: ~/.claude/projects/{project}/memory/handoff-{topic}.md. O sistema de memória carrega arquivos relevantes com base em descrições de frontmatter, então handoffs são descobertos por sessões futuras sem referência explícita.

Handoffs substituem documentação?

Não. A documentação descreve como o sistema funciona. Um handoff descreve o que foi aprendido sobre um problema específico e o que fazer a respeito. A documentação é permanente. Um handoff é consumido pela sessão de implementação e então se torna contexto histórico.

E se o handoff ficar desatualizado?

O campo de status do handoff rastreia isso. Handoffs ativos são marcados como PLANNED ou IN PROGRESS. Handoffs concluídos são marcados como RESOLVED com o hash do commit de implementação. Handoffs desatualizados ficam visíveis como contexto histórico, mas não são acionáveis.

Fontes

Este artigo baseia-se no handoff de performance da página de market (handoff-market-page-perf.md), que guiou a correção do formato de query publicada em 25 de março de 2026. O handoff sobreviveu a três ciclos de revisão ao longo de quatro dias e informou uma implementação que alcançou uma melhoria de performance de 132x. Referenciado em Compound Context.