De la idea a una especificación ejecutable con IA

1. Objetivos de la semana

2. El gran problema: "quiero una aplicación"

Quiero una aplicación para gestionar empleados.

El mismo requisito mejor definido

Como responsable de recursos humanos,

quiero poder crear un empleado indicando:

- nombre;
- apellidos;
- email;
- categoría;
- fecha de incorporación;

para poder mantener actualizado
el inventario de empleados.

Ahora tenemos mucha más información. Pero todavía falta.

3. Requirements Engineering

Requirements Engineering es el proceso de descubrir, documentar, analizar, validar y gestionar las necesidades que debe satisfacer un sistema.

Tipos de requisitos

Ejemplo completo

Ejercicio

Convierte:

"Quiero que el usuario pueda gestionar tareas."

en al menos 8 requisitos concretos.

4. User Stories

Una User Story describe una necesidad desde el punto de vista del usuario.

Formato clásico

Como [TIPO DE USUARIO]

quiero [ACCIÓN / OBJETIVO]

para [BENEFICIO / MOTIVACIÓN].

Ejemplo

Como gestor de proyectos,

quiero asignar una tarea a un empleado,

para saber quién es responsable de realizarla.

Mal ejemplo

Crear tabla task_assignment.

Esto describe una implementación técnica, no una necesidad del usuario.

Buen ejemplo

Como gestor de proyectos,

quiero asignar una tarea a un empleado,

para que quede claro quién es responsable.

User Story demasiado grande

Como usuario quiero gestionar toda mi cuenta,
mis proyectos, mis tareas, mis documentos,
mis preferencias y mis notificaciones.

Esto probablemente debería dividirse.

Descomposición

US-01
Crear proyecto

US-02
Editar proyecto

US-03
Eliminar proyecto

US-04
Crear tarea

US-05
Asignar tarea

US-06
Completar tarea

US-07
Configurar notificaciones

5. Acceptance Criteria

Los criterios de aceptación son una de las herramientas más importantes cuando desarrollamos con IA.

Ejemplo

USER STORY

Como usuario,

quiero crear una tarea,

para organizar mi trabajo.


CRITERIOS DE ACEPTACIÓN

AC-01
El usuario puede introducir un título.


AC-02
El título es obligatorio.


AC-03
El título debe tener entre 1 y 200 caracteres.


AC-04
Al guardar correctamente,
la tarea aparece en la lista.


AC-05
Si falta el título,
se muestra un mensaje de error.


AC-06
La tarea se guarda en la base de datos.

¿Por qué son tan importantes para la IA?

Porque permiten transformar una conversación subjetiva en condiciones verificables.

REQUISITO

↓

CRITERIO

↓

TEST

↓

RESULTADO

PASS / FAIL

Ejemplo de criterio ambiguo

La aplicación debe ser rápida.

Mejor

El endpoint GET /api/tasks debe responder
en menos de 500 ms en condiciones normales
con 1000 tareas.

Otro ejemplo

Mal:

El formulario debe ser fácil de usar.

Mejor:

El usuario debe poder crear una tarea
sin abandonar la página actual.

Ejercicio

Transforma:

"El login debe ser seguro."

en al menos 5 criterios comprobables.

6. Edge Cases

Los casos normales son fáciles. Los problemas reales aparecen en las excepciones.

Ejemplo: crear usuario

Camino feliz:

Usuario introduce email válido

↓

Sistema valida

↓

Usuario creado

¿Qué puede salir mal?

• Email vacío.
• Email inválido.
• Email duplicado.
• Email con espacios.
• Email extremadamente largo.
• Password vacía.
• Password demasiado corta.
• Password comprometida.
• Error de base de datos.
• Usuario ya existente.

Matriz de casos

Prompt para descubrir Edge Cases

Analiza esta funcionalidad:

[DESCRIPCIÓN]

Actúa como QA Senior.

Identifica:

1. Happy paths.
2. Validation errors.
3. Boundary conditions.
4. Security issues.
5. Concurrency problems.
6. Data consistency problems.
7. Integration failures.
8. UX failures.

No escribas código.

Devuelve una tabla con:

Caso
Entrada
Resultado esperado
Prioridad

7. Specification-Driven Development

A partir de ahora empezaremos a trabajar con una idea fundamental: La especificación es la fuente de verdad.

Estructura recomendada

docs/
│
├── product.md
│
├── requirements/
│   ├── US-001-login.md
│   ├── US-002-register.md
│   └── US-003-create-task.md
│
├── architecture/
│   └── architecture.md
│
├── api/
│   └── api.md
│
└── testing/
    └── test-plan.md

Plantilla de Specification

# US-003 — Crear tarea

## Objetivo

Permitir al usuario crear una tarea.

## Actor

Usuario autenticado.

## Precondiciones

El usuario debe estar autenticado.

## User Story

Como usuario,
quiero crear una tarea,
para organizar mi trabajo.

## Functional Requirements

FR-01
El título es obligatorio.

FR-02
La descripción es opcional.

FR-03
La prioridad puede ser:
LOW, MEDIUM, HIGH.

## Acceptance Criteria

AC-01
...

AC-02
...

## Edge Cases

EC-01
Título vacío.

EC-02
Título demasiado largo.

EC-03
Error de base de datos.

## Security

...

## Tests

...

## Out of Scope

...

¿Por qué "Out of Scope"?

Porque decirle a la IA qué NO debe hacer es tan importante como decirle qué debe hacer.

IN SCOPE

Crear tarea.


OUT OF SCOPE

- Reorganizar arquitectura.
- Cambiar framework.
- Crear sistema de notificaciones.
- Crear aplicación móvil.
- Cambiar autenticación.

8. Cómo trabajar con IA para crear especificaciones

Prompt 1 — Analista de negocio

Actúa como Business Analyst Senior.

Tengo esta necesidad:

"Quiero que los gestores puedan
asignar empleados a proyectos."

No escribas código.

Necesito:

1. Actores.
2. Objetivo.
3. User Stories.
4. Requisitos funcionales.
5. Requisitos no funcionales.
6. Reglas de negocio.
7. Edge Cases.
8. Criterios de aceptación.
9. Preguntas que faltan por resolver.

No inventes decisiones.
Cuando falte información,
indícalo explícitamente.

Prompt 2 — Product Manager

Actúa como Product Manager.

Revisa estos requisitos:

[PEGAR REQUISITOS]

Busca:

- ambigüedad;
- duplicaciones;
- contradicciones;
- requisitos innecesarios;
- funcionalidades demasiado grandes;
- funcionalidades que faltan.

Devuelve una lista priorizada.

No escribas código.

Prompt 3 — QA

Actúa como QA Lead.

A partir de esta specification:

[PEGAR SPEC]

Genera:

- casos positivos;
- casos negativos;
- edge cases;
- casos de seguridad;
- casos de integración;
- casos de regresión.

Cada caso debe incluir:

ID
Descripción
Precondiciones
Entrada
Resultado esperado
Prioridad

Prompt 4 — Software Architect

Actúa como Software Architect.

A partir de esta especificación:

[PEGAR SPEC]

Analiza si los requisitos son técnicamente
implementables.

Identifica:

- componentes;
- servicios;
- entidades;
- APIs;
- dependencias;
- riesgos.

No implementes.

Si una decisión requiere información
que no tenemos, pregunta antes de asumir.

IDEA
 ↓
BUSINESS ANALYST
 ↓
PRODUCT MANAGER
 ↓
ARCHITECT
 ↓
DEVELOPER
 ↓
QA
 ↓
CODE REVIEW
 ↓
RELEASE

9. Workflow completo

10. Proyecto práctico de la semana

Contexto

Una empresa necesita una aplicación donde sus empleados puedan solicitar vacaciones y los responsables puedan aprobarlas o rechazarlas.

Requisito inicial

"Queremos una aplicación para gestionar vacaciones."

Trabajo del alumno

Fase 1 — Descubrimiento

docs/product.md

• ¿Quién utiliza la aplicación?
• ¿Qué problema resuelve?
• ¿Qué procesos existen?
• ¿Qué información necesitamos?
• ¿Qué funcionalidades son imprescindibles?

Fase 2 — User Stories

US-001
Solicitar vacaciones

US-002
Consultar vacaciones

US-003
Aprobar vacaciones

US-004
Rechazar vacaciones

US-005
Cancelar solicitud

Fase 3 — Acceptance Criteria

Fase 4 — Edge Cases

Fase 5 — Reglas de negocio

RULE-001

Un empleado no puede solicitar
dos periodos que se solapen.


RULE-002

Solo un responsable autorizado
puede aprobar solicitudes.


RULE-003

Una solicitud aprobada no puede
ser modificada directamente.

Fase 6 — Specification

docs/requirements/

Fase 7 — Revisión con IA

BUSINESS ANALYST
        ↓
PRODUCT MANAGER
        ↓
QA LEAD

11. Ejercicios prácticos

El sistema debe permitir
gestionar empleados rápidamente.

"El usuario necesita recuperar su contraseña."

Como usuario,

quiero poder recuperar mi contraseña,

para recuperar el acceso a mi cuenta
si la he olvidado.

Como usuario quiero eliminar una tarea.

"Permitir crear proyectos."

12. Challenge avanzado

"Quiero una aplicación para gestionar
empleados que están en bench."

01 — Product Vision

02 — Personas / Actors

03 — Functional Requirements

04 — Non-Functional Requirements

05 — User Stories

06 — Acceptance Criteria

07 — Business Rules

08 — Edge Cases

09 — Security Requirements

10 — Out of Scope

11 — Data Requirements

12 — API Requirements

13 — UX Requirements

14 — Test Scenarios

15 — Final Specification

Regla

No permitas que la IA invente requisitos sin marcarlos. Utiliza:

[CONFIRMAR]

[SUPOSICIÓN]

[DECISIÓN]

[NO DEFINIDO]

Esto es extremadamente importante. La IA tiende a rellenar huecos. Un buen desarrollador aprende a distinguir entre información conocida e información inventada.

13. Test de evaluación

14. Recursos externos

15. Checklist de finalización

16. Autoevaluación

17. Conclusión

NO:

"IA, constrúyeme una aplicación."


SÍ:

"Este es el problema.

Estos son los usuarios.

Estos son los requisitos.

Estas son las reglas.

Estos son los criterios de aceptación.

Estos son los casos límite.

Esto está fuera del alcance.

Esta es la specification.

Ahora analiza cómo implementarlo."

SPECIFICATION
      ↓
   AGENT
      ↓
IMPLEMENTATION
      ↓
    TESTS
      ↓
VALIDATION
      ↓
   RELEASE