Gobernanza de IA Multi-Repo

Pasé semanas construyendo archivos de contexto para IA. La mitad mentían.

No a propósito. Los archivos eran correctos cuando los escribí. Luego las cosas cambiaron — actualizaciones de stack, migraciones de esquema, pivotes de negocio — y nadie actualizó la documentación.

La IA seguía leyendo el contexto antiguo. Yo seguía recibiendo respuestas seguras y equivocadas.

Lo peor: no me di cuenta de inmediato. Los resultados parecían razonables. Los errores eran sutiles. Para cuando los detecté, ya había construido sobre una base falsa.

Ese es el fallo del que nadie habla. No "la IA alucinó" — no lo hizo. Leyó exactamente lo que le di. El problema fue que lo que le di estaba obsoleto.

En ese momento gestionaba cinco proyectos en paralelo — un sitio de hostelería, una app de gestión financiera, un sitio corporativo, un pitch deck, un portafolio personal. Cada uno tenía su propio contexto de IA. Cada uno se desviaba a su propio ritmo. No había ningún sistema que conectara nada de esto.

Lo primero que construí fue lo equivocado: más documentación.

Más detalle, más estructura, más cobertura. Ayudó durante una semana. Luego esos archivos también empezaron a desviarse.

Lo segundo que construí se acercó más: una matriz de disparadores. Cada tipo de cambio — nueva ruta, actualización de esquema, nueva dependencia, cambio de modelo de negocio — mapeado al documento exacto que debe actualizarse. En el mismo PR. No como seguimiento. La tarea no está completa hasta que la documentación refleje la realidad.

Eso frenó el desvío en los proyectos individuales.

Pero propagarlo en cinco repositorios expuso el siguiente vacío. Las reglas genéricas no sobreviven al contacto con dominios específicos. La app financiera necesitaba un documento de modelo de datos. El sitio de hostelería necesitaba una especificación de portal. El pitch deck necesitaba una capa de afirmaciones verificadas — porque un inversor preguntando "¿de dónde sale este número?" no es el momento de descubrir que tu archivo de contexto era optimista.

Lo que finalmente entendí: hay dos tipos de contexto. Contexto que pertenece a una plantilla compartida — reglas base, patrones de arquitectura, cadencia de revisiones de estado. Y contexto que pertenece al repositorio — decisiones de dominio, anomalías de datos, afirmaciones verificadas. Mezclarlos rompe ambos.

La mayoría de las personas que se topan con este problema asumen que necesitan mejores herramientas de IA. Lo que normalmente necesitan es mejor disciplina de mantenimiento.

El archivo de contexto no es documentación. Es un contrato entre tú y el modelo. Cuando se rompe, el modelo no avisa. Simplemente sigue adelante.

Si estás construyendo con asistentes de IA en más de un proyecto, la pregunta que vale la pena hacerse ahora — antes de que te cueste caro — es: ¿quién actualiza el contexto cuando algo cambia, y cómo saben que necesita actualizarse?

La plantilla es de código abierto — enlace en los comentarios.

Fuentes

• ai-product-architecture-template (open source, GitHub): https://github.com/gtcuco-personal/ai-product-architecture-template