Cómo leer una spec: Metodologías Given-When-Then y EARS

Cuando trabajas con spec driven development y CloudCode te genera una especificación, el verdadero valor no está en el código, sino en entender qué construyes y por qué. Aquí aprendes a leer una spec, sus componentes estándar y dos metodologías clave que la sostienen: Given-When-Then y EARS. Es ideal para quien quiere dominar su aplicación sin importar su perfil técnico.

Piensa en la spec como los planos de una casa. CloudCode ya nos los entregó, y ahora toca revisarlos con calma antes de levantar una sola pared. Abrimos el archivo spec.md dentro del folder de specs y hacemos un recorrido general por su contenido [00:20].

¿Qué contiene una especificación de software bien hecha?

Una spec completa reúne el contenido mínimo que cualquier proyecto de software debería tener. No es un capricho de la IA, son estándares reales de la industria [00:45].

Estos son los componentes que encontramos al hacer el overview:

• Historias de usuario.
• Criterios de aceptación.
• Casos de borde o edge cases.
• Requerimientos funcionales.
• Métricas de resultados y outputs.
• Assumptions o supuestos.

Cada bloque cumple una función distinta, y aquí viene lo interesante: entenderlos te permite conversar de igual a igual con cualquier persona de ingeniería.

¿Qué son las historias de usuario en una spec?

Las historias de usuario son los requerimientos funcionales vistos desde el lado del negocio [01:10]. Siguen la lógica del negocio e indican qué hará cada feature.

Dentro de cada historia encuentras la descripción de la funcionalidad, por qué es prioritaria, cómo se manejan los independent tests y cuáles son los criterios de aceptación. Todo conectado a una razón concreta, no a suposiciones sueltas.

¿Qué es una historia de usuario? Es un requerimiento funcional escrito desde la perspectiva del negocio que describe qué debe hacer una funcionalidad, por qué importa y cómo se validará.

¿Cómo funciona la metodología Given-When-Then?

Al leer los criterios de aceptación notas una estructura muy definida. CloudCode usa la metodología Given-When-Then para eliminar ambigüedades [01:35].

La lógica es sencilla y directa:

• Given un visitante se encuentra en cierta situación.
• When se registra con un correo y contraseña válidos.
• Then el sistema crea la cuenta y le permite iniciar sesión.

Dado que un usuario hace algo, cuando pasa esto, entonces se ejecuta esto otro. Parece obvio a simple vista, pero es justo esa claridad la que evita malentendidos entre negocio e ingeniería.

¿Para qué sirve Given-When-Then? Es una metodología estandarizada para definir criterios de aceptación en historias de usuario y evitar ambigüedades al describir el comportamiento esperado del sistema.

¿Qué son los casos de borde y por qué importan?

Los casos de borde describen esos escenarios extremos que pueden suceder y cómo el sistema debe gestionarlos [02:15]. Son el detalle que separa una app frágil de una robusta.

Un ejemplo claro: ¿qué pasa si dos usuarios confirman el mismo bloque horario casi al mismo tiempo? Solo el primero en completar la validación obtiene la reserva. El segundo recibe un rechazo con un mensaje claro.

Y aquí hay una diferencia fundamental que quiero que notes: la inteligencia artificial no se inventó este caso. Lo dedujo de toda la información que le pasamos en la constitución y en la spec del proyecto [02:40].

¿Qué es la metodología EARS en los requerimientos funcionales?

Al bajar llegamos a los functional requirements, que ya son requerimientos técnicos concretos [02:55]. Por ejemplo: el sistema debe permitir a un visitante registrarse con correo electrónico y contraseña.

Aquí CloudCode aplica el estándar EARS, que significa Easy Approach to Requirement Syntax. Cada requerimiento empieza nombrando al sistema y qué debe hacer [03:10].

La diferencia está en cómo redactas:

• Ambiguo: que la gente no pueda reservar en el pasado.
• Con EARS: el sistema debe prevenir que los usuarios reserven fechas pasadas.

Esa precisión evita interpretaciones múltiples y deja el requerimiento listo para ejecutar.

¿Qué significa EARS? Es Easy Approach to Requirement Syntax, una metodología para escribir requerimientos funcionales sin ambigüedad, iniciando siempre con el sistema y la acción que debe realizar.

¿Qué son las assumptions que hace la IA?

Al final de la spec encuentras cómo se van a medir las salidas del sistema y las assumptions que la IA hace sobre tu aplicación [03:30].

Un ejemplo: no se requiere verificación del correo electrónico para completar el registro, porque esa interacción no incluye notificaciones externas. Es información que nosotros nunca le pasamos, así que conviene leerla con atención.

En este punto siéntete libre de editar el archivo. Si un supuesto no tiene sentido para tu proyecto, cámbialo. La spec es tuya.

¿Por qué el spec driven development te da control real?

Sin darnos cuenta usamos dos metodologías muy poderosas y comunes en el desarrollo de software: Given-When-Then para criterios de aceptación y EARS para requerimientos funcionales [04:00].

Aquí está el poder del spec driven development: con estas especificaciones ya podrías entregar el proyecto a cualquier persona de ingeniería o a cualquier inteligencia artificial, y recibirías el código y la aplicación sin problema [04:20].

Y ese es el punto central: que entiendas cómo funciona tu aplicación y qué está haciendo. Si lo piensas bien, eso debería hacerlo cualquier persona, sin importar a qué se dedique.

¿Ya revisaste tu propia spec? Cuéntame en los comentarios qué assumption te sorprendió más de las que generó la IA.