DESARROLLO BASADO EN CHECKPOINTS CON LLMS - Rollback sin drama
Trabajar con LLMs acelera el desarrollo. También acelera los errores. Un LLM puede en un solo mensaje reescribir tres archivos, romper dos funciones que funcionaban, y resolver el problema original. Resultado Final: un paso adelante, dos atrás. La solución no es desconfiar del LLM — es tener un sistema de checkpoints que haga el rollback tan trivial que no duela hacerlo.
Stack: Git · Python · cualquier proyecto
Proyectos de referencia: FocOs · TeliOs
Objetivo: Convertir el rollback en una operación de 2 segundos sin drama
01. EL PROBLEMA QUE RESUELVE
Cuando un LLM modifica múltiples archivos en una sesión, es fácil perder track de qué estado era estable. Sin checkpoints explícitos, el desarrollador se encuentra eligiendo entre dos opciones igualmente costosas: seguir adelante con código roto esperando arreglarlo después, o reescribir manualmente para volver al estado anterior. Los checkpoints eliminan esa elección.
Cuando el rollback no duele, el desarrollador acepta más riesgos calculados. Y los riesgos calculados son exactamente los que producen los avances reales.
🎓 Explicación no técnica
Imagina que estás construyendo un castillo de LEGO muy complicado. Cada vez que terminas una parte importante — una torre, un puente, una muralla — le tomas una foto. Si en algún momento rompes algo sin querer, no tienes que empezar de cero. Miras la foto y reconstruyes solo la parte que se rompió. Los checkpoints son esas fotos. Git las toma automáticamente si tú le dices cuándo.
02. LA REGLA DE ORO — UN CHECKPOINT POR ESTADO ESTABLE
Un checkpoint no es un commit por cada cambio. Es un commit por cada estado verificado como funcional. La diferencia es fundamental.
git commit -m 'cambios'
git commit -m 'más cambios'
git commit -m 'arreglando algo'
git commit -m 'wip'
# Resultado: historial inútil. No sabes cuál estado funcionaba.
# ✅ COMMIT BIEN — commit por estado estable verificado
# Antes de empezar a trabajar con el LLM:
git add .
git commit -m 'CHECKPOINT: LLM panel funcional — antes de agregar historial'
# Después de verificar que el nuevo estado funciona:
git add .
git commit -m 'CHECKPOINT: historial de conversación implementado y verificado'
# Resultado: cada commit es un punto de restauración confiable.
03. EL PROTOCOLO COMPLETO — ANTES, DURANTE Y DESPUÉS
# 1. Verificar que el estado actual funciona
python main.py
# 2. Hacer el checkpoint
git add .
git commit -m 'CHECKPOINT: [descripción del estado actual]'
# 3. Anotar qué vas a pedirle al LLM (en SESSION-LOG o comentario)
# 'Le voy a pedir que implemente el historial de conversación'
# DURANTE el trabajo con el LLM:
# 4. Revisar CADA cambio antes de aplicarlo — no aplicar en lote sin leer
# 5. Probar después de cada archivo modificado — no esperar todos los cambios
# DESPUÉS — si el resultado funciona:
git add .
git commit -m 'CHECKPOINT: [descripción del nuevo estado]'
# DESPUÉS — si el resultado está roto:
git checkout . # descarta cambios no commiteados
# o
git reset --hard HEAD # vuelve al último checkpoint
04. CONVENCIÓN DE NOMBRES — LA QUE SALVA TIEMPO
El nombre de un checkpoint debe comunicar dos cosas: qué estado existe en ese punto y por qué ese momento merece un checkpoint. Si no puedes describir el estado en una línea, el estado no está claro todavía — no hacer checkpoint.
# Ejemplos reales de FocOs:
CHECKPOINT: bridge JS↔Python estable — antes de integrar Monaco
CHECKPOINT: Monaco con model:null — pestañas sin bug de buffer compartido
CHECKPOINT: LLM Groq respondiendo — User-Agent fix aplicado
CHECKPOINT: terminal xterm.js funcional — antes de agregar autocompletado
CHECKPOINT: dashboard con datos reales — antes de conectar SQLite
# Lo que NUNCA debe ser un nombre de checkpoint:
# 'fix' | 'cambios menores' | 'wip' | 'actualizando'
| Nombre | ¿Vale como checkpoint? | Razón |
|---|---|---|
| CHECKPOINT: bridge estable — antes de Monaco | ✅ Sí | Describe estado y contexto claramente. |
| fix | ❌ No | No describe qué se arregló ni el estado resultante. |
| wip | ❌ No | Work in progress no es un estado estable verificado. |
| cambios menores | ❌ No | Ambiguo. Historial inútil a las 48 horas. |
05. GIT STASH — EL CHECKPOINT TEMPORAL
Cuando quieres explorar una idea sin comprometerte a un checkpoint, git stash guarda el estado actual temporalmente sin hacer commit. Ideal para experimentos rápidos sin contaminar el historial.
git stash push -m 'experimento: probar enfoque alternativo con Monaco'
# Si el experimento funcionó — checkpoint y descartar stash
git add .
git commit -m 'CHECKPOINT: enfoque alternativo Monaco funciona mejor'
git stash drop
# Si el experimento falló — recuperar el trabajo previo
git stash pop
# Inspección de stashes
git stash list
git stash show stash@{0} -p
06. RAMAS PARA EXPERIMENTOS MAYORES
Para cambios que afectan arquitectura completa, usar una rama separada — nunca el branch principal. Si el experimento falla, main nunca fue tocado. Cero drama.
git checkout -b experimento/streaming-llm
# Si funciona — merge a main
git checkout main
git merge experimento/streaming-llm
git commit -m 'CHECKPOINT: streaming LLM integrado desde rama'
# Si no funciona — eliminar rama sin contaminar main
git checkout main
git branch -D experimento/streaming-llm
# Nomenclatura de ramas en FocOs:
# feature/onboarding | feature/file-explorer
# experimento/monaco-vim-mode | fix/bridge-timeout
07. INTEGRACIÓN CON SESSION-LOG
Cada checkpoint debería tener una entrada en el SESSION-LOG del día. Así el historial de Git y el historial del proyecto están sincronizados — puedes reconstruir exactamente qué decisión tomaste y con qué LLM.
- 10:30 — CHECKPOINT: bridge JS↔Python estable
Commit: a3f9c2b
Estado antes: bridge caía en arranque frío
Estado después: on_start() callback estable
LLM usado: Claude Sonnet
- 14:15 — CHECKPOINT: Monaco pestañas independientes
Commit: d8e4f1a
Estado antes: todas las pestañas compartían buffer
Estado después: model:null + URI único por pestaña
LLM usado: Groq llama-3.3-70b
## Rollbacks del día
- 12:00 — Rollback a bridge estable
Razón: intento de agregar streaming rompió el bridge
Tiempo perdido: 45 min
Lección: probar streaming en rama separada
✅ CONCLUSIÓN
El checkpoint-based development aplicado a proyectos con LLMs convierte el rollback de una operación costosa y dolorosa en una rutina de 2 segundos. El efecto psicológico es tan importante como el técnico: cuando el desarrollador sabe que puede volver atrás sin drama, acepta más experimentos. Más experimentos significa más descubrimientos. El costo de equivocarse cae a cero — y eso cambia la velocidad de construcción tanto como el LLM mismo.
> SYSTEM_READY > NODE_ONLINE