Handoff

Gerar um arquivo estruturado HANDOFF.md que dê a uma nova sessão do Claude tudo o que ele precisa para continuar este trabalho sem arrastar o contexto degradado atual.

O claude-mem já injeta observações recentes em cada nova sessão, então o novo agente começa com uma linha do tempo do que aconteceu. O handoff adiciona o que essa linha do tempo não pode: o objetivo, as tentativas falhas e por que falharam, a teoria atual e os próximos passos exatos, além de ponteiros na memória para um recall mais profundo.

Quando Usar

• A sessão é longa e o Claude se sente confuso ou repetitivo
• O Claude continua tentando a mesma solução falha repetidamente
• O usuário quer se afastar e retomar mais tarde
• /compact foi executado, mas o Claude ainda carece de direção clara
• O usuário diz "handoff", "gerar um handoff", "quero começar do zero" ou "escrever um documento de handoff"

O Que Capturar

Pense cuidadosamente sobre o arco completo desta conversa antes de escrever. O handoff deve ser útil para uma instância do Claude que nunca viu esta conversa.

Seções Obrigatórias

1. Objetivo — Um parágrafo. O que o usuário está realmente tentando realizar? Declare o estado final, não a subtarefa atual. Seja específico o suficiente para que um novo agente possa se orientar imediatamente.

2. Estado Atual — O que está funcionando agora? O que está quebrado? Qual é o sintoma exato do problema? Inclua mensagens de erro literais, se relevante.

3. Arquivos em Jogo — Liste todos os arquivos que foram lidos, editados ou criados durante esta sessão que são relevantes para a tarefa atual. Use caminhos absolutos ou relativos ao repositório. Inclua uma nota de uma linha sobre por que cada arquivo é importante.

4. O Que Foi Tentado (e Por Que Falhou) — Esta é a seção mais importante. Liste todas as abordagens tentadas que não funcionaram e explique POR QUE falharam (não apenas que falharam). Um novo agente que pular esta seção repetirá os mesmos erros.

5. Teoria Atual Mais Promissora — Qual você acredita ser o caminho correto a seguir, mesmo que ainda não o tenha provado? Inclua qualquer evidência ou raciocínio que o suporte.

6. Próximos Passos — Ações concretas e ordenadas para o novo agente tomar. Seja específico: caminhos de arquivo, nomes de funções, comandos a serem executados. O novo agente deve ser capaz de começar no passo 1 imediatamente.

7. Restrições e Contexto Chave — Quaisquer restrições não óbvias: especificidades do ambiente, preferências do usuário expressas durante esta sessão, coisas que o usuário explicitamente disse para NÃO fazer, dependências externas, requisitos de desempenho, etc.

8. Ponteiros de Memória — Se as ferramentas de busca do claude-mem estiverem disponíveis, execute search para os termos-chave desta tarefa e liste os poucos IDs de observação que mais importam (uma decisão, a causa raiz, uma abordagem falha), para que o novo agente possa puxar detalhes completos com get_observations. Liste também uma ou duas consultas search que valem a pena serem reexecutadas. Pule esta seção se as ferramentas não estiverem disponíveis.

Regras de Escrita

• Escreva o handoff para um Claude novo, não para o usuário. O usuário sabe o que aconteceu; o Claude novo não.
• Seja brutalmente específico. Próximos passos vagos são inúteis. "Corrigir a autenticação" é ruim. "Em src/auth/middleware.ts:47, a verificação de expiração do token usa Date.now(), mas deveria usar req.timestamp — altere a comparação na linha 52" é bom.
• Inclua mensagens de erro exatas, stack traces ou saída de teste que capturem o modo de falha.
• Não encha linguiça. Cada frase deve conter informações essenciais para o novo agente.
• Não escreva o handoff da perspectiva do usuário. Escreva-o como um documento de briefing direcionado ao agente que está chegando.

Saída

Escreva o handoff em HANDOFF.md no diretório de trabalho atual (a raiz do projeto).

Use esta estrutura:

# Handoff

> Gerado: [timestamp]
> Projeto: [nome ou diretório do projeto]
> Resumo da sessão: [uma frase descrevendo sobre o que foi esta sessão]

## Objetivo

[O que o usuário está tentando realizar — o estado final real]

## Estado Atual

**Funcionando:**
- [lista o que está confirmado funcionando]

**Quebrado:**
- [sintoma exato, mensagem de erro ou modo de falha]

## Arquivos em Jogo

| Arquivo | Por Que Importa |
|------|---------------|
| `path/to/file.ts` | [uma linha] |

## O Que Foi Tentado (e Por Que Falhou)

### Tentativa 1: [nome curto]
- **O quê:** [o que foi feito]
- **Por que falhou:** [causa raiz, não apenas "não funcionou"]

### Tentativa 2: [nome curto]
...

## Teoria Atual Mais Promissora

[O que você acredita ser a abordagem correta e por quê]

## Próximos Passos

1. [Passo específico e acionável com caminho de arquivo ou comando]
2. [Próximo passo]
3. ...

## Restrições Chave


…