De un párrafo a un análisis técnico completo: Cómo usamos IA para transformar las ideas en documentación

El problema: documentación de negocio incompleta

Todos los desarrolladores conocemos la situación: negocio nos envía un documento con los requisitos de una nueva funcionalidad. Lo abrimos con ilusión y nos encontramos con… un párrafo.

Esto es exactamente lo que nos llegó para el último proyecto en el que vamos a empezar a trabajar.

Un párrafo de 10 líneas y tres capturas de pantalla. Eso era todo.

¿Cómo pasamos de esto a un análisis técnico completo de más de 1.400 líneas y un documento funcional de negocio de más de 600 líneas? La respuesta: Instrucciones compartidas + IA como copiloto.

La solución: Instrucciones en un .md como estándar de documentación

En el equipo llevamos tiempo trabajando en la estandarización de la documentación, un conjunto de reglas compartidas que definen cómo debe estructurarse nuestra documentación técnica. Estas reglas actúan como una plantilla inteligente que la IA sigue para generar documentación completa y consistente.

Nuestras tres reglas fundamentales

Tenemos tres ficheros de reglas:

Fichero	Propósito
01-intake.md	Define la estructura obligatoria del documento (15 puntos) y las fases de desarrollo
02-techdoc-style.md	Establece el tono, formato de tablas, diagramas y especificaciones por pantalla
03-build-and-diagrams.md	Define los artefactos obligatorios: C4, ERD, OpenAPI, workflows

¿Qué garantizan estas reglas?

1. Estructura consistente: Todos los análisis técnicos tienen la misma estructura de 15 puntos
2. Trazabilidad completa: Mapeo entre entidades, APIs y pantallas
3. Diagramas obligatorios: ERD, flujos, estados, casos de uso
4. Especificaciones detalladas: Por cada pantalla: campos, validaciones, mensajes, estados

El proceso: de un párrafo a documentación enterprise

Paso 1: Alimentar la IA con contexto

Le proporcionamos a Cursor:

• El documento original de negocio (el párrafo + imágenes)
• Nuestras Instrucciones
• Acceso al código existente del proyecto
• Acceso al código de proyectos relacionados

Paso 2: Generación del análisis técnico

Con un simple prompt, la IA generó un primer borrador siguiendo la estructura de las instrucciones:

Tenemos que desarrollar una nueva funcionalidad que debe integrarse 
en el proyecto actual. La definición que nos ha dado negocio está 
en @funcionales/funcional. Utiliza las instrucciones definidas 
para generar un análisis técnico.

El resultado: un documento estructurado con todos los puntos obligatorios.

Paso 3: Iteración y refinamiento (el más importante)

Lo más potente no fue la generación inicial, sino la iteración. Fuimos refinando el documento con indicaciones específicas. Algunos ejemplos serían:

• «El soporte de múltiples idiomas debe ir a la fase 1»
• «La validez del UUID debe ser de 24 horas»
• «Los documentos firmados deben registrarse en el sistema de ficheros»
• «Elimina el código de ejemplo, no es necesario inicialmente»

Cada cambio se aplicaba manteniendo la consistencia del documento completo lo que nos hacía ir llegando, poco a poco, a la solución definitiva.

Paso 4: Generación del documento funcional ampliado

Una vez teníamos el análisis técnico, generamos un documento de negocio ampliado sin detalle técnico, pensado para:

• Validación por parte de negocio
• Primera toma de contacto para otros equipos
• Referencia de requisitos sin jerga técnica

Los resultados

Documento original de negocio

• 17 líneas de texto
• 3 imágenes
• Sin estructura

Documento funcional ampliado generado

• 631 líneas
• 12 secciones estructuradas
• Flujos visuales en ASCII
• Tablas de permisos, estados, reglas de negocio
• Casos especiales documentados
• Glosario de términos

Análisis técnico generado

• +1.400 líneas
• 8 secciones principales
• Diagramas Mermaid (ERD, estados, flujos)
• Especificaciones por pantalla
• Requisitos no funcionales
• Plan de pruebas
• Matriz de permisos

Qué incluye el documento funcional ampliado

El documento generado cubre todo lo que negocio y otros equipos necesitan saber:

• Actores y roles: Definición clara de quién hace qué en el sistema: trabajador, administrador, enfermera, médico.
• Flujo completo del proceso: Diagrama visual del proceso completo, desde la carga de datos hasta el cierre de la actuación.
• Pantallas y formularios: Descripción detallada de cada pantalla que verá cada actor.
• Comunicaciones: SMS, notificaciones, confirmaciones: qué se envía, cuándo, a quién.
• Reglas de negocio: reglas documentadas y organizadas por categoría (reglas de envío, de reintentos, de aceptación de históricos, …)
• Casos especiales: ¿Qué pasa cuando… el usuario no tiene smartphone, el teléfono es incorrecto, el enlace expira, el usuario rechaza, hay un error, …?
• Puntos pendientes: Lista clara de decisiones que aún debe tomar negocio, facilitando la comunicación.

Lecciones aprendidas

1. Las instrucciones compartidas son clave

Sin ellas, cada documento sería diferente. Con ellas, tenemos consistencia y completitud garantizadas.

2. La IA es un copiloto, no un autopiloto

La IA genera el 80%, pero el 20% de refinamiento humano es lo que convierte un borrador en documentación útil y con sentido.

3. Iterar es más eficiente que especificar todo de inicio

Es más fácil corregir y refinar que intentar definir todo en un único prompt.

4. Separar técnico de funcional

Tener dos documentos (funcional para negocio, técnico para desarrollo) mejora la comunicación entre equipos.

5. Documentar los pendientes

Marcar explícitamente lo que falta por definir evita malentendidos y acelera las reuniones de refinamiento.

Cómo replicar este proceso

Si quieres implementar algo similar en tu equipo:

1. Define tus instrucciones: Crea ficheros .md con la estructura que quieres para tus documentos
2. Incluye ejemplos: Las reglas funcionan mejor con ejemplos concretos de tablas, diagramas y formatos
3. Clasifica por fases: Obliga a separar lo que se hace ahora (Fase I) de lo que queda para después (Fase II)
4. Itera con la IA: No esperes perfección en el primer intento. El valor está en la iteración rápida

Conclusión

La combinación de instrucciones detalladas y asistentes de IA nos permite transformar requisitos vagos en documentación enterprise completa en cuestión de horas, no días.

El documento original de negocio tenía 17 líneas. Ahora tenemos:

• Un análisis técnico de +1.400 líneas listo para desarrollo
• Un documento funcional de +600 líneas para validación de negocio

Y lo más importante: ambos documentos son CONSISTENTES porque siguen las mismas reglas que todo el equipo comparte.

¿El párrafo inicial sigue siendo el mismo? Sí. Pero ahora sabemos exactamente qué pantallas construir, qué estados gestionar, qué mensajes mostrar, qué validaciones aplicar, y qué queda pendiente de definir.

Eso es documentación que sirve.