Escribir Historias de Usuario para GenAI

Hola a todos,

En el desarrollo de aplicaciones basadas en Inteligencia Artificial Generativa (GenAI), la definición de historias de usuario juega un papel crucial para garantizar que los modelos entreguen valor real a los usuarios. A diferencia de las historias tradicionales de software, en GenAI debemos considerar aspectos como el procesamiento de lenguaje natural, la calidad de respuestas generadas y la iteración con datos reales.

Este artículo explora cómo escribir historias de usuario efectivas para proyectos de GenAI, incluyendo criterios de aceptación en prosa y en BDD (Behavior-Driven Development), casos de agentes inteligentes y estrategias para mantener el tiempo de desarrollo hasta preproducción en menos de 36 horas, que es el tiempo aproximado para construir una historia de usuario.

Estructura de una Historia de Usuario para proyectos o funcionalidades con GenAI

Las historias de usuario para GenAI pueden seguir la estructura popular:

Como [rol del usuario],
quiero [acción],
para [objetivo o beneficio].

Sin embargo, es fundamental incluir:

• Entradas esperadas: tipo de datos que el usuario proporcionará.
• Salidas esperadas: qué debe generar el modelo en respuesta, incluyendo la descripción y ejemplos de lo que se espera obtener.
• Criterios de calidad: precisión, relevancia y tiempos de respuesta (1).
• Limitaciones: alcance de la funcionalidad dentro del ciclo de desarrollo ágil.

Dado que los modelos de IA son probabilísticos, la validación de historias debe centrarse en métricas cuantificables y validaciones iterativas con usuarios.

Ejemplo 1: Generación de Resúmenes Automáticos

Como usuario de un sistema de análisis de documentos,
quiero que la IA genere un resumen preciso de un documento PDF,
para poder extraer información clave rápidamente.

Criterios de Aceptación en Prosa

• El resumen debe reducir el contenido original en al menos un 70% manteniendo coherencia.
• Debe extraer y sintetizar los puntos clave sin omitir información esencial.
• El tiempo de respuesta no debe superar los 5 segundos por página procesada.
• La salida debe estar estructurada en párrafos y permitir correcciones manuales por parte del usuario.

Criterios de Aceptación en BDD (gherkin)

Escenario: Generación exitosa de un resumen  

• Dado un documento PDF de más de 10 páginas  
• Cuando el usuario solicita un resumen  
• Entonces el sistema genera un texto condensado  
• Y el contenido preserva los puntos clave  
• Y el tiempo de procesamiento no supera los 5 segundos por página 

¿Qué es RAG y por qué importa en historias de usuario?

RAG (Retrieval-Augmented Generation) combina recuperación de información con modelos generativos para mejorar la precisión de las respuestas. En lugar de depender solo del conocimiento estático del modelo, RAG consulta una base de datos de documentos relevantes en tiempo real.

Cuando escribimos historias de usuario para sistemas basados en RAG, debemos considerar:

• Cómo se selecciona la información relevante (método de recuperación).
• Cómo se combinan los datos recuperados con la generación de respuestas.
• Qué métricas de calidad asegurarán que la respuesta sea útil y precisa.

Ejemplo 2: Uso de RAG para Respuestas Basadas en Documentos

Como analista de servicio al cliente,
quiero que la IA consulte documentación técnica y genere respuestas a preguntas frecuentes,
para reducir el tiempo de búsqueda de información en manuales.

Criterios de Aceptación en Prosa

• La IA debe buscar respuestas en documentos actualizados antes de generar una respuesta.
• Si no encuentra información relevante, debe indicar que no tiene suficiente contexto.
• La confianza en la respuesta debe ser superior al 85%.
• El tiempo de respuesta no debe superar los 3 segundos.

Criterios de Aceptación en BDD

Escenario: Generación de respuestas con RAG

• Given un usuario con una consulta técnica 
• Cuando la IA recibe la pregunta 
• Entonces busca la información en la base de documentos 
• Y combina los datos encontrados con su modelo generativo
• Y genera una respuesta precisa con referencias And la respuesta tiene una confianza superior al 85%

Ejemplo 3: Uso de Embeddings para Búsqueda Semántica

Como investigador,
quiero encontrar artículos académicos relevantes mediante búsqueda semántica,
para acelerar la revisión de literatura sin depender de coincidencias exactas de palabras clave.

Criterios de Aceptación en Prosa

• El sistema debe utilizar embeddings para representar documentos en un espacio vectorial.
• La búsqueda debe devolver documentos semánticamente similares, no solo coincidencias exactas.
• Los resultados deben estar ordenados por relevancia en función de la consulta.
• El tiempo de respuesta no debe superar los 2 segundos.

Criterios de Aceptación en BDD

Escenario: Búsqueda semántica con embeddings   
Dada una consulta sobre inteligencia artificial  
Cuando el usuario realiza una búsqueda  
Entonces el sistema devuelve artículos relevantes  
Y la similitud semántica se basa en embeddings  
Y los resultados se ordenan por relevancia  

Ejemplo de Historia de Usuario con Agentes de IA Autónomos

Los agentes de IA pueden realizar tareas complejas en múltiples pasos, como recopilar información, tomar decisiones y ejecutar acciones en nombre del usuario. Al escribir historias de usuario para agentes, es clave definir:

• Cuándo deben actuar automáticamente y cuándo necesitan intervención humana.
• Cómo gestionan interacciones multi-turno.
• Cómo garantizan que sus decisiones sean explicables y verificables.

Ejemplo 4: Agente de Atención al Cliente con IA

Como usuario de una plataforma de servicio al cliente,
quiero que el chatbot GenAI me ayude a solucionar preguntas frecuentes,
para recibir respuestas rápidas sin esperar a un agente humano.

Criterios de Aceptación en Prosa

• El chatbot debe responder con un nivel de confianza del 85% o superior basado en su entrenamiento.
• Si la consulta es ambigua, debe solicitar aclaraciones en lugar de dar una respuesta incorrecta.
• Si la pregunta no está en la base de datos, debe redirigir a un agente humano.
• El tiempo de respuesta debe ser menor a 2 segundos.

Criterios de Aceptación en BDD (gherkin)

Escenario: Chatbot responde correctamente  

Dado un usuario con una consulta sobre facturación  
Cuando el usuario pregunta “¿Cuánto debo pagar este mes?”  
Entonces el chatbot responde con el monto exacto  
Y la respuesta tiene una confianza superior al 85%  
Y el tiempo de respuesta es menor a 2 segundos 

Ejemplo 5: Agente de IA para Gestión de Correo Electrónico

Como ejecutivo ocupado,
quiero que un agente de IA clasifique y responda automáticamente correos electrónicos,
para reducir el tiempo dedicado a la gestión del correo y poder dedicarme a otras tareas.

Criterios de Aceptación en Prosa

• La IA debe clasificar correos en categorías como "Urgente", "Esperando Respuesta" y "Para Leer Luego".
• Si detecta preguntas frecuentes, debe generar una respuesta basada en plantillas predefinidas.
• Para correos que requieren atención humana, debe sugerir respuestas sin enviarlas automáticamente.
• Debe mejorar con el tiempo en función del feedback del usuario.

Criterios de Aceptación en BDD

Eecenario: Clasificación automática de correos  
Dada una bandeja de entrada con correos nuevos  
Cuando el agente los procesa  
Entonces clasifica cada correo en una categoría adecuada  
Y sugiere respuestas para preguntas frecuentes  
Y envía solo aquellas que el usuario haya autorizado
  

Ejemplo 6: Agente de IA para Automatización de Tareas Repetitivas

Como gestor de proyectos,
quiero que un agente de IA genere reportes semanales automáticamente,
para reducir el tiempo dedicado a la creación manual de informes.

Criterios de Aceptación en Prosa

• El agente debe recopilar datos desde múltiples fuentes (JIRA, Notion, Google Sheets).
• Debe estructurar la información en un formato predefinido y visualmente claro.
• Si detecta anomalías en los datos, debe alertar al usuario en lugar de generar el informe sin verificación.
• El tiempo de generación no debe superar los 5 minutos.

Criterios de Aceptación en BDD

Escenario: Generación de reportes automatizados  
Dado un conjunto de datos de proyectos activos  
Cuando el agente ejecuta su proceso semanal  
Entonces recopila la información desde las fuentes disponibles  
Y genera un informe en el formato solicitado  
Y alerta al usuario si detecta anomalías  

Garantizando Historias de Usuario Pequeñas (≤36 horas hasta Preproducción)

Para garantizar que las historias de usuario sean pequeñas y manejables una buena práctica es que tomen menos de 36 horas desde que se realiza su análisis, se realiza su desarrollo, se ejecutan las pruebas y se hasta preproducción o el ambiente definido en la Definition of Done, para esto se sugiere  las siguientes estrategias:

1. Definir historias con alcance limitado

   • Enfocarse en una funcionalidad específica dentro del sistema.
   • Evitar historias demasiado generales o con dependencias complejas.

2. Validación rápida

   • Implementar pruebas automáticas con métricas de precisión.
   • Usar entornos de pruebas con datos reales desde el inicio.

3. Integración sencilla

   • Aprovechar APIs existentes en lugar de construir modelos desde cero.
   • Definir entradas y salidas claras para reducir ajustes manuales.

4. Despliegue incremental

• Probar en entornos de staging antes de la implementación en producción.
• Obtener feedback temprano de usuarios reales para ajustar modelos.

Ejemplo de Historia Pequeña y Ejecutable en ≤36 horas

Como editor de contenido,
quiero que la IA sugiera mejoras gramaticales en mi texto,
para mejorar la claridad sin cambiar el significado.

Criterios de Aceptación en Prosa

• La IA debe detectar errores gramaticales sin modificar el estilo del usuario.
• Las sugerencias deben incluir una explicación breve de cada corrección.
• El tiempo de procesamiento debe ser menor a 2 segundos por párrafo.

Conclusión

Las historias de usuario bien escritas son clave para garantizar el éxito de proyectos de GenAI. Para lograrlo, debemos:

• Definir claramente las entradas y salidas esperadas.
• Escribir criterios de aceptación en prosa o en BDD.
• Los agentes de IA pueden automatizar tareas repetitivas, pero requieren criterios de aceptación claros para garantizar su efectividad.
• Diseñar historias pequeñas y ejecutables en menos de 36 horas, permitiendo iteraciones rápidas y mejoras continuas.

Siguiendo estos principios, las organizaciones pueden desarrollar soluciones de GenAI más efectivas, ágiles y centradas en el usuario.

Saludos ágiles,

Jorge Abad

Notas:

1. En el ámbito de la inteligencia artificial y de la Inteligencia Artificial Generativa, existen un sinnumero de métricas para contextos y usos específicos tales como: F1score, Perplejidad (Perplexity - PPL),Exactitud BLEU (Bilingual Evaluation Understudy), ROUGE (Recall-Oriented Understudy for Gisting Evaluation), y un largo etcétera, por lo que se sugiere conocer estás metricas y hacer uso de ellas para garantizar coherencia y confiabilidad en los resultados.