Cómo aplicar ingeniería inversa a una funcionalidad existente para generar artefactos de GitHub Spec Kit

La mayoría de los equipos no necesita ayuda para generar especificaciones de una funcionalidad completamente nueva.

Necesita ayuda para entender una funcionalidad existente lo suficientemente bien como para modificarla con seguridad.

Ese es el problema brownfield que me interesa abordar aquí. Ya tienes código. Ya tienes rutas, handlers, pruebas y casos límite extraños. Lo que no tienes es un conjunto claro de artefactos, como spec.md, plan.md y tasks.md, que le explique a un nuevo ingeniero, a un PM o a un agente de IA cómo funciona realmente la funcionalidad hoy.

Este artículo es la guía independiente que me habría gustado tener la primera vez que intenté hacer esto con GitHub Spec Kit y Cursor.

También complementa mi artículo más amplio sobre cómo integrar GitHub Spec Kit en repositorios existentes con Cursor. Ese artículo anterior cubre la configuración brownfield en términos generales. Este se enfoca en una pregunta más específica y práctica:

Si elijo una funcionalidad existente en un repositorio real, ¿qué hago primero, qué hago después y qué artefactos debería esperar al final?

Una aclaración importante desde el principio: al April 13, 2026, el README y la documentación actuales de GitHub Spec Kit enumeran comandos principales como /speckit.constitution, /speckit.specify, /speckit.plan y /speckit.tasks, y comandos opcionales como /speckit.clarify, /speckit.analyze y /speckit.checklist, pero no documentan un comando oficial /reverse dedicado a «convertir esta funcionalidad existente en artefactos».

Así que lo que sigue no es un flujo de trabajo oficial oculto. Es el modelo de trabajo brownfield que recomiendo para usar deliberadamente las etapas normales de Spec Kit y documentar el estado actual.

Las partes de este artículo respaldadas por las fuentes son:

• la instalación de Spec Kit en el directorio actual
• el uso de --ai cursor-agent
• el establecimiento temprano de una constitución
• la existencia y el propósito de los principales comandos /speckit.*

La secuencia brownfield de ingeniería inversa en sí es mi síntesis a partir de esos elementos.

TL;DR

• La ingeniería inversa con Spec Kit funciona mejor cuando eliges una funcionalidad de alcance acotado, no un subsistema completo.
• El modelo mental correcto no es «generar una funcionalidad nueva». Es «documentar la funcionalidad actual exactamente como funciona hoy».
• La mejor secuencia es:
  1. agregar Spec Kit al repositorio si aún no está
  2. redactar o actualizar la constitución brownfield a partir de evidencia del repositorio
  3. definir el alcance de una funcionalidad
  4. reunir evidencia en Cursor
  5. crear una rama solo para documentación
  6. ejecutar /speckit.specify
  7. ejecutar /speckit.clarify
  8. ejecutar /speckit.plan
  9. ejecutar /speckit.tasks, /speckit.checklist y /speckit.analyze
• Para el trabajo brownfield, la instrucción más importante es: no inventes mejoras mientras reconstruyes el estado actual.
• Mi resultado final preferido son dos ramas:
  • una rama que documente la funcionalidad actual
  • otra rama posterior que la mejore

Qué aprenderás aquí

• Cómo agregar GitHub Spec Kit a un repositorio existente que aún no lo tiene
• Cómo generar una constitución brownfield a partir de la evidencia actual del repositorio
• Cómo elegir el tipo de funcionalidad adecuado para aplicar ingeniería inversa
• Qué evidencia reunir antes de ejecutar cualquier comando de Spec Kit
• El orden exacto que usaría para los comandos de Spec Kit
• Cómo redactaría los prompts para mantener el resultado sustentado en el código existente
• Qué conjunto de artefactos esperaría al final
• Cómo cambia este flujo de trabajo para una funcionalidad pequeña frente a un sistema más grande y complejo

El orden exacto que usaría

Si le entregas este flujo de trabajo a un ingeniero de tu equipo, quiero que la respuesta a «¿qué hago primero?» sea evidente.

Esta es la secuencia que usaría:

1. Si hace falta, agrega GitHub Spec Kit al repositorio existente.
2. Redacta o actualiza la constitución brownfield a partir de evidencia real del repositorio.
3. Elige una funcionalidad con una superficie de producto clara.
4. Reúne la evidencia en Cursor antes de usar los comandos de Spec Kit para la funcionalidad.
5. Crea una rama de funcionalidad orientada a la documentación.
6. Usa /speckit.specify para registrar el comportamiento actual.
7. Usa /speckit.clarify para resolver las brechas evidentes.
8. Usa /speckit.plan para generar el conjunto de artefactos técnicos.
9. Usa /speckit.tasks, /speckit.checklist y /speckit.analyze para validar la reconstrucción.
10. Separa la documentación y la mejora en ramas distintas si planeas modificar la funcionalidad después.

Esa es la idea general. El resto del artículo explica cada paso en el orden en que lo haría.

Paso opcional 0: Agrega Spec Kit al repositorio si aún no está

Si el repositorio todavía no tiene GitHub Spec Kit instalado, lo haría primero para que el resto del flujo de trabajo tenga un lugar real dentro del repositorio.

Si primero quieres una instalación persistente de la CLI specify:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Luego, dentro del repositorio existente:

specify init --here --ai cursor-agent

Si prefieres una inicialización puntual sin instalar la CLI globalmente:

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai cursor-agent

Esto importa porque no quiero que el flujo de ingeniería inversa exista solo en el chat. Quiero que el repositorio tenga la estructura, los comandos, las plantillas y las carpetas de artefactos de Spec Kit que otros ingenieros puedan reutilizar en el futuro.

Si ya tienes Spec Kit en el repositorio, considera este paso una comprobación rápida de los requisitos previos y continúa.

Paso 1: Redacta una constitución brownfield a partir de la evidencia

Antes de aplicar ingeniería inversa a una funcionalidad, quiero tener establecidos los límites a nivel de repositorio.

Este es el paso que responde directamente a la pregunta que planteó Fayaz: ¿deberías crear primero las constituciones o especificar primero una funcionalidad?

Para un repositorio brownfield, mi respuesta es:

• si el repositorio aún no tiene una constitución útil, redacta primero la constitución
• si el repositorio ya tiene una constitución sólida, revísala brevemente y luego pasa a la funcionalidad

La razón es sencilla. Quiero que los artefactos de la funcionalidad se produzcan dentro de las restricciones adecuadas para todo el proyecto, no en el vacío.

El uso temprano de /speckit.constitution está respaldado por la guía de inicio rápido. Usar evidencia del repositorio para redactar una constitución específica para brownfield es la adaptación que recomiendo para repositorios existentes.

Usaría este prompt:

/speckit.constitution
Analyze this existing repository before drafting the constitution.

Use the current codebase, .cursor/rules, AGENTS.md, CI workflows, tests,
deployment files, and repo docs as evidence.

Create 6-10 durable principles only.
Separate project-wide invariants from feature-specific behavior.
Use MUST/SHOULD language.
For each principle, include:
- the rule
- why it exists in this project
- what kinds of future specs it should influence

Do not include temporary implementation details, current library preferences
unless they are a real team constraint, or aspirational best practices that are
not already supported by the repo.

Eso te da un punto de partida mucho más claro para todo lo que sigue.

No quiero que la constitución se convierta en una colección de consejos genéricos. Quiero que refleje el repositorio que realmente tienes:

• las verificaciones que ya exige
• los límites arquitectónicos que ya respeta
• las reglas operativas que ya le importan al equipo
• las normas de revisión que aparecen una y otra vez

Una vez que eso existe, la ingeniería inversa de la funcionalidad tiene un mejor marco de referencia.

Paso 2: Elige una funcionalidad, no un subsistema enorme

Este flujo de trabajo deja de funcionar rápidamente si el alcance inicial es impreciso.

Si le pides al agente que reconstruya:

• «el sistema de facturación»
• «la plataforma de autenticación»
• «la arquitectura de analítica»

el resultado normalmente será amplio, difuso y demasiado abstracto para confiar en él.

La ingeniería inversa funciona mucho mejor cuando la funcionalidad tiene una superficie de producto clara, por ejemplo:

• la aplicación de cupones durante el checkout
• la configuración de SSO y el inicio de sesión para un tenant
• la exportación de facturas a CSV
• el filtrado de eventos en un dashboard de telemetría

Me gustan funcionalidades como estas porque me dan algo concreto que rastrear:

• por dónde entra un usuario
• qué acciones puede realizar
• qué API o jobs intervienen
• cómo se ven el éxito y los errores

Esa es la primera decisión importante sobre el alcance de la funcionalidad, y pesa más que la redacción específica del prompt que usarás después.

Paso 3: Reúne evidencia en Cursor antes de ejecutar los comandos de Spec Kit para la funcionalidad

Creo que este es el paso que la gente omite con demasiada frecuencia.

Antes de ejecutar /speckit.specify, quiero que Cursor me ayude a identificar los límites de la funcionalidad y la evidencia que describe su comportamiento actual.

Para una funcionalidad brownfield, reuniría:

• rutas o páginas de la interfaz
• menús, botones y puntos de entrada
• endpoints de API y estructuras de solicitudes y respuestas
• entidades de dominio, tablas de base de datos o registros almacenados
• jobs en segundo plano, programadores de tareas o webhooks
• feature flags
• eventos de logging, analítica o auditoría
• pruebas que ya describen el comportamiento
• documentación, capturas de pantalla y runbooks, si existen

El objetivo es sencillo: quiero darle al agente un conjunto de evidencias para que reconstruya la funcionalidad a partir del repositorio, en lugar de llenar los vacíos con una explicación «que suene bien».

Si solo recuerdas un principio de este artículo, que sea este:

Spec Kit es mucho más útil para aplicar ingeniería inversa cuando la evidencia limita al agente, en lugar de dejarlo actuar con optimismo.

Paso 4: Crea una rama solo para documentación

Como /speckit.specify está diseñado para trabajar con ramas de funcionalidad, prefiero aprovechar ese enfoque en lugar de luchar contra él.

Prefiero nombres de rama que dejen claro el propósito:

050-document-existing-telemetry-dashboard

o:

050-baseline-invoice-csv-export-current-state

Esa convención de nombres aporta dos beneficios:

1. Les indica a quienes revisan que esta rama documenta el comportamiento actual, no que entrega un rediseño.
2. Mantiene separada la futura rama de mejora si decides mejorar la funcionalidad más adelante.

Para los equipos brownfield, esa separación importa. La limpieza de documentación y los cambios de comportamiento son mucho más fáciles de revisar cuando no están mezclados en el mismo diff.

Paso 5: Usa /speckit.specify para registrar el comportamiento actual

Este es el prompt más importante del flujo porque marca la pauta para todo lo que sigue.

Un prompt incorrecto sería algo como:

Create a new feature for invoice CSV export

Un prompt más seguro sería:

/speckit.specify
Reverse-engineer the existing invoice CSV export feature from this repository.

Describe the feature exactly as it works today.
Infer requirements, user journeys, system boundaries, and acceptance criteria
from the current code, tests, routes, API handlers, data access patterns,
background jobs, and existing docs.

Do not propose enhancements.
Do not redesign the feature.
Mark uncertainty explicitly instead of guessing.

Ese cambio de enfoque es lo que convierte a Spec Kit de «generador de ideas» en «herramienta para documentar el estado actual».

Lo que quiero obtener de esta etapa es un spec.md que registre:

• quién puede usar la funcionalidad
• cómo accede a ella
• qué puede hacer
• qué hace el sistema en respuesta
• qué restricciones y modos de falla ya existen

No lo que la funcionalidad debería llegar a ser. Lo que es.

Paso 6: Usa /speckit.clarify para convertir «probablemente» en «lo sabemos»

Una vez que existe la primera especificación, asumo que todavía hay vacíos.

Eso es normal en el trabajo brownfield porque el comportamiento real suele estar repartido entre:

• código
• pruebas
• supuestos de la interfaz
• restricciones operativas no documentadas

Así que el siguiente paso no es implementar. El siguiente paso es aclarar.

Usaría un prompt como este:

/speckit.clarify
Clarify gaps in the reverse-engineered spec for the invoice CSV export feature.
Focus on permissions, export limits, file format details, failure modes,
retry behavior, and any places where tests or code paths disagree.

Aquí es donde el flujo de trabajo empieza a ser útil para los equipos, no solo para una persona.

Una buena revisión de aclaración saca a la luz preguntas como:

• quién tiene permiso para exportar
• si se permiten exportaciones vacías
• si el esquema CSV es estable
• cómo se presentan los errores en la interfaz
• qué casos límite están realmente cubiertos por pruebas

En el trabajo greenfield, la aclaración ayuda a definir mejor el futuro.

En el trabajo brownfield, la aclaración ayuda a evitar que tu documentación mienta.

Paso 7: Usa /speckit.plan para generar el conjunto de artefactos técnicos

Cuando estoy satisfecho con que la especificación describe suficientemente bien la funcionalidad actual, uso /speckit.plan para inferir la arquitectura técnica que la rodea.

Mi prompt sería algo así:

/speckit.plan
Create an implementation plan that documents the current architecture of the
existing invoice CSV export feature.

Infer the data model, component boundaries, integration points, API contracts,
background processing, test scenarios, and operational constraints from the
current implementation.

Prefer documenting the existing architecture over proposing a new one.
If the current implementation has inconsistencies, record them clearly.
Generate contracts only for externally observable APIs, events, or interfaces
that this feature currently depends on.

En este paso espero que Spec Kit genere el conjunto principal de artefactos de la funcionalidad, normalmente algo como:

specs/050-baseline-invoice-csv-export-current-state/
  spec.md
  plan.md
  research.md
  data-model.md
  quickstart.md
  contracts/

La estructura exacta puede variar según las plantillas y el resultado del plan, pero ese es el objetivo adecuado.

En este punto ya no solo estoy reconstruyendo una historia de usuario. Estoy creando una carpeta duradera para la funcionalidad que otras personas pueden revisar, usar para aprender y tomar como base para futuras mejoras.

Paso 8: Genera los artefactos de ejecución y validación

Una vez que la especificación y el plan están listos, continúo con la secuencia.

Primero:

/speckit.tasks

Para la ingeniería inversa, trato tasks.md de una de estas dos maneras:

• como la hoja de ruta para validar si la comprensión reconstruida está completa
• como el punto de partida para la siguiente mejora o refactorización

Luego genero una lista de verificación para comprobar que no falte nada:

/speckit.checklist
Generate a reverse-engineering completeness checklist for the invoice CSV
export feature.

Check whether the artifacts cover:
- user-visible behavior
- routes and entry points
- permissions and access control
- API contracts
- data model and persistence
- background jobs or async flows
- failure modes
- tests and validation scenarios
- known inconsistencies or undocumented assumptions

La guía oficial de inicio rápido muestra /speckit.checklist antes, durante la validación de la especificación. Para la ingeniería inversa brownfield, también me gusta usarlo aquí como una auditoría de completitud en una etapa avanzada, una vez que existe el conjunto completo de artefactos.

Finalmente, ejecuto:

/speckit.analyze

Este es el último paso para generar confianza.

En el trabajo greenfield, el análisis ayuda a detectar contradicciones entre la especificación, el plan y las tareas.

En el trabajo brownfield, importa aún más porque ayuda a exponer contradicciones entre:

• la especificación reconstruida
• el plan inferido
• las tareas generadas
• la realidad del código existente del que partiste

Eso es lo que hace que el resultado sea útil, en lugar de simplemente verse bien.

El conjunto de artefactos que querría al final

Si el proceso de ingeniería inversa salió bien, quiero que la carpeta de la funcionalidad se vea más o menos así:

specs/050-baseline-invoice-csv-export-current-state/
  spec.md
  plan.md
  research.md
  data-model.md
  quickstart.md
  contracts/
  tasks.md
  checklist artifact from /speckit.checklist

Eso es suficiente para hacer tres cosas valiosas:

• incorporar más rápido a un nuevo ingeniero al trabajo con la funcionalidad
• revisar la funcionalidad con un PM usando artefactos estables en lugar del historial de chat
• comenzar la siguiente mejora con mucha menos ambigüedad

Ese último punto es el verdadero beneficio.

El resultado no debería ser «creamos algo de markdown».

El resultado debería ser «ahora tenemos una fuente de verdad de referencia para cambios futuros».

Un ejemplo sencillo: exportación de facturas a CSV

Uso la exportación de facturas a CSV como ejemplo a lo largo del artículo porque es el tipo de funcionalidad brownfield lo suficientemente pequeña para acotar y lo suficientemente rica para resultar útil:

• tiene un punto de entrada claro
• normalmente tiene reglas de permisos
• tiene una salida observable
• puede implicar colas o procesamiento asíncrono
• a menudo tiene casos límite relacionados con resultados vacíos, formato y reintentos

Si estuviera reconstruyendo esa funcionalidad, querría que los artefactos resultantes respondieran preguntas como:

• qué usuarios pueden iniciar la exportación
• si la exportación se ejecuta de forma síncrona o asíncrona
• qué filtros afectan a las filas exportadas
• si el esquema CSV es fijo o tiene versiones
• qué sucede si la exportación está vacía, tarda demasiado o falla
• qué pruebas demuestran el comportamiento actual

Ese es el tipo de funcionalidad para la que la ingeniería inversa con Spec Kit puede ayudar de inmediato con el onboarding, el soporte y la planificación de mejoras futuras.

Cómo cambia esto para una funcionalidad pequeña frente a un sistema grande

El flujo de trabajo se mantiene. El riesgo cambia según el alcance.

Para una funcionalidad pequeña:

• la evidencia es más fácil de reunir
• el comportamiento actual es más fácil de verificar
• los artefactos generados son más fáciles de revisar de principio a fin

Para un sistema más grande o más antiguo:

• los límites son menos evidentes
• las pruebas pueden contradecir la interfaz
• el conocimiento operativo puede estar en las personas y no en la documentación
• el acoplamiento oculto hace que sea más difícil describir claramente el «comportamiento actual»

Por eso empezaría con una funcionalidad más pequeña, incluso si el objetivo a largo plazo es documentar un área mucho más grande.

El objetivo no es demostrar que Spec Kit puede describir toda tu plataforma desde el primer día.

El objetivo es establecer un flujo de ingeniería inversa repetible en el que tu equipo pueda confiar.

Mi modelo recomendado de ramas

Si sé que vamos a modificar la funcionalidad después de documentarla, dividiría el trabajo en dos ramas:

050-baseline-invoice-csv-export-current-state
051-enhance-invoice-csv-export

Primera rama:

• reconstruir el estado actual mediante ingeniería inversa
• generar y revisar el conjunto de artefactos
• integrar la documentación de referencia

Segunda rama:

• crear la especificación de la mejora
• reutilizar los nuevos artefactos de referencia
• implementar con mucha menos ambigüedad

No es el flujo más rápido posible.

Es el más claro que he encontrado hasta ahora si te importan una documentación fácil de mantener, un mejor onboarding y el trabajo futuro asistido por IA que parte de una base duradera.

Qué le diría a un equipo de ingeniería que haga primero

Si mañana tuviera que enseñar esto a un equipo, no empezaría con todo el repositorio.

Les diría:

1. agreguen Spec Kit al repositorio si aún no está
2. generen o actualicen la constitución brownfield a partir de la evidencia
3. elijan una funcionalidad de alcance acotado
4. reúnan la evidencia
5. creen una rama solo para documentación
6. ejecuten en orden el flujo de Spec Kit para la funcionalidad
7. revisen los artefactos tanto con ingeniería como con producto
8. solo entonces comiencen la siguiente mejora

Esa secuencia es la verdadera lección.

Una vez que el equipo confía en ella para una funcionalidad, el flujo de trabajo se vuelve mucho más fácil de repetir.

La brecha en el producto sigue existiendo

Quiero ser explícito al respecto porque importa.

La comunidad ya ha señalado que existe demanda de:

• un flujo de ingeniería inversa más claro
• un mejor flujo para refinar especificaciones en el mismo lugar
• una evolución brownfield más fluida después de que existe el primer conjunto de artefactos

Así que no presento esto como «la solución mágica oficial».

Lo presento como el modelo de trabajo más claro que he encontrado con los elementos disponibles actualmente.

Y hasta que GitHub Spec Kit ofrezca una vía de ingeniería inversa como funcionalidad de primera clase, eso basta para que este enfoque sea realmente útil.

Conclusión

Si tuviera que resumir todo el artículo en una sola frase, sería esta:

No le pidas a Spec Kit que imagine una mejor versión de tu funcionalidad existente antes de pedirle que documente la funcionalidad que ya tienes.

Para los equipos brownfield, ese orden lo cambia todo.

Lista de fuentes

Validado con estas fuentes primarias el April 13, 2026:

• README de GitHub Spec Kit
• Guía de inicio rápido de Spec Kit
• Guía de instalación de Spec Kit
• Guía de actualización de Spec Kit
• Documentación de Cursor: uso de la CLI
• Documentación de Cursor: reglas