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.

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. 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 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).

¿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 vagoCriterio comprobable
El modo oscuro debe funcionar bienEl 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ápidaLos resultados aparecen en menos de 300 ms con 1.000 registros
Los errores deben ser clarosSi 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).

¿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 CRUD95 %
Pruebas nuevas90 %
Migración de base de datos90 %
Componente de UI con un patrón existente85 %
Corrección de un error con pasos para reproducirlo80 %
Función nueva sin precedente50 %

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. Y para depurar una respuesta que no cumple un criterio, 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

Preguntas frecuentes

¿Qué debe tener un PRD para un agente de IA?
Un resumen del producto, usuarios y casos de uso, requisitos en forma de lista, restricciones técnicas, lo que queda fuera de alcance, los archivos que se modifican y los que no, y criterios de aceptación comprobables.
¿Por qué incluir una lista de archivos que no se deben tocar?
Porque sin ella un agente puede cambiar archivos cercanos a la tarea que nadie pidió. Blake Crosley, que escribió más de 30 PRDs para agentes, cuenta que esa sección fue la mayor mejora de su plantilla.
¿Qué tipo de tareas suele resolver bien un agente con un PRD?
Tareas acotadas y con patrones existentes, como endpoints CRUD, pruebas, migraciones o componentes que siguen un patrón del proyecto. Las funciones nuevas sin precedente, las decisiones de arquitectura y el código de seguridad fallan más.
¿Cómo se escribe un criterio de aceptación útil?
Como una condición observable y comprobable, por ejemplo ’el valor se guarda en el campo X y se restaura al recargar’, en lugar de ’la experiencia debe mejorar'.