Apariencia
Por Qué los Agentes AI Necesitan Specs (Y Qué Pasa Sin Ellas)
Hay un patrón que aparece una y otra vez en las comunidades de desarrolladores. Alguien descubre que Claude puede escribir una feature entera en minutos, o que Cursor puede refactorizar todo un servicio mientras va a por un café. La AI es genuinamente impresionante. Luego, unas semanas después, el codebase empieza a sentirse inconsistente. Las decisiones tomadas en una sesión contradicen las de otra. El código que supuestamente estaba "listo" sigue necesitando arreglos. El desarrollador no puede explicar exactamente por qué las cosas son más difíciles ahora que antes de empezar a usar AI.
La causa raíz es casi siempre la misma: el agente AI no tenía spec.
El Problema: Los Agentes AI No Recuerdan Tus Decisiones
Cada nueva conversación con un agente AI de programación empieza desde cero. El agente tiene acceso a tu codebase — a veces todo, a veces solo los archivos que mencionas — pero no recuerda el razonamiento detrás de tu arquitectura, los trade-offs que evaluaste el mes pasado, ni la decisión que tomaste hace tres sesiones de usar un patrón concreto para el manejo de errores.
Esto genera modos de fallo predecibles:
Implementaciones contradictorias. Le pides al agente que añada una feature. Produce código que funciona técnicamente pero introduce un patrón que choca con algo que construiste hace dos semanas. Ambos son "válidos" por separado. Juntos, son inconsistentes.
Scope creep sin visibilidad. El agente interpreta "añade una página de configuración" de forma amplia. Crea nuevas tablas de base de datos, nuevas rutas de API, un nuevo enfoque para la librería de componentes. Cada decisión individual puede parecer razonable. El conjunto supera con creces lo que pediste.
Sin definición de "hecho". ¿Cuándo termina la feature? El agente seguirá — añadiendo manejo de errores, casos límite, fallbacks, tests — hasta que lo pares. Sin criterios de aceptación, "hecho" es arbitrario.
Conflictos entre sesiones paralelas. A medida que los flujos multi-agente se vuelven comunes, dos agentes trabajando en features relacionadas pueden producir código que colisiona. Sin una spec compartida, no hay coordinación.
Por Qué las Specs Lo Resuelven
Una spec es un contrato. Define:
- Qué hace la feature — en lenguaje claro que tanto tú como el agente pueden entender
- Criterios de aceptación — condiciones concretas y verificables que deben ser verdaderas para que la feature esté completa
- Límites de alcance — qué archivos se tocan, cuáles están fuera de límites, qué nuevos tipos o esquemas se introducen
- Riesgos y restricciones — casos límite conocidos, preocupaciones de rendimiento, complejidad del rollback
Cuando un agente AI tiene una spec, tiene contexto que sobrevive al límite de sesión. Más importante aún, tiene una definición de "hecho" que acordaste por adelantado.
El trabajo del agente cambia de "descubrir qué construir" a "satisfacer estos criterios". Eso es un uso mucho mejor de sus capacidades.
Cómo Se Ve una Buena Spec en la Práctica
Aquí hay una spec mínima para una feature como "enviar notificación por email al registrarse":
## Historia de Usuario
Como nuevo usuario, cuando completo el registro, recibo un email de bienvenida
para saber que mi cuenta se creó correctamente.
## Criterios de Aceptación
- [ ] El email de bienvenida se envía en los 5 segundos siguientes al registro
- [ ] El email contiene el nombre del usuario y un enlace de verificación
- [ ] Si el servicio de email no está disponible, el registro igual tiene éxito (fire-and-forget)
- [ ] No se envían emails duplicados al reintentar
- [ ] El envío del email se registra con estado de éxito/fallo
## Alcance
Archivos modificados: src/auth/signup.ts, src/services/email.ts (nuevo)
Nuevos tipos: EmailPayload (en src/types/notifications.ts)
Externo: requiere variable de entorno EMAIL_SERVICE_URL
## Fuera de alcance
- Plantillas de email más allá del email de bienvenida
- Gestión de desuscripción (spec separada)Esto lleva cinco minutos escribirlo. Ahorra horas de ida y vuelta y previene al menos dos o tres implementaciones incorrectas.
Ejemplos Reales de Flujo de Trabajo
Sin spec
Desarrollador: "Añade rate limiting a la API"
Agente: [escribe rate limiting en middleware]
Desarrollador: "No es exactamente eso — debería ser por usuario, no por IP"
Agente: [lo reescribe]
Desarrollador: "También necesita funcionar con nuestro sistema de auth tokens existente"
Agente: [lo reescribe otra vez, introduce nueva dependencia]
Desarrollador: "Ahora entra en conflicto con la capa de caché"
[Tres iteraciones más]Cada iteración cuesta tokens, tiempo e introduce nuevos puntos de inconsistencia.
Con spec
Desarrollador: "Crea una spec para rate limiting por usuario"
Agente: [genera spec con criterios de aceptación]
Desarrollador: [revisa, añade un criterio sobre compatibilidad con caché, aprueba]
Agente: [implementa exactamente según la spec, marca criterios conforme avanza]
Desarrollador: [revisa el output — todos los criterios satisfechos, sin sorpresas]La spec hizo los requisitos explícitos antes de la implementación. El agente no tenía nada que malinterpretar.
El Gate de Aprobación Importa
Una parte del SDD ante la que los desarrolladores inicialmente se resisten es el paso de aprobación explícita. El flujo es:
- Escribe la spec
- Obtén aprobación antes de escribir cualquier código
- Implementa contra la spec aprobada
Esto parece lento. No lo es.
El gate de aprobación es donde se detectan los problemas de alcance, los conflictos arquitectónicos y los requisitos que faltan. Detectarlos en la fase de spec lleva minutos. Detectarlos después de la implementación lleva horas. Detectarlos en producción lleva días.
Más en la práctica: el gate de aprobación significa que realmente has leído y acordado lo que el agente está a punto de hacer. Eso no es burocracia — es disciplina básica de ingeniería.
Primeros Pasos con Planu
Planu es un servidor MCP que integra el flujo de trabajo SDD directamente en tus sesiones AI. En lugar de gestionar documentos de spec manualmente, tu agente lo maneja a través de herramientas estructuradas:
create_spec— genera una Historia de Usuario estructurada y una Ficha Técnica a partir de una descripción en lenguaje naturallist_specs— muestra todas las specs y su estado de implementaciónvalidate— comprueba que la implementación satisface los criterios de aceptacióndetect_drift— identifica cuándo el código se ha desviado de la spec
El flujo de trabajo se integra con Claude, Cursor, Windsurf, Gemini CLI y cualquier agente compatible con MCP. La configuración lleva unos cinco minutos.
Por dónde empezar
No necesitas adoptar SDD para todo de golpe. Empieza solo con las features nuevas. Una vez que notes la diferencia — menos sorpresas, revisiones más limpias, mejores handoffs — lo aplicarás de forma natural en más sitios.
Las specs no te hacen más lento. La ambigüedad sí.