PRD para agentes de código IA: que Claude Code lo construya

Un PRD del que un agente de código pueda construir es corto, declarativo y verificable. Cada requisito es una frase numerada que dice qué hace el sistema, cada uno tiene un criterio de aceptación que el agente puede comprobar ejecutando algo, y los no-objetivos están escritos para que el agente no rellene los huecos con suposiciones. Todo lo demás de un PRD clásico, el contexto, las personas y el mercado, pasa a un anexo o desaparece.

Dirigimos una pequeña empresa de software con Claude Code, Cursor y Codex, y reescribimos nuestra plantilla de PRD dos veces en 2026 antes de que dejara de producir software equivocado. Este artículo es lo que nos quedó, con el razonamiento, una tabla de antes y después y un ejemplo copiable.

Por qué el PRD cambió en 2026

Durante veinte años un PRD fue un documento de alineación. Su lector era una persona: un ingeniero que haría preguntas en una reunión, rebatiría un mal requisito y rellenaría pequeños huecos con criterio. Un PRD podía ser vago porque un humano resolvía la vaguedad.

Un agente de código resuelve la vaguedad eligiendo la interpretación estadísticamente más probable y construyéndola, rápido, sin preguntar. Ese es todo el problema. La ambigüedad que antes costaba una conversación de diez minutos ahora cuesta una implementación errónea, una revisión, un revert y una segunda ejecución. Los equipos que entregan con agentes todo el día notaron lo mismo en 2025: la calidad del resultado seguía la calidad de la especificación escrita más de cerca que la elección del modelo.

Dos proyectos de código abierto hicieron visible el cambio. Spec Kit de GitHub, publicado en septiembre de 2025, estructura el trabajo del agente como una secuencia con compuertas: una constitución de principios del proyecto, una especificación, un plan técnico, una lista de tareas y solo entonces la implementación. A octubre de 2026 el repositorio muestra unas 143.000 estrellas. Task Master, de Eyal Toledano, hace algo más acotado: task-master parse-prd your-prd.txt convierte un PRD en una lista de tareas ordenada por dependencias que Cursor, Windsurf o Claude Code van resolviendo; el repositorio muestra unas 28.000 estrellas a octubre de 2026. Ambas herramientas asumen que el PRD es la interfaz con el agente, no un memorando para el equipo.

Ese es el cambio en una frase: el PRD dejó de ser un documento que la gente acuerda y pasó a ser la entrada que un agente ejecuta.

Qué necesita un agente de un PRD

Un agente necesita cuatro cosas, y la mayoría de los PRD no le dan ninguna de forma limpia.

Requisitos numerados y atómicos. Una frase por requisito, con un ID estable (R1, R2, R3). "El usuario puede restablecer su contraseña por correo" es un requisito. "El usuario tiene una experiencia fluida de recuperación de cuenta" no lo es. Los ID importan porque el agente, el plan, las tareas y las pruebas se referirán a ellos.

Un criterio de aceptación que el agente pueda probar. Para cada requisito, escribe cómo es una comprobación que pasa, en términos que el agente pueda ejecutar: una respuesta HTTP, un estado de base de datos, un elemento renderizado, un código de salida de CLI. Si no puedes formular la comprobación, el requisito no está terminado.

No-objetivos explícitos. Los agentes sobreconstruyen. Sin control, "añadir restablecimiento de contraseña" se convierte en un flujo de restablecimiento más un limitador de peticiones más un registro de auditoría más una página de ajustes para configurarlos. Una sección de no-objetivos ("Sin limitación de peticiones en esta iteración. Sin UI de administración. Sin SMS.") es la línea más barata que puedes añadir a un PRD, y elimina más trabajo desperdiciado que cualquier otra.

Restricciones y la forma actual del sistema. Qué framework, qué base de datos, dónde vive la autenticación, qué archivos no tocar, qué convenciones seguir. Spec Kit lo llama la constitución. En Cursor vive en los archivos de reglas; en Claude Code vive en CLAUDE.md; en Codex vive en AGENTS.md. El PRD debe referenciarlos en lugar de repetirlos.

Antes y después: el mismo requisito, reescrito

La tabla siguiente sale de nuestros propios PRD. La columna izquierda es como escribíamos antes; la derecha es sobre lo que un agente puede actuar.

Línea de PRD clásico	Versión construible por un agente
"Los usuarios deberían poder recuperar su cuenta fácilmente."	R1: Un usuario sin sesión puede solicitar un restablecimiento de contraseña introduciendo su correo. R1 pasa cuando POST /auth/reset con un correo conocido devuelve 200 y crea una fila `password_reset` con caducidad de 30 minutos.
"La exportación debería ser rápida y fiable."	R4: Exportar un espacio de hasta 10.000 incidencias termina en menos de 60 segundos y produce un ZIP. R4 pasa cuando la prueba de integración `export_10k` termina en menos de 60 s en CI.
"Añadir buen manejo de errores."	R7: Todo error de la API devuelve `{ error: { code, message } }` con un estado 4xx o 5xx. R7 pasa cuando la prueba existente de forma de error cubre los tres endpoints nuevos.
"Notificaciones para eventos importantes."	R9: Un comentario en una incidencia asignada al usuario envía un correo en menos de 5 minutos. No-objetivo: sin push, sin resumen, sin preferencias por usuario en esta iteración.
"Compatible con móvil."	R12: La página de reservas se renderiza sin scroll horizontal a 375 px de ancho. R12 pasa cuando la comprobación de Playwright a 375 px no informa de desbordamiento.

La columna derecha es más larga por requisito y más corta en conjunto, porque los párrafos vagos que rodeaban cada línea han desaparecido.

La plantilla, sección por sección

Este es el esqueleto que usamos. Es Markdown porque todos los agentes leen Markdown y porque hace diff limpio en Git. Dentro del bloque de código, las etiquetas de sección van en negrita y no como encabezados, para que la estructura siga visible.

**Funcionalidad:** Restablecimiento de contraseña por correo
**Responsable:** (nombre)   **Estado:** Borrador | Congelado   **Línea base:** v1 (2026-10-28)

**Problema**
Los usuarios que olvidan su contraseña escriben a soporte. Soporte atendió
41 correos así en septiembre de 2026. No existe una vía de autoservicio.

**Objetivo**
Un usuario sin sesión puede restablecer su contraseña en menos de dos
minutos sin contactar con nadie.

**Requisitos**
R1. Un usuario sin sesión puede solicitar un restablecimiento introduciendo
    su correo.
    Pasa: POST /auth/reset con un correo conocido devuelve 200 y crea una
    fila password_reset que caduca en 30 minutos.
R2. Un correo desconocido devuelve la misma respuesta 200 y no crea nada.
    Pasa: POST /auth/reset con un correo desconocido devuelve 200; el
    recuento de filas no cambia.
R3. El correo de restablecimiento contiene un enlace que abre un formulario
    con campos de nueva contraseña y confirmación.
    Pasa: el enlace del correo de prueba capturado resuelve a
    /auth/reset/:token y muestra ambos campos.
R4. Enviar un token válido y contraseñas coincidentes actualiza el hash,
    borra el token e inicia sesión.
    Pasa: la prueba de integración reset_happy_path termina y el usuario
    llega a /home.
R5. Los tokens caducados o usados muestran "Este enlace ha caducado" y un
    botón para pedir uno nuevo.

**No-objetivos**
Sin limitación de peticiones en esta iteración. Sin SMS. Sin UI de
administración. Sin cambios en el formulario de inicio de sesión.

**Restricciones**
Seguir CLAUDE.md. Usar el mailer existente (lib/mail). No añadir
dependencias. Los tokens son 32 bytes aleatorios en hexadecimal.

**Preguntas abiertas**
Q1. ¿Un restablecimiento debe cerrar también las demás sesiones?
    Responsable de la decisión: (nombre), fecha 2026-10-30. Hasta que se
    decida, no implementar.

**Fuera del alcance del agente**
El texto del cuerpo del correo: un marcador de posición es suficiente.

Algunas notas sobre las decisiones.

Estado y línea base. "Congelado" con versión y fecha significa que el agente construye contra este texto y nada más nuevo. Congelamos antes de la primera ejecución y subimos la versión cuando cambia un requisito, para que una auditoría posterior pueda comparar lo entregado con lo acordado.
Líneas "Pasa". Se escriben junto al requisito, no en un plan de pruebas aparte. El agente las lee como especificación de prueba, y la mayoría escribirá primero la prueba.
Preguntas abiertas con responsable. Una pregunta abierta sin responsable es un hueco que el agente rellenará. "Hasta que se decida, no implementar" es la instrucción que lo evita.

Cómo escribir uno en una tarde

Escribe el problema en tres frases con un número real. Si no tienes el número, ve a buscarlo. "Soporte atendió 41 correos de restablecimiento en septiembre" gana a "los usuarios tienen problemas con la recuperación".
Lista los requisitos como frases sueltas y numéralos. Apunta a entre 5 y 15. Si pasas de 20, la funcionalidad son dos funcionalidades; divide el PRD.
Escribe una línea "Pasa" bajo cada requisito. Si no puedes, o el requisito no es atómico o aún no sabes cómo es "hecho". Ambas cosas conviene descubrirlas antes que el agente.
Escribe los no-objetivos antes de que nadie lea los requisitos. Pregúntate: ¿qué añadiría aquí un ingeniero entusiasta que no queremos? Anótalo.
Apunta al archivo de restricciones en lugar de repetirlo. Mantén CLAUDE.md, AGENTS.md o tus reglas de Cursor como única fuente de convenciones.
Congélalo. Marca el estado, fija la versión y ponlo donde el agente pueda leerlo: un archivo en el repositorio o una página que el agente pueda obtener a través de un servidor MCP.
Ejecuta el agente solo sobre R1. Revisa ese resultado antes de dejarle ejecutar el resto. El primer requisito te dice si el agente puede leer el PRD en absoluto.

Dónde vive el PRD y cómo lo lee el agente

Un PRD en un Google Doc es invisible para Claude Code. Las opciones que funcionan:

Un archivo en el repositorio. docs/prd/password-reset.md, referenciado desde CLAUDE.md o AGENTS.md. Lo más simple, con control de versiones, y todos los agentes pueden leerlo. Spec Kit y Task Master asumen esto.
Una página que el agente obtiene por MCP. Si tu equipo escribe los PRD en una herramienta de espacio de trabajo y no en el repositorio, un servidor MCP permite al agente leer la página directamente. Atrix expone sus páginas, incidencias y ciclos a través de un servidor MCP con 85 herramientas y OAuth 2.1; está listado en el Official MCP Registry y en Glama. El efecto práctico es que un agente de código puede leer la página del PRD congelado, crear las incidencias planificadas y actualizarlas al terminar, sin copiar texto entre herramientas. El límite, dicho claramente: el agente lee y escribe objetos del espacio de trabajo; no ejecuta tu código ni tus pruebas.
Ambos. Mantenemos el PRD canónico como página, y el agente copia la versión congelada al repositorio al inicio de una ejecución para que el commit registre exactamente a partir de qué construyó.

Para Cursor y Codex en concreto, la integración con Cursor y la integración con Codex describen la configuración: una conexión OAuth, y después el agente ve el PRD, el backlog y el ciclo actual como herramientas.

Qué dejar fuera

Todo lo que un humano necesita y un agente no:

Personas e investigación de usuarios. Déjalas en una página enlazada; el agente necesita el requisito, no la persona.
Análisis de la competencia. Lo mismo.
Maquetas, salvo que el requisito sea visual. Si lo es, una captura que el agente pueda ver vale más que tres párrafos describiéndola.
Cronogramas. El agente no planifica sprints; eso lo hace tu ciclo.

El PRD clásico sigue existiendo; solo deja de ser el documento que lee el agente. Si quieres la forma larga para las partes interesadas, nuestra plantilla de PRD con IA cubre esa versión, y la plantilla de PRD del sitio es la copia alojada que puedes duplicar.

Preguntas frecuentes

¿Un PRD para un agente de código IA es lo mismo que una especificación en el desarrollo guiado por especificación?

Casi. El desarrollo guiado por especificación, tal como lo plantea Spec Kit, separa la especificación (qué y por qué) del plan (cómo, con qué stack) y de las tareas (el trabajo ordenado). El PRD descrito aquí es la capa de especificación. El plan y las tareas se generan a partir de él, por el agente o por una herramienta como Task Master.

¿Qué longitud debe tener un PRD para Claude Code o Cursor?

Lo bastante corto para caber en el contexto del agente junto al código que toca. En la práctica, entre 400 y 1.200 palabras, con 5 a 15 requisitos numerados. Si es más largo, divide la funcionalidad.

¿Sigo necesitando historias de usuario?

No en la forma "Como usuario, quiero". El agente necesita el requisito y el criterio de aceptación; la envoltura de historia añade palabras sin añadir contenido verificable. Conserva las historias si tu equipo las usa para planificar, pero pon primero los requisitos numerados.

¿Qué va en CLAUDE.md o AGENTS.md y qué va en el PRD?

Las convenciones van en el archivo de reglas: stack, estructura de carpetas, comandos de prueba, estilo, archivos que no tocar. El PRD es por funcionalidad y referencia el archivo de reglas. Repetir convenciones en cada PRD provoca desviaciones entre ellos.

¿Debería escribir el PRD el agente?

Puede redactar un borrador a partir de un brief, y ese borrador suele ser una buena lista de lo que aún no has decidido. El agente de Atrix lo hace en una ejecución Develop: entra un brief, salen requisitos, arquitectura e incidencias planificadas, con 100 ejecuciones al mes en Builder. Pero la congelación, los no-objetivos y las decisiones sobre preguntas abiertas son tuyas. Un agente no sabrá qué no quieres que se construya.

¿Cómo sé si el agente construyó lo que decía el PRD?

Compara el resultado con la línea base congelada, requisito por requisito, usando las líneas "Pasa". La auditoría de requisitos de Atrix hace esa comparación contra la página congelada; comprueba cobertura y desviación de requisitos, no el código en sí. Para el código, ejecuta las pruebas que implican las líneas "Pasa" y revisa a mano las rutas de autenticación y pagos.

Siguiente paso

Copia la plantilla de PRD, escribe R1 con su línea "Pasa" y ejecuta tu agente sobre ese único requisito antes de escribir R2. Si tus PRD viven fuera del repositorio, el servidor MCP es la forma en que Claude Code, Cursor y Codex los leen.

Fuentes

Repositorio de GitHub Spec Kit, estrellas consultadas el 27 de octubre de 2026; Spec-driven development with AI: get started with a new open source toolkit, GitHub Blog, septiembre de 2025; Repositorio de Task Master, estrellas consultadas el 27 de octubre de 2026.

Cómo escribir un PRD que Claude Code o Cursor puedan construir