Descubrimiento de arquitectura con IA: cómo funciona
El año pasado, heredé una codebase sin documentación. 200.000 líneas de código en 15 servicios, escritas por un equipo que ya se había ido. Mi tarea era entenderlo lo suficiente para agregar una nueva integración de pagos. La empresa estimaba que tomaría 2-3 semanas solo mapear la arquitectura.
Esa experiencia es la razón por la que construí la función de descubrimiento con IA de Archyl. Y ahora, después de pasar meses trabajando con modelos de lenguaje para analizar código, quiero compartir qué funciona realmente, qué no, y por qué el descubrimiento de arquitectura con IA es poderoso pero no mágico.
El problema con el descubrimiento manual
Antes de sumergirnos en IA, reconozcamos por qué lo necesitamos en primer lugar.
Cuando enfrenté esa codebase sin documentar, así fue mi proceso de descubrimiento:
Semana 1: Grep a través del código buscando palabras clave. Encontrar los puntos de entrada principales. Dibujar algunas cajas en una pizarra. Darme cuenta de que malentendí los límites de los servicios. Borrar y redibujar.
Semana 2: Entrevistar al único ingeniero que ha estado aquí lo suficiente para recordar algo de la historia. La mitad de lo que me dice contradice lo que encontré en el código. Resulta que las cosas cambiaron pero nadie actualizó su modelo mental.
Semana 3: Finalmente sentir que entiendo el sistema lo suficiente para hacer cambios. Crear documentación que juro mantener actualizada. (Spoiler: no lo hice.)
Este proceso es lento, propenso a errores, y no escala. Cada nuevo miembro del equipo pasa por el mismo doloroso descubrimiento. La documentación se desactualiza en meses.
Cómo funciona realmente el descubrimiento con IA
Cuando conectas un repositorio a Archyl y ejecutas el descubrimiento, esto es lo que pasa bajo el capó:
Paso 1: Escaneo del repositorio
Primero, construimos un mapa de tu codebase. Esto no es IA todavía — es un recorrido simple del sistema de archivos:
- Listar todos los archivos y directorios
- Identificar archivos de configuración (package.json, go.mod, docker-compose.yml)
- Encontrar puntos de entrada (funciones main, archivos index, rutas API)
- Construir un grafo de dependencias desde los imports
Esto nos da el esqueleto. Sabemos qué archivos existen y cómo se referencian entre sí. Pero aún no entendemos qué hacen.
Paso 2: Análisis por chunks
Aquí es donde entran los LLMs, y también donde se pone complicado.
Los modelos de lenguaje modernos tienen límites de contexto. GPT-4 puede manejar alrededor de 128K tokens, Claude puede hacer 200K. Suena como mucho, pero una codebase mediana fácilmente excede eso. Así que no podemos simplemente meter toda la codebase en un prompt y preguntar "¿qué es esto?"
En cambio, dividimos la codebase en pedazos digeribles:
- Agrupar archivos por directorio o módulo
- Enviar cada chunk al LLM con contexto sobre su ubicación en el proyecto
- Pedir al modelo que identifique: ¿De qué es responsable este código? ¿Qué patrones usa? ¿Con qué sistemas externos interactúa?
Las respuestas regresan como datos estructurados — JSON describiendo sistemas, containers y componentes con sus relaciones.
Paso 3: Agregación y reconciliación
Esta es la parte más difícil, y donde pasé la mayor parte de mi tiempo de desarrollo.
Cada análisis de chunk nos da una vista parcial. El chunk del servicio de usuarios conoce la base de datos de usuarios. El chunk de pagos conoce Stripe. Pero ninguno conoce el panorama completo.
Necesitamos reconciliar estas vistas parciales:
- Fusionar entidades duplicadas (¿"UserDB" es lo mismo que "users_database"?)
- Inferir relaciones entre chunks (el servicio de órdenes llama al servicio de usuarios, pero fueron analizados por separado)
- Resolver conflictos (un chunk dice que usamos PostgreSQL, otro dice MySQL — ¿cuál tiene razón?)
Esta reconciliación usa otra ronda de análisis LLM, más heurísticas basadas en patrones comunes. Es imperfecto. A veces la IA se equivoca. Por eso el descubrimiento produce sugerencias que los humanos revisan, no documentación final.
Paso 4: Generación del modelo C4
Finalmente, mapeamos las entidades descubiertas a elementos del modelo C4:
- Sistemas externos (APIs de terceros, bases de datos que no manejamos)
- Containers (nuestras unidades desplegables)
- Componentes (módulos principales dentro de containers)
- Relaciones (quién llama a quién, qué datos fluyen hacia dónde)
El resultado es un conjunto de borradores de diagramas C4 que capturan el entendimiento de la IA de tu arquitectura.
Qué hace bien la IA
Después de ejecutar descubrimiento en docenas de codebases durante el desarrollo, esto es lo que me impresionó:
Detección de stack tecnológico
Los LLMs son notablemente buenos identificando qué tecnologías usa un proyecto. Reconocen patrones de framework, idiomas de bibliotecas, y formatos de archivos de configuración. Cuando GPT ve una anotación @Controller, sabe que estás usando Spring. Cuando ve fiber.New(), sabe que estás usando Go Fiber.
Detección de límites de servicios
En arquitecturas de microservicios, la IA identifica de manera confiable los límites de servicios. Entiende que el código en /services/user/ es probablemente un servicio separado de /services/order/. Reconoce archivos Docker Compose como indicadores de topología de servicios.
Reconocimiento de patrones comunes
La IA ha visto millones de codebases en sus datos de entrenamiento. Reconoce patrones de repositorio, estructuras MVC, arquitecturas event-driven, y configuraciones de API gateway. Cuando tu código sigue patrones comunes, la IA los identifica rápidamente.
Descubrimiento de integraciones externas
Cada constante de API key, URL de webhook, o import de SDK es una pista sobre integraciones externas. La IA captura la mayoría de estas, construyendo una imagen de qué servicios de terceros depende tu sistema.
Qué hace mal la IA
Aquí es donde tuve que establecer expectativas realistas:
Lógica de negocio personalizada
La IA no entiende tu dominio de negocio. Puede decir que tienes una función processOrder, pero no sabe qué significa "procesar una orden" en tu contexto de negocio específico. Podría identificar mal el propósito de componentes específicos del dominio.
Arquitecturas inusuales
Si tu arquitectura no sigue patrones comunes, la IA batalla. Un sistema de plugins personalizado, una estructura de carpetas no convencional, o un framework hecho en casa la confundirá. La IA espera que las apps Rails se vean como apps Rails.
Dependencias ocultas
No todas las dependencias son explícitas en el código. Quizás tu servicio requiere una versión específica de Redis que solo existe en producción. Quizás hay un container sidecar que la IA nunca ve. Las dependencias en runtime son frecuentemente invisibles al análisis estático.
Caminos de código obsoletos
La IA no sabe qué código se usa activamente versus cuál es legacy que nadie ha tocado en años. Podría destacar prominentemente un servicio deprecado que todavía está en la codebase pero ya no se despliega.
Haciendo que el descubrimiento con IA funcione mejor
A través de prueba y error, he encontrado formas de mejorar la precisión del descubrimiento:
Proporcionar contexto
Antes de ejecutar el descubrimiento, dile a la IA sobre tu sistema. "Esta es una plataforma de e-commerce con procesamiento de pagos" le da al modelo un marco de referencia. Sin contexto, está adivinando a ciegas.
Empezar con estructura
Si tienes alguna documentación existente — incluso un README con un boceto aproximado de arquitectura — proporciónala. La IA usa esto como prior para guiar su análisis.
Revisar incrementalmente
No ejecutes el descubrimiento en toda tu codebase de una vez. Empieza con un servicio. Revisa y corrige los resultados. Luego expande al siguiente servicio. Las correcciones que haces informan los análisis futuros.
Confía pero verifica
Trata las sugerencias de la IA como punto de partida, no como respuesta final. La IA podría ser 80% precisa. Necesitas verificar el otro 20%. Haz clic en los enlaces al código fuente, confirma que las relaciones tienen sentido, y corrige errores.
Los detalles técnicos
Para los curiosos sobre la implementación:
Estrategia de chunking
Usamos chunking semántico en lugar de chunks de tamaño fijo. Un chunk es típicamente un módulo, un servicio, o un árbol de directorios. Esto mantiene código relacionado junto, lo que mejora el entendimiento de la IA.
Ingeniería de prompts
Los prompts evolucionaron significativamente. Las primeras versiones producían descripciones verbosas y narrativas. Los prompts actuales demandan salida estructurada con campos específicos. Usamos ejemplos few-shot para demostrar el formato esperado.
Concurrencia
Las codebases grandes tienen miles de archivos. Procesar secuencialmente tomaría una eternidad. Analizamos chunks en paralelo, con límites de concurrencia configurables para evitar límites de tasa de API.
Selección de modelo
Diferentes modelos tienen diferentes fortalezas. GPT-4 produce análisis más preciso pero cuesta más. Claude es mejor siguiendo requisitos de salida estructurada. Soportamos ambos, más modelos locales vía Ollama para equipos que no pueden enviar código a APIs externas.
El futuro del descubrimiento con IA
Lo que tenemos hoy es la versión 1. Esto es hacia donde trabajo:
Descubrimiento continuo
En lugar de análisis puntual, monitorear tu codebase continuamente. Cuando el código cambia, actualizar los diagramas relevantes automáticamente. Detectar drift arquitectural antes de que se vuelva un problema.
Entendimiento más profundo
El análisis actual es mayormente estructural. Versiones futuras podrían entender comportamiento: "Este endpoint valida input, llama al servicio de pagos, luego envía un email de confirmación." Diagramas de secuencia generados desde código.
Análisis cross-repositorio
La mayoría de las organizaciones tienen múltiples repositorios. El descubrimiento debería entender cómo se conectan — qué servicios en repo A llaman a servicios en repo B.
Puntuación de confianza
No todos los descubrimientos son igualmente seguros. Estamos agregando puntuaciones de confianza para que sepas qué sugerencias escrudiñar más cuidadosamente.
Conclusión
El descubrimiento de arquitectura con IA no es magia. Es una herramienta que acelera las partes tediosas de entender una codebase mientras sigue requiriendo juicio humano para las partes matizadas.
Cuando ejecuto descubrimiento en esa codebase de 200K líneas hoy, obtengo un borrador de diagrama de arquitectura en 10 minutos en lugar de 3 semanas. No es perfecto — todavía necesito revisar y corregir. Pero es un punto de partida dramáticamente mejor que una pizarra en blanco.
Si te estás ahogando en código sin documentar, prueba el descubrimiento con IA. Ve con expectativas realistas: no entenderá tu dominio de negocio, podría perder patrones inusuales, y definitivamente requiere revisión humana. Pero te llevará 80% del camino en una fracción del tiempo.
¿Quieres aprender más? Consulta nuestra introducción al modelo C4 que genera el descubrimiento con IA, o lee sobre por qué la documentación de arquitectura importa en primer lugar.