Cómo soltar la IA en código heredado antiguo sin romper nada

Imagina un escenario típico: has heredado un proyecto con cinco años de historia. No hay documentación, el autor original del código se fue hace tres años, y la lógica de negocio está esparcida en cientos de archivos. Conectar un agente de IA como Claude Code o Cursor a una base de código así da miedo. Le pides que corrija una función — reescribe el módulo vecino y destruye dependencias implícitas que nadie sabía que existían.

Hace poco, apareció en GitHub una herramienta interesante llamada Reversa, creada por un desarrollador con el nombre de usuario sandeco. El framework resuelve este problema de una manera original: se sumerge en un proyecto heredado, realiza ingeniería inversa y transforma el código fuente en especificaciones ejecutables.

Por qué reemplazar código con especificaciones

La mayoría de los agentes de codificación destacan en crear proyectos desde cero. Escribes un prompt, la herramienta genera una estructura limpia y código funcional. Este truco no funciona con código heredado. Si el agente no entiende las restricciones arquitectónicas y el contexto, trabaja a ciegas.

Reversa actúa como un puente entre el código antiguo y los asistentes de IA modernos. La herramienta no escribe documentación para humanos en el sentido tradicional. En su lugar, genera contratos operativos. Basándose en estos, cualquier agente de codificación puede ver inmediatamente las reglas del juego, las tablas de base de datos, las matrices de permisos y los algoritmos que no deben violarse.

Cómo funciona el proceso de investigación

La instalación se ejecuta en la raíz del proyecto mediante un único comando:

npx reversa install

El instalador detecta automáticamente los motores instalados en el sistema — Cursor, Claude Code, Codex, Windsurf o Copilot. Después de eso, copia los conjuntos de habilidades al directorio .agents/skills/ y crea un archivo de configuración.

Cuando ejecutas el comando /reversa dentro de tu cliente de IA, se activa una tubería de varios agentes especializados. Cada uno realiza su propio rol en el proceso de análisis:

• Scout escanea la estructura superficial, identifica lenguajes, frameworks y puntos de entrada.
• Archaeologist se sumerge en los módulos, analiza estructuras de datos y algoritmos complejos.
• Detective extrae reglas de negocio implícitas, diagramas de estado y reglas de acceso.
• Architect compila los datos recopilados en diagramas C4, esquemas ERD y mapas de integración.
• Writer formatea las especificaciones finales como contratos con enlaces a líneas de código específicas.

Un detalle interesante: Reversa marca cada enunciado en los documentos finales con una insignia especial de precisión. El icono 🟢 significa que la regla está respaldada directamente por código con referencias de archivo y línea. El icono 🟡 se coloca donde la IA realizó una inferencia lógica. El marcador rojo 🔴 indica "lagunas" donde el código no pudo explicar algo y se requiere intervención humana.

Seguro por defecto

El miedo principal al lanzar cualquier utilidad automatizada sobre un repositorio complejo es la pérdida de datos o las ediciones accidentales. Los creadores de Reversa enfatizaron el aislamiento completo.

El framework sigue una regla estricta: el código fuente del proyecto nunca se modifica ni se elimina durante el análisis. Todos los resultados son escritos por los agentes en solo dos carpetas de servicio: .reversa/ para el estado del análisis y _reversa_sdd/ para las especificaciones terminadas.

Además, la herramienta no solicita ni transmite claves API. Todo el trabajo analítico se descarga a la herramienta de IA que ya tengas ejecutándose localmente.

Qué sucede después de la extracción de datos

Crear especificaciones es solo el primer paso. Basándose en la carpeta _reversa_sdd/ generada, puedes lanzar otros flujos de trabajo a través de comandos adicionales.

• /reversa-forward ayuda a evolucionar el sistema paso a paso, transformando nuevos requisitos en código funcional con control de regresión.
• /reversa-migrate prepara un plan para migrar el stack heredado a una arquitectura moderna.
• /reversa-docs compila los datos recopilados en un sitio HTML estático con gráficos D3 interactivos y un mapa de arquitectura 3D.
• /reversa-debugger registra errores y los vincula causalmente a las especificaciones.

Si necesitas ejecutar un ciclo completo sin paradas y confirmaciones constantes, existe un modo autónomo /reversa-autonomous. En él, la utilidad hace todas las preguntas aclaratorias durante una entrevista inicial y luego trabaja de forma independiente.

Dónde se guardan los resultados

Dentro de la carpeta _reversa_sdd/ aparece una estructura clara de archivos Markdown. Allí puedes encontrar un diccionario de datos, descripción del dominio, matrices de roles, especificaciones OpenAPI y diagramas de secuencia en formato Mermaid.

_reversa_sdd/
├── inventory.md              # Инвентаризация файлов
├── dependencies.md           # Зависимости и версии
├── code-analysis.md          # Помодульный технический анализ
├── data-dictionary.md        # Словарь данных
├── domain.md                 # Бизнес-правила и глоссарий
├── state-machines.md         # Конечные автоматы в формате Mermaid
├── architecture.md           # Обзор архитектуры
├── confidence-report.md      # Отчет о точности анализа 
└── sdd/                      # Спецификации отдельных компонентов

Si modificas el código a través de /reversa-forward durante el refinamiento del sistema, un agente especial de Sync añade cuidadosamente información sobre las nuevas características a la carpeta _reversa_sdd/addenda/, preservando el historial de cambios.

¿Vale la pena adoptarlo

Reversa parece ser un intento maduro de poner orden en el caos de los proyectos heredados antes de entregarlos a la IA. El proyecto se está desarrollando activamente, y una preprint reciente en arXiv de mayo de 2026 respalda la arquitectura del framework con un enfoque académico.

La herramienta será útil para equipos que heredaron servicios descuidados sin documentación, así como para aquellos que planean una migración gradual desde stacks antiguos. Puedes probar la utilidad en cualquier repositorio de prueba, ya que no cambia ningún archivo existente.

Para un inicio rápido, simplemente ejecuta npx reversa install en la terminal y abre el proyecto en tu editor de IA habitual.