🔁 Handoff y prime: el ciclo diario
El readback prueba que el núcleo funciona una vez. El ciclo diario es lo que lo mantiene funcionando todos los días: sesión → handoff → Markdown → prime → nueva sesión. En este módulo escribes el handoff, armas el latest.md, aprendes el prompt de prime y haces que Claude y Codex se turnen en el mismo trabajo sin perder nada en el camino.
📦 Qué va en un handoff
El handoff es la nota que la sesión que está terminando le deja a la sesión que todavía no empezó. No es un informe para humanos, no es un changelog y no es un resumen bonito: es la información mínima que permite que un agente sin ninguna memoria retome el trabajo en el punto exacto donde lo dejaste. El criterio es brutalmente simple: si el próximo agente necesita preguntar algo para empezar, al handoff le faltó algo.
El flujo que describe la documentación del kit tiene cinco elementos obligatorios, y surgieron de la práctica, no de la teoría: decisiones tomadas, tareas inconclusas, próximos pasos, rutas de archivos y checks ejecutados con su resultado. Los cuatro primeros son lo que el comando /handoff busca en una sesión; el quinto es lo que el módulo 2.5 enseñó a producir y es lo que impide que el próximo agente celebre una migración que nadie probó.
El ciclo gira siempre en el mismo sentido: la sesión que cierra produce un archivo, y la sesión que abre lee ese archivo. Ninguna flecha pasa por dentro del chat: por eso el ciclo sobrevive a un /clear, a un reinicio y a un cambio de runtime.
🧭 ¿Eres nuevo aquí? Cuatro palabras de este módulo
- Sesión — una conversación continua con el agente, desde el primer prompt hasta que la cierras o ejecutas
/clear. Cuando termina, el agente lo olvida todo. - Handoff — el archivo Markdown que la sesión deja escrito antes de morir, con el estado del trabajo.
- Prime — el acto de pedirle a la sesión nueva que lea ese archivo antes de tocar cualquier cosa. "Primar" es cargar el contexto en la largada.
- JSONL — el formato en que los runtimes guardan el historial bruto de las conversaciones, una línea JSON por evento. Es un log de máquina, no un documento.
✓ Entra en el handoff
- ✓Decisiones aceptadas, junto con lo que se descartó ("elegimos X, abandonamos Y").
- ✓Tareas inconclusas, con el punto exacto en que se detuvieron.
- ✓Rutas de archivo absolutas o relativas a la raíz del proyecto, nunca "aquel script".
- ✓Checks ejecutados con su resultado: pasó, falló o no ejecutado.
- ✓Preguntas abiertas que dependen de la respuesta del dueño humano.
✗ Queda fuera
- ✗Narrativa de la sesión ("primero intenté esto, después aquello"). El próximo agente no necesita el viaje.
- ✗Búsquedas que fallaron, caminos descartados, ruido de exploración.
- ✗Credenciales, tokens, claves de API — nunca, bajo ninguna circunstancia.
- ✗La promesa de que algo sin commit "está disponible en otro worktree".
- ✗Una falla no resuelta borrada para que el handoff parezca limpio.
Conceptos clave
Nota estructurada de la sesión que cierra para la sesión que abre.
Una futura instancia del agente, no un gerente. Escribe para quien va a ejecutar.
Decisiones, pendientes, próximos pasos, rutas, checks con resultado.
Un error no resuelto sigue en el handoff hasta que alguien lo resuelva de verdad.
📄 La plantilla de handoffs/latest.md
El kit resuelve la cuestión del formato con una plantilla de siete secciones en template/handoffs/latest.md. Está vacía a propósito: la estabilidad de la estructura es el valor. Si cada sesión escribe en las mismas siete secciones, en el mismo orden, el agente que lee sabe dónde buscar sin interpretar nada. Cuando una sección no tiene nada que decir, escribes "ninguna" — nunca borras la sección.
Objetivo: crear la carpeta de handoffs de tu proyecto a partir de la plantilla del 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 exataCómo verificar: el cat muestra las siete secciones y nada más. Cambia <seu-projeto> por la carpeta real. Si tu proyecto ya tiene handoffs/latest.md, no lo sobrescribas: compara los títulos de las secciones y agrega las que falten.
La plantilla sola no enseña mucho. Lo que enseña es ver el archivo llenado de verdad. Abajo está el handoffs/latest.md real del kit, escrito al final de la sesión del 13 de septiembre de 2026 — la misma sesión cuyo readback estudiaste en el módulo anterior. Fíjate en lo que hace y en lo que no hace: ninguna frase sobre cómo fue la sesión, todas las secciones presentes, dos checks marcados como no ejecutados y una próxima acción que es literalmente un comando para copiar y pegar.
Archivo real: handoffs/latest.md del kit (fragmento, con las secciones en el orden de la plantilla).
# 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`.Cómo verificar el tuyo: lee solo la última sección y pregúntate "¿podría ejecutar esto ahora, sin abrir nada más?". Si la respuesta es no, la sección está escrita como intención ("continuar la migración") y no como acción ("ejecutar tal comando en tal carpeta").
💡 Consejo práctico: por qué el archivo se llama latest
El nombre fijo es lo que vuelve automatizable el prime. Puedes guardar un historial fechado al lado (handoffs/2026-09-13.md), pero latest.md tiene que apuntar siempre al más reciente, porque ese es el nombre que entra en el prompt de prime, en los scripts y en el AGENTS.md. Un nombre variable obliga al agente a adivinar qué archivo leer, y adivinar es justamente lo que el núcleo portátil existe para eliminar.
Conceptos clave
Alcance, objetivo, estado aceptado, archivos, checks, preguntas, próxima acción.
Una sección vacía se vuelve "ninguna"; nunca se borra una sección.
Nombre fijo, contenido más reciente. Es lo que busca el prime.
Un comando para pegar, no una intención. Es la sección que más tiempo ahorra.
🚀 Prime: la nueva sesión lee antes de actuar
Escribir el handoff es la mitad del ciclo. La otra mitad es asegurarse de que alguien lo lea. Un agente nuevo, librado a su suerte, empieza a actuar: abre archivos al azar, deduce el objetivo por el README, propone una refactorización que nadie pidió. El prime invierte el orden: primero leer, luego hablar y solo entonces actuar. Es un cambio de una frase en tu primer prompt del día, y es la diferencia entre retomar el trabajo y empezarlo de nuevo.
Objetivo: abrir el día en cualquier runtime sin que el agente salga a ejecutar cosas. Pega este texto como primer mensaje de la sesión, dentro de la carpeta del proyecto.
Lee handoffs/latest.md y tasks/current.md antes de actuar y dime la próxima
acción exacta, citando el archivo.Cómo verificar: la respuesta es corta, nombra los dos archivos y devuelve una acción, no un plan. Si el agente responde con una propuesta de refactorización, o si no cita ningún archivo, no leyó; y lo primero que hay que investigar es el orden de lectura del AGENTS.md, no el prompt.
Fíjate en cada parte de la frase, porque cada una está ahí por una razón. "Lee … antes de actuar" bloquea la edición prematura. "la próxima acción exacta" pide una sola cosa, ejecutable, y no un guion de diez pasos. "citando el archivo" es el mismo truco del readback: obliga al agente a mostrar la fuente, lo que hace visible la mentira. Dos archivos, una acción, una cita: ese es el prime completo.
Abres la sesión en la carpeta del proyecto
Sin eso, el agente lee los archivos de otro lugar, o de ninguno. La carpeta es el alcance.
Pegas el prompt de prime
Una frase. El agente lee handoffs/latest.md y tasks/current.md y todavía no se modifica nada.
Te devuelve la próxima acción, citando la fuente
Lo comparas con lo que recuerdas. Si coincide, sigues. Si no coincide, el handoff está desactualizado: corrige el archivo antes de trabajar.
Solo entonces autorizas la ejecución
El trabajo del día empieza con el contexto cargado y alineado, no con una suposición.
Al final del día, el handoff cierra el ciclo
La sesión reescribe handoffs/latest.md y la rueda vuelve al comienzo, con el estado actualizado.
📋 Prime y readback no son lo mismo
El readback es una prueba: lo ejecutas de vez en cuando, con cinco preguntas, para demostrar que el núcleo funciona, y no dejas que el agente edite nada. El prime es rutina: lo ejecutas todos los días, con una pregunta, para cargar el contexto y empezar a trabajar. El mismo principio (leer los archivos y citar la fuente) en dos dosis diferentes.
Conceptos clave
Cargar el contexto desde el archivo al arrancar la sesión, antes de cualquier acción.
Frena la edición prematura, que es el error más común de una sesión nueva.
Pedir "la próxima acción exacta" evita guiones especulativos.
Si la respuesta no coincide con tu memoria, el handoff envejeció. Corrige el archivo.
🔀 Cross-runtime: Claude escribe, Codex retoma
Aquí el ciclo diario cumple la promesa de todo el curso. Como el handoff es un archivo Markdown en la carpeta del proyecto, y no un estado interno de un runtime, quien escribe y quien lee no tienen que ser el mismo programa. Cierras la tarde en Claude, abres la noche en Codex y el trabajo continúa. O al revés. El archivo es el punto de encuentro; los ejecutores se turnan a su alrededor.
Las flechas azules y cian convergen en el mismo archivo: handoffs/latest.md es lo único compartido. Abajo, el camino cortado muestra lo que no cruza: los historiales JSONL de cada runtime son islas, y por eso existe el Markdown.
Objetivo: comprobar el relevo en la práctica: hacer prime a Claude y a Codex con el mismo handoff y comparar las respuestas.
cd ~/projetos/<tu-proyecto>
claude -p "Lee handoffs/latest.md y tasks/current.md antes de actuar y dime \
la próxima acción exacta, citando el archivo."
codex exec --skip-git-repo-check "Lee handoffs/latest.md y tasks/current.md \
antes de actuar y dime la próxima acción exacta, citando el archivo."Cómo verificar: las dos respuestas señalan la misma próxima acción y citan los mismos archivos. Las diferencias de estilo son normales y esperables; una diferencia de contenido significa que el handoff es ambiguo, y la corrección va en el archivo, no en el prompt. El --skip-git-repo-check evita que Codex se niegue a ejecutarse cuando la carpeta no es un repositorio git.
✓ Cruza entre runtimes
- ✓
handoffs/latest.md: texto plano, legible por cualquier agente. - ✓
tasks/current.mdycontext/decisions/: el mismo principio. - ✓
AGENTS.md, que ambos runtimes tratan como instrucción del proyecto. - ✓El prompt de prime, que es una frase y no depende de un comando integrado.
✗ No cruza
- ✗El historial JSONL de cada runtime, que vive en la home y es ilegible para el otro.
- ✗El comando
/handoffen sí: el gesto cambia, el archivo producido es el mismo. - ✗Memoria de sesión, contexto cargado, "lo que acordamos ayer".
- ✗Estado de las herramientas del harness (procesos en segundo plano, servidores abiertos).
Conceptos clave
Uno escribe, el otro retoma, en ambos sentidos, a través del mismo archivo.
El Markdown del proyecto, no el runtime ni la cuenta.
Permite que codex exec se ejecute en una carpeta que no es repositorio git.
Síntoma de un handoff ambiguo. Se corrige el archivo, no el agente.
🗃️ Las sesiones JSONL son historial, no fuente
Ambos runtimes guardan todo lo que ocurre en una sesión en archivos JSONL (una línea JSON por evento) dentro de tu home. Es un registro fiel y completo, y justamente por eso no sirve como memoria de trabajo: lo guarda todo, incluso lo que salió mal, lo que se descartó y aquello en lo que cambiaste de opinión tres veces. Un handoff de veinte líneas curadas vale más que trescientos megabytes de transcripción fiel.
Objetivo: ver con tus propios ojos el tamaño del historial bruto en tu máquina, y dónde vive en cada runtime.
find ~/.claude/projects -name '*.jsonl' | wc -l
du -sh ~/.claude/projects
find ~/.codex/sessions -name '*.jsonl' | wc -l
du -sh ~/.codex/sessions
# en esta máquina, el 14/09/2026:
# Claude: 6.859 archivos .jsonl · 2,3 GB
# Codex: 209 archivos .jsonl · 601 MBCómo verificar: los números de tu máquina serán otros, y no importa cuáles sean: lo que importa es notar que son dos acervos, en carpetas distintas, y que ningún runtime lee el del otro. Si la ruta no existe, el runtime no está instalado o guarda en otro lugar; ninguno de los dos casos cambia la conclusión.
Es tentador pensar en herramientas que lean ese historial y reconstruyan el contexto automáticamente. Existen, y son útiles para auditoría y para análisis de comportamiento. Pero fíjate en lo que pasa cuando dependes de ellas: el contexto del proyecto pasa a vivir en un formato propietario, dentro de la home de una cuenta, atado a un runtime. Es exactamente la dependencia que todo el curso está desmontando. El JSONL es la caja negra del vuelo; el handoff es el plan de vuelo del siguiente.
✓ Para qué sirve el JSONL
- ✓Auditar lo que realmente ocurrió cuando algo salió muy mal.
- ✓Recuperar un fragmento específico que olvidaste registrar en el handoff.
- ✓Analizar patrones de comportamiento del modelo a lo largo de muchas sesiones.
- ✓Prueba forense de que un check se ejecutó en una fecha.
✗ Para qué no sirve
- ✗Ser la fuente de verdad del proyecto: vive en la home, no en la carpeta del trabajo.
- ✗Pasar contexto entre runtimes: el formato y la ruta son propios de cada uno.
- ✗Ser leído por un humano: gigabytes de eventos, sin curaduría.
- ✗Entrar en el git del proyecto: tiene ruido, tamaño y, a veces, secretos.
Fíjate: la diferencia entre 6.859 y 209 archivos no dice que un runtime sea mejor. Dice que el acervo de historial crece con el uso y es totalmente local a cada herramienta. Quien apostó la memoria del trabajo a ese acervo queda atado al runtime que lo produjo, y empieza de cero al cambiar de herramienta, de máquina o de cuenta.
Conceptos clave
Una línea JSON por evento. Log de máquina, fiel y voluminoso.
Registro de lo que pasó, no declaración de lo que vale ahora.
Lo que vive en la home no viaja con el repositorio.
Veinte líneas elegidas valen más que gigabytes de transcripción.
🏅 Regla de oro: handoff antes de cerrar, siempre
Una sola regla, y no tiene excepción: ninguna sesión se cierra sin handoff escrito. Ni la sesión de cinco minutos, ni la que "no cambió nada", ni la que terminó a mitad de un comando. La sesión corta es justamente la que vas a olvidar, y la interrumpida es la que más necesita la nota. El costo es un minuto; el costo de no hacerlo es la media hora que la próxima sesión pierde redescubriendo dónde estaba.
Para escribir ese handoff sin depender de tu disciplina, hay un prompt listo en la prompt library del kit, guardado en prompts/03-readback-handoff.md con el título "Continuation handoff". Es el par exacto del readback que viste en el módulo 2.5: aquel lee y prueba, este escribe y preserva. Fíjate en las prohibiciones en medio del texto: están ahí porque son las tres formas más comunes en que un handoff miente.
Objetivo: pedirle a la sesión que está terminando que escriba su propio handoff. Pégalo como último mensaje, en cualquier 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.Cómo verificar: la salida cubre las siete secciones de la plantilla, cita rutas de archivo reales, mantiene las fallas no resueltas y termina con un comando ejecutable. Guárdala en handoffs/latest.md y reléela: si alguna sección describe la conversación en lugar del estado, reescribe esa sección a mano antes de cerrar.
"Preserve unresolved failures"
La falla que no se resolvió sigue en el handoff. Un handoff demasiado limpio es un handoff que borró el problema.
"Do not include credentials"
El handoff suele ir a git. Una clave de API en Markdown versionado es una filtración, no contexto.
"Checks actually run"
Los tres estados del módulo 2.5 entran aquí: pasó, falló o no ejecutado. Nada de "debería estar funcionando".
"Only where the evidence supports it"
El agente actualiza tasks/current.md hasta donde llega la evidencia, y se detiene. El resto se vuelve pregunta abierta.
⚠️ El error a evitar
Cerrar la sesión pensando "mañana me acuerdo". Mañana recuerdas la mitad, y el agente no recuerda nada: su memoria terminó en el instante en que se cerró la sesión. El handoff no es para ti: es para el ejecutor que llegará sin ningún contexto, sea Claude, Codex o el tercer runtime que todavía ni existe.
Conceptos clave
Sesión corta, sesión interrumpida, sesión "sin novedad": todas escriben.
Prompt listo en prompts/03-readback-handoff.md. Par del readback.
El archivo va a git; un secreto nunca entra en él.
Actualiza el estado solo hasta donde haya prueba; el resto es pregunta abierta.
Autoevaluación (opcional): trabajaste la tarde en Claude y quieres continuar por la noche en Codex. ¿Qué tiene que pasar de un lado al otro para que el trabajo continúe?
🎯 Resumen del módulo
handoffs/latest.md con nombre fijo, estructura estable y próxima acción exacta como comando listo para pegar.Siguiente:
Ruta 3 · Proyecto 3.1 — migrar tu primer proyecto real