Guía de "New Project Bootstrap"

Esta guía está pensada para entender qué hace el asistente de IA cuando ejecuta este playbook. La idea es que puedas leerla, entender qué pasa en cada paso, y saber qué información tenés que darle al asistente para que el trabajo salga bien.

1. ¿Qué es un "playbook"?

Pensalo como una receta de cocina para el asistente de IA. Vos le decís "quiero hacer esto" (por ejemplo, "quiero preparar un proyecto nuevo para hacer QA") y el playbook es la receta que el asistente sigue paso a paso, en orden, sin saltarse nada, para que el resultado sea siempre el mismo sin importar quién lo pida.

Cada paso de la receta usa una herramienta puntual (en la jerga técnica se las llama "skills"), algo así como un utensilio de cocina: uno sirve para pelar, otro para cortar, otro para hornear. Vos no necesitás saber cómo funciona cada utensilio por dentro — solo necesitás saber qué ingrediente hay que poner en cada paso (por ejemplo, la URL de la aplicación, o el nombre de una historia de usuario) para que el plato final salga bien.

En resumen: un playbook = una guía ordenada de pasos. Una skill = la herramienta puntual que ejecuta cada paso. Interactuás con el playbook — el asistente se encarga de usar la herramienta correcta en cada momento.

2. ¿Qué hace el playbook "New Project Bootstrap"?

Es el punto de partida para dejar un proyecto nuevo listo para hacer QA automatizado, sin que nadie tenga que configurar nada a mano.

Hoy, cuando llega un proyecto nuevo (una app, un sitio web, una API), alguien tiene que: 1. Averiguar con qué herramientas está armado ese proyecto. 2. Generar o impactar cambios en los tests para que estos corran automáticamente cada vez que se sube código nuevo. 3. Comprobar que todo eso realmente funciona, corriendo una primera prueba.

Ese trabajo, hecho a mano, puede tardar horas o días y depende de tener a alguien técnico disponible. Este playbook hace esas tres cosas de forma automática, conversando con vos solo para lo que no puede averiguar solo (por ejemplo, la URL del ambiente de pruebas).

Al terminar, el proyecto queda con: - Una "ficha técnica" guardada que describe cómo está armado (para no tener que volver a preguntar). - Una configuración de pasos (pipeline) que corre las pruebas solo cada vez que alguien sube cambios. - Una primera prueba real ejecutada de punta a punta, que confirma que todo el circuito funciona.

3. ¿Cuándo tengo que usar este playbook?

Usalo cuando estés frente a alguna de estas situaciones:

Situación	Ejemplo de negocio
Un proyecto totalmente nuevo, que nunca tuvo QA automatizado	El equipo acaba de arrancar el desarrollo de una tienda online nueva y todavía no hay ni una sola prueba automática corriendo.
Un proyecto viejo que se quiere "poner al día"	Existe desde hace 2 años una app de turnos médicos, pero las pruebas siempre se hicieron a mano y se quiere empezar a automatizar.
Se quiere arrancar de cero con todo el combo (archivo con el stack técnologico del repositorio + pipeline preparado para correr las pruebas CI + primera prueba tomando de referencia Jira, Confluence, AzureDevops o historias de usuario)	Se decide estandarizar cómo se hace QA en todos los proyectos nuevos de la empresa.

¡IMPORTANTE! - Si el proyecto ya tiene un archivo con el stack técnologico del repositorio (el archivo qa-stack.yaml) y un pipeline preparado para correr las pruebas funcionando, NO es necesario correr este playbook — para el trabajo del día a día (probar una nueva funcionalidad, un bug, un cambio de UI) existen otros playbooks más específicos.

4. Ejemplo guía: "TechStore", una tienda online con carrito de compras

Vamos a seguir un caso de negocio de ejemplo: TechStore, una tienda online de electrónica con carrito de compras (agregar productos, ver el carrito, pagar). Es el mismo tipo de aplicación que cualquiera reconoce por haber comprado alguna vez online.

Supongamos que el equipo de desarrollo terminó la primera versión de TechStore y te pide: "necesitamos que QA empiece a probar esto de forma automática desde ya". Ese es exactamente el escenario para el que se usa este playbook.

A lo largo de los pasos siguientes vamos a ver qué le responderías al asistente en cada pregunta, usando TechStore como ejemplo.

5. Antes de arrancar: lo que necesitás tener a mano

No hace falta saber programar, pero sí tener a mano estos tres datos:

Dato	Ejemplo con TechStore
Acceso al proyecto (que el asistente pueda leer los archivos del código)	El repositorio de TechStore ya clonado o accesible
La URL de la aplicación, en qué versión está y en qué sistema operativo corre el ambiente de pruebas	`https://techstore-staging.com`, versión `2.4.1`, `Windows 11`
Una historia de usuario de referencia, chica y simple, para hacer la primera prueba	Por ejemplo: "Como cliente quiero poder agregar un producto al carrito de compras"

Si no tenés una historia de usuario a mano, no es un problema: se puede escribir una mínima solo para validar que el circuito funciona (no tiene que ser la prueba más completa del sistema).

6. Paso a paso

¡Aclaración! Este es un ejemplo, vos debes seguir el playbook original.

Paso 1 — "Averiguar con qué está armado el proyecto"

Qué pasa: el asistente revisa los archivos del proyecto (como quien mira una caja para ver qué contiene) y trata de adivinar solo con qué herramienta de testing se trabaja, en qué lenguaje está escrito el proyecto, y en qué plataforma se corren las pruebas automáticas cuando alguien sube código. Todo lo que no puede adivinar, te lo pregunta directamente a vos.

Qué te va a preguntar seguro (porque no lo puede adivinar solo): - La URL de la aplicación bajo prueba → https://techstore-staging.com - La versión de la app y el sistema operativo del ambiente → 2.4.1, Windows 11 - Si la aplicación requiere login para entrar (y de qué tipo) → en TechStore, por ejemplo, "sí, usuario y contraseña" - Dónde viven las historias de usuario (¿en un archivo local, en Jira, en Azure DevOps?) → "local, en la carpeta user-stories/"

Qué te queda al final de este paso: una especie de "carnet de identidad" del proyecto, guardado en un archivo (qa-stack.yaml), que el resto de los playbooks van a leer automáticamente de ahora en adelante — así nunca más hay que volver a responder estas preguntas.

Importante: si la herramienta de testing que detecta no es la principal que soporta el sistema todavía (hoy: Playwright), el asistente te va a avisar que algunos pasos siguientes pueden no estar disponibles hasta que se termine de dar soporte a esa herramienta. No es un error tuyo — es una limitación conocida que hay que tener en cuenta antes de seguir.

Paso 2 — "Armar el robot que corre las pruebas solo"

Qué pasa: con la descripción del stack tecnológico del Paso 1, el asistente escribe la configuración de un robot automático (pipeline) que, de ahora en adelante, va a correr las pruebas de TechStore cada vez que alguien suba un cambio de código — sin que nadie tenga que acordarse de hacerlo a mano.

Es como poner un guardia de seguridad en la puerta: cada vez que entra algo nuevo (un cambio de código), el guardia lo revisa automáticamente antes de dejarlo pasar.

Qué te queda al final de este paso: un archivo de configuración (el nombre exacto depende de dónde vive el código de TechStore — GitHub, GitLab o Bitbucket) que el equipo de desarrollo va a subir junto con el resto del código. A partir de ahí, cada cambio en TechStore dispara pruebas automáticas.

Este paso solo escribe la configuración del robot. Todavía no lo pone a correr pruebas reales — eso pasa en el Paso 3.

Paso 3 — "Prueba piloto: confirmar que todo el circuito funciona"

Qué pasa: el asistente toma la historia de usuario que preparaste ("agregar un producto al carrito") y corre, de punta a punta, el circuito completo de QA:

Lee la historia de usuario.
Armar un plan de prueba a partir de ella con sus correspondientes criterios de aceptación.
Ejecuta el plan y reporta fallas.
Genera las pruebas automáticas correspondientes.
Las corre — y si alguna falla, intenta repararla sola.
Escribe un reporte final con el resultado sobre la automatización.

Con TechStore, esto significa que el asistente realmente entra a la tienda online, agrega un producto al carrito, y confirma que el carrito lo refleja correctamente — y deja ese comportamiento convertido en una prueba automática reutilizable.

Esto no es una regresión completa del sistema. Es solo una prueba piloto para confirmar que el "cableado" quedó bien conectado: que se puede leer, planificar, probar, generar, correr y reportar sin que nada se rompa en el camino.

Cómo saber si salió bien:

Resultado	Qué significa
La prueba pasó o falló, pero se ejecutó de punta a punta	El circuito funciona correctamente (que una prueba falle no es un error del playbook — puede ser un bug real de la app)
Se generó un reporte con el resultado	Podés abrirlo y leer el detalle
Se generó al menos un archivo de prueba automática	Ya queda algo reutilizable para el futuro
El proceso quedó "bloqueado" sin poder correr nada	Ahí sí hay que avisar al equipo técnico — la herramienta de testing detectada en el Paso 1 puede no estar soportada todavía

7. ¿Qué me queda al finalizar los tres pasos?

Qué obtenés	Para qué te sirve
Un archivo con el stack tecnológico del proyecto guardado	Nunca más hay que volver a responder las preguntas de configuración
Un robot (pipeline) de pruebas automáticas configurado	Cada cambio de código en TechStore dispara pruebas solo
Un plan de prueba de la historia piloto	Documentación de qué se probó y cómo
Una prueba automática ya generada y corriendo	Punto de partida para seguir sumando pruebas
Un reporte de resultados	Evidencia de que el setup quedó validado

A partir de acá, TechStore ya "entró" al ecosistema de QA automatizado: para seguir probando nuevas funcionalidades, bugs o cambios, se usan otros playbooks más específicos (por ejemplo, uno para features nuevas, otro para bugs, otro para cambios de UI) — este playbook ya cumplió su función de dejar la base lista.

8. Problemas comunes (y qué hacer)

Lo que ves	Por qué puede pasar	Qué hacer
El asistente no logra armar el archivo del stack tecnológico del proyecto	El proyecto no tiene los archivos típicos que permiten adivinar la configuración	Respondé las preguntas que te haga directamente, sin problema
El robot de pruebas quedó armado sin la parte de pruebas de pantalla (UI)	El asistente entendió que el proyecto es solo una API, no una aplicación con pantallas	Avisá al equipo técnico para corregir el archivo de stack tecnológico y repetir el Paso 2
La prueba piloto queda "bloqueada" sin poder correr	La herramienta de testing detectada todavía no tiene soporte completo	Es un tema para el equipo técnico, no algo que puedas resolver solo/a
Las pruebas fallan y no se pueden reparar solas	Puede ser que la aplicación no esté levantada, o que la URL/credenciales estén mal	Verificá que la URL de TechStore esté accesible y que las credenciales sean correctas

9. Resumen visual del flujo

Proyecto nuevo sin QA automatizado (ej: TechStore recién armado)
            │
            ▼
Paso 1 — Averiguar con qué está armado el proyecto
            │
            ▼
Paso 2 — Armar el robot que corre las pruebas solo
            │
            ▼
Paso 3 — Prueba piloto de punta a punta (ej: "agregar producto al carrito")
            │
            ▼
Proyecto listo para darle continuidad