10. PRD — qué construir antes de cualquier línea de código

Los primeros nueve artículos de esta serie trataron sobre qué es Alice — persona, memoria, skills, hooks, Multi-Agent, verificación, economía de tokens, protocolos de sesión. Cosas que viven dentro del sistema.

Los próximos tres artículos tratan sobre el trabajo que fluye a través de Alice. La forma de la intención antes de que empiece el código, la puerta que dice cuándo el código está listo, y el bucle que ejecuta ambos sin el operador en el teclado.

Este es el primero de esos tres. PRD.

0. La premisa — el código es lo último que se escribe

La mayoría de los operadores empieza por el código. Abrir el editor, escribir una función, ver si funciona.

Ese patrón colapsa en el momento en que el trabajo se vuelve más grande que una sola tarde. El código de ayer no recuerda por qué existe. La sesión de mañana no sabe qué cuenta como listo. El líder del equipo aprueba una porción y semanas después la porción ya no encaja.

El problema no es el código. El problema es que la intención nunca quedó escrita en ningún lugar duradero. El operador la llevaba en la cabeza, la IA llevaba fragmentos en la context window, y ambas superficies se evaporan.

PRD — Product Requirement Document — es la respuesta. No un artefacto de planificación. Una superficie donde la intención del operador vive fuera de la sesión, donde la próxima sesión y el próximo colaborador pueden leerla sin volver a preguntar.

1. Qué se rompe cuando no hay PRD

Algunos patrones que he visto colapsar, en mi propio trabajo y en entregas que me hicieron.

• Putrefacción de decisiones. Una elección se toma en una sesión de chat. Tres semanas después nadie — incluido el operador — recuerda por qué. El código vuelve atrás, deriva, o se vuelve a litigar cada sesión.
• Deriva de alcance. "Ya que estamos" se cuela. Para cuando se entrega la porción, ha hecho cuatro cosas en lugar de una, y ninguna de las cuatro está revisada.
• Colapso de la definición de listo. Alguien reporta "la feature está dentro." El líder del equipo pregunta "¿en qué sentido?" ¿Construida? ¿Probada? ¿Live? ¿Revisada? Cada respuesta es parcialmente sí y la conversación da vueltas.
• Colapso del onboarding. Un nuevo colaborador — un agente distinto, un compañero distinto, la futura Alice en un contexto nuevo — no tiene punto de entrada. Hacen ingeniería inversa de la intención a partir del código, que es exactamente el bucle que el operador pagó por evitar.

El hilo común es el mismo con el que abrió la Parte 1 — Por qué Alice. La mente del operador — el propósito detrás del código — no sobrevive al límite de la sesión.

2. El PRD es la mente hecha duradera

El trabajo de un PRD es estrecho y específico. No planifica tareas, no asigna responsables, no rastrea progreso. Eso pertenece a otro lugar.

Un PRD responde a una pregunta: ¿qué estamos construyendo, y qué hace que cuente como construido?

Fíjate en lo que no está en esta lista. No hay lista de tareas, no hay log diario, no hay quién-hizo-qué. Esas cosas cambian cada sesión. Un PRD cambia cuando cambia la intención, que es mucho más lento.

Un PRD describe el destino. Todo lo demás describe la ruta.

3. Qué poner dentro, y qué dejar fuera

La regla a la que llegué, después de escribir PRDs que crecieron hasta cuarenta páginas y PRDs que cabían en una postal:

Va en el PRD si: cambiar la línea cambia lo que el sistema es. Ejemplos — "i18n es obligatorio, seis locales," "las descargas deben mostrar SHA-256," "el nombre real del operador no aparece en ningún sitio."

No va en el PRD si: cambiar la línea cambia solo cómo se construye el sistema. Ejemplos — "usar pnpm para los builds," "usar shadcn para primitivas de UI," "etiquetar commits con el prefijo [devAlice]."

La segunda lista vive en CLAUDE.md o un README o un documento de tooling. No el PRD.

La razón de esta separación no es estética. Es vida útil. Las líneas del PRD deberían sobrevivir un año. Las líneas del sistema de build pueden no sobrevivir dos trimestres. Mantenerlas en documentos distintos permite que cada una se pudra a su propio ritmo sin arrastrar a la otra.

4. El patrón de puerta acumulativa

El patrón más útil que he usado en PRDs es una sección de release gates acumulativa.

La forma:

Gate 0: lanzamiento M0 (dominio temporal)
  - Build pasa
  - Cuatro rutas de categoría renderizan
  - Una guía semilla por categoría
  - ESLint clean

Gate 1: cumplimiento (requerido antes de la publicación)
  - Privacy Policy (ko + en)
  - Licencia de contenido (CC BY)
  - Licencia de código (MIT)
  - Página About existe
  - ...

Gate 2: infraestructura
  - Dominio personalizado vinculado
  - SSL activo (auto)
  - Variables de entorno de producción configuradas
  - ...

Gate 3: seguridad
  - Sin secretos hardcodeados
  - .env.example tiene todas las claves
  - RLS activado en tablas de usuario
  - ...

... Gate 10

Cada gate es una tabla. Cada fila es [ítem | estado | nota]. El estado es uno de ✅ pasa / ⏳ en progreso / 🔒 esperando al operador / ❌ no iniciado / — N/A.

Tres cosas hacen que este patrón funcione.

Acumulativo. El Gate 2 asume que el Gate 1 pasó. El Gate 9 asume los Gates 0–8. La forma del camino está incorporada. Nadie tiene que preguntar "¿en qué orden?" — el documento responde.

Filas atómicas. Una fila o pasa o no pasa. "Más o menos funciona" no es un estado. Esto obliga al operador a descomponer ítems vagos ("el rendimiento está bien") en filas que se pueden marcar ("Lighthouse Performance ≥ 90 en cinco páginas de referencia").

Estado visible a nivel de fila. El operador no necesita leer prosa para saber dónde está el proyecto. Una ojeada a la columna — contar los ✅ frente a los 🔒 — y la imagen es inmediata.

Esta es la sección que el líder del equipo lee primero, cada sesión. También es la sección que impulsa la Parte 11 — Release gates y la Parte 12 — Ralph loop.

5. PRD frente al plan puntual

Los operadores a menudo confunden un PRD con el plan a nivel de sesión. No son lo mismo. Viven en escalas de tiempo distintas.

Una línea de intención que rebota entre estos — cayendo en HANDOFF un día, en PLAN al siguiente, en una sesión de chat al siguiente — nunca se acumula. La misma intención tiene que poder expresarse en un único lugar consistente. El PRD es ese lugar.

Cuando empieza una sesión, Alice lee primero PRD.md, luego HANDOFF.md, luego PLAN.md. Las lecturas se componen. El PRD fija qué cuenta; el HANDOFF dice dónde lo dejó el operador; el PLAN dice qué está pasando en esta porción.

6. Mantener vivo el PRD

Un PRD que se pudre es peor que no tener PRD, porque todos siguen leyéndolo y actuando sobre intención obsoleta. Tres hábitos que mantengo en rotación.

Versionado in-place. Al inicio del archivo: v1.0 → v1.1 → v1.2. Cada versión tiene una nota de una línea sobre qué cambió. La versión actual es la que dice la última línea. No hay archivo de changelog aparte.

La sección de preguntas abiertas es obligatoria. Cada PRD que escribo tiene una sección de "preguntas abiertas" que nunca está vacía durante el desarrollo activo. El día que se vacía, o bien el proyecto está hecho o bien alguien esconde decisiones en su cabeza.

Revisión de estado en cada hito. Cuando un hito se cierra, recorrer la tabla entera de gates. Los ítems que derivaron a ✅ durante el hito se promueven; los ítems sin tocar migran a la sección de preguntas abiertas. El PRD es la instantánea de la intención actual, no de la intención histórica.

7. Las trampas

Patrones que he visto romper PRDs en la práctica.

7.1 PRD como marketing

Líneas como "UX deliciosa" y "rendimiento de clase mundial." Nada en esas líneas es verificable. Borrarlas. Si "rendimiento" importa, escribir "Lighthouse Performance ≥ 90 en móvil, cinco páginas de referencia."

7.2 PRD como lista de tareas

Cada línea empieza con un verbo. "Implementar X. Construir Y. Conectar Z." Eso es un tablero de tareas, no un PRD. Las líneas del PRD describen el sistema — qué es, qué debe hacer — no el trabajo para llegar ahí.

7.3 PRD que nunca se actualiza

El PRD tiene v1.0 en la cabecera y el hito es M3. O bien las decisiones están ocurriendo en sesiones de chat y no aterrizan aquí, o bien el proyecto está navegando sobre intención obsoleta. Ambos son señales de alerta.

7.4 Decisiones en chat, no en el PRD

El líder del equipo aprueba algo en un mensaje de Slack o en una respuesta de sesión. Dos semanas después nadie recuerda por qué. Si una decisión cambia el PRD, va al PRD antes de que termine la sesión. Ese es el coste de aprobar.

7.5 Dos PRDs

Alguien escribe un "PRD real" y un "PRD resumen" o un "PRD coreano" y un "PRD inglés" que derivan. Elegir uno. Las superficies multilingües son para usuarios; los PRDs son para el equipo y viven en un solo idioma y un solo archivo.

Descarga — plantilla PRD

Una plantilla PRD lista para copiar: alcance de trabajo, restricciones globales, el comando de verificación, una matriz de autoridad de decisión y criterios de finalización por elemento. La forma que describe este artículo, en un solo archivo.

shasum -a 256 PRD-code.md
# expected: 1c41c0e61b3dd027fa261e10a8b1f06381e40ee3ce476c24a8df673acb310e7c

8. Un principio

La forma entera de cómo uso los PRDs se reduce a una línea.

"Cualquier cosa que la mente del operador perdería entre sesiones, escríbela en el PRD. Cualquier cosa que no sobreviva un trimestre, mantenla fuera."

Ese es también el puente a los dos próximos artículos. Un PRD responde a cuál es el destino. La Parte 11 — Release gates responde a cómo sabemos que llegamos. La Parte 12 — Ralph loop responde a cómo dejamos que el sistema recorra la mayor parte del camino sin que el operador le sujete la mano.

Juntos, esos tres convierten la intención del operador — la mente de la Parte 1 — en algo que el sistema puede llevar a través de sesiones, días y colaboradores sin perderlo.