Arcovia: Una herramienta de inteligencia para arquitecturas basadas en reglas para aplicaciones React
Descubra cómo un proyecto de hackathon analiza los repositorios de código de React y Next.js mediante reglas deterministas para evaluar la salud de la arquitectura y detectar deudas técnicas ocultas.
El desafío que dio origen a este proyecto
Durante un reciente hackathon de OpenAI Build Week, un equipo se propuso un objetivo sencillo: crear algo que un desarrollador realmente quisiera usar a diario.
Al final de la primera tarde, el concepto ya estaba claro. En dos días más, ese concepto se convirtió en un proyecto de código abierto funcional llamado Arcovia.
No se trataba de una demostración única de inteligencia artificial. Su objetivo era abordar una frustración recurrente que enfrentan los desarrolladores al mantener grandes bases de código React durante largos períodos.
La brecha en las herramientas existentes
Ya existen muchas herramientas sólidas para mantener el código limpio.
- ESLint señala patrones problemáticos.
- Prettier se encarga del formato.
- SonarQube detecta problemas de calidad.
- Los revisores basados en IA proponen mejoras a nivel de línea.
Pero ninguno de estos herramientas puede responder a preguntas más estructurales como:
- ¿Está la arquitectura general en buen estado?
- ¿Qué módulos se están convirtiendo en puntos críticos?
- ¿Dónde se está acumulando la deuda técnica?
- ¿Qué archivos merecen ser refactorizados primero?
- ¿Qué causó realmente la calificación de un proyecto determinado?
Los problemas arquitectónicos suelen surgir solo en las discusiones de revisión de código, o peor aún, una vez que la base de código ya resulta difícil de trabajar. Lo que faltaba era una forma de evaluar la salud de una arquitectura antes de que se convirtiera en un verdadero problema.
Conozca Arcovia
Arcovia se describe como una herramienta de Inteligencia Arquitectónica diseñada para bases de código React y Next.js.
En lugar de saturar al usuario con una larga lista de advertencias desconectadas, evalúa el proyecto de manera integral y genera un informe HTML interactivo.
Ese informe incluye:
- Una puntuación de salud de la arquitectura
- Un gráfico de dependencias
- Puntos críticos en la arquitectura
- Un desglose que explica cómo se obtuvo la puntuación
- Resultados basados en reglas
- Un indicador de carga de mantenimiento
- Recomendaciones prácticas
Arcovia no intenta reemplazar a los herramientas de análisis estático. Su propósito es brindar a los desarrolladores una visión del panorama estructural general que las reglas individuales de análisis no pueden capturar.
Dentro del funcionamiento
La herramienta ejecuta internamente un pipeline de análisis completamente determinista.
Project
│
▼
Scanner
│
▼
AST Parser
│
▼
Project Model
│
▼
Dependency Graph
│
▼
Rule Engine
│
▼
Score Engine
│
▼
Interactive HTML Report
El analizador actualmente puede identificar una serie de problemas estructurales. Entre ellos:
- “Módulos principales” excesivamente centrales de los que depende demasiada parte de la aplicación
- Componentes o archivos con alto número de dependencias entrantes
- Componentes o archivos con alto número de dependencias salientes
En lugar de listar estos hallazgos por separado, Arcovia los agrega en una única puntuación de arquitectura fácil de interpretar.
Las reglas primero, la IA después
Una decisión de la que los creadores están muy satisfechos es excluir a la IA de la lógica principal de análisis.
La puntuación de arquitectura en sí nunca es generada por un modelo de lenguaje.
En su lugar, Arcovia funciona de la siguiente manera:
- analizando la base de código a través de su AST
- construyendo gráficos de dependencias
- aplicando reglas arquitectónicas deterministas a los resultados
- calculando puntuaciones por categoría
Graças a este diseño, los resultados permanecen consistentes y reproducibles.
El plan general es que la IA mejore la experiencia en lugar de hacerse cargo directamente de la puntuación. Los usos previstos incluyen:
- explicar los hallazgos individuales en lenguaje sencillo
- proponer enfoques de refactorización
- indicar recursos de aprendizaje relevantes
- responder preguntas adicionales sobre el informe
El análisis determinista sigue siendo la única fuente de verdad, con la IA como capa adicional que actúa como intérprete.
Trabajando con GPT-5.6 y Codex
Este hackathon también marcó la primera vez que el equipo utilizó a la IA como un colaborador real durante todo el proceso de desarrollo, en lugar de tratarla como un autocompletado mejorado.
Durante el fin de semana, se utilizaron GPT-5.6 y Codex para:
- generar ideas sobre qué reglas arquitectónicas era conveniente incluir
- mejorar la forma en que el modelo de puntuación valora diferentes señales
- implementar características individuales
- perfeccionar el diseño visual del informe
- simplificar lógicas complejas
- verificar la validez de las decisiones de implementación
También se empleó ChatGPT Images para diseñar la identidad visual de Arcovia, incluyendo su mascota búho, logotipo y otros materiales de lanzamiento.
El flujo de trabajo general resultó más natural de lo esperado. En lugar de entregar características completas para que se generaran de principio a fin, el mayor beneficio provino de iteraciones rápidas y continuas, similar a contar con un segundo ingeniero para analizar opciones de diseño y sopesar las compensaciones.
Lecciones del fin de semana
Comprimir este proceso en un solo fin de semana reveló varias lecciones útiles.
La arquitectura resiste las métricas simples
Evaluar la calidad del código de forma aislada es bastante mecánico.
Evaluar la arquitectura es mucho más difícil, ya que depende del contexto, de compromisos competitivos y de un ponderamiento cuidadosamente ajustado entre muchas reglas diferentes.
Encontrar el equilibrio adecuado entre señales realmente útiles y falsos positivos engañosos sigue siendo un esfuerzo constante e abierto.
Una puntuación sin contexto no es útil
Darle a alguien un número por sí solo no le dice mucho.
Los desarrolladores necesitan ver:
- por qué la puntuación resultó de esa manera
- qué factores contribuyeron más
- qué problemas tienen mayor importancia
- qué abordar primero
Ese es el razonamiento detrás del diseño del informe, que se centra en explicar la puntuación en lugar de tratarla como un resultado opaco.
La IA acelera las cosas, pero no de la manera que uno esperaría
GPT-5.6 y Codex claramente aceleraron el proceso de creación.
Aun así, el mayor aumento en la productividad no se debió a generar código más rápido.
Sino al utilizar la IA como un socio de reflexión: analizar opciones de diseño, cuestionar suposiciones y probar rápidamente diferentes ideas.
Qué viene después
Esta versión es solo un punto de partida.
Las funcionalidades que se están considerando para futuras versiones incluyen:
- Una integración con GitHub Action
- Seguimiento del historial de informes
- Análisis de tendencias arquitectónicas a lo largo del tiempo
- Una extensión para VS Code
- Comparación de proyectos lado a lado
- Tableros de control para todo el equipo
- Asesoría arquitectónica impulsada por la IA
El objetivo a largo plazo es ayudar a los equipos de ingeniería a monitorear, medir y mejorar continuamente la arquitectura de su software con el paso del tiempo.
Se agradece cualquier comentario
Arcovia es completamente de código abierto, y los comentarios de los desarrolladores que crean aplicaciones con React o Next.js serían especialmente valiosos.
Algunas preguntas que vale la pena explorar:
- ¿La puntuación de arquitectura parece reflejar algo significativo?
- ¿Qué otros problemas arquitectónicos deberían detectarse?
- ¿Qué haría que un informe como este sea realmente útil en su flujo de trabajo diario?
El código fuente del proyecto se encuentra en su repositorio en github.com/gkhan205/arcovia; el paquete puede instalarse directamente desde npmjs.com/package/arcovia, y la documentación completa está disponible en arcovia.ghazikhan.in.
Las ideas, los comentarios y hasta las críticas son bienvenidos, ya que el uso en entornos reales es la forma más eficaz de mejorar Arcovia con el tiempo.
Lecturas relacionadas
- 20 patrones avanzados de Next.js para aplicaciones App Router de nivel profesional — Aprenda veinte patrones de alto nivel para Next.js que abarcan el diseño basado en servidor, la transmisión en tiempo real, el caché, el enrutamiento y el rendimiento, con el fin de crear aplicaciones profesionales más rápidas y escalables.