Mover una pieza compartida no es cambiar una ruta
El 8 de junio hubo varios commits que, vistos por separado, parecen menores:
10:48-docs: move nima agent to packages10:48-system: load nima agent from packages10:48-editor: package nima agent from packages17:02-docs: add workspace setup migration guide17:02-app: restructure reveal it frontend
La lectura rápida es "se movió un módulo compartido y luego se actualizó la documentación".
La lectura correcta es otra: una pieza solo está realmente compartida cuando el workspace entero sabe vivir con ella.
El cambio pequeño que no era pequeño
nima-agent ya no debía vivir como un componente colgado de un producto concreto. El cambio de la mañana fue moverlo a packages, y hacer que tanto nima-system como nima-editor lo cargaran desde ahí.
Eso no era una preferencia estética sobre carpetas. Era una corrección de propiedad.
Si una capacidad la consumen varios productos, su dirección también comunica quién la posee:
Mientras una pieza compartida sigue viviendo dentro de un producto, el código puede reutilizarse, pero la arquitectura sigue mintiendo.
Lo que el commit obligo a tocar
Mover nima-agent a packages no terminó en los imports.
Hubo que alinear cuatro capas:
| Capa | Qué cambió | Por qué importaba |
|---|---|---|
| Consumidores | nima-system y nima-editor cargan el agente desde packages |
Evita que un producto siga pareciendo el dueño de una capacidad compartida |
| Documentación | README y mapas de arquitectura apuntan al sitio nuevo | La estructura oficial deja de contradecir al código |
| Bootstrap | apareció una guía de migración del workspace y un script de setup | Un repo reorganizado que no se puede reconstruir fácil es una reorganización incompleta |
| Operación | hubo que revisar el estado de decenas de repos antes de actualizar | Cambiar la topología del workspace obliga a subir el nivel de disciplina operacional |
El punto importante es el tercero. Cuando hace falta escribir una guía de migración y un script de setup, ya no estás ordenando carpetas: estás cambiando el contrato de entrada al proyecto.
La conversacion que dejo clara la regla
Ese mismo día hubo una conversación operativa sobre sincronizar todos los repos del workspace local.
Lo valioso no fue el git pull. Fue la secuencia mental:
- Primero se hizo
fetchy revision en bloque. - Se detectó que el repo raíz tenía cambios locales y que el remoto también tocaba
README.md. - Se paró antes de cruzar la frontera destructiva.
- Luego se comparó si los cambios locales seguían teniendo sentido con la reorganización nueva.
- Solo después se descartaron los que ya estaban obsoletos.
- Al final se amplió el alcance porque el primer barrido había contado 20 repos, pero el workspace local real tenía 22.
Ese chat explicó mejor que el código una regla de plataforma: nunca actualices un workspace reorganizado como si fuera una carpeta grande; actualízalo como un sistema con alcance, propiedad y riesgo.
Por qué la guía de migración era parte del producto
El commit de la tarde añadió una guía de migración del workspace y un setup-notipad-workspace.ps1.
Eso puede parecer documentación interna, pero en realidad es trabajo de producto de plataforma.
Cuando una plataforma depende de que solo una persona recuerde:
- que repo va en que sitio,
- qué carpeta ya no es canónica,
- qué consumidor carga desde qué paquete,
- y qué script hay que ejecutar después del cambio,
la plataforma todavía no existe del todo. Existe el conocimiento del operador.
La guía convierte memoria en procedimiento. El script convierte procedimiento en arranque reproducible.
El efecto lateral bueno: reestructurar productos sin tocar lo compartido
Horas después, reveal-it-app recibió una reestructuración grande de frontend: rutas, parciales, contenido SEO, shell común, assets y scripts.
No es el mismo cambio, pero sí la misma lección.
Cuanto más claro queda qué es compartido y cuanto mejor se reconstruye el workspace, más fácil es que un producto cambie mucho por dentro sin volver a mezclar límites.
El objetivo no era "tener packages". El objetivo era poder mover piezas grandes sin volver a esconder dependencias dentro del producto equivocado.
Lo que me llevo de este tramo
- Compartido no significa "usado por varios"; significa "ubicado, documentado y cargado como compartido".
- Una reorganización no termina cuando compila; termina cuando otro workspace puede arrancar sin conocimiento tribal.
- Las conversaciones operativas también son arquitectura. A veces revelan mejor que un diagrama dónde está el riesgo real.
- Revisar alcance antes de borrar es una disciplina técnica, no prudencia administrativa.
Mover una pieza compartida no fue un git mv. Fue una corrección de propiedad, seguida de una corrección de arranque y de una corrección de operación.
Y eso es una señal útil: cuando un cambio de ruta te obliga a tocar código, docs, setup y criterios de sincronización, no estás moviendo un fichero. Estás estabilizando una plataforma.
Parte de mis notas de plataforma. Sigue el blog o escríbeme.