El Arqui: el agente que entiende cualquier stack

Pensé que mi documentador hacía todo… hasta que se lo mostré a otros equipos.

Hasta ese momento lo venía usando con mi propio equipo: Laravel, Vue.js, algo de Python. Todo relativamente conocido. El sistema entendía el código, generaba la documentación, cumplía.

Pero cuando empezamos a trabajar en proyectos de terceros, apareció de todo. .NET, React, Flutter, React Native y varios stacks más. Proyectos que nadie había tocado en años, hechos con criterios completamente distintos a los nuestros.

Y ahí fue donde mi modelo mental empezó a romperse. El problema no era técnico, era conceptual. Lo que yo había construido estaba optimizado para cómo yo trabajo. Mis decisiones, mis estructuras, mis frameworks.

Los proyectos de otros equipos son otra cosa. La primera reacción fue la obvia: crear el set de tareas a mano. Un stack nuevo, un nuevo set. Otro stack, otro set. Y así funcionó un par de veces, pero rápidamente se volvió insostenible.

No es lo mismo analizar Laravel que PHP sin framework. No es lo mismo Vue estándar que Vue con Nuxt o con Inertia. No es lo mismo cómo funciona Eloquent que el ORM de FastAPI. Cuando me di cuenta de que iba a tener que hacer esto indefinidamente, cambié el enfoque.

En lugar de crear cada plan a mano, me pregunté qué tienen en común todos los proyectos. Y la respuesta es siempre la misma: necesitás entender cómo está armado el sistema. Independientemente del stack, el recorrido base es parecido. Primero, los readmes y la documentación existente. Después de la configuración y los archivos de paquetes. Luego la estructura de carpetas. Rutas, entidades, DER. Validaciones, servicios, DTOs. Casos de uso, autenticación, autorización, vulnerabilidades, bla bla bla.

El esqueleto no cambia. Lo que cambia es el lenguaje en el que se hace el análisis. Con eso definido, el siguiente paso fue automatizar la creación de planes.

Cuando aparece un stack que el sistema no conoce, mi nuevo agente, "El Arqui", investiga las mejores prácticas para ese lenguaje o framework —arranca mirando context7 y documentación oficial— y genera el plan. Una sola vez. Después, ese plan queda disponible para que cualquier dev experto lo revise y lo ajuste.

En Laravel tiene sentido hablar de modelos, controladores y Eloquent. En FastAPI, la lógica pasa por routers, schemas y el ORM que eligas. En frontend, el recorrido es completamente distinto. Pero el objetivo es el mismo en todos los casos: entender el sistema.

El proceso tiene más pasos de lo que parece: el agente consulta en paralelo los stacks existentes y la documentación oficial, combina todo, y recién ahí genera el plan.

Hoy en el sistema tengo un área de stacks donde cada tecnología tiene su propio plan de trabajo: Laravel, Express, FastAPI, Flutter, React, Spring Boot, PHP custom, Playwright, entre otros. Y cuando entra un proyecto nuevo, el sistema arma un plan específico para ese proyecto.

Un proyecto puede ejecutar en paralelo el plan de backend, el de frontend, el de testing, el de seguridad, escalabilidad y mejores prácticas. El resultado es un análisis completo sin reinventar nada cada vez. Esto cambió cómo abordamos proyectos heredados o de terceros.

Logramos bajar esas semanas de onboarding para entender el proyecto, antes de tirar código, a un par de días.

Ahora lo primero que hacemos es correr el documentador. En poco tiempo tenemos visión general del sistema, estructura clara, entidades identificadas, rutas listadas, puntos críticos detectados. De acá salió el ragcito que armamos para poder hacerle preguntas, pero eso lo explico en otro post.

Y lo más interesante no es la herramienta, es el cambio de mentalidad. Empecé construyendo algo para documentar mi código, y hoy tengo un sistema para entender sistemas. La documentación es una consecuencia.

El problema nunca fue el lenguaje. Fue siempre el mismo: entrar a un código que no escribiste y tratar de entender qué está pasando. Si podés sistematizar eso, ya tenés una ventaja enorme.