Alguien te pasa una «spec» y resulta ser un argumento de dos páginas sobre por qué importa la feature. Otra persona te pasa un «PRD» y es una lista de endpoints de API. Las palabras se han difuminado hasta el punto de que saber qué documento tienes en la mano no te dice casi nada de lo que hay dentro.
Ese difuminado es inofensivo cuando lo lee una persona, porque una persona rellena los huecos con contexto. Deja de ser inofensivo en cuanto le pasas el documento a un agente, que no rellena los huecos con contexto sino que más bien los inventa. Así que vale la pena ser preciso: un PRD y una spec son documentos distintos que hacen trabajos distintos, y un agente necesita algo concreto de cada uno.
Para qué sirve un PRD
Un documento de requisitos de producto responde a por qué y qué, para quién. Es el caso a favor de construir algo: el problema, quién lo tiene, cómo se ve el éxito, qué entra y qué sale del alcance a nivel de producto. Su audiencia es la gente que necesita estar de acuerdo en que esto merece la pena antes de que nadie construya.
Un buen PRD trata sobre todo de intención y criterio. Defiende una dirección, registra los trade-offs y dibuja el límite alrededor del problema. Lo que deliberadamente no hace es fijar la implementación. Un PRD que especifica endpoints exactos suele haberse salido de su carril.
El modo de fallo de los PRD es de sobra conocido: se hacen largos, se leen una vez y luego se quedan sin leer mientras las decisiones de verdad pasan en Slack. Es el problema del PRD que nadie lee, y vale la pena nombrarlo aquí porque es justo la parte de un PRD que un agente no puede usar. La prosa que defiende una dirección es para humanos que deciden. No es algo contra lo que un agente pueda construir.
Para qué sirve una spec
Una especificación responde a qué tiene que ser cierto y cómo lo sabrás. Es el contrato entre la intención acordada y la implementación: el comportamiento que tiene que cambiar, las restricciones que tienen que sostenerse y los criterios de aceptación que deciden si el resultado es correcto.
Una spec está aguas abajo de un PRD. El PRD dice «compra como invitado, porque perdemos registros en el muro de la cuenta». La spec dice «los usuarios invitados completan la compra en tres pasos; no se guardan datos de tarjeta; el camino con sesión iniciada no cambia; aquí están los criterios de aceptación». Uno defiende la dirección. La otra define la línea de meta con la precisión suficiente para poder decirle a una máquina cuándo la ha cruzado.
Donde un PRD es sobre todo criterio, una spec es sobre todo precisión. Y la precisión es justo lo que hace una spec construible y verificable, que es toda la premisa del desarrollo guiado por especificaciones.
Los dos documentos lado a lado
| PRD | Spec | |
|---|---|---|
| Pregunta | Por qué, y qué para quién | Qué tiene que ser cierto, y cómo lo sabemos |
| Audiencia | Quien decide construir | Quien (o lo que) construye y verifica |
| Contenido | Problema, usuarios, éxito, alcance | Comportamiento, límites, criterios de aceptación |
| Registro | Argumento y criterio | Contrato y precisión |
| Vida útil | La decisión | La implementación y su verificación |
Las filas importan menos que la separación que describen. Un PRD sirve para llegar a una decisión. Una spec sirve para ejecutarla correctamente. Cuando un documento intenta hacer las dos, no hace bien ninguna: demasiado vago para construir contra él, demasiado detallado para decidir desde él.
Qué necesita un agente de cada uno
Aquí es donde la distinción deja de ser pedante. Un agente necesita cosas distintas de los dos documentos, y darle las partes equivocadas es como consigues output convencido y equivocado.
Del PRD, un agente necesita intención y límites, no el argumento. Los tres párrafos sobre por qué importa la compra como invitado son para los humanos que la aprobaron. Lo que el agente necesita extraer es la versión comprimida: construye la compra como invitado, aquí está para quién es, aquí está lo que queda fuera. Dale a un agente el PRD persuasivo completo y tratará el énfasis retórico como requisitos, y construirá aquello con lo que el documento se entusiasmó más, no lo que se decidió.
De la spec, un agente necesita el contrato, sobre todo los criterios de aceptación. Esta es la parte que tiene que ser utilizable por una máquina. Límites que no debe cruzar, comportamiento que debe producir y criterios de aceptación que puede verificar de verdad en lugar de asentir ante ellos. Un agente que recibe una spec precisa puede contrastar su propio trabajo contra ella. Un agente que recibe una vaga informará de éxito contra criterios que se inventó.
El error más común, con diferencia, es darle a un agente un PRD y esperar resultados a nivel de spec. El documento se escribió para ganar una decisión, no para definir una línea de meta. El agente lee intención donde necesitaba un contrato, y produce algo que argumenta bien y verifica mal.
El traspaso entre ellos
El PRD y la spec son dos etapas de un solo flujo, no rivales. El PRD zanja el para qué y el si. La spec convierte la decisión zanjada en un qué exactamente y un cómo lo sabemos. El traspaso entre ellos es donde mucho trabajo asistido por IA se rompe en silencio: la decisión vive en un artefacto, el contrato en otro, y nada los conecta, así que la razón detrás de la spec se pierde y la spec deriva de la decisión que la motivó.
En la práctica no siempre necesitas una versión pesada de los dos. Un cambio pequeño puede colapsar el PRD en dos frases de intención y poner el peso en la spec. Está bien, y es el núcleo de un flujo spec-driven ligero: conserva la intención y el contrato, suelta la ceremonia que no sirve a ninguno. Lo que no puedes hacer es colapsarlos en un único documento vago y esperar que el agente distinga qué partes son el argumento y cuáles el contrato.
Dónde encaja PaellaDoc
El hueco entre un PRD y una spec es un hueco entre dos documentos en dos herramientas que no saben la una de la otra. PaellaDoc mantiene los dos en un solo modelo local: la intención y los límites de la decisión, conectados con el contrato y los criterios de aceptación de la spec, conectados a su vez con el código y la evidencia. Un agente lee la intención como intención y el contrato como el contrato, y la decisión detrás de una spec sigue unida a ella en vez de perderse en el traspaso.
Preguntas frecuentes
¿Necesito un PRD y una spec para cada cambio? No. Los cambios grandes o compartidos se benefician de los dos. Para un cambio pequeño, dos frases de intención más una spec apretada bastan. La idea es mantener los dos trabajos distintos, no producir siempre dos documentos.
¿Una spec es solo un PRD más detallado? No, y tratarla así es el error. Un PRD defiende una decisión; una spec define un contrato. Más detalle en un PRD hace un PRD largo, no una spec. Se diferencian en clase, no en nivel de detalle.
¿Desde cuál construye de verdad un agente de IA? Desde la spec. El PRD le da al agente intención comprimida y límites; la spec le da el contrato y los criterios de aceptación contra los que construye y verifica. Dale solo un PRD y se inventará el contrato, normalmente mal.