Cómo escribir un PRD listo para IA que realmente funcione

Quiero contarte una historia rápida. Hace unas semanas, empecé a construir un panel de administración de usuarios para mi hermana. Tenía prisa, así que no escribí ninguna especificación. Solo abrí mi editor con IA y le pedí: "Crea una tabla de datos usando Kendo UI en Angular para mostrar una lista de usuarios".

Al principio todo fue perfecto. Para el miércoles, la tabla básica ya estaba funcionando, los datos de prueba estaban listos y todo se veía genial. Estaba contento, y mientras se validaba esa primera funcionalidad, pasé a trabajar en otra cosa.

Pero dos semanas después, mi hermana volvió con un nuevo requerimiento de negocio: antes de que un usuario pueda ver el botón "Eliminar" en la tabla, el sistema debe comprobar si su rol es "Admin", y además debemos guardar el estado de los filtros en la URL.

Abrí mi editor con IA, inicié una nueva sesión de chat y le pedí que agregara esta lógica. ¿El resultado? Un caos total. La IA rompió el enrutamiento de mi aplicación en Angular, usó directivas incorrectas de Kendo Grid y echó a perder la tabla que ya funcionaba.

¿Por qué pasó esto? Muy simple. Esto nos enseña que la IA necesita límites claros. Cuando abres una nueva sesión de chat, la IA empieza desde cero. No tiene memoria de las decisiones de arquitectura que tomaste dos semanas atrás. Para construir funcionalidades estables, necesitamos una única fuente de la verdad. Y eso empieza escribiendo un Documento de Requisitos de Producto (PRD) preparado para IA.

El auge de Spec-Driven Development

En este artículo, vamos a ver cómo escribir un PRD listo para IA que realmente funcione. Basaremos nuestro enfoque en los capítulos 3, 4 y 5 del libro Spec-Driven Development de Bezael Pérez. Veremos cómo un PRD funciona como la fuente de la verdad y cómo estructurarlo usando las ocho secciones que recomienda el libro. Por último, usaremos una herramienta agéntica como Antigravity CLI impulsada por Gemini para convertir ese PRD en código limpio y funcional. Empecemos revisando el proyecto que queremos construir.

1. Victoria rápida: el panel de administración

Antes de ver la teoría, veamos nuestro objetivo. Queremos que nuestra herramienta de IA implemente un panel completo de administración de usuarios usando Kendo UI Grid en Angular, con control de acceso basado en roles (RBAC).

Para construir este panel con éxito y evitar que la IA invente sus propias reglas, necesitamos un plan estructurado. Veamos cómo diseñar esa especificación.

2. La especificación como fuente de la verdad

En la programación tradicional, el código es la fuente de la verdad. La documentación pasa a un segundo plano. En Spec-Driven Development (SDD), esta relación se invierte. La especificación es la fuente de la verdad y el código está al servicio de la especificación.

Una buena especificación debe ser una especificación viva (Living Spec). Esto significa:

Vive en el mismo repositorio que tu código.
Se gestiona con control de versiones mediante Git.
Cuando los requisitos cambian, primero actualizas la especificación y luego la IA actualiza el código.

Además, la especificación debe enfocarse en el comportamiento, no en la arquitectura. En lugar de decirle a la IA: "Usa RxJS BehaviorSubject para el estado de la tabla", dile: "El estado de los filtros de la tabla debe reflejarse en los parámetros de consulta de la URL". Esto le da a la IA la libertad de escribir la mejor solución técnica respetando siempre las reglas de negocio. Pero, ¿cuáles son los pasos para construir software con IA?

3. Las 7 fases del desarrollo con IA

Antes de redactar nuestra especificación, entendamos dónde encaja. El capítulo 4 del libro presenta las 7 fases para crear software con IA:

Idea: Describe lo que quieres en dos oraciones claras.
Investigación: Investiga primero las APIs que no conozcas.
Prototipo: Construye un prototipo rápido y temporal para validar tus ideas.
PRD: Escribe la especificación del comportamiento.
Kanban: Divide el PRD en tareas independientes.
Bucle de ejecución: La IA lee las tareas y escribe el código.
QA: Ejecuta pruebas manuales o automatizadas.

Hasta ahora hemos hecho la lluvia de ideas y la investigación inicial. Ahora pasemos a escribir el PRD real. Puedes saltarte la investigación o el prototipo si ya conoces bien las tecnologías, pero nunca debes saltarte el PRD, el tablero Kanban, el bucle de ejecución ni las pruebas de QA. Cuando estemos listos para redactar nuestra especificación, debemos seguir una estructura muy concreta.

4. Las 8 partes de un PRD preparado para IA

Ahora ya estamos listos para redactar el PRD. El capítulo 5 nos enseña que un PRD debe tener exactamente ocho secciones específicas. Ni una más, ni una menos.

Estas son las ocho secciones:

Declaración del problema (Problem Statement): Una o dos oraciones que explican qué está fallando y por qué es importante resolverlo.
Solución (Solution): Una descripción del destino, no del camino. Qué condiciones deben cumplirse cuando la funcionalidad esté lista.
Historias de usuario (User Stories): Acciones del usuario en el formato: Como [rol], cuando [acción], entonces [resultado esperado].
Restricciones (Constraints): Restricciones no negociables (por ejemplo, "Debe usar Angular Signals").
Criterios de aceptación (Acceptance Criteria): Casillas de verificación que pueden aprobarse o fallar.
Fuera de alcance (Out of Scope): Lo que explícitamente no entra en este ciclo. Esto evita que la IA añada cosas extra que nadie le pidió.
Supuestos (Assumptions): Lo que das por hecho sobre el sistema (por ejemplo, "AuthService ya está disponible en el módulo raíz").
Notas de implementación (Implementation Notes): Sugerencias técnicas que la IA puede seguir o ignorar.

Escribir estas 8 partes a mano cada vez requiere demasiado esfuerzo. Por suerte, podemos dejar que un agente de IA automatice este proceso por nosotros. Veamos cómo hacerlo.

Deja que la IA lo escriba: automatizando la especificación

En esta guía, usaremos Antigravity CLI (ejecutado mediante el comando agy en tu terminal) para automatizar el flujo de trabajo. Puedes aplicar estos mismos principios con cualquier otro asistente de código con IA.

Si utilizas Antigravity CLI, el proceso se apoya en dos comandos principales:

/grill-me: Inicia una sesión interactiva de preguntas y respuestas en tu terminal. El agente te consulta sobre historias de usuario, restricciones y casos límite, y luego genera un PRD limpio con sus 8 partes.
/goal: Le indica al agente que lea de forma autónoma la especificación, planifique los cambios y escriba el código directamente en tu proyecto.

Configurar Antigravity CLI y ejecutar `/grill-me`

Aquí te muestro cómo configurar Antigravity CLI y usar /grill-me para construir tu PRD:

Paso 1: Instalar Antigravity CLI

Ejecuta el script de instalación para descargar e instalar el comando global agy:

curl -fsSL https://antigravity.google/cli/install.sh | bash

Paso 2: Abrir la herramienta en tu proyecto

Navega a la carpeta de tu proyecto y ejecuta la CLI:

agy

(En tu primera ejecución, se abrirá una ventana del navegador para autenticarte con tu cuenta de Google).

Paso 3: Ejecutar `/grill-me` para la lluvia de ideas

Inicia la sesión interactiva dentro de la herramienta. Usa /grill-me junto con un prompt que describa lo que quieres construir:

/grill-me "I need to build an admin user management dashboard using Angular and Kendo UI Grid. It must include Role-Based Access Control (RBAC) to hide the delete button from non-admins, and persist the filter state in the URL. Save the final PRD to specs/admin-grid-prd.md"

El agente te hará preguntas concretas para afinar los detalles. Puedes responderle en lenguaje natural. Por ejemplo, puedes aclarar los roles exactos o qué debe ocurrir si una petición falla.

Paso 4: Dejar que el agente escriba el PRD

Una vez terminada la entrevista, el agente organiza las notas y genera automáticamente un archivo de PRD limpio con sus 8 partes en tu repositorio (guardado en specs/admin-grid-prd.md):

Este es el PRD técnico exacto generado por el agente tras la sesión con /grill-me:

# PRD: Admin Data Grid with Kendo UI
 
## 1. Problem Statement
Administrators need a fast and reliable way to view and manage users, but the current system lacks advanced filtering and role protection.
 
## 2. Solution
Create an Angular component using Kendo UI Grid that displays users, supports URL state persistence, and hides sensitive actions based on the user role.
 
## 3. User Stories
- As an admin, when I view the grid, then I can see the delete button.
- As a regular user, when I view the grid, then the delete button is hidden.
 
## 4. Constraints
- Must use Angular Signals for state management.
- Grid filter state must reflect in the URL query parameters.
 
## 5. Acceptance Criteria
- [ ] Renders the Kendo UI Grid without console errors.
- [ ] Users without the Admin role cannot see the delete button.
- [ ] Refreshing the page keeps the current grid filters intact.
 
## 6. Out of Scope
- Real backend integration (use local mock data).
- Adding new user creation forms.
 
## 7. Assumptions
- AuthService is already provided in the root module.
 
## 8. Implementation Notes
- Consider using the Kendo Grid state change event to update the router URL.

Con una especificación clara en su lugar, podemos ejecutar /goal "Read the PRD and implement the admin grid" en la CLI. El agente creará los archivos y configurará la estructura base del proyecto. Ahora necesitamos un motor de IA capaz de leer y ejecutar estos requisitos técnicos complejos sin romper nuestro código.

5. Presentamos Gemini: nuestro motor de IA

Una vez que tenemos el PRD completo, necesitamos un motor de IA que pueda ejecutar nuestra especificación a la perfección. Con Antigravity CLI, usamos los modelos Gemini de Google como motor principal de ejecución.

¿Por qué Gemini es ideal para Spec-Driven Development a través de Antigravity?

Ventana de contexto masiva: Gemini puede leer todo tu repositorio de código, estilos, dependencias de Angular y el PRD al mismo tiempo. Nunca "olvida" las reglas de arquitectura.
Llamadas a herramientas agénticas (Tool Calling): Al ejecutarse dentro de Antigravity CLI, Gemini no se limita a sugerir fragmentos de código. Puede escribir archivos, instalar paquetes y verificar configuraciones de forma nativa.
Cumplimiento estricto de reglas: Los modelos Gemini están muy optimizados para seguir instrucciones del sistema. Respetan tus restricciones y lo que dejaste fuera de alcance.

Como Antigravity CLI ya cuenta con esta integración lista para usar, no hace falta configurar servidores locales de modelos. Veamos ahora cómo usamos esta integración para hacer realidad nuestro PRD.

6. Ejecutar el PRD con Antigravity CLI

En los tutoriales tradicionales de programación, este sería el momento donde abrirías tu terminal, ejecutarías ng generate component y pasarías horas escribiendo código línea por línea.

Pero en Spec-Driven Development no hacemos eso. El agente de IA hace el trabajo.

Nuestro rol como desarrolladores es actuar como arquitectos. Escribimos el PRD y se lo entregamos al agente. En Antigravity CLI, hacemos esto con el comando /goal. El agente con Gemini lee el PRD, planifica los archivos, ejecuta los comandos de configuración inicial, instala paquetes y escribe el código.

Dentro de la herramienta, solo debes indicar el objetivo:

/goal "Read the PRD and set up the Admin Grid project. Follow all constraints and out-of-scope sections."

Empezar un proyecto nuevo desde cero es bastante directo. Pero, ¿qué pasa cuando necesitas actualizar un proyecto existente semanas después?

7. Agregar lógica de negocio real a código existente

La configuración inicial está lista, la tabla básica funciona y ahora necesitas agregar lógica de negocio compleja a un proyecto que ya existe.

En el desarrollo tradicional, aquí es donde la IA suele fallar. Cuando vuelves al proyecto dos semanas después, abres una nueva sesión de chat. Esa nueva sesión no tiene acceso a las decisiones de diseño que tomaste antes. Empieza desde cero y se pone a adivinar.

En Spec-Driven Development, resolvemos esto guardando nuestras especificaciones con control de versiones directamente en el repositorio. Gestionamos este cambio siguiendo tres reglas simples:

Regla 1. Documentar la "Constitución" del proyecto

Antes de añadir nuevas funcionalidades, define las reglas técnicas del código. Puedes pedirle a Antigravity CLI que analice tu código actual y genere un borrador:

"/goal Read the project code and generate a draft constitution capturing the technical decisions that already exist. Save it to CONSTITUTION.md"

Esto crea un documento central (guardado como CONSTITUTION.md) que resume tu stack tecnológico, estándares de código y restricciones de seguridad.

Regla 2. Documentar solo lo que tocas

No necesitas especificar toda la base de código desde el primer día. Cuando tengas que modificar una funcionalidad, escribe primero una especificación corta y clara sobre su comportamiento actual. Por ejemplo, documenta cómo funciona la lógica actual de la tabla en un archivo specs/admin-grid.md.

Regla 3. Escribir especificaciones para cada funcionalidad

Una vez documentado el estado actual, redacta una nueva especificación que defina la nueva lógica de negocio. Puedes hacer referencia directa a tus módulos existentes. Guarda este archivo como specs/role-validation.md en tu repositorio. Luego, ejecuta /goal para que el agente implemente el cambio paso a paso sin romper las funcionalidades previas.

Gemini lee la Constitución junto con la nueva especificación, entiende la estructura exacta de carpetas y escribe la lógica de validación directamente en los archivos existentes. Veamos cómo podemos verificar el trabajo del agente.

Verificar el resultado

Una vez que el agente con Gemini complete la implementación, puedes comprobar que todo funcione como esperabas. Como el agente se encargó de configurar el proyecto, solo necesitas ejecutarlo en local:

Paso 1: Navegar al proyecto

cd admin-dashboard

Paso 2: Iniciar el servidor

npm start

Paso 3: Probar el panel

Abre tu navegador y ve a http://localhost:4200. Prueba iniciar sesión con un usuario administrador verificado y con un usuario normal para asegurarte de que el control de acceso por roles funcione exactamente como lo definiste.

8. Conclusiones clave

Escribir un PRD preparado para IA cambia la forma en que desarrollamos software. Estas son las lecciones principales del libro:

La especificación es el artefacto principal: Vive en el repositorio y controla el código.
Define comportamiento, no arquitectura: Explícale a la IA qué debe cumplirse, no cómo construirlo paso a paso.
Usa herramientas CLI agénticas: Herramientas como Antigravity CLI (agy), respaldadas por la enorme ventana de contexto de Gemini, hacen el trabajo pesado de configuración.
SDD funciona en proyectos existentes: Usar una Constitución del proyecto te permite hacer actualizaciones seguras en sistemas existentes semanas o meses después.

¡Un reto para ti!

Ahora que tienes la tabla de administración funcionando, aquí tienes un reto: amplía la lógica de validación para verificar el rol del usuario desde una API real en el backend usando la nueva API httpResource de Angular. Muestra un mensaje de error al usuario si la petición al servidor falla.

Si quieres aprender a fondo este flujo de trabajo, te recomiendo mucho leer Spec-Driven Development de Bezael Pérez. Es una guía fantástica que te enseña las bases necesarias para construir aplicaciones estables con IA sin perder jamás el control de tu código.

En el próximo artículo, tomaremos este PRD y lo dividiremos en pequeñas tareas que la IA pueda construir una a una. ¡Nos vemos en el siguiente post!

Foto por Alvaro Reyes en Unsplash