El diario progress.md

El diario que lo recuerda todo

Si el artesano olvida todo al despertar, la solución no es curarle la memoria: es que lleve un diario. Cada noche anota qué hizo y qué toca mañana. Por la mañana lo lee y sigue.

En un proyecto con agentes ese diario es un archivo en el repo, normalmente progress.md (o PROGRESS.md; la plantilla del curso lo llama claude-progress.md). Es el artefacto de continuidad más básico y el más útil.

Qué debe tener

Un buen diario responde cinco preguntas sin que nadie tenga que explicar nada:

• ¿En qué estado está el repo ahora mismo?
• ¿Qué está hecho?
• ¿Qué está a medias?
• ¿Qué problemas conocidos hay?
• ¿Cuál es el mejor siguiente paso?

Un ejemplo mínimo que puedes copiar:

# Progreso del proyecto

## Estado actual
- Último commit: abc1234 (añade endpoint de preferencias)
- Pruebas: 42 de 43 pasan (falla test_paginacion_vacia)
- Lint: pasa

## Hecho
- [x] Modelo de usuario y migración
- [x] CRUD básico
- [x] Middleware de autenticación

## En curso
- [ ] Paginación (90 %, falla el caso de resultados vacíos)

## Problemas conocidos
- test_paginacion_vacia devuelve 500 si no hay resultados

## Siguientes pasos
1. Arreglar el caso de resultados vacíos
2. Añadir parámetro «incluir borrados»
3. Actualizar la documentación de la API

Fíjate en que cada línea es comprobable: un commit concreto, un test concreto, un error concreto. Compáralo con «casi terminado, algún fallo»: eso no le dice nada a nadie.

La versión de plantilla: un registro por sesión

La plantilla que acompaña al curso añade una estructura útil: arriba, un bloque de estado verificado actual (cómo arrancar, cómo verificar, la función inacabada más prioritaria, el bloqueo actual) y debajo un registro de sesiones, una entrada por sesión con estos campos:

La diferencia entre «hecho» y «verificado» es la clave. Anotar «completado: login» sin decir cómo se comprobó es contar una impresión, no un hecho.

Un compañero: el registro de decisiones

Junto al progreso conviene un DECISIONS.md corto: qué se decidió, por qué y qué se descartó. Tres líneas por decisión bastan.

## Caché de preferencias en Redis
- Motivo: se lee en cada petición y los datos son pequeños
- Descartado: vista materializada (cambia demasiado, mantenerla no compensa)
- Restricción: caducidad de 5 minutos

Esto evita que la sesión siguiente «descubra» que la opción descartada era mejor y derribe la pared de ayer.

El diario cuenta el estado; el traspaso entre sesiones tiene su propio formato, lo vemos en el handoff.