P1 · Requisitos

Publicado: semana 3 · Entrega: semana 5 · En equipo de 4 a 5 personas · Tag: p1

En esta entrega el equipo consigue su cliente, lo entrevista y decide con él qué se va a construir. Al final tienen que poder responder, con documentos y no de memoria: ¿quién es el cliente y qué problema tiene?, ¿qué historias resuelven ese problema y cómo sabremos que están terminadas?, ¿qué entra en el semestre y qué no? Todavía no se escribe código de la aplicación.

Cubre las semanas 2 (procesos, planificación y estimación), 3 (elicitación, entrevistas, historias de usuario, criterios de aceptación y priorización) y 4 (especificaciones). Las reglas generales del proyecto (el cliente, los equipos, el repositorio, el registro de uso de IA) están en el README de proyectos.

1. Antes de empezar

• Creen el repositorio del equipo en GitHub y protejan main desde el primer día: todo cambio entra por un pull request revisado por otra persona del equipo. P1 son solo documentos, y igual se trabajan así. En un repositorio privado, las reglas de protección de ramas de GitHub necesitan GitHub Pro (gratis con GitHub Education) o una organización con GitHub Team; si no las tienen, la regla se cumple por acuerdo del equipo y la revisión automática la comprueba en la historia de Git.

• Propongan el cliente al docente en la semana 3 (una persona u organización real, con un problema que quepa en el semestre; ver El cliente). Sin cliente aprobado no hay P1.

• Dónde va cada repositorio. El repositorio del equipo se clona dentro de la carpeta del curso, con un nombre que empiece con equipo- (el .gitignore del curso lo ignora), y el contenedor se abre desde la carpeta del curso. Así, dentro del contenedor, el curso está en /work y el repositorio del equipo en /work/equipo-nombre:

  cd curso                                      # la carpeta del curso
  git clone <url-del-repositorio-del-equipo> equipo-nombre
  ./env/run.sh                                  # el contenedor monta el curso en /work
  cd /work/equipo-nombre
  make -f /work/projects/p1-requisitos/Makefile check

  Al revés no: no copien el curso dentro del repositorio del equipo. Las pruebas, ESLint y la revisión recorren todo el repositorio del equipo y encontrarían los archivos del curso.

• Todo va en Markdown dentro de docs/. Los nombres de archivo y los títulos ## que se piden abajo son exactos: la revisión automática los busca (las mayúsculas, las tildes y una numeración al inicio, como ## 2. Alcance, no importan).

2. Qué entregan

docs/cliente.md

Con estas secciones:

• ## Quién es: la persona u organización, a qué se dedica, quién es el contacto del equipo. No suban teléfonos ni correos personales del cliente: el repositorio lo puede ver más gente.
• ## El problema: qué le cuesta hoy, en sus palabras y con ejemplos concretos (cuántas veces, cuánto tiempo, qué se pierde).
• ## Alcance: qué se va a construir en el semestre y qué queda fuera.
• ## Aprobación: cuándo aprobó el docente el cliente y cuándo aprobó el cliente el alcance y el backlog (fecha y medio: reunión, correo, mensaje).

docs/entrevistas/

Al menos 3 entrevistas, una por archivo, con el nombre AAAA-MM-DD-tema.md (la fecha de la entrevista: 2026-04-08-el-problema.md). Cada una con:

• ## Datos: fecha, lugar o medio, duración, participantes (del cliente y del equipo) y el objetivo de la entrevista.
• ## Notas: lo que se preguntó y lo que se respondió. Citas textuales cuando importan (“a las seis ya sé cuánta harina voy a usar”).
• ## Hallazgos: qué aprendieron, qué reglas del negocio aparecieron, qué quedó pendiente para la siguiente entrevista.

Una de las tres puede ser la revisión del prototipo con el cliente.

docs/historias.md

Cada historia es una sección con el título ## HU-NN · Título corto (HU-01, HU-02, …), y adentro:

1. La frase “Como <rol>, quiero <acción> para <beneficio>”. El rol es alguien concreto (cliente de la panadería, dueña), no el usuario.

2. La estimación en story points.

3. Los criterios de aceptación, cada uno con la forma Dado / Cuando / Entonces en español:

   - **Dado** que son las 18:00 del lunes en Lima, **cuando** pido para el
     martes, **entonces** veo "Los pedidos para esa fecha cerraron".

Al menos 6 historias, y cada una con al menos un criterio. Las historias importantes llevan varios: el caso normal y los casos límite o de error. Un criterio es verificable si dos personas, leyéndolo, harían la misma prueba.

docs/backlog.md

Las historias priorizadas con MoSCoW, en cuatro secciones: ## Must, ## Should, ## Could y ## Won't (pueden decir ## Must have, etc.). Cada historia de docs/historias.md aparece en una sola sección, por su id (HU-04), y dentro de cada sección el orden es el orden en que se van a trabajar. ## Must no puede estar vacía. ## Won't dice lo que se acordó no hacer y por qué: es tan útil como lo demás.

docs/requisitos-no-funcionales.md

Al menos 3, con ids RNF-01, RNF-02, …, y para cada uno cómo se comprueba: “rápida” no es un requisito; “la página de pedidos carga en menos de 2 s con 4G, medido con la pestaña de red del navegador” sí. Piensen en el celular del cliente, en su horario, en sus datos personales y en la accesibilidad.

docs/prototipo/

El prototipo de baja fidelidad de las pantallas principales: fotos de bocetos en papel, imágenes (.png, .jpg, .svg, .pdf) o un README.md con el enlace a la herramienta donde lo hicieron (Figma, Excalidraw, Penpot). Lo importante es que el cliente lo haya visto: anoten en las entrevistas qué cambió después.

docs/glosario.md

Una tabla con al menos 8 términos del dominio del cliente (no de programación): la palabra como la usa el cliente, su definición y, desde P2, cómo se llama en el código.

| Término | Definición | En el código |
|---|---|---|
| Turno | Franja de dos horas para recoger un pedido. | `slot` |

docs/registro-ia.md

El registro de uso de herramientas de IA del equipo (reglas generales). Es una tabla con, al menos, estas columnas, en este orden o en otro: Fecha (AAAA-MM-DD), Herramienta, Qué se pidió, Qué se aceptó, Qué se rechazó y por qué. Pueden agregar otras (Quién, PR). Una fila por uso que influyó en lo entregado: preparar las preguntas de una entrevista, revisar las historias, proponer criterios. Si en P1 no usaron ninguna, el archivo existe con la tabla vacía (la revisión avisa, no falla).

3. Revisión automática

Dentro del contenedor del curso, desde la carpeta del repositorio del equipo (clonado dentro de la carpeta del curso, como en la sección 1):

cd /work/equipo-nombre
make -f /work/projects/p1-requisitos/Makefile check

Revisa lo que se puede revisar con un programa y termina con un resumen. Una entrega que no pasa make check no pasa a la revisión del docente.

Cada línea dice ok, FALLA (obligatoria y no se cumple) o aviso (una recomendación o algo que no se pudo comprobar). La revisión no juzga si las historias son buenas: eso lo revisan el docente y el cliente.

4. Cómo entregar

Cuando la entrega esté en main, creen el tag y súbanlo antes del plazo que fije el docente:

git tag p1
git push origin p1

Se revisa el commit del tag. Si corrigen algo después del tag y antes del plazo, muevan el tag (git tag -f p1 && git push -f origin p1).

5. Consejos y errores comunes

• Llegar a la entrevista con la solución. “¿Le gustaría una app con notificaciones?” no es una pregunta de requisitos. Pregunten cómo lo hacen hoy, qué pasó la última vez que salió mal y cuánto les costó.
• Una historia por pantalla o por tabla. “Como usuario, quiero un CRUD de productos” no dice para qué. Escriban la historia desde lo que el cliente logra.
• Criterios que no se pueden probar. “Entonces el sistema responde rápido” no es un criterio; “entonces el turno aparece sin cupos y no se puede elegir” sí. Al escribir cada criterio, piensen en la prueba que lo va a verificar en P3.
• Todo es Must. Si todo es Must, nada lo es. Un Must es lo que, si falta, el cliente no usaría el producto.
• Inventar al cliente. Las historias tienen que salir de las entrevistas. El docente compara lo que dicen las notas con lo que dicen las historias, y puede llamar al cliente.
• Con IA. Una herramienta puede proponer preguntas para la entrevista o revisar si una historia cumple INVEST; no sabe qué necesita su cliente. Si una historia o un criterio salió de una herramienta, que se note en el registro y que el cliente lo haya confirmado.
• Datos personales. No suban los datos de contacto del cliente ni datos reales de sus clientes. En las notas, la dueña o un nombre de pila basta.