docs: [TESIS-000] require full real timestamps for new migrations

[LauAubert]

Ticket de Jira

N/A — sin card asociada (TESIS-000).

---

Descripción

Agrega a CLAUDE.md una regla obligatoria para que cualquier persona o agente que cree una migración use el timestamp completo y real (YYYYMMDDHHMMSS), generado con bin/rails generate migration o date -u +%Y%m%d%H%M%S.

Hoy casi todas las migraciones tienen timestamps escritos a mano y redondeados (...120000, ...000000). Revisé master, todas las ramas remotas y las locales: no hay versiones duplicadas, nombres de clase repetidos ni dependencias fuera de orden. Pero ese patrón hace muy probable que dos ramas elijan el mismo número, lo que termina en DuplicateMigrationVersionError o en una migración marcada como corrida sin haberse aplicado.

• Regla en la sección "1. Migración" de CLAUDE.md
• Comando para chequear duplicados antes de pushear
• Aclaración de no renombrar migraciones ya mergeadas (se volverían a correr)

No se renombra ninguna migración existente.

---

Evidencia visual

N/A

---

Cómo probar

1. Leer la sección "1. Migración" de CLAUDE.md.
2. Correr ls db/migrate | cut -c1-14 | sort | uniq -d: tiene que salir vacío.

---

Impacto y consideraciones

¿Introduce breaking changes?
No

¿Requiere nuevas variables de entorno?
No

¿Afecta la arquitectura o genera un nuevo patrón?
No, es solo documentación.

---

🤖 Generated with Claude Code

[TomasMartin2004]

Revisión — TESIS-000 (PR #92) · Regla del timestamp de las migraciones

Trece líneas de documentación que nacen del choque real de anteayer, cuando api#89 y api#90 eligieron los dos 20260924120000 y el segundo dejaba a master sin poder migrar. La regla es la correcta y está bien explicada: el problema no es sólo el error ruidoso, es el caso silencioso que mencionás —una migración marcada como corrida sin haberse aplicado—, que es el que cuesta días encontrar.

✅ Verifiqué las tres afirmaciones

«Casi todas tienen timestamps redondeados»: cierto, y peor de lo que suena. De 31 migraciones, 22 tienen minutos y segundos en cero, y el patrón dominante es literalmente 120000:

20260921 12:00:00
20260921 13:00:00
20260924 12:00:00
20260925 12:00:00

Con ese patrón, dos ramas del mismo día chocan salvo que alguien se acuerde de mover la hora a mano. No es «poco probable»: ya pasó.

«No hay duplicados»: confirmado en master (0) y también crucé master contra las dos ramas abiertas — TESIS-000 y TESIS-131 —, sin coincidencias. La de TESIS-131 ya está renumerada a 20260924130000.

El comando funciona. Lo probé con dos archivos que comparten versión y sale lo que tiene que salir:

$ ls /tmp/fake | cut -c1-14 | sort | uniq -d
20260101120000

✅ Lo que más me gustó

La advertencia de no renombrar migraciones ya mergeadas. Es la reacción instintiva cuando aparece un duplicado, y es justo la que rompe las bases donde ya se aplicaron. Que esté al lado de la regla evita que el arreglo cause el daño que el problema no llegó a causar.

🟡 Una regla documentada se olvida; un chequeo no

lefthook.yml y ci.yml no miran las migraciones hoy. El comando que proponés es de una línea y ya está escrito, así que convertirlo en un paso automático cuesta poco:

pre-push:
  commands:
    migration-versions:
      run: |
        dupes=$(ls db/migrate | cut -c1-14 | sort | uniq -d)
        [ -z "$dupes" ] || { echo "❌ Migraciones con la misma versión: $dupes"; exit 1; }

Ojo con el alcance: eso detecta el choque dentro de una rama, que es el caso que quedó después de mergear. El que nos mordió —dos ramas abiertas con el mismo número, cada una limpia por su lado— sólo aparece al compararse contra master, así que en CI el chequeo tendría que correr sobre el merge, que es justamente lo que GitHub Actions evalúa en un PR.

No lo bloqueo: la regla escrita ya es mejor que nada y el chequeo puede ir en otra card. Pero mientras sea sólo documentación, el próximo que cree una migración a mano un martes a las 12 va a volver a chocar.

Veredicto

APPROVE.

Es documentación, no cambia comportamiento, y ataca algo que nos costó un PR bloqueado esta semana. Lo del chequeo automático queda como sugerencia.

🤖 Generated with Claude Code

https://claude.ai/code/session_012xAtddb53LRNVLuyTXyELp