Spec-Driven Development: Buenas Prácticas, Técnicas y Cuándo Usar Cada Una
Los agentes de IA son buenos generando código y malos adivinando qué quisiste decir. Dale a un agente un prompt vago y va a llenar cada vacío con una suposición: la base de datos equivocada, un flujo de OAuth que nadie pidió, manejo de errores que no coincide con cómo falla el resto del sistema. Spec-driven development (SDD) es la disciplina que surgió de este problema: en vez de escribir un prompt y esperar lo mejor, escribís primero una especificación precisa, y la tratás como la fuente de verdad a la que tanto humanos como agentes quedan atados.
No es una idea nueva — toma prestado de BDD, de las pruebas de contrato de APIs, y de los documentos de diseño de toda la vida. Lo nuevo es que en un flujo de trabajo con agentes, la spec deja de ser un artefacto que escribís y después ignorás. Se convierte en lo que el agente realmente construye, y en lo que los tests verifican para detectar desvíos.
Por qué importa ahora
Los tests unitarios detectan funciones rotas. No detectan que un agente reintroduzca en silencio una vulnerabilidad que "arregló" la semana pasada, que viole un límite arquitectónico entre servicios, o que reinvente una decisión que ya tomaste y que no quedó documentada en ningún lugar visible para el agente. Estudios sobre código generado por LLMs encontraron tasas de vulnerabilidades que van de aproximadamente 10% a más del 40% según el benchmark, y el problema se acumula: sin una spec que codifique una restricción, el mismo vacío reaparece cada vez que se regenera el código. Parchás el código y el siguiente ciclo de regeneración reintroduce el mismo bug, porque nada capturó por qué importaba el arreglo.
La distinción central que hace que SDD sea distinto de un documento de diseño: un documento de diseño lo leen humanos, que llenan los vacíos con juicio y contexto. Una spec escrita para SDD la lee un agente y, idealmente, se ejecuta — como tests de aceptación, chequeos de contrato, o un gate de CI que falla el build ante cualquier divergencia.
Las tres técnicas, y cuándo usar cada una
La mayoría de las guías de SDD de 2026 convergen en la misma escalera de tres niveles. No son metodologías que compiten entre sí — son niveles crecientes de cuánta autoridad tiene la spec sobre el código, y elegís el nivel según cuánto está en juego.
1. Spec-first. La spec siembra la generación inicial — la escribís, el agente construye a partir de ella — pero nada obliga a que el código siga coincidiendo con ella después. El código puede desviarse de la spec a medida que se edita, y nadie se entera cuando pasa.
Usalo para funcionalidades asistidas por IA, prototipos, y trabajo en etapa temprana donde los requisitos todavía probablemente cambien. Es el nivel de ceremonia correcto cuando el costo de que el código se desvíe silenciosamente de la spec es bajo, o el código de todos modos tiene vida corta.
2. Spec-anchored. La spec y el código evolucionan juntos, y tests automatizados obligan a que se mantengan alineados — los criterios de aceptación de la spec se traducen en tests que fallan el build si la implementación los viola. Este es el nivel que la mayoría de las fuentes de 2026 — incluido el paper de arXiv que se convirtió en referencia del campo — llaman "el punto óptimo para la mayoría de los sistemas en producción".
Usalo cuando varias personas (o varios agentes) tocan el mismo código a lo largo del tiempo, cuando el sistema tiene mucha integración o límites arquitectónicos reales que proteger, o cuando necesitás un rastro de auditoría de qué se decidió y qué se verificó. Acá es donde la disciplina justifica su costo.
3. Spec-as-source. Los humanos editan solo la spec. El código se genera por completo y nunca se edita a mano — la spec es la fuente de verdad en sentido literal, y regenerar a partir de ella es cómo hacés cambios. Esto elimina el desvío por diseño, porque no queda código editado a mano que pueda desviarse.
Sigue siendo mayormente aspiracional fuera de dominios acotados y bien definidos (servicios API-first con generación de código madura, por ejemplo). Exige herramientas de generación lo suficientemente maduras como para confiar en ellas sin que un humano revise cada línea, y la mayoría de los equipos todavía no las tiene. No elijas este nivel porque suene como la opción "más rigurosa" — elegí spec-anchored a menos que tengas una razón concreta por la que spec-as-source es viable en tu dominio.
La regla práctica: por defecto, spec-anchored. Spec-first está bien para ese 20% exploratorio del trabajo; spec-as-source es donde vive el hype, no donde la mayoría de los equipos obtiene valor hoy.
Escribir specs que un agente no pueda malinterpretar
El error más grande en SDD no es una spec mala — es una ambigua. EARS (Easy Approach to Requirements Syntax) es lo más parecido a un estándar para criterios de aceptación que se lean igual para un humano y para un modelo. Cinco patrones cubren casi todos los casos:
- Ubicuo — "El sistema deberá registrar cada intento de autenticación."
- Basado en eventos — "CUANDO un usuario envía el formulario de login, EL sistema DEBERÁ validar las credenciales."
- Basado en estado — "MIENTRAS una sincronización esté en curso, EL sistema DEBERÁ mostrar un indicador de progreso."
- Comportamiento no deseado — "SI la validación falla tres veces, ENTONCES el sistema DEBERÁ bloquear la cuenta durante 15 minutos."
- Opcional — "DONDE el MFA esté habilitado, EL sistema DEBERÁ requerir un código TOTP."
Los criterios escritos así se traducen casi uno a uno en casos de test, que es lo que hace que una spec sea ejecutable en vez de solo orientativa.
Una buena spec responde seis preguntas
Si una spec deja alguna de estas abierta, un agente la va a responder por vos — normalmente no como vos hubieras elegido:
- ¿Cómo se ve "terminado"? No un nombre de funcionalidad — un resultado. "Un usuario puede registrarse con email y contraseña, recibe un email de verificación, y sigue logueado después de refrescar la página" es mejor que "construir autenticación".
- ¿Qué queda explícitamente fuera de alcance? Los agentes expanden el alcance por defecto. Si OAuth no forma parte de esta tarea, decilo — un agente que vio mil sistemas de autenticación asume que corresponde.
- ¿Qué restricciones y supuestos ya existen? Decisiones de stack, límites de rate de terceros, requisitos de performance — cualquier cosa que no sea obvia solo con leer el código.
- ¿Qué ya se decidió? Si elegiste el esquema o la librería de encriptación, escribilo. Un agente que no sabe que una decisión ya se tomó va a tomar la suya propia.
- ¿Cómo se divide el trabajo en tareas? Pedir demasiado en un solo paso es una de las formas más comunes en que los agentes fallan. Dividir en subtareas atómicas y verificables por separado también permite que varios agentes trabajen en paralelo cuando no tocan los mismos archivos.
- ¿Cómo se verifica? No "¿funciona?", sino qué tests pasan y qué casos límite están cubiertos. Esto es lo que una pasada de verificación — humana o de agente — chequea.
El flujo de trabajo canónico
La mayoría de las herramientas de SDD en 2026 (GitHub Spec Kit, AWS Kiro, los flujos de SDD de Claude Code, el Plan Mode de Cursor) implementan más o menos el mismo pipeline, con una instancia de revisión humana entre cada fase:
La regla de oro en todas las herramientas que implementan esto: nunca saltar directo de la spec al código. Revisar el plan antes de dividir en tareas; revisar las tareas antes de implementar. Saltarse una fase es donde empieza el desvío.
Un ejemplo trabajado
Una spec recortada para una funcionalidad de login sin contraseña, escrita en EARS:
## Funcionalidad: Login sin contraseña por enlace mágico
### Criterios de aceptación
- CUANDO un usuario envía un email válido
EL sistema DEBERÁ enviar un enlace de login de un solo uso válido por 15 minutos.
- SI un enlace de login se usa más de una vez
ENTONCES el sistema DEBERÁ rechazarlo con HTTP 410 Gone.
- DONDE el email no está asociado a una cuenta
EL sistema DEBERÁ igual devolver HTTP 202 (sin enumeración de cuentas).
- EL sistema DEBERÁ almacenar los tokens del enlace hasheados, nunca en texto plano.
### Fuera de alcance
- Login social, SSO, contraseña como alternativa.El plan que sigue nombra el stack, el modelo de datos y las decisiones ya tomadas (formato del token, esquema de hasheo). La lista de tareas se descompone en una migración, dos endpoints, tests de contrato para los caminos 202 y 410, y rate limiting — cada tarea citando la cláusula de la spec que satisface. Cuando un test falla más adelante, sabés exactamente qué pieza de intención se rompió, no solo qué línea de código.
Buenas prácticas
- Fijá una constitución antes de la primera spec. Un
AGENTS.mdo.specify/memory/constitution.mdcon reglas del proyecto — codificalas como declaraciones EARS ubicuas, como "el sistema deberá usar TypeScript strict mode". - Una funcionalidad, una spec. Mantené las specs entre una y tres páginas; dividí cualquier cosa más grande en vez de dejar que una sola spec se extienda sin límite.
- Escribí en lenguaje de dominio, no en detalle de implementación. Una spec que se lee como pseudocódigo perdió el sentido — escribiste el programa dos veces, una en prosa y otra en código, y ahora tenés dos cosas que mantener sincronizadas.
- Cerrá la puerta al alcance explícitamente. Una sección "fuera de alcance" hace tanto trabajo como la de "en alcance".
- Citá las specs en los commits.
feat(auth): magic link, refs specs/004-magic-link/spec.md— es lo que hace que el rastro de auditoría sea útil después. - Tratá las specs como duraderas, y el código como generado. Las specs sobreviven a cualquier implementación particular; ese es el sentido de escribirlas.
- Considerá un patrón adversarial para lo que realmente importa. Un agente verificador separado, que chequea la salida de un agente implementador contra la spec, detecta más que dejar que el agente implementador se autoevalúe — los implementadores son estructuralmente optimistas sobre lo que construyeron.
Cuándo no usarla
No toda tarea necesita una spec, y pretender lo contrario es en sí mismo un error. Saltéatela para prototipos descartables, proyectos individuales de vida corta, y trabajo exploratorio donde de verdad todavía no conocés los requisitos — escribir una spec rigurosa para algo que todavía estás descubriendo solo significa reescribir la spec tan seguido como el código. La prueba práctica: si te molestaría que un agente interpretara tu pedido de forma distinta a lo que quisiste decir, escribí la spec. Si un prompt de seguimiento rápido lo arreglaría, saltéate la ceremonia.
SDD también tiene críticos serios que vale la pena tomar en cuenta — Thoughtworks lo ubica en el anillo "Assess" de su Technology Radar, no en "Adopt", y algunos argumentan que en gran parte es diseño por contrato y pensamiento waterfall con otro nombre para la era de la IA. Ambas cosas pueden ser ciertas: la disciplina de fondo no es nueva, y igual vale la pena adoptarla, porque el valor nunca estuvo en la novedad — está en que escribir la spec es donde ocurre el pensamiento, y eso importa más, no menos, ahora que quien escribe la implementación es un agente.
Fuentes: