Desarrollo guiado por PRD: Cómo uso más de 30 PRD para entregar software con agentes de IA

El flujo de trabajo RalphBlaster de SaasMaker genera un pull request completo a partir de un ticket de una línea en menos de 45 minutos, sin que el desarrollador toque una sola línea de código durante la implementación.¹

He probado este patrón. Funciona. También falla de maneras que los videos de demostración no muestran.

TL;DR

He escrito más de 30 PRD para tareas con agentes de IA durante los últimos seis meses. El patrón funciona bien para tareas bien definidas con criterios de aceptación claros: endpoints CRUD, adición de pruebas, componentes de interfaz que siguen patrones establecidos. Falla con requisitos ambiguos, decisiones de arquitectura novedosas y cualquier cosa que requiera juicio humano iterativo. Mi plantilla de PRD evolucionó de un formato simple de historia de usuario a un documento estructurado con ubicaciones de archivos, expectativas de pruebas, restricciones y listas explícitas de “no tocar”. La evolución ocurrió porque los agentes interpretaron PRD vagos de maneras sorprendentes.

El flujo de trabajo que realmente uso

Paso 1: Crear un ticket

Defino lo que necesita suceder en lenguaje natural. La especificidad importa más de lo que inicialmente pensé:

Vago (produce resultados impredecibles):

Add user preference saving to the settings page.

Específico (produce resultados predecibles):

Add dark mode toggle to /settings. Persist to user_preferences
table (column: dark_mode, type: boolean, default: false).
Use existing SettingsForm component. Add toggle below the
notification section. No new dependencies.

La segunda versión restringe al agente lo suficiente como para que el resultado coincida con las expectativas. La primera versión me dio una página de configuración con un nuevo componente de React, tres nuevos paquetes de npm y una implementación con localStorage en lugar de la persistencia en base de datos que quería.

Paso 2: Generar o escribir el PRD

Mi skill /prd convierte un ticket en un PRD estructurado con historias de usuario, criterios de aceptación, ubicaciones de archivos y expectativas de pruebas.² Un PRD típico se ve así:

## Story: Add dark mode toggle
**As a** user
**I want to** toggle dark mode from settings
**So that** I can read comfortably in low light

### Acceptance Criteria
- [ ] Toggle appears in SettingsForm below notifications
- [ ] Persists to user_preferences.dark_mode (boolean)
- [ ] Default: false (light mode)
- [ ] Toggle state reflects current DB value on page load

### Files to Modify
- app/routes/settings.py (add dark_mode to form handler)
- app/templates/settings.html (add toggle component)
- app/models/user.py (add dark_mode column if missing)

### Files NOT to Modify
- app/static/css/styles.css (dark mode CSS already exists)
- app/templates/base.html (already reads dark_mode class)

### Test Expectations
- Test toggle persists to database
- Test default value on new user
- Test toggle reflects current state on reload

La sección “Files NOT to Modify” fue la mayor evolución de la plantilla. Sin ella, los agentes “mejoraban” amablemente archivos relacionados, introduciendo cambios que no había solicitado y no deseaba.

Paso 3: Implementación por el agente

El agente trabaja en un git worktree aislado, evitando interferencia con mi rama actual:³

# Create isolated worktree for agent task
git worktree add ../worktrees/dark-mode -b feature/dark-mode

# Agent works in ../worktrees/dark-mode/
# I continue working in main workspace

# Review and cleanup after merge
git worktree remove ../worktrees/dark-mode

Mi guardia de recursión monitorea el comportamiento de generación de subprocesos del agente. Mi guardián de seguridad git evita que el agente haga force-push o confirme credenciales. Estos hooks se ejecutan automáticamente. No superviso al agente durante la implementación.

Paso 4: Revisión

Llega una notificación cuando el agente termina. Reviso el diff contra los criterios de aceptación del PRD. Si todos los criterios pasan, hago merge. Si no, corrijo manualmente o reinicio el agente con contexto actualizado.⁴

Dónde funciona el desarrollo guiado por PRD

Endpoints CRUD con modelos de datos claros. El PRD especifica el modelo, las rutas y el formato de respuesta. El agente genera código repetitivo que coincide con los patrones existentes.

Adición de pruebas para código existente. “Write tests for app/content.py covering load_post_by_slug with valid slug, invalid slug, and missing file” produce pruebas útiles porque la función ya existe y los criterios de aceptación son objetivos.

Componentes de interfaz que siguen patrones establecidos. “Add a category filter to the blog listing page using the same tab pattern as the guide page” funciona porque el agente puede hacer referencia al patrón existente.

Migraciones de base de datos con esquemas definidos. El PRD especifica columnas, tipos, valores predeterminados y restricciones. El agente genera la migración y actualiza el modelo.

Dónde falla el desarrollo guiado por PRD

Requisitos ambiguos. “Make the blog better” no es un PRD. El agente realizará cambios, pero no coincidirán con su intención porque su intención no fue especificada.

Decisiones de arquitectura novedosas. Cuando necesité diseñar el modelo de consenso del sistema de deliberación, ningún PRD podía capturar la decisión. Necesitaba explorar opciones, evaluar compensaciones e iterar sobre el diseño. Eso requirió mi skill de deliberación, no un PRD.

Optimización de rendimiento. “Make the page load faster” requiere perfilado, medición e investigación iterativa. El agente no puede perfilar los patrones de tráfico de su producción a partir de un PRD.

Código crítico para la seguridad. Los PRD para sistemas de autenticación producen código que maneja el camino feliz. Los casos extremos en autenticación (ataques de temporización, fijación de sesión, CSRF en flujos no estándar) requieren experiencia humana que los PRD no pueden codificar.

Cómo evolucionó mi plantilla de PRD

Versión 1 (Mes 1): Historias de usuario simples

As a user, I want to save preferences so I can customize my experience.

Problema: Demasiado vago. El agente hizo suposiciones razonables pero incorrectas sobre el mecanismo de almacenamiento, la ubicación en la interfaz y el alcance.

Versión 2 (Mes 2): Se agregaron ubicaciones de archivos

## Story: Save preferences
### Files to Modify
- app/routes/settings.py
- app/templates/settings.html

Problema: Mejor, pero los agentes aún “mejoraban” archivos adyacentes sin permiso.

Versión 3 (Mes 4): Se agregaron restricciones

## Story: Save preferences
### Files to Modify (only these)
- app/routes/settings.py
- app/templates/settings.html
### Constraints
- No new dependencies
- Use existing database models
- Do not modify CSS

Problema: Los agentes a veces ignoraban las restricciones cuando entraban en conflicto con las “mejores prácticas” de sus datos de entrenamiento.

Versión 4 (Actual): Exclusiones explícitas + expectativas de pruebas

La plantilla actual agrega “Files NOT to Modify”, expectativas de pruebas explícitas y casillas de verificación de criterios de aceptación. Esta versión produce resultados predecibles aproximadamente el 85% de las veces. El 15% restante requiere una segunda pasada con instrucciones clarificadas.⁵

La biblioteca de patrones de 30 PRD

Después de más de 30 PRD, surgieron patrones:

La tasa de éxito para funciones novedosas (50%) explica por qué el desarrollo guiado por PRD complementa mi flujo de trabajo en lugar de reemplazarlo. La mitad de las veces, el trabajo novedoso requiere iteración que los PRD no pueden capturar de antemano.

Conclusiones clave

Para desarrolladores independientes: - Comience con un tipo de PRD bien definido (CRUD, pruebas) y valide el flujo de trabajo antes de expandirse a tareas complejas - Agregue “Files NOT to Modify” a cada PRD; los agentes “mejorarán” amablemente código que usted no les pidió que tocaran - Use git worktrees para aislar el trabajo del agente; el costo de limpieza de una ejecución fallida del agente debería ser un solo comando, no una sesión de arqueología git

Para gerentes de ingeniería: - La calidad del PRD determina la calidad del resultado del agente; invierta en plantillas de PRD y procesos de revisión antes de escalar el uso autónomo de agentes - Rastree la proporción de merge sin cambios para medir la madurez del flujo de trabajo; la proporción debería mejorar a medida que las plantillas de PRD evolucionan - El trabajo de arquitectura novedosa y el código crítico para la seguridad no deberían delegarse mediante PRD; reserve la delegación a agentes para tareas bien definidas y repetibles

Referencias