La nota de 40 líneas que deja a una sesión nueva de Claude Code seguir donde se quedó la anterior

Cierras una sesión un jueves por la noche con un test todavía en rojo. El viernes abres otra y escribes «continúa». No sabe que había un test, ni que ya probaste la solución obvia, ni que una carpeta no se toca.

El consejo habitual es «lleva un archivo de notas». Funciona hasta que el archivo es un muro de texto escrito de memoria a las once de la noche. Lo que nos ayudó fue hacer la nota pequeña, con forma fija y comprobable.

Seis apartados, menos de 40 líneas

Al final de la sesión escribimos un HANDOFF.md con estos apartados exactos:

• Hecho: hasta cinco puntos, cada uno comprobable («añadido parse.py, los tests pasan»).
• Sin hacer: lo que queda, por orden.
• Decisiones: cada una con su motivo, en una línea. El motivo es lo primero que se pierde.
• Archivos tocados: rutas reales, sacadas de git status, no de memoria.
• Primer comando: el comando que la sesión siguiente ejecuta antes que nada.
• No tocar: archivos o acciones que deben quedar como están, y por qué.

Si pasa de 40 líneas, recorta «Hecho» primero. La sesión siguiente puede leer el código; no puede leerte la cabeza.

Dos reglas para poder fiarse de la nota

Saca los hechos con comandos. git status --short y git log --oneline -5 dicen qué cambió. Si escribes la lista de archivos de memoria, fallará en uno, y la sesión siguiente se lo creerá.

Comprueba la nota antes de cerrar. Confirma que cada ruta existe, ejecuta tú el «Primer comando» y escribe el resultado en la última línea. Un relevo que dice «los tests pasan» cuando no pasan es peor que no tener relevo.

Cómo queda

# Relevo 2026-10-29 17:40
Hecho
- export.py escribe CSV; pasan 6 de 7 tests
Sin hacer
1. Arreglar test_unicode_names (falla con "Zoë")
2. Añadir la opción --out a cli.py
Decisiones
- Módulo csv y no pandas: sin dependencia nueva para 30 líneas
Archivos tocados
- export.py (nuevo), tests/test_export.py (nuevo), cli.py (solo lectura)
Primer comando
- pytest tests/test_export.py -x
No tocar
- legacy/old_export.py: lo usa el proceso nocturno
Comprobado: pytest tests/test_export.py -x -> 1 fallo, 6 bien

A la mañana siguiente, la sesión nueva lo lee, ejecuta el primer comando, ve el mismo fallo y empieza por el problema de Unicode.

Como skill

Lo convertimos en una skill de texto llano para no repetir las instrucciones: session-handoff (los textos están en inglés), un SKILL.md que se lee en un minuto y un WHY.md corto. Licencia MIT, gratis para copiar en ~/.claude/skills/.

Con honestidad

La probamos a mano en nuestros propios proyectos. No la hemos medido con los flujos de otras personas, así que no prometemos que te ahorre tiempo. No sustituye a buenos mensajes de commit ni a un README.

Mira también: Flujos de cada día: retomar, plan, worktrees · Sesiones de Claude Code: reanudar, nombrar, ramificar.