AI 2026-09-11 8 min

El Reto del Código Existente (Brownfield) y la Gestión de Múltiples Specs con Jira/Git

Descubre cómo hacer ingeniería inversa en código legacy y gestionar múltiples especificaciones en paralelo usando el patrón Delta-Spec y convenciones de Git/Jira.

Escrito por Samir El Azem Crovetto • Senior Backend Engineer & DevSecOps

En las guías ideales de desarrollo, siempre se asume que estás creando un proyecto reluciente desde cero. En la vida real, te incorporas a un equipo y te encuentras con un sistema que lleva años funcionando, un monolito que mezcla tres patrones de arquitectura diferentes y una montaña de código legacy que nadie se atreve a tocar por si se cae el chiringuito.

Si además intentas coordinar el desarrollo de varias funcionalidades complejas estimadas en varios días de trabajo, la cosa se complica. En el día a día de una empresa, los pipelines de Git y las convenciones de Jira o Agility mandan. No puedes simplemente usar un numerito secuencial aleatorio para tus ramas si tienes un ticket con nombre y apellidos asignado en tu tablero.

Hoy vamos a ver cómo abordar el código legacy sin morir en el intento utilizando la ingeniería inversa para documentar sistemas antiguos, cómo funciona el patrón "Delta-Spec" en profundidad, y cómo gobernar múltiples especificaciones en paralelo adaptando el comportamiento por defecto de Spec Kit a tu nomenclatura de ramas de Jira o Git.

1. Ingeniería Inversa sobre Código Legacy: El arte de reconstruir Specs

Cuando te enfrentas a una funcionalidad legacy compleja y desordenada que necesitas refactorizar o ampliar, intentar adivinar qué hace leyendo miles de líneas de JavaScript espagueti es una pérdida de tiempo. En lugar de eso, podemos usar la IA para hacer ingeniería inversa y que sea ella la que nos extraiga un contrato lógico estructurado en Markdown.

Imagina que tienes una función de cálculo de comisiones de pago súper enrevesada escrita en un archivo JS antiguo, lleno de condicionales anidados y variables con nombres incomprensibles como temp_val o res2.

El primer paso no es picar código TypeScript moderno. El primer paso es abrir el chat de tu editor agéntico (como Google Antigravity) y lanzarle un prompt de ingeniería inversa estructurado:

"Quiero que analices esta lógica legacy de cálculo de comisiones. Tu objetivo es reconstruir el contrato lógico de negocio que hay detrás y volcarlo en un archivo spec.md estructurado con sintaxis EARS. Identifica todas las reglas de negocio ocultas, los casos extremos, las tasas fijas y variables, y las condiciones de error. No escribas código nuevo todavía; solo quiero la especificación lógica."

El agente procesará ese galimatías de código antiguo y te generará una especificación limpia y perfectamente legible:

# specs/legacy-fees/spec.md

## Reglas de Negocio (Sintaxis EARS)

CUANDO el volumen de transacciones mensuales del comercio supere los 50.000€, ENTONCES el sistema DEBERÁ aplicar una comisión variable del 1.2% más una tasa fija de 0.10€ por operación.

SI el comercio está marcado con la etiqueta 'Socio VIP', ENTONCES el sistema DEBERÁ eximir de la tasa fija de 0.10€, aplicando únicamente la comisión variable reducida del 0.9%.

SI la divisa de origen de la transacción es diferente a la de destino, ENTONCES el sistema DEBERÁ añadir una comisión por cambio de divisa del 0.5% adicional al cálculo base.

A partir de este Markdown, ya tienes un contrato ejecutable. Ahora puedes refactorizar esa función legacy de forma súper segura: dejas que el agente reescriba el código en TypeScript limpio basándose en esta especificación reconstruida, asegurándote de que no se pierde ni una sola de las sutiles reglas de negocio originales que estaban escondidas en el laberinto del código antiguo.

2. El Patrón "Delta-Spec" en Profundidad

Un error muy común cuando un equipo intenta adoptar el Spec-Driven Development es pensar que tienen que documentar absolutamente todo el sistema antes de poder programar algo. Esto es un suicidio técnico y organizativo.

En producción se utiliza el enfoque Delta-Spec (Especificación de Delta). La regla es muy simple: el código antiguo se queda en modo de solo lectura (Read-Only) para la IA, y solo especificamos el cambio que vamos a realizar.

┌────────────────────────────────────────────────────────────────────────┐
│                        Estrategia Delta-Spec                           │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│   Código Legacy del Monolito (Read-Only para la IA)                    │
│   - Sirve únicamente como contexto de integración e interfaces.        │
│                                                                        │
│                                  ▲                                     │
│                                  │ (Puntos de contacto y contratos)    │
│                                  ▼                                     │
│                                                                        │
│   Especificación de Delta (specs/descuentos.md)                        │
│   - Solo describe el NUEVO comportamiento (ej. sistema de cupones).    │
│   - Código nuevo aislado en módulos independientes (Wrappers/Adapters). │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

Al limitar el contexto de escritura de la IA exclusivamente al "delta" (el cambio actual), consigues tres cosas brutales:

Cero inflación de tokens: La IA no se satura leyendo ni procesando especificaciones gigantescas de partes de la aplicación que no vienen al caso.
Aislamiento de la entropía: El código nuevo se implementa bajo un estándar de máxima calidad (arquitectura limpia, tests unitarios exhaustivos), mientras que el monolito antiguo sigue funcionando en su rincón sin ser alterado de forma peligrosa.
Definición clara de fronteras: En tu especificación de delta, te enfocas únicamente en describir cómo se comunica lo nuevo con lo viejo utilizando contratos explícitos.

3. Control y Gobernanza de Múltiples Specs con Jira y Git

En cualquier equipo de ingeniería serio, vas a tener a varios desarrolladores trabajando en funcionalidades diferentes en paralelo. Es inevitable que te preguntes: ¿Qué pasa si mi tablero de Jira o Agility exige convenciones de nomenclatura estrictas para las ramas? ¿Cómo evito que la IA sufra amnesia o que los specs paralelos se pisen entre sí?

Ajustando los números secuenciales por defecto a la nomenclatura de tu Jira

Por defecto, cuando ejecutas el comando /speckit.specify, las plantillas out-of-the-box de Spec Kit escanean la carpeta specs/ y le asignan un número secuencial automático (como 001-, 002-) seguido del slug que extrae del prompt.

Sin embargo, en el día a día de una empresa donde tienes un ticket asignado en tu tablero (por ejemplo, la rama feature/S-143562_pasarela-pago), lo que buscas es mantener esa trazabilidad exacta sin depender de un contador secuencial numérico.

Para alinear el comportamiento de Spec Kit con tu rama de Git activa, tienes tres alternativas muy sencillas en la práctica:

Pasar el slug explícito en el prompt:

Puedes indicarle al comando el nombre exacto de la carpeta que quieres crear:

   /speckit.specify slug=S-143562_pasarela-pago Diseña el flujo de cobro con tarjetas...

Renombrar la carpeta generada (La solución inmediata):

Si la plantilla de Spec Kit te crea por defecto la carpeta specs/001-pasarela-pago, puedes renombrarla a mano en tu editor o terminal a specs/S-143562_pasarela-pago. Todos los comandos posteriores (/speckit.plan, /speckit.tasks) funcionarán a la perfección leyendo la especificación que esté activa dentro de esa carpeta renombrada.

Personalizar el Workflow en .agents/workflows/ (La automatización definitiva):

Dado que los workflows de Spec Kit son simples archivos Markdown editables dentro de tu propio repositorio, puedes abrir .agents/workflows/speckit.specify.md (o la plantilla en .specify/templates/) y añadir una regla estricta:

"Antes de asignar un número secuencial (001-, 002...), ejecuta git branch --show-current. Si estás situad@ en una rama de feature, utiliza el nombre exacto de la rama activa como nombre de la subcarpeta dentro de specs/."

De esta forma, tus especificaciones se guardarán limpiamente en specs/S-143562_pasarela-pago/, manteniendo una trazabilidad 1:1 entre tu gestor de tareas de negocio y el código del repositorio.

La Metodología del "Rifle de un solo disparo"

Tener varios specs de varios días de desarrollo conviviendo en paralelo puede acabar en desastre si los agentes de la IA empiezan a leer código a medias o a pisarse los archivos locales. Para evitarlo, los equipos de producción aplican de forma estricta la metodología del "Rifle de un solo disparo":

Regla 1: Un spec por rama de Git (Aislamiento absoluto de contexto). Nunca mezcles el desarrollo de dos specs diferentes en la misma rama local. Cuando cambias de rama en Git (git checkout), cambias de contexto completo. Los agentes de IA de editores como Antigravity solo consumirán la carpeta specs/S-143562_pasarela-pago/ correspondiente a tu rama activa. El resto de carpetas de especificaciones se quedan invisibles o se ignoran, protegiendo a la IA de la amnesia por saturación de contexto.
Regla 2: El ciclo de vida lineal y enfocado. El agente rinde de forma sobresaliente cuando le das un objetivo único y cerrado. El flujo recomendado es terminar por completo el ciclo de tu feature actual (Spec → Plan → Tasks → Implement → Analyze) hasta obtener el "OK" de convergencia, abrir la Pull Request en GitHub o GitLab, pasar la revisión humana, hacer el merge a la rama principal (main), y solo entonces borrar tu rama local y crear la siguiente desde el estado limpio de main.
Regla 3: Matar el "Contract Drift" en Integración Continua (CI). Si el desarrollador A modifica la base de datos de usuarios en su spec y el desarrollador B asume en su spec de pasarela de pago que esa tabla sigue igual en otra rama, el choque de integración puede ser doloroso. Para solucionarlo, antes de permitir que una rama se fusione en main, el pipeline de CI ejecuta de forma automatizada el comando /speckit.analyze. Este validador cruza los contratos de la rama con el estado de la rama principal; si detecta que la API de la pasarela de pago asume campos que ya no existen, la compilación de la CI falla inmediatamente antes de que el código roto llegue a producción.

Resumen de Aprendizaje

Si vas a liderar el desarrollo con SDD en bases de código reales, quédate con estos tres pilares de producción:

Reconstruye con Ingeniería Inversa: Usa el prompt de sparring técnico para que la IA lea el código de esa funcionalidad legacy enrevesada y te maquete el spec.md en Markdown. Te ahorrarás horas de análisis manual.
No sobre-documentes, usa "Delta-Specs": Deja el monolito antiguo en modo de solo lectura para los agentes e implementa las nuevas historias en módulos aislados con contratos explícitos.
Toma el control con Git y Jira: Ajusta o personaliza el workflow de Spec Kit para que use la nomenclatura de tus ramas. Spec Kit adaptará la jerarquía de specs a tu rama de forma transparente, manteniendo una organización de contexto impecable y sin amnesia en la IA.

En el siguiente artículo, Google Antigravity y MCP: Sandboxing, Autocorrección y la Nube, el cierre definitivo de esta serie, daremos el salto al entorno de ejecución más profesional del sector. Nos meteremos de lleno en Google Antigravity para explicar el funcionamiento de su Sandbox local agéntico (contenedores Linux aislados) y cómo configurar servidores MCP (Model Context Protocol) como Playwright MCP para que tus agentes ejecuten pruebas visuales interactivas en navegador real y se auto-corrijan los errores de consola de forma autónoma antes de entregarte la Pull Request. ¡Nos vemos en la última entrega!

📚 Serie Spec-Driven Development (SDD)

Extra: 🚀 CHEATSHEET: El Ciclo SDD en Google Antigravity con Spec Kit