🔁 Handoff e prime: o ciclo diário
O readback prova que o núcleo funciona uma vez. O ciclo diário é o que mantém ele funcionando todo dia: sessão → handoff → Markdown → prime → nova sessão. Neste módulo você escreve o handoff, monta o latest.md, aprende o prompt de prime e faz Claude e Codex se revezarem no mesmo trabalho sem perder nada no caminho.
📦 O que entra num handoff
O handoff é o bilhete que a sessão que está terminando deixa para a sessão que ainda não começou. Ele não é um relatório para humano, não é um changelog e não é um resumo bonito: é o mínimo de informação que faz um agente sem memória nenhuma retomar o trabalho no ponto exato onde você parou. O critério é brutalmente simples — se o próximo agente precisa perguntar alguma coisa para começar, faltou algo no handoff.
O fluxo que a documentação do kit descreve tem cinco itens obrigatórios, e eles vieram da prática, não da teoria: decisões tomadas, tarefas inacabadas, próximos passos, caminhos de arquivos e checks rodados com resultado. Os quatro primeiros são o que o comando /handoff procura numa sessão; o quinto é o que o módulo 2.5 ensinou a produzir e é o que impede que o próximo agente comemore uma migração que ninguém testou.
O ciclo gira sempre no mesmo sentido: a sessão que fecha produz um arquivo, e a sessão que abre lê esse arquivo. Nenhuma seta passa por dentro do chat — é por isso que o ciclo sobrevive a um /clear, a um reboot e a uma troca de runtime.
🧭 Novo aqui? Quatro palavras deste módulo
- Sessão — uma conversa contínua com o agente, do primeiro prompt até você fechar ou dar
/clear. Quando ela acaba, o agente esquece tudo. - Handoff — o arquivo Markdown que a sessão deixa escrito antes de morrer, com o estado do trabalho.
- Prime — o ato de mandar a sessão nova ler esse arquivo antes de tocar em qualquer coisa. "Primar" é carregar o contexto na largada.
- JSONL — o formato em que os runtimes gravam o histórico bruto das conversas, uma linha JSON por evento. É log de máquina, não é documento.
✓ Entra no handoff
- ✓Decisões aceitas, com o que foi descartado junto ("escolhemos X, abandonamos Y").
- ✓Tarefas inacabadas, com o ponto exato em que pararam.
- ✓Caminhos de arquivo absolutos ou relativos à raiz do projeto, nunca "aquele script".
- ✓Checks rodados com o resultado: passou, falhou ou não rodado.
- ✓Perguntas abertas que dependem do dono humano responder.
✗ Fica de fora
- ✗Narrativa da sessão ("primeiro tentei isso, depois aquilo"). O próximo agente não precisa da viagem.
- ✗Buscas que falharam, caminhos descartados, ruído de exploração.
- ✗Credenciais, tokens, chaves de API — nunca, em hipótese alguma.
- ✗Promessa de que algo não commitado "está disponível em outro worktree".
- ✗Falha não resolvida apagada para o handoff parecer limpo.
Conceitos-chave
Bilhete estruturado da sessão que fecha para a sessão que abre.
Uma futura instância do agente, não um gerente. Escreva para quem vai executar.
Decisões, pendências, próximos passos, caminhos, checks com resultado.
Erro não resolvido continua no handoff até alguém resolver de verdade.
📄 O template de handoffs/latest.md
O kit resolve a questão do formato com um template de sete seções em template/handoffs/latest.md. Ele é propositalmente vazio: a estabilidade da estrutura é o valor. Se toda sessão escreve nas mesmas sete seções, na mesma ordem, o agente que lê sabe onde procurar sem interpretar nada. Quando uma seção não tem o que dizer, você escreve "nenhuma" — nunca apaga a seção.
Objetivo: criar a pasta de handoffs do seu projeto a partir do template do kit.
mkdir -p ~/projetos/<seu-projeto>/handoffs
cp ~/projetos/agente-claude-codex/template/handoffs/latest.md \
~/projetos/<seu-projeto>/handoffs/latest.md
cat ~/projetos/<seu-projeto>/handoffs/latest.md
# → # Handoff — AAAA-MM-DD
# ## Projeto e escopo
# ## Objetivo atual
# ## Estado aceito
# ## Arquivos alterados
# ## Checks rodados e resultado (passou / falhou / não rodado)
# ## Perguntas abertas
# ## Próxima ação exataComo verificar: o cat mostra as sete seções e nada mais. Troque <seu-projeto> pela pasta real. Se o seu projeto já tem handoffs/latest.md, não sobrescreva: compare os títulos das seções e acrescente as que faltarem.
O template sozinho não ensina muito. O que ensina é ver o arquivo preenchido de verdade. Abaixo está o handoffs/latest.md real do kit, escrito ao final da sessão de 13 de setembro de 2026 — a mesma sessão cujo readback você estudou no módulo anterior. Repare no que ele faz e no que ele não faz: nenhuma frase sobre como a sessão foi, todas as seções presentes, dois checks marcados como não rodado, e uma próxima ação que é literalmente um comando colável.
Arquivo real: handoffs/latest.md do kit (trecho, com as seções na ordem do template).
# Handoff — 2026-09-13
## Projeto e escopo
agente-claude-codex: kit de migração / workspace agnóstico. Escopo desta
sessão: criar o repo, plano, prompts, scripts, template e primeira evidência.
## Objetivo atual
Ver tasks/current.md: validar piloto (session-handoff no Codex + readback
nos dois runtimes).
## Estado aceito
Repo criado, 2 commits, branch main, sem remote. Auditoria rodada
(relatorios/auditoria-2026-09-13.md). Readback aprovado no Codex e no Claude.
Nada em ~/.claude ou ~/.codex alterado.
## Arquivos alterados
PLANO.md, README.md, AGENTS.md, CLAUDE.md, prompts/*, scripts/*, template/*,
context/*, tasks/current.md, .gitignore, este arquivo.
## Checks rodados e resultado
- scripts/audit.sh — passou (89 skills só no Claude).
- template/scripts/check.sh — passou.
- scripts/readback-test.sh . codex — passou na 2ª rodada.
- scripts/sync-skills.sh — não rodado (aguarda escolha do piloto).
- Cópia isolada + check.sh — não rodado.
## Perguntas abertas
- Qual projeto real é o piloto? (default: este repo)
- Publicar em inematds/agente-claude-codex?
## Próxima ação exata
`scripts/sync-skills.sh import session-handoff && scripts/sync-skills.sh build`,
depois `install session-handoff --codex` e `drift`.Como verificar o seu: leia só a última seção e pergunte "eu conseguiria executar isso agora, sem abrir mais nada?". Se a resposta for não, a seção está escrita como intenção ("continuar a migração") e não como ação ("rodar tal comando em tal pasta").
💡 Dica prática: por que o arquivo se chama latest
O nome fixo é o que torna o prime automatizável. Você pode guardar um histórico datado ao lado (handoffs/2026-09-13.md), mas latest.md tem que apontar sempre para o mais recente, porque é esse nome que entra no prompt de prime, nos scripts e no AGENTS.md. Nome variável obriga o agente a adivinhar qual arquivo ler — e adivinhar é exatamente o que o núcleo portátil existe para eliminar.
Conceitos-chave
Escopo, objetivo, estado aceito, arquivos, checks, perguntas, próxima ação.
Seção vazia vira "nenhuma"; nunca se apaga uma seção.
Nome fixo, conteúdo mais recente. É o que o prime procura.
Comando colável, não intenção. É a seção que mais economiza tempo.
🚀 Prime: a nova sessão lê antes de agir
Escrever o handoff é metade do ciclo. A outra metade é garantir que alguém leia. Um agente novo, deixado à própria sorte, começa a agir: abre arquivos aleatórios, deduz o objetivo pelo README, propõe uma refatoração que ninguém pediu. O prime inverte a ordem — primeiro ler, depois falar, só então agir. É uma mudança de uma frase no seu primeiro prompt do dia, e é a diferença entre retomar o trabalho e recomeçá-lo.
Objetivo: abrir o dia em qualquer runtime sem o agente sair executando. Cole este texto como primeira mensagem da sessão, dentro da pasta do projeto.
Leia handoffs/latest.md e tasks/current.md antes de agir e me diga a próxima
ação exata, citando o arquivo.Como verificar: a resposta é curta, nomeia os dois arquivos e devolve uma ação, não um plano. Se o agente responder com uma proposta de refatoração, ou se não citar nenhum arquivo, ele não leu — e a primeira coisa a investigar é a ordem de leitura do AGENTS.md, não o prompt.
Repare em cada pedaço da frase, porque cada um está lá por um motivo. "Leia … antes de agir" bloqueia a edição prematura. "a próxima ação exata" pede uma coisa só, executável, e não um roteiro de dez passos. "citando o arquivo" é o mesmo truque do readback: obriga o agente a mostrar a fonte, o que torna a mentira visível. Dois arquivos, uma ação, uma citação — é o prime inteiro.
Você abre a sessão na pasta do projeto
Sem isso o agente lê os arquivos de outro lugar, ou de lugar nenhum. A pasta é o escopo.
Cola o prompt de prime
Uma frase. O agente lê handoffs/latest.md e tasks/current.md e nada é modificado ainda.
Ele devolve a próxima ação, citando a fonte
Você compara com o que lembra. Bateu, segue. Não bateu, o handoff está desatualizado — corrija o arquivo antes de trabalhar.
Só então você autoriza a execução
O trabalho do dia começa com o contexto carregado e alinhado, não com uma suposição.
No fim do dia, o handoff fecha o ciclo
A sessão reescreve handoffs/latest.md e a roda volta ao começo, com o estado atualizado.
📋 Prime e readback não são a mesma coisa
O readback é um teste: você roda de vez em quando, com cinco perguntas, para provar que o núcleo funciona, e não deixa o agente editar nada. O prime é rotina: você roda todo dia, com uma pergunta, para carregar o contexto e começar a trabalhar. Mesmo princípio — ler os arquivos e citar a fonte — em duas doses diferentes.
Conceitos-chave
Carregar o contexto do arquivo na largada da sessão, antes de qualquer ação.
Trava a edição prematura, que é o erro mais comum de sessão nova.
Pedir "a próxima ação exata" evita roteiros especulativos.
Se a resposta não bate com sua memória, o handoff envelheceu. Corrija o arquivo.
🔀 Cross-runtime: Claude escreve, Codex retoma
Aqui o ciclo diário paga a promessa do curso inteiro. Como o handoff é um arquivo Markdown na pasta do projeto, e não um estado interno de um runtime, quem escreve e quem lê não precisam ser o mesmo programa. Você fecha a tarde no Claude, abre a noite no Codex, e o trabalho continua. Ou o contrário. O arquivo é o ponto de encontro; os executores se revezam ao redor dele.
Setas azuis e cianas convergem no mesmo arquivo: handoffs/latest.md é a única coisa compartilhada. Embaixo, o caminho cortado mostra o que não atravessa: os históricos JSONL de cada runtime são ilhas, e é por isso que o Markdown existe.
Objetivo: provar o revezamento na prática — primar o Claude e o Codex contra o mesmo handoff e comparar as respostas.
cd ~/projetos/<seu-projeto>
claude -p "Leia handoffs/latest.md e tasks/current.md antes de agir e me diga \
a próxima ação exata, citando o arquivo."
codex exec --skip-git-repo-check "Leia handoffs/latest.md e tasks/current.md \
antes de agir e me diga a próxima ação exata, citando o arquivo."Como verificar: as duas respostas apontam a mesma próxima ação e citam os mesmos arquivos. Divergência de estilo é normal e esperada; divergência de conteúdo significa que o handoff está ambíguo, e a correção é no arquivo, não no prompt. O --skip-git-repo-check evita que o Codex se recuse a rodar quando a pasta não é um repositório git.
✓ Atravessa os runtimes
- ✓
handoffs/latest.md— texto puro, lido por qualquer agente. - ✓
tasks/current.mdecontext/decisions/— mesmo princípio. - ✓
AGENTS.md, que os dois runtimes tratam como instrução do projeto. - ✓O prompt de prime, que é uma frase e não depende de comando embutido.
✗ Não atravessa
- ✗O histórico JSONL de cada runtime, que fica na home e é ilegível para o outro.
- ✗O comando
/handoffem si: o gesto muda, o arquivo produzido é o mesmo. - ✗Memória de sessão, contexto carregado, "a gente combinou ontem".
- ✗Estado de ferramentas do harness (processos em background, servidores abertos).
Conceitos-chave
Um escreve, o outro retoma, nos dois sentidos, pelo mesmo arquivo.
O Markdown do projeto, não o runtime nem a conta.
Deixa o codex exec rodar em pasta que não é repositório git.
Sintoma de handoff ambíguo. Conserta-se o arquivo, não o agente.
🗃️ Sessões JSONL são histórico, não fonte
Os dois runtimes gravam tudo o que acontece numa sessão em arquivos JSONL — uma linha JSON por evento — dentro da sua home. É um registro fiel e completo, e é justamente por isso que ele não serve como memória de trabalho: ele guarda tudo, inclusive o que deu errado, o que foi descartado e o que você mudou de ideia três vezes. Um handoff de vinte linhas curadas vale mais que trezentos megabytes de transcrição fiel.
Objetivo: ver com os próprios olhos o tamanho do histórico bruto na sua máquina, e onde ele mora em cada runtime.
find ~/.claude/projects -name '*.jsonl' | wc -l
du -sh ~/.claude/projects
find ~/.codex/sessions -name '*.jsonl' | wc -l
du -sh ~/.codex/sessions
# nesta máquina, em 14/09/2026:
# Claude: 6.859 arquivos .jsonl · 2,3 GB
# Codex: 209 arquivos .jsonl · 601 MBComo verificar: os números da sua máquina vão ser outros, e não importa quais sejam — o que importa é notar que são dois acervos, em pastas diferentes, e que nenhum runtime lê o do outro. Se o caminho não existir, o runtime não está instalado ou guarda em outro lugar; nenhum dos dois casos muda a conclusão.
É tentador pensar em ferramentas que leiam esse histórico e reconstruam o contexto automaticamente. Elas existem, e são úteis para auditoria e para análise de comportamento. Mas repare no que acontece quando você depende delas: o contexto do projeto passa a morar num formato proprietário, dentro da home de uma conta, preso a um runtime. É exatamente a dependência que o curso inteiro está desmontando. O JSONL é a caixa-preta do voo; o handoff é o plano de voo do próximo.
✓ Para que o JSONL serve
- ✓Auditar o que realmente aconteceu quando algo deu muito errado.
- ✓Recuperar um trecho específico que você esqueceu de registrar no handoff.
- ✓Analisar padrões de comportamento do modelo ao longo de muitas sessões.
- ✓Prova forense de que um check foi executado numa data.
✗ Para que não serve
- ✗Ser a fonte de verdade do projeto: mora na home, não na pasta do trabalho.
- ✗Passar contexto entre runtimes: o formato e o caminho são de cada um.
- ✗Ser lido por um humano: gigabytes de eventos, sem curadoria.
- ✗Entrar no git do projeto: tem ruído, tamanho e, às vezes, segredo.
Repare: a diferença entre 6.859 e 209 arquivos não diz que um runtime é melhor. Diz que o acervo de histórico cresce com o uso e é totalmente local a cada ferramenta. Quem apostou a memória do trabalho nesse acervo fica preso ao runtime que o produziu — e recomeça do zero ao trocar de ferramenta, de máquina ou de conta.
Conceitos-chave
Uma linha JSON por evento. Log de máquina, fiel e volumoso.
Registro do que houve, não declaração do que vale agora.
O que mora na home não viaja com o repositório.
Vinte linhas escolhidas valem mais que gigabytes de transcrição.
🏅 Regra de ouro: handoff antes de fechar, sempre
Uma regra só, e ela não tem exceção: nenhuma sessão fecha sem handoff escrito. Nem a sessão de cinco minutos, nem a que "não mudou nada", nem a que terminou no meio de um comando. A sessão curta é justamente a que você vai esquecer, e a interrompida é a que mais precisa do bilhete. O custo é um minuto; o custo de não fazer é a meia hora que a próxima sessão gasta redescobrindo onde estava.
Para escrever esse handoff sem depender de disciplina sua, existe um prompt pronto na prompt library do kit, guardado em prompts/03-readback-handoff.md sob o título "Continuation handoff". Ele é o par exato do readback que você viu no módulo 2.5: aquele lê e prova, este escreve e preserva. Note as proibições no meio do texto — elas estão ali porque são os três jeitos mais comuns de um handoff mentir.
Objetivo: mandar a sessão que está acabando escrever o próprio handoff. Cole como última mensagem, em qualquer runtime.
Create a concise continuation handoff for a fresh agent. Include the project and scope,
current objective, accepted state, changed files, checks actually run and their results, open
questions, and exact next action. Cite source paths and relevant revisions. Preserve
unresolved failures. Do not include credentials or claim that uncommitted changes are
available in another worktree. Update the current task/state only where the evidence
supports it.Como verificar: a saída cobre as sete seções do template, cita caminhos de arquivo reais, mantém as falhas não resolvidas e termina com um comando executável. Salve em handoffs/latest.md e releia: se alguma seção descreve a conversa em vez do estado, reescreva aquela seção na mão antes de fechar.
"Preserve unresolved failures"
A falha que não foi resolvida continua no handoff. Handoff limpo demais é handoff que apagou o problema.
"Do not include credentials"
O handoff costuma ir para o git. Chave de API em Markdown versionado é vazamento, não contexto.
"Checks actually run"
Os três estados do módulo 2.5 entram aqui: passou, falhou ou não rodado. Nada de "deve estar funcionando".
"Only where the evidence supports it"
O agente atualiza tasks/current.md até onde a evidência alcança, e para. O resto vira pergunta aberta.
⚠️ O erro a evitar
Fechar a sessão pensando "amanhã eu lembro". Amanhã você lembra da metade, e o agente não lembra de nada — a memória dele acabou no instante em que a sessão fechou. O handoff não é para você: é para o executor que vai chegar sem nenhum contexto, seja ele Claude, Codex ou o terceiro runtime que ainda nem existe.
Conceitos-chave
Sessão curta, sessão interrompida, sessão "sem novidade": todas escrevem.
Prompt pronto em prompts/03-readback-handoff.md. Par do readback.
O arquivo vai para o git; segredo nunca entra nele.
Atualize o estado só até onde houver prova; o resto é pergunta aberta.
Auto-checagem (opcional): você trabalhou a tarde no Claude e quer continuar à noite no Codex. O que precisa atravessar para o trabalho continuar?
🎯 Resumo do módulo
handoffs/latest.md com nome fixo, estrutura estável e próxima ação exata como comando colável.Próximo:
Trilha 3 · Projeto 3.1 — migrar seu primeiro projeto real