# Cómo escribir un PRD que un agente de IA entienda

> Un PRD para agentes de código necesita criterios comprobables, una lista de archivos que no se tocan y límites claros. Estructura, ejemplo y errores comunes.

*Tags: ia, prd, agentes, ux-para-ia*

---


> [!info] Definición Rápida
> **Un PRD para agentes** es un documento de requisitos escrito para que una IA que programa pueda ejecutarlo sin adivinar: define qué se construye, qué no se toca y cómo se verifica que quedó bien.


## ¿En qué se diferencia de un PRD para personas?

Un PRD tradicional convence a un equipo y deja espacio para conversar. Un agente no pregunta: cuando encuentra un hueco, elige la implementación que le parece más probable. Eso puede ser útil o puede significar que cambió un archivo que nadie esperaba. ChatPRD lo describe como un problema de "rellenar los huecos": si no indicas la tecnología o un requisito, la IA completa con lo que le parezca plausible. Por eso el PRD para agentes debe ser más explícito en tres cosas: el alcance, los límites y la forma de comprobar el resultado.

La base es la idea de especificación primero que describe [[spec-driven-development|spec-driven development]]. GitHub la presentó en septiembre de 2025 con su kit Spec Kit y un flujo de cuatro fases: especificar, planificar, dividir en tareas e implementar. El PRD es el documento concreto de la primera fase.

## ¿Qué secciones debe tener?

Esta estructura combina la plantilla de ChatPRD con la de Blake Crosley, que usa PRDs para que agentes implementen funciones:

1. **Resumen del producto.** Un párrafo con el objetivo principal, para que el agente tenga contexto antes del detalle.
2. **Usuarios y casos de uso.** Qué rol hace qué, y por qué. El "por qué" ayuda al agente a elegir entre opciones.
3. **Requisitos.** Agrupados por funcionalidad, cada uno con su lista de condiciones. Las reglas de negocio van dentro de la funcionalidad a la que aplican.
4. **Restricciones técnicas.** Framework, base de datos, dependencias permitidas y reglas de seguridad. No supongas que el agente las infiere. Las que valen para todo el proyecto pueden vivir en [[claude-md-y-agents-md|CLAUDE.md o AGENTS.md]].
5. **Fuera de alcance.** Lo que explícitamente no se hace. Es la forma más barata de evitar funciones que nadie pidió.
6. **Archivos que se modifican y archivos que no.** Con rutas concretas.
7. **Criterios de aceptación.** La lista que el agente y la persona revisan al final.

ChatPRD advierte contra las metas vagas: "mejorar la experiencia de usuario" es demasiado amplio y puede llevar a la IA a hacer muchos cambios sin relación ([ChatPRD, PRDs for AI Software Engineering](https://www.chatprd.ai/resources/prd-for-ai-codegen)).

## ¿Cómo se escribe un criterio de aceptación?

Un criterio sirve si alguien puede comprobarlo mirando la pantalla o ejecutando una prueba. Ejemplo ilustrativo de la diferencia:

| Criterio vago | Criterio comprobable |
|---|---|
| El modo oscuro debe funcionar bien | El botón aparece en Ajustes; al activarlo, el fondo cambia a #111; el valor se guarda en `user_preferences.dark_mode` |
| La búsqueda debe ser rápida | Los resultados aparecen en menos de 300 ms con 1.000 registros |
| Los errores deben ser claros | Si el correo está vacío, aparece "Escribe tu correo para continuar" bajo el campo |

Crosley escribe los criterios como casillas de verificación en Markdown que el agente marca durante la implementación. Su plantilla actual incluye la lista de archivos a modificar, la de archivos que no se tocan, las expectativas de pruebas y las restricciones, como no añadir dependencias nuevas. También nota que los agentes a veces ignoran las restricciones, y que las exclusiones explícitas ("NO hagas X") le funcionan mejor que las instrucciones en positivo ([Blake Crosley, PRD-driven development](https://blakecrosley.com/blog/prd-driven-development)).

## ¿Qué tareas funcionan y cuáles no?

Crosley reporta tasas de éxito aproximadas de su propio repositorio, tras más de 30 PRDs. Son cifras de un solo autor y un solo proyecto, no una medición general, pero el patrón es útil:

| Tipo de tarea | Éxito aproximado |
|---|---|
| Endpoint CRUD | 95 % |
| Pruebas nuevas | 90 % |
| Migración de base de datos | 90 % |
| Componente de UI con un patrón existente | 85 % |
| Corrección de un error con pasos para reproducirlo | 80 % |
| Función nueva sin precedente | 50 % |

Según el mismo autor, falla más con requisitos ambiguos, decisiones de arquitectura, optimización de rendimiento y código crítico de seguridad, como los casos borde de autenticación. La conclusión práctica: un PRD bien escrito amplía lo que el agente puede hacer solo, pero en las zonas ambiguas la revisión humana sigue siendo la protección principal.

## Ejemplo

Ejemplo ilustrativo: un diseñador quiere que el agente agregue una opción de modo oscuro a un panel. El PRD tiene tres líneas de resumen, una lista de requisitos (el botón aparece en Ajustes, la preferencia se guarda por usuario, el valor por defecto es claro), una restricción ("no añadir dependencias") y una lista de archivos que no se tocan: el componente de login y la configuración de la base de datos. Los criterios son cuatro, todos comprobables. Al terminar, el diseñador revisa el diff contra esos cuatro criterios antes de aceptar el cambio.

## ¿Cómo lo aplico mañana?

1. Escribe el PRD de una tarea pequeña, como añadir un campo a un formulario, con las siete secciones de este artículo. Anota cuánto tiempo te toma y cuántas preguntas quedan sin responder.
2. Antes de pedir el cambio, pide al agente que repita el PRD con sus palabras. Si lo repite mal, el documento tiene un hueco.
3. Lista tres archivos que no deben tocarse y escríbelos en el PRD con la razón.
4. Al revisar, marca cada criterio como cumplido o no cumplido. Si un criterio no se puede marcar, reescríbelo como condición observable.
5. Guarda el PRD en el mismo repositorio que el código y actualízalo en el mismo cambio cuando una regla cambie. Si vive aparte, es fácil que quede desactualizado.

Para ver el flujo completo, lee [[spec-driven-development|spec-driven development]]. Y para depurar una respuesta que no cumple un criterio, [[debugging-con-ia|debugging con IA]].

## Errores comunes

- Escribir el PRD como una conversación en lugar de una lista de condiciones.
- Omitir la lista de archivos que no se deben tocar.
- Criterios que dependen de juicio subjetivo.
- No decir qué queda fuera de alcance.
- Pedir funciones de seguridad o de arquitectura sin revisión humana.
- Actualizar el código pero no el PRD, de modo que el documento queda obsoleto.

## Fuentes

- ChatPRD, "PRDs for AI Software Engineering": [https://www.chatprd.ai/resources/prd-for-ai-codegen](https://www.chatprd.ai/resources/prd-for-ai-codegen)
- Blake Crosley, "PRD-driven development": [https://blakecrosley.com/blog/prd-driven-development](https://blakecrosley.com/blog/prd-driven-development)
- GitHub Blog, "Spec-driven development with AI: Get started with a new open source toolkit": [https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)


---

Source: https://www.fernandoux.com/es/wiki/ia/prd-para-agentes/