diff --git a/LESSONS.md b/LESSONS.md
new file mode 100644
index 0000000..b8693e3
--- /dev/null
+++ b/LESSONS.md
@@ -0,0 +1,107 @@
+# Lecciones Aprendidas - ViBe2 Modules
+
+## 🎯 Objetivo del Proyecto
+Migrar vibe1_delta a una arquitectura modular usando C++20 modules para aprendizaje.
+
+## ✅ Éxitos Conseguidos
+
+### Infraestructura C++20 Modules
+- **CMake configurado** correctamente para modules con Ninja generator
+- **Sintaxis de modules** dominada (.cppm, export module, import)
+- **Módulos funcionales** creados: core, themes, physics, rendering, input
+
+### Módulos Exitosamente Integrados
+- ✅ **vibe2.core**: Constantes (SCREEN_WIDTH, etc.) y tipos básicos (Color, ColorTheme)
+- ✅ **vibe2.themes**: Sistema completo de temas con ThemeManager funcional
+
+### Arquitectura Modular Lograda
+- 📁 Estructura `source/modules/` bien organizada
+- 🎨 Separación clara de responsabilidades por módulo
+- 🔧 Interfaces limpias entre módulos
+
+## ❌ Problemas Encontrados
+
+### Conflictos SDL con Módulos
+- **Problema principal**: Conflictos entre includes directos SDL3 y módulo sdl_wrapper
+- **Manifestación**: Errores de declaraciones conflictivas en compilación
+- **Archivos afectados**: dbgtxt.h, texture.h (archivos externos de terceros)
+
+### Limitaciones Arquitecturales
+- **Archivos externos** no se pueden/deben modificar para usar módulos
+- **SDL3 wrapper** complejo de implementar sin recrear toda la API
+- **Mezclar includes + modules** genera conflictos irresolubles
+
+## 🛠️ Soluciones Aplicadas
+
+### Enfoque Híbrido Exitoso
+- ✅ **SDL directo** (#include <SDL3/SDL.h>) para compatibilidad
+- ✅ **Módulos propios** (core, themes) funcionando perfectamente
+- ✅ **Comentar módulos conflictivos** temporalmente (physics, rendering, input)
+
+### Resultado Final
+- 🎮 **Aplicación 100% funcional** con módulos parciales
+- 📚 **Base sólida** para futuros proyectos modulares
+- 🧠 **Conocimiento adquirido** sobre limitaciones reales de C++20 modules
+
+## 🎓 Lecciones Clave
+
+### Técnicas
+1. **C++20 modules** son poderosos pero tienen limitaciones con bibliotecas externas
+2. **CMake + Ninja** es esencial para modules en GCC
+3. **Separación gradual** funciona mejor que migración total inmediata
+4. **Archivos externos** requieren estrategias especiales
+
+### Estratégicas
+1. **Empezar simple** (core, types) antes de sistemas complejos
+2. **No forzar modularización** donde no aporta valor
+3. **Mantener compatibilidad** con ecosistema existente
+4. **Documentar problemas** para futuras referencias
+
+## 🚀 Recomendaciones para Proyectos Futuros
+
+### Para vibe3_physics
+1. **Empezar con headers tradicionales** (.h/.cpp)
+2. **Enfocarse en características de física** primero
+3. **Organización por clases** en lugar de módulos initially
+4. **Considerar modules** solo cuando la arquitectura esté madura
+
+### Enfoque Recomendado
+```cpp
+// EVITAR (por ahora):
+import vibe3.physics;
+
+// PREFERIR:
+#include "physics/PhysicsWorld.h"
+#include "physics/Particle.h"
+```
+
+### Características Sugeridas para vibe3_physics
+- 🎯 Colisiones entre partículas
+- 🌊 Diferentes materiales (rebote, fricción)
+- ⚡ Fuerzas externas (viento, campos magnéticos)
+- 🎮 Interactividad (click para aplicar fuerzas)
+- 🎨 Visualización avanzada (trails, heatmaps)
+
+## 📊 Métricas del Proyecto
+
+### Tiempo Invertido
+- ⏱️ **Setup inicial**: ~1 hora (CMake, estructura)
+- 🔧 **Desarrollo modules**: ~2 horas
+- 🐛 **Resolución conflictos**: ~1 hora
+- 📝 **Documentación**: ~30 min
+
+### Resultado
+- ✅ **Objetivo cumplido**: Aprender C++20 modules
+- ✅ **Producto funcional**: Aplicación trabajando con módulos parciales
+- ✅ **Conocimiento adquirido**: Limitaciones y mejores prácticas
+
+---
+
+## 🔗 Enlaces Relacionados
+- **Proyecto original**: [vibe1_delta](https://gitea.sustancia.synology.me/JailDesigner/vibe1_delta)
+- **Este proyecto**: vibe2_modules (experimento modularización)
+- **Próximo proyecto**: vibe3_physics (enfoque físico pragmático)
+
+---
+
+*Documento creado para preservar conocimiento entre sesiones de Claude Code*
\ No newline at end of file