HANDOFF.md: que la IA no pierda el hilo entre sesiones

Cuando un proyecto con IA dura días o semanas, se acumulan cosas que el código no cuenta: por qué se eligió una solución, qué se probó y no funcionó, qué falta y qué no hay que tocar. Un HANDOFF.md (un «relevo» en Markdown) guarda ese estado para que otra sesión, otro agente u otra persona siga donde lo dejaste, sin repetir la investigación ni reabrir decisiones.

1. Sesión A
2. Estado comprobado en HANDOFF.md
3. Sesión B

HANDOFF.md no es un archivo especial de Claude Code: es una costumbre de documentación. Claude Code no lo lee solo por llamarse así; tienes que pedírselo.

Lo que ya hace Claude Code por ti

Cerrar una conversación ya no significa perderlo todo. Claude Code guarda las conversaciones en tu equipo, deja continuarlas, ponerles nombre, compactarlas y exportarlas, y tiene CLAUDE.md y memoria automática. El HANDOFF sigue siendo útil, pero para otras cosas:

• pasar el trabajo a otro agente, a otro modelo o a otra persona;
• cambiar de ordenador, o del terminal a la web;
• empezar a propósito una sesión limpia;
• dejar el estado del proyecto por escrito, junto al código.

Cada archivo, para una cosa

• La sesión de Claude Code: qué pasó en esa conversación. Se guarda en tu equipo.
• HANDOFF.md: dónde está el trabajo ahora y qué toca después. Cambia a menudo.
• CLAUDE.md: las reglas que Claude debe seguir siempre en ese proyecto. Este sí lo carga Claude Code al empezar.
• Memoria automática: lo que Claude aprende de tus preferencias. Es local, de ese proyecto y ese equipo.
• PROJECT_SPEC.md: qué producto estamos construyendo.
• DECISIONS.md: las decisiones duraderas y por qué.
• BACKLOG.md: lo que dejamos para más adelante.
• README.md: cómo se instala y se usa.

Un ejemplo de la diferencia: en CLAUDE.md, «ejecuta npm test antes de dar por terminado un cambio del servidor»; en HANDOFF.md, «los tests del servidor pasan; falta probar el inicio de sesión de principio a fin».

No metas en CLAUDE.md el estado de cada sesión: crece, gasta contexto y Claude le hace menos caso. Mantenlo corto (la documentación oficial habla de menos de unas 200 líneas).

Cuándo usarlo

Sí, cuando cambias de agente, de persona, de máquina o de entorno; cuando quieres empezar limpio; al cerrar una fase; o cuando hay un bloqueo o una decisión que el siguiente tiene que conocer.

No hace falta para una pausa corta en la misma sesión y el mismo equipo. Basta con continuar:

claude --continue
            claude --resume

--continue retoma la conversación más reciente de esa carpeta; --resume te deja elegir una.

La estructura

El mínimo útil son tres bloques:

# HANDOFF
            ## 1. Estado actual
            ## 2. Decisiones tomadas y motivos
            ## 3. Siguiente paso exacto

Para un proyecto de software de verdad, esta plantilla más completa:

# HANDOFF
            Última actualización: AAAA-MM-DD HH:MM

            ## 0. Resumen en una frase

            ## 1. Estado actual
            Terminado: …
            En progreso: …
            Pendiente: …
            Bloqueos: …

            ## 2. Contexto Git
            Rama: …   HEAD: …   Base: …   PR: …   Árbol de trabajo: …

            ## 3. Cambios de esta sesión
            Archivos modificados y cambios principales.

            ## 4. Decisiones y motivos
            ### D-001 — Título
            Decisión: …  Motivo: …  Alternativas descartadas: …
            No reabrir salvo que: …

            ## 5. Intentos descartados
            Qué se probó, qué pasó y por qué se descartó.

            ## 6. Pruebas y verificación
            Ejecutado: …  Resultado: …  No verificado: …

            ## 7. Riesgos y límites

            ## 8. No tocar todavía

            ## 9. Siguiente paso exacto
            1. …
            Criterio de terminado: …

No rellenes campos con datos inventados. Si no hay PR, pon «PR: no existe». Si no has comprobado la integración continua, «CI: no comprobado».

Qué poner en cada parte

Estado actual: qué funciona, qué acaba de terminar, qué está a medias, qué falta y qué bloquea. Sin contar la historia por orden.

Decisiones, siempre con su porqué. «Usamos PostgreSQL» no sirve; esto sí:

Decisión: PostgreSQL como base de datos principal.
            Motivo: hay relaciones, restricciones y transacciones.
            Descartado: SQLite en producción.
            No reabrir salvo que: cambien los requisitos de despliegue.

Intentos descartados: solo los que podrían tentar al siguiente. Por ejemplo, «guardar el token en localStorage: descartado, agrava un posible XSS».

Git: consulta los datos, no los escribas de memoria.

git status --short --branch
            git rev-parse HEAD
            git log -1 --oneline
            git diff --stat

Pruebas: hechos, no impresiones. «Todo funciona» no vale; «go test ./...: PASS. De principio a fin: no ejecutado. CI: no comprobado», sí.

No tocar todavía: límites temporales y con motivo. Las reglas permanentes van en CLAUDE.md.

Siguiente paso: concreto, comprobable, limitado y en orden, con su criterio de terminado.

1. Añadir tres casos límite al test del ranking.
            2. Ejecutar solo esa suite; si pasa, la global.
            No tocar la interfaz.
            Terminado cuando: los tres casos nuevos y la suite global pasan.

Comprobarlo contra el repositorio

Un HANDOFF se queda viejo. Nunca vale más que el estado real. Por orden de confianza: el código actual, Git, las pruebas, la documentación vigente, el HANDOFF y, al final, lo que diga una conversación.

Si el HANDOFF dice un HEAD y Git dice otro, hay que pararse y averiguar qué pasó, no suponerlo.

Cerrar una sesión

Prepara el relevo de esta sesión.
            Primero comprueba el estado real: git status, rama, HEAD, último commit,
            pruebas relevantes y, si están disponibles, PR y CI.
            Después actualiza HANDOFF.md. Sin crónica, sin inventar datos,
            sin secretos y sin empezar ninguna tarea nueva.

Abrir una sesión nueva

Lee PROJECT_SPEC.md, CLAUDE.md y HANDOFF.md si existen.
            No modifiques nada todavía. Comprueba HANDOFF.md contra Git,
            los archivos y las pruebas. Después: resume dónde estamos,
            enumera las diferencias, di cuál es el siguiente paso y espera.
            No reabras decisiones ya tomadas sin pruebas nuevas.

Es mucho mejor que un simple «lee HANDOFF.md»: obliga a comprobar antes de tocar nada.

Las sesiones de Claude Code

• claude --continue (o -c): la conversación más reciente de esa carpeta.
• claude --resume (o -r): elegir una. Dentro de Claude Code, /resume.
• claude -n nombre: arrancar con un nombre, para encontrarla luego.
• claude --resume --fork-session: retomar una conversación como una copia nueva, para probar otro camino sin tocar la original.
• /compact: resumir la conversación para liberar contexto. Puedes decirle qué conservar: /compact Conserva las decisiones, los archivos modificados, las pruebas y el siguiente paso.
• /clear: empezar de cero entre tareas que no tienen que ver, o cuando la sesión está llena de intentos fallidos. Un contexto limpio suele rendir mejor.
• /export: guardar la conversación como texto. Revísala antes de compartirla: puede llevar rutas, resultados y datos internos. Y no sustituye a un buen HANDOFF.
• /context muestra qué ha cargado (por ejemplo, tu CLAUDE.md) y /memory, la memoria.

El historial del terminal, el de la app de escritorio, el de la web y el de VS Code son independientes. Y la memoria automática no viaja entre equipos. Para cambiar de uno a otro: repositorio al día, HANDOFF al día y documentación en el propio proyecto.

CLAUDE.md, en breve

Claude Code lo lee al empezar. Puede estar en la raíz del proyecto (./CLAUDE.md o ./.claude/CLAUDE.md), en ./CLAUDE.local.md para tus preferencias en ese proyecto, o en ~/.claude/CLAUDE.md para todos tus proyectos.

Pon ahí los comandos que no son obvios, las convenciones, las reglas de estilo, las decisiones de arquitectura estables y las trampas conocidas. No pongas el estado del día, listas enormes de archivos ni lo que Claude puede deducir leyendo el código.

Se pueden importar otros archivos con @ruta, pero importar el HANDOFF en cada sesión suele ser mala idea: gasta contexto y se queda viejo. Mejor pedir que lo lea al hacer el relevo.

Cómo organizar la documentación

Proyecto pequeño          Proyecto mediano
            ├── README.md             ├── README.md
            ├── PROJECT_SPEC.md       ├── PROJECT_SPEC.md
            ├── CLAUDE.md             ├── CLAUDE.md
            └── HANDOFF.md            ├── HANDOFF.md
                                      └── docs/
                                          ├── DECISIONS.md
                                          └── BACKLOG.md

No crees treinta documentos vacíos por adelantado.

Entre modelos o agentes: el HANDOFF es del proyecto, no del modelo. Nada de «Claude ya sabe que…»; escribe la decisión y su motivo, y marca lo que sea específico de una herramienta.

Secretos: nunca

Ni contraseñas, ni claves de API, ni tokens, ni cookies, ni claves SSH, ni frases semilla, ni credenciales de producción, ni enlaces con tokens. En vez de API_KEY=sk-…, escribe «la integración necesita la variable API_KEY; su valor no se guarda en el repositorio». Antes de cada commit, git diff -- HANDOFF.md.

Si un secreto ya llegó a un commit, borrarlo del archivo no basta: sigue en el historial. Hay que cambiarlo (rotarlo) y tratarlo como comprometido.

Errores frecuentes

• Creer que HANDOFF.md es una función oficial de Claude.
• Hacer un HANDOFF cuando bastaba con --continue.
• Meterlo todo en CLAUDE.md.
• Fiarse del HANDOFF sin comprobar Git y las pruebas.
• Escribir una crónica en vez de estado, decisiones, pruebas y siguiente paso.
• Inventar el HEAD o el estado de la integración continua.
• Guardar decisiones sin su porqué.
• Acumular meses de información vieja: se actualiza, no se apila. Git ya guarda el historial del archivo.
• Confundir los puntos de control de Claude Code con Git: no lo sustituyen.

Chuleta

• ¿Misma sesión y mismo equipo? claude --continue o --resume.
• ¿Otro agente, otro equipo u otro contexto? HANDOFF.md.
• Antes de cerrar: pruebas, git status, rama, HEAD, PR y CI, y actualizar el HANDOFF.
• Al abrir: leer, comprobar contra Git, ver diferencias, confirmar el siguiente paso y no tocar nada todavía.

Documentación oficial: sesiones, memoria y CLAUDE.md y buenas prácticas.