3 de noviembre de 2026Actualizado el Fathy Shalaby17 min de lectura
Plantilla de PRD para agentes de código con IA (Claude Code, Cursor, Copilot)
Una plantilla de PRD para copiar y pegar para agentes de código con IA, dónde encaja junto a CLAUDE.md, AGENTS.md y las reglas de Cursor, y cómo escribir comprobaciones de aceptación que un agente pueda ejecutar.
Una plantilla de PRD para agentes de código con IA es un brief corto y específico de una tarea que le dice a Claude Code, Cursor o GitHub Copilot quién tiene el problema, qué debe cambiar, qué queda fuera del alcance y qué comprobaciones demuestran que el trabajo está terminado. Guarda las reglas estables del proyecto en CLAUDE.md, AGENTS.md o las reglas de Cursor. Guarda la decisión de la funcionalidad en el PRD. La plantilla de abajo cabe en una o dos páginas.
Ideas clave
Los agentes son rápidos y a menudo se equivocan un poco. En la encuesta de Stack Overflow de 2025, el 66 % de los desarrolladores señaló las soluciones de IA «casi correctas, pero no del todo» como una de sus principales frustraciones, y el 86,9 % se mostró preocupado por la precisión de los agentes de IA (Stack Overflow, 2025).
Los proveedores coinciden en que los archivos de instrucciones del proyecto deben ser breves y generales: Anthropic apunta a menos de 200 líneas por CLAUDE.md, Cursor recomienda mantener las reglas por debajo de 500 líneas, y el prompt de incorporación de GitHub limita las instrucciones de Copilot a 2 páginas y excluye el contenido específico de una tarea.
Por eso la decisión de la funcionalidad necesita su propio sitio: un PRD por tarea, enlazado desde el issue o la pull request.
La sección que más cambia el resultado del agente son las comprobaciones de aceptación. Un agente con una comprobación de pasa/falla puede probar y corregir su propio trabajo; uno sin ella se detiene cuando el trabajo simplemente parece terminado.
Los requisitos vagos ya eran caros antes de la IA. El PMI encontró una mala gestión de requisitos detrás del 47 % de los proyectos que no alcanzaron sus objetivos (PMI, 2014).
¿Qué es una plantilla de PRD para agentes de código con IA?
Un documento de requisitos de producto (PRD) para un agente de código responde las mismas preguntas que cualquier PRD: ¿de quién es el problema?, ¿qué debe cambiar? y ¿cómo sabremos que funcionó? La diferencia está en quién lo lee. Un ingeniero humano pregunta en Slack cuando algo es ambiguo. Un agente suele elegir una interpretación y seguir adelante.
La guía de Claude Code de Anthropic lo dice sin rodeos: Claude tiende a interpretar una petición en su sentido más estrecho y a construir lo mínimo que la satisface, porque no puede saber qué tan ambicioso querías ser (). La solución no es un prompt más largo. Es un brief que diga lo que un compañero humano habría captado en la sala.
Un agente de código y la persona que revisa su trabajo
Alcance
A menudo un release completo
Una tarea o un corte vertical
Extensión
A menudo varias páginas
Una o dos páginas; enlaces para el detalle
Ambigüedad
Se resuelve conversando
Se lista como preguntas abiertas y reglas de parada
No objetivos
Útiles
Obligatorios, para que el agente deje en paz el código contiguo
Criterios de aceptación
Los lee QA
Escritos como comprobaciones que el agente puede ejecutar y sobre las que puede informar
Dónde vive
Wiki o herramienta de documentos
Repositorio o issue, enlazado desde la pull request
¿Por qué necesitan un PRD los agentes de código con IA?
Porque el código no le dice a un agente qué problema de cliente importa, qué compromiso aceptó el equipo ni qué queda fuera del alcance a propósito. Esos datos viven en entrevistas, tickets y reuniones. Si nadie los escribe, el agente rellena el vacío con una suposición plausible.
El uso de agentes ya es lo bastante habitual como para que esto importe. En la encuesta de Stack Overflow de 2025, el 84 % de los encuestados usaba o planeaba usar herramientas de IA, el 14,1 % usaba agentes de IA en el trabajo a diario y otro 9 % cada semana. La confianza va por detrás del uso: el 46 % desconfiaba de la precisión de los resultados de la IA, frente al 33 % que confiaba en ella (Stack Overflow, 2025).
La intención vaga salía cara mucho antes de los agentes. La investigación de 2014 del PMI halló que la mala gestión de requisitos provocó que el 47 % de los proyectos fallidos no alcanzara sus objetivos y desperdició el 5,1 % de cada dólar gastado en proyectos (PMI, 2014). Con un agente, la misma vaguedad aparece como una pull request muy segura de sí misma en minutos en lugar de una sorpresa en la revisión del sprint.
La seguridad es el otro motivo para ser explícito. Veracode probó más de 100 modelos de lenguaje grandes y encontró que el 45 % de las muestras de código generadas introducía una vulnerabilidad del OWASP Top 10; en las muestras de Java, el fallo llegó al 72 % (Veracode, 2025). Un PRD no lo soluciona por sí solo, pero una lista de «no debe» y una comprobación de seguridad con nombre le indican tanto al agente como al revisor dónde mirar.
¿Qué va en CLAUDE.md o AGENTS.md y qué va en el PRD?
Reparte el contexto según cuánto tiempo sigue siendo cierto. Los archivos de instrucciones del repositorio contienen las reglas que valen para cada tarea. El PRD contiene la decisión de esta tarea. Mezclarlos empeora ambos: el archivo de instrucciones se hincha y la decisión de la funcionalidad queda enterrada.
Cada herramienta documenta sus propios archivos de instrucciones y su propio consejo de tamaño:
Herramienta
Archivos de instrucciones del proyecto
Pauta de tamaño del proveedor
Opción a nivel de tarea
Claude Code
CLAUDE.md (ámbitos managed, user, project y local), .claude/rules/ con filtros de ruta; lee AGENTS.md cuando no hay CLAUDE.md
Apuntar a menos de 200 líneas por archivo
Referenciar un archivo de spec con @path; pedirle a Claude que te entreviste y escriba SPEC.md
Cursor
.cursor/rules/*.mdc (siempre, inteligente, por archivo o manual); AGENTS.md, incluidos los anidados
Mantener las reglas por debajo de 500 líneas
Mencionar el archivo del PRD con @ en el chat
GitHub Copilot
.github/copilot-instructions.md, .github/instructions/*.instructions.md con applyTo; AGENTS.md, CLAUDE.md o GEMINI.md
Prompt de incorporación: no más de 2 páginas, sin contenido específico de una tarea
Archivos de prompt, elegidos en cada chat
Cualquier agente con AGENTS.md
AGENTS.md; gana el archivo más cercano al código editado
Sin campos obligatorios; lo usan más de 60 000 proyectos de código abierto
Dos detalles de la documentación de los proveedores marcan el reparto. Anthropic dice que Claude trata CLAUDE.md como contexto y no como configuración de cumplimiento obligatorio, y que los archivos más largos reducen el seguimiento. La documentación de Copilot de GitHub describe los archivos de prompt como algo que eliges en cada chat, a diferencia de las instrucciones, que se aplican automáticamente (GitHub Docs). Ambos apuntan en la misma dirección: las reglas duraderas van en el archivo que siempre se carga, las decisiones puntuales en un archivo que entregas para esa tarea.
Pon en las instrucciones del repositorio:
Los comandos de build, test, comprobación de tipos y lint, incluido cómo ejecutar un solo archivo de test
Los lugares donde el código engaña, como un patrón heredado que el código nuevo no debe copiar
Decisiones que no se ven en el código: el helper de errores, el proceso de despliegue, qué necesita una revisión de migración
Reglas de seguridad, privacidad y accesibilidad que valen en todas partes
Dónde viven las decisiones de producto, como un enlace
Pon en el PRD:
El usuario, el problema y la evidencia que lo respalda
El resultado, su línea base y las barreras de protección
Dentro del alcance, fuera del alcance y «no debe»
El comportamiento requerido, incluidos los estados vacío, de carga y de error
Las comprobaciones de aceptación y los comandos que las verifican
Las preguntas abiertas y quién las decide
La documentación de Cursor añade una regla útil para ambos: referencia archivos en lugar de copiar su contenido, porque las copias quedan obsoletas. Enlaza la investigación; no la pegues.
La plantilla de PRD para copiar para agentes de código con IA
Cópiala en docs/specs/<feature>.md o en el cuerpo del issue. Mantén cada respuesta breve y enlaza la investigación, los diseños o las notas técnicas para el detalle.
# PRD: [título provisional]
Responsable: [nombre] | Estado: borrador / aprobado | Fecha: [AAAA-MM-DD]
Issue / PR: [enlace]
## 1. Problema
- Usuario principal:
- Situación y problema (una frase):
- Evidencia: [enlaces]. Marca cada elemento como observado / inferido / supuesto.
- Por qué ahora:
- Qué todavía no sabemos:
## 2. Resultado
- Resultado para el usuario: ¿qué se vuelve más fácil, rápido o seguro?
- Señal de producto: el comportamiento que mostraría que ayudó
- Línea base: [número + fuente] o «desconocida: instrumentar primero»
- Barreras de protección: qué no debe empeorar (errores, privacidad, latencia, control del usuario)
## 3. Alcance
- Dentro del alcance:
- Fuera del alcance (no objetivos):
- No debe: [acciones o efectos secundarios prohibidos]
- Dependencias:
## 4. Comportamiento requerido
R1. Punto de entrada y camino principal, en lenguaje sencillo:
R2. Estados vacío, de carga y de error:
R3. Permisos y tratamiento de datos:
R4. Casos límite que cambian la decisión:
## 5. Contexto
- Comportamiento actual: [ruta, pantalla o archivo]
- Decisiones relevantes: [enlace al registro de decisiones]
- Restricciones conocidas: [plataforma, compatibilidad, latencia, política]
- Reglas del repositorio: ver CLAUDE.md / AGENTS.md
- Si dos fuentes se contradicen: detenerse y preguntar a [responsable]
## 6. Comportamiento de la IA (solo si la funcionalidad usa un modelo)
- Entradas que el modelo puede usar:
- Salida mostrada o guardada:
- Fundamentación: qué fuente respalda cada afirmación
- Incertidumbre: cuándo decir «evidencia insuficiente» o preguntar
- Control humano: qué acciones requieren revisión
- Manejo de fallos: tiempo de espera, salida mal formada, evidencia ausente
- Casos de evaluación: [enlace, incluidos ejemplos difíciles y negativos]
## 7. Comprobaciones de aceptación
AC1. Dado [estado], cuando [acción], entonces [resultado observable].
AC2. Si [condición no deseada], entonces el sistema deberá [alternativa segura].
AC3. Dado [usuario sin permiso], cuando [lo abra], entonces no aparecen datos restringidos.
AC4. Regresión: [comando de test existente] sigue pasando.
Verificar con: [comandos de test, comprobación de tipos, lint y extremo a extremo]
## 8. Acuerdo de ejecución del agente
1. Lee este PRD y las instrucciones del repositorio antes de editar.
2. Reformula el requisito y lista las preguntas abiertas. Espera respuestas sobre todo lo marcado como «decisión».
3. Propón un plan: archivos a cambiar, tests a añadir. Espera la aprobación.
4. Construye el corte más pequeño que pase las comprobaciones de aceptación.
5. Detente y pregunta antes de cambiar una API pública, tocar autenticación, facturación o migraciones, añadir una dependencia o resolver una pregunta abierta.
6. Ejecuta los comandos de verificación y pega los comandos y su salida.
7. Resume el comportamiento cambiado, las suposiciones y los riesgos pendientes.
¿Qué secciones importan más?
No objetivos y «no debe». Un no objetivo de una línea («ningún constructor de dashboards nuevo», «no cambiar las definiciones de informes») evita que un agente razonable convierta una petición pequeña en un rediseño. Algunas herramientas ya bloquean las acciones más arriesgadas. El modo automático de Claude Code, por ejemplo, bloquea por defecto los despliegues a producción y las migraciones, los force push y el merge de una pull request que ningún humano aprobó (Anthropic, permission modes). Tu lista añade las prohibiciones propias del producto que ninguna herramienta puede conocer: la lógica de precios, el texto de consentimiento, un correo dirigido a clientes.
Estado de la evidencia. Marcar cada línea de evidencia como observada, inferida o supuesta evita que una hipótesis parezca un hecho una vez que está en un documento ordenado. El rastreo de afirmaciones en 15 minutos para specs escritas por IA muestra cómo comprobarlo antes de la entrega.
Un límite: todo lo que se escribe en un PRD o en CLAUDE.md es una orientación que el agente puede decidir que no aplica. El consejo de Anthropic es que una regla que no admite excepciones pertenece a un hook, a una regla de denegación o a un ajuste gestionado, no a la prosa (Anthropic, Claude Code best practices).
¿Cómo escribir criterios de aceptación que un agente de código con IA pueda verificar?
Escribe cada comprobación de modo que devuelva pasa o falla, y nombra el comando o la observación que lo decide. La guía de Anthropic enumera los tipos de comprobaciones que Claude puede leer: un archivo de test, el código de salida de un build, un linter, un script que compara la salida con una fixture, o una captura de pantalla del navegador junto a la maqueta.
Dos sintaxis mantienen los criterios de aceptación comprobables:
Given / When / Then (dado / cuando / entonces), del desarrollo guiado por comportamiento: «Dada una vista guardada, cuando el usuario la elimina, entonces desaparece de la barra lateral y la API de listado ya no la devuelve».
EARS (Easy Approach to Requirements Syntax), creada por Alistair Mavin y sus colegas en Rolls-Royce y publicada por primera vez en 2009 (Mavin, EARS). Usa cinco patrones:
Patrón EARS
Plantilla
Ejemplo de producto
Ubiquitous
El sistema deberá …
La exportación deberá incluir una fila de encabezado.
Event-driven
Cuando [disparador], el sistema deberá …
Cuando una subida supere los 10 MB, el sistema deberá mostrar el límite de tamaño.
State-driven
Mientras [estado], el sistema deberá …
Mientras se ejecute una sincronización, el sistema deberá desactivar el botón Guardar.
Unwanted behaviour
Si [condición], entonces el sistema deberá …
Si el modelo no devuelve ninguna fuente, entonces el sistema deberá marcar el tema como «sin respaldo».
Optional feature
Donde [funcionalidad], el sistema deberá …
Donde el SSO esté activado, el sistema deberá ocultar el campo de contraseña.
Los ejemplos son ilustrativos. El patrón «Si … entonces» es el más útil para los agentes, porque el comportamiento no deseado es donde adivinan.
Después pide evidencia, no un veredicto. Anthropic recomienda pedirle a Claude el comando que ejecutó y su salida, porque la simple afirmación de que los tests pasan es una prueba débil. Como segunda línea de defensa, haz que una sesión nueva o un subagente que no escribió el código revise el diff contra el PRD.
Ejemplo completado: resúmenes de temas para transcripciones de entrevistas
Este ejemplo es ilustrativo, no una investigación de un cliente real.
Problema. Un equipo de producto de cinco personas tiene 12 transcripciones de entrevistas repartidas en varios documentos. Antes de una reunión de planificación quiere ver los problemas recurrentes sin perder la evidencia de los participantes que hay detrás de cada uno.
Comportamiento deseado. Un miembro del equipo selecciona transcripciones y pide un borrador de resumen de temas. Cada tema enlaza con los pasajes que lo respaldan. El miembro edita el resumen antes de compartirlo.
Dentro del alcance. Borradores de temas, enlaces a las fuentes, un paso de revisión editable.
Fuera del alcance. Publicar temas automáticamente, cambiar la roadmap, o presentar un recuento de temas de 12 entrevistas como una estimación válida para todo el mercado.
No debe. Inventar una cita, atribuir una afirmación al participante equivocado, o declarar una frecuencia que las transcripciones no respaldan.
Comprobaciones de aceptación.
Dada una transcripción con un pasaje sobre un problema de configuración, cuando el resumen incluye ese tema, entonces el lector puede abrir el pasaje exacto que lo respalda.
Si un tema no tiene ningún pasaje que lo respalde, entonces el sistema deberá marcarlo como «incierto» en lugar de rellenar el hueco.
Dado un resumen generado, cuando el miembro del equipo lo abre, entonces puede editarlo antes de compartirlo.
Dada una transcripción con información personal, cuando la funcionalidad la procesa, entonces se aplican las reglas de datos y acceso ya existentes del workspace.
Línea base. Desconocida. Antes de fijar un objetivo, el equipo cronometra cuánto tarda en encontrar a mano la evidencia de tres temas y cuenta las correcciones de los revisores. El ejemplo no supone ninguna mejora concreta.
¿Cómo entregas el PRD a Claude Code, Cursor o Copilot?
Redacta el PRD. Escríbelo tú, parte del generador de PRD gratuito o usa los prompts de cómo escribir un PRD con IA. En Claude Code puedes pedirle que te entreviste hasta poder escribir la spec y guardarla como SPEC.md.
Colócalo donde el agente pueda leerlo. Guárdalo en el repositorio o en el issue y referéncialo por ruta (@docs/specs/saved-views.md en Claude Code o Cursor).
Pide primero una reformulación y un plan. El modo plan de Claude Code deja que el agente lea y explore, pero bloquea las ediciones hasta que apruebes el plan. Corrige los malentendidos aquí, donde no cuestan nada.
Construye en una sesión nueva. Anthropic sugiere iniciar la construcción en una sesión nueva una vez que existe la spec, para empezar sin la charla de planificación y con la spec como definición de terminado.
Devuelve las decisiones nuevas al registro. Si el trabajo dejó al descubierto una decisión, actualiza el PRD o el registro de decisiones, no solo el chat.
Antes de dejar a un agente funcionando sin supervisión, Anthropic sugiere cinco preguntas: ¿sabe cómo es «terminado»?, ¿puede comprobar su propio trabajo?, ¿qué tiene permitido tocar?, ¿qué lo detiene? y ¿quién da el visto bueno al resultado? Las secciones 3, 7 y 8 de la plantilla responden cuatro de ellas.
¿Cuándo usar Spec Kit o Kiro en su lugar?
Usa un flujo de specs estructurado cuando quieras toda la cadena, no solo un mejor traspaso. Spec Kit de GitHub, con unas 150 000 estrellas, separa la spec («qué construir y por qué») del plan técnico y luego genera tareas e implementación (GitHub, Spec Kit). Kiro divide cada spec en requirements.md, design.md y tasks.md (Kiro docs). La plantilla de arriba corresponde al paso de requisitos: las secciones 1 a 4 y 7. Si tu equipo ya usa una de estas herramientas, pega las secciones de producto en su paso de spec en lugar de mantener dos documentos.
¿Qué extensión debe tener un PRD para un agente de código con IA?
Proporcional al riesgo del cambio. Estos rangos son una regla práctica, no un benchmark:
Cambio
Qué incluir
Extensión aproximada
Corrección de texto o pequeño ajuste de UI reversible
Problema, alcance, 1-2 comprobaciones
5-15 líneas
Corte de funcionalidad estándar
Secciones 1-5, 7 y 8
Alrededor de una página
Permisos, facturación, datos personales o afirmaciones generadas por IA
Plantilla completa con la sección 6, una comprobación de seguridad y un revisor con nombre
Hasta dos páginas, más enlaces
El límite superior sigue la misma lógica que aplican los proveedores a los archivos de instrucciones. Cada línea compite por la atención del modelo, así que un PRD de cinco páginas esconde la única restricción que importaba. Si una sección pasa de media página, probablemente contiene varias decisiones; divídela o enlaza. Para un PRD de un release completo escrito para personas, consulta cómo escribir un PRD.
Errores comunes con los PRD para agentes de código con IA
Pegar toda la wiki de producto. Más contexto no es mejor contexto. Enlaza las dos o tres fuentes que cambian la decisión.
Poner detalles de la funcionalidad en CLAUDE.md o AGENTS.md. Estos archivos se cargan en cada tarea. El prompt de incorporación de GitHub deja explícitamente fuera del archivo de instrucciones de Copilot el contenido específico de una tarea.
Requisitos como «haz que la IA sea precisa». Indica qué puede inspeccionar el usuario y qué hace el sistema cuando no puede cumplir el requisito.
Inventar un objetivo. Si no hay línea base, escribe «desconocida» e instrumenta primero.
Aceptar «hecho» sin salida. Pide los comandos y sus resultados.
Dejar que el agente escriba y apruebe su propio PRD. Un agente puede redactar uno, pero una persona tiene que confirmar el problema, la evidencia y el alcance.
Escribir reglas estrictas como prosa. «Nunca toques las migraciones» pertenece también a una regla de denegación o a un hook, además de al PRD.
Dónde encaja Specky
Specky redacta PRD en su editor de PRD con citas en línea a las llamadas de clientes, los tickets y el feedback de tu Product Graph, de modo que la sección de evidencia enlaza con fuentes reales. Su servidor MCP permite que Claude Code, Cursor y otros clientes MCP carguen ese brief directamente: get_coding_brief devuelve los PRD, las decisiones y la evidencia relevantes para un ticket, y todo lo que un agente escribe de vuelta llega como borrador para revisión humana. La configuración está en la página de configuración de MCP para agentes de IA.
Preguntas frecuentes
¿Un PRD para un agente de código con IA es distinto de un PRD normal?
Las preguntas son las mismas: quién tiene el problema, qué debe cambiar y cómo sabrás que funcionó. La versión para agentes es más corta, se limita a una tarea y es más explícita sobre los no objetivos, las reglas de parada y las comprobaciones que el agente puede ejecutar, porque un agente actúa ante la ambigüedad en lugar de preguntar. Mantén el brief proporcional al tamaño y al riesgo del cambio.
¿Qué extensión debe tener un PRD para Claude Code o Cursor?
Alrededor de una página para un corte de funcionalidad estándar, y hasta dos páginas para cambios que tocan permisos, facturación, datos personales o afirmaciones generadas por IA. Enlaza para el detalle. Los proveedores dan límites similares para los archivos de instrucciones: menos de 200 líneas por CLAUDE.md, menos de 500 líneas por regla de Cursor y no más de 2 páginas en el prompt de incorporación de GitHub.
¿Debe ir el PRD en CLAUDE.md o AGENTS.md?
No. CLAUDE.md y AGENTS.md se cargan en cada sesión, así que deben contener reglas duraderas del proyecto, como comandos, convenciones y restricciones de seguridad. Pon el PRD de la funcionalidad en su propio archivo o en el issue, y referéncialo para esa tarea. Un enlace al lugar donde viven las decisiones de producto es la cantidad justa de contexto de producto para el archivo de instrucciones.
¿Puede el agente de código escribir el PRD él mismo?
Puede redactar uno, ordenar tus notas y sugerir casos límite. Claude Code incluso puede entrevistarte y escribir un archivo de spec. Aun así, una persona tiene que confirmar el problema del usuario, la evidencia, el alcance y la señal de éxito, porque el texto generado no prueba que el equipo tomara esas decisiones. Trata un PRD redactado por un agente como un borrador.
¿Qué es el desarrollo guiado por specs (spec-driven development)?
El desarrollo guiado por specs consiste en escribir una especificación de qué construir y por qué antes de que un agente de IA planifique e implemente. Spec Kit de GitHub y Kiro lo formalizan en etapas: requisitos o spec, luego plan técnico o diseño, luego tareas y luego código. La plantilla de PRD de este artículo cubre la etapa de requisitos.
¿Cómo escribo criterios de aceptación para un agente de código con IA?
Escribe cada uno como una afirmación de pasa/falla vinculada a algo que el agente pueda ejecutar u observar: un test, un build, un linter, una comparación de fixture o una captura de pantalla. Usa la sintaxis Given/When/Then o EARS, incluye al menos un caso «si algo sale mal, entonces» y pídele al agente que pegue los comandos y su salida.
GDPR-aligned. EU workspace data is stored in Frankfurt, Germany. GDPR and EU data Built in Vienna, Austria. A product of influence solutions fm GmbH (FN 675374y). Imprint 14-day trial. Card required, and nothing is charged until day 14. 30-day refund after subscribing. See pricing