Category: Spec Driven Development

La spec tenía 900 palabras, títulos bien puestos, listas numeradas y hasta un diagrama. El agente la leyó entera y construyó otra cosa.

El dev que me la pasó estaba convencido de que el problema era el modelo. Probó con otro. Mismo resultado.

Le hice una sola pregunta: cuando el agente termine, ¿qué comando ejecutas para saber si lo ha hecho bien?

Silencio. No había ninguno.

Ese silencio es el diagnóstico completo. La mayoría de las specs que fallan —también las de quien ya aplica Spec-Driven Development a diario— no fallan por estar mal escritas. Fallan por no ser verificables. Y una spec que no se puede comprobar no es una especificación: es una carta de intenciones. Un agente no ejecuta intenciones.

El SDD no consiste en redactar un documento bonito antes de programar — de eso hablé cuando expliqué por qué el Spec-Driven Development evita el caos. Consiste en escribir un contrato que una máquina pueda dar por cumplido o por incumplido, sin que tú tengas que opinar.

Esto no es otro tutorial de redacción. Para la estructura desde cero ya tienes la anatomía de una spec para Claude Code. Esto es el diagnóstico de la spec que ya escribiste y no funcionó.

Siete fallos, ordenados por lo que más veo. Los cinco primeros los detectas leyendo el documento. Los dos últimos, no.

Busca tu síntoma: por qué tu spec falla con un agente de IA

Lo que ves cuando el agente termina	El fallo en la spec	El arreglo
Dice "está hecho" y no sabes si está hecho	Criterios de éxito no comprobables	Un comando debajo de cada criterio
Hace las cosas como las hace todo el mundo, no como tu repo	Ambigüedad sin marcar	Señala el fichero que manda
Toca ficheros que nadie le pidió	No hay límites	Sección "Fuera de alcance"
Ignora la mitad de tus instrucciones técnicas	Mezcla el qué con el cómo	Cierra el qué, deja el cómo abierto
catch vacíos y fallos que devuelven 200	Solo describe el camino feliz	Tabla de estados de error
Empieza bien y se desmadra a la mitad	La spec es demasiado grande	Pártela por unidad verificable
Cumple la spec, pero la spec ya no es verdad	Spec desactualizada	Vive en el repo o se borra

Fallo 1: criterios de éxito que nadie puede comprobar

Un criterio de éxito es comprobable cuando existe un comando que lo declara cumplido o incumplido sin que nadie opine. Este es el fallo padre: los otros seis son variaciones suyas.

Mira esta spec. La he leído con distintos nombres decenas de veces:

## Feature: listado de productos

Endpoint para listar el catálogo.
Tiene que ser rápido y soportar filtros.
La respuesta debe ser consistente con el resto de la API.
Gestionar bien los errores.

Cuatro frases. Tres deseos y un título. ¿Rápido comparado con qué? ¿Consistente con cuál de los catorce endpoints que ya tienes? ¿Gestionar bien es devolver un 400 o un 422?

Ninguna de esas preguntas la puede responder el agente ejecutando algo. Así que las responde inventando, y tú te enteras después.

Ahora la misma feature escrita para que se pueda comprobar:

## Feature: GET /products

### Criterios de aceptación
1. `GET /products?limit=20` devuelve 200 con
   `{ items: Product[], nextCursor: string | null }`.
2. Paginación por cursor sobre `created_at DESC, id DESC`.
   `GET /products?cursor=<nextCursor>` devuelve la página siguiente
   sin repetir ni saltarse elementos. Nada de offset/limit.
3. `limit` acepta 1-100, por defecto 20.
   Fuera de rango devuelve 400 con `{ code: 'INVALID_LIMIT' }`.
4. p95 por debajo de 200 ms con 10.000 productos en tabla.

### Cómo se verifica
- `bun test test/products.e2e.ts` en verde (cubre los puntos 1 a 3).
- `bun run bench:products` imprime el p95 y sale con código 1
  si supera los 200 ms.

La diferencia no es la longitud. Es que la segunda tiene una sección Cómo se verifica.

"Que sea rápido" es un deseo. "Que GET /products responda por debajo de 200 ms de p95 con 10.000 registros, y aquí está el comando que lo mide" es un criterio. El primero obliga a que alguien juzgue. El segundo se cierra solo.

Regla corta: debajo de cada criterio, el comando que lo prueba. Si no puedes escribir el comando, no tienes un criterio, tienes una preferencia.

Y cuando el criterio es ejecutable pasa lo interesante: puedes delegar el ciclo entero —escribe, ejecuta, lee el fallo, corrige— en lugar de revisar cada iteración a mano. Es el flujo diario que describí en cómo usar Claude Code a diario, y depende por completo de que exista ese comando.

Fallo 2: la ambigüedad la rellena el modelo, no tú

Todo hueco de la spec se rellena. Siempre. La pregunta no es si el agente va a improvisar, es con qué.

Y improvisa con lo más común de su entrenamiento: la mediana de internet. Tu repo no es la mediana de internet.

Si tu API pagina por cursor y la spec solo dice "con paginación", el agente escribe offset y limit, porque es el patrón que domina en el código público con el que se entrenó. Si tu proyecto devuelve Result en vez de lanzar, escribirá try/catch. Si tus tests usan Testing Library, te meterá un TestBed clásico.

Ninguno de esos es un error del modelo. Son la respuesta estadísticamente correcta a una pregunta que no hiciste.

Aquí está el matiz que casi nadie aplica: la spec no tiene que decirlo todo. Tiene que decir dónde no se puede improvisar.

Y la forma más barata de decirlo no es describir tu patrón en tres párrafos. Es apuntar al código que ya lo hace:

### Referencias obligatorias
- Paginación: copia el patrón de `src/orders/orders.controller.ts` (solo lectura).
  Si hay conflicto entre este documento y ese fichero, manda el fichero.
- Errores: usa los helpers de `src/common/http-errors.ts`.
  Prohibido lanzar `Error` pelado.

### Libre elección
- Nombres internos, orden de los métodos, dónde partes los helpers.
  No preguntes por esto.

Ese último bloque parece de relleno y no lo es. Marcar lo que sí es libre evita el otro extremo: el agente que se para cada dos minutos a preguntar cómo llamar a una variable.

Tu trabajo no es documentar el proyecto entero dentro de la spec. Es marcar las tres o cuatro fronteras donde una decisión razonable sería, en tu repo, la decisión equivocada.

Fallo 3: no dice qué NO hacer

Los desastres que he visto con agentes casi nunca vienen de lo que el agente no hizo. Vienen de lo que hizo de más.

Le pides un endpoint y te reformatea 40 ficheros porque detectó que el estilo era inconsistente. Le pides un filtro y te instala una librería de query building. Le pides un fix y "de paso" refactoriza el módulo de auth, que estaba feo.

Todo eso es técnicamente razonable. Ninguna spec lo prohibía.

Los límites son parte del contrato, no una nota al margen:

### Fuera de alcance
- No tocar `src/auth/**` ni `src/orders/**`.
- No añadir dependencias. La paginación sale del query builder
  que ya está en `src/common/pagination.ts`.
- No crear migraciones. Si hace falta un índice, lo propones
  en el PR y paras.
- No cambiar la forma de respuesta de endpoints existentes.
- No reformatear ficheros que no toque la feature.

Cinco líneas. Te ahorran la revisión de un diff de 40 ficheros donde lo que importa está en tres. Es, por cierto, uno de los patrones que aparece una y otra vez en los errores comunes al adoptar Claude Code: falta de guardarraíles, no falta de capacidad.

No es opinión mía: las buenas prácticas oficiales de Claude Code lo dicen con todas las letras — las specs más útiles "nombran los ficheros e interfaces implicados, declaran qué queda fuera de alcance, y terminan con un paso de verificación end-to-end que demuestra que la feature funciona". Los tres primeros fallos de esta lista son exactamente esas tres cosas, en negativo.

Fallo 4: la spec que ya decide la implementación

Este falla al revés que los anteriores. No peca de vaga, peca de mandona.

Crea un `ProductsCacheInterceptor` en `src/products/interceptors/`.
Usa un `Map<string, { data: Product[]; ts: number }>` en memoria.
TTL de 60 s, limpieza con un `setInterval` cada 30 s.
La clave del Map es `JSON.stringify(req.query)`.

Eso no es una spec. Es pseudocódigo con saltos de línea.

Y tiene un agujero que probablemente no has visto: JSON.stringify(req.query) genera claves distintas para ?limit=20&cursor=x y ?cursor=x&limit=20. Son la misma petición. El agente puede implementar ese documento al pie de la letra, perfectamente, y aun así pegarle dos veces a la base de datos.

La versión que sí es un contrato:

### Criterio
Dos peticiones con los mismos parámetros a `GET /products` en menos de 60 s
golpean la base de datos una sola vez, independientemente
del orden de los parámetros en la query string.

### Cómo se verifica
`bun test test/products.cache.e2e.ts` — el test espía el
repositorio y afirma que solo hubo una query.

### Restricciones
Sin dependencias nuevas. Sin Redis: todavía no está en infra.

Fíjate en la paradoja. La versión que no dice cómo implementarlo es más exigente que la que lo dictaba línea a línea. La primera se puede cumplir y estar mal. La segunda no se puede fingir.

Además, cuando cierras el cómo, cierras también las soluciones mejores que la tuya. Y en cachés, colas y consultas, el agente propone alternativas buenas más a menudo de lo que resulta cómodo admitir.

Tú decides el qué observable. Él decide el cómo. El test decide quién tiene razón.

Fallo 5: la spec solo describe el camino feliz

Abre tu última spec y cuenta cuántas líneas hablan de qué pasa cuando algo falla. Lo normal es cero.

Aquí está la trampa: el agente no deja el manejo de errores sin hacer. Lo inventa. Y su versión inventada suele ser un catch que loguea y sigue, o un 200 con array vacío cuando la base de datos no responde. Un endpoint que miente en lugar de fallar.

Cuatro filas arreglan esto:

Caso	Respuesta	Qué se loguea
cursor malformado	400 INVALID_CURSOR	warn, sin volcar el cursor entero
limit fuera de 1-100	400 INVALID_LIMIT	nada
Timeout de la base de datos (>2 s)	503 DB_TIMEOUT	error, con query y duración
Fila de producto sin precio	se excluye del listado	warn con el id

La última fila separa una spec escrita por alguien que ha estado de guardia de una escrita de memoria. Los datos sucios existen, y si no decides tú qué hacer con ellos, decide el agente.

Dos minutos de escritura. Es lo que hay entre un endpoint y un endpoint que puedes dejar sin mirar.

Los dos fallos que no ves leyendo la spec

Los cinco anteriores se detectan releyendo el documento. Estos dos solo aparecen cuando comparas la spec con el repo y con el tamaño del trabajo.

Fallo 6: la spec es demasiado grande

La unidad de una spec no es la feature, es el paso verificable. Si la sección "Cómo se verifica" no cabe en cinco líneas, no tienes una spec: tienes tres disfrazadas de una.

El síntoma es inconfundible: el agente empieza bien y se desmadra a la mitad, porque cada decisión que toma amplía la superficie de las siguientes.

Partir el trabajo en unidades que se cierran una a una es, literalmente, la mitad del método que enseño en Construye con IA. La otra mitad es no volver a abrir una unidad ya cerrada.

Fallo 7: la spec está desactualizada

La spec dice que el endpoint devuelve items, el código lleva tres semanas devolviendo data. El agente no tiene forma de saber cuál manda. Unas veces sigue al documento y otras al código, y ninguna de las dos es una elección tuya.

La regla que uso: la spec vive en el repo, entra en el mismo PR que el código, y cuando se contradicen gana el código. Entonces actualizas la spec o la borras. Una spec muerta es peor que no tener spec, porque es contexto con autoridad que resulta ser mentira.

El test de 30 segundos: ¿tu spec es verificable?

Una spec es verificable si responde a tres preguntas por escrito. No hace falta reescribir nada para saberlo. Coge la que ibas a pasarle al agente y hazle estas tres:

1. ¿Qué comando prueba que está terminada?
2. ¿Qué ficheros no puede tocar?
3. ¿Qué pasa exactamente cuando falla?

Si las tres tienen respuesta escrita en el documento, la spec funciona. Si falta una, ya sabes dónde está el bug — y no está en el modelo.

Empieza hoy por la primera. Coge tus criterios de aceptación y escribe debajo de cada uno el comando que lo demuestra. Los que se queden sin comando, o los conviertes en algo medible o los sacas de la spec, porque no van a pasar de deseo.

Todo el sistema —el contrato verificable, los límites, cómo partir el trabajo y cómo mantener la spec viva junto al código— es lo que ordené en SDD: Spec-Driven Development. Si este post te ha señalado tres fallos en tu documento, ahí tienes el método completo para que no vuelvan.

Y si prefieres verlo sobre proyectos reales, con specs de gente que las está usando en producción, es una de las conversaciones habituales en Dominicode Labs.

Preguntas frecuentes

¿Cómo sé si mi spec es verificable?

Una spec es verificable si cada criterio de aceptación tiene debajo un comando que devuelve verde o rojo sin que nadie opine. Un test, un benchmark, un script de validación, un curl con la respuesta esperada.

La prueba rápida: pásale la spec a alguien que no conozca el proyecto y pídele que te diga si está hecha sin abrir el código. Si necesita preguntarte algo, el agente también lo habría necesitado, solo que él no pregunta.

¿Qué hago con los criterios que no se pueden medir con un comando?

Los conviertes en algo observable o los sacas de la spec. "Que la UI sea intuitiva" no es un criterio, pero "que el flujo de compra se complete en tres clics desde la ficha de producto y no haya ningún campo obligatorio sin marcar" sí lo es, y se comprueba con un test end-to-end.

Cuando de verdad no se puede —criterios estéticos, tono de los textos, decisiones de marca— déjalo fuera de la spec y márcalo como revisión humana explícita. Lo que no puede pasar es que quede dentro como si el agente pudiera resolverlo.

¿Cuánto debe ocupar una spec para un agente de IA?

No la mides en palabras, la mides en unidades verificables. Una spec debe cubrir un trozo de trabajo que se cierre con una tanda de comprobaciones y una revisión.

Si la sección "Cómo se verifica" ocupa más de cinco líneas o mezcla áreas del sistema que no comparten test, pártela. Dos specs de 300 palabras funcionan mejor que una de 900.

¿La spec sustituye a los tests?

No, los ordena. La spec dice qué tiene que ser cierto y el test lo comprueba en cada ejecución.

En la práctica la relación es más estrecha de lo que parece: si los criterios de aceptación están bien escritos, los nombres de tus tests salen casi copiados de ellos. Cuando un criterio no se deja convertir en un nombre de test, casi siempre es que el criterio estaba vago.

¿Por qué el agente ignora partes de mi spec?

Rara vez las ignora. Lo habitual es que las haya interpretado de una forma que a ti no se te ocurrió, porque estaban abiertas a más de una lectura.

Revisa esas partes buscando dos cosas: adjetivos sin unidad ("rápido", "robusto", "limpio") y sustantivos que en tu proyecto tienen un significado propio ("paginación", "validación", "caché"). Son los dos sitios donde el modelo rellena con lo más común de su entrenamiento en lugar de con lo que hace tu repo.

¿Qué hago si el agente toca ficheros que nadie le pidió?

Añade una sección "Fuera de alcance" a la spec y trátala como parte del contrato, no como una nota al margen. Cinco líneas bastan: qué directorios no se tocan, que no se añaden dependencias, que no se crean migraciones, que no se cambia la forma de respuesta de endpoints existentes y que no se reformatea nada que la feature no toque. Los desastres con agentes casi nunca vienen de lo que no hicieron, sino de lo que hicieron de más, y ninguna spec se lo prohibía.

¿La spec tiene que decir cómo implementar la feature?

No, y decirlo suele empeorar el resultado. Una spec que dicta la implementación línea a línea se puede cumplir al pie de la letra y aun así estar mal, porque el agente reproduce también tus errores de diseño. Una spec que fija el comportamiento observable y el comando que lo verifica no se puede fingir. Tú decides el qué, el agente decide el cómo, y el test decide quién tenía razón.

¿Dónde guardo la spec y quién manda si contradice al código?

En el repositorio, junto al código, y entra en el mismo pull request que la implementación. Fuera del repo se queda desactualizada en semanas y se convierte en contexto falso.

Cuando spec y código se contradicen, manda el código y la spec se corrige o se borra en ese mismo momento. Déjalo escrito dentro del propio documento: es la línea que evita que el agente tenga que adivinar cuál de las dos fuentes es la buena.

---

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

Escribí una spec de tres páginas —objetivo, contratos de datos, casos de error, criterios de aceptación— para una integración que no llegó a existir.

A la mañana siguiente abrí la documentación de la API y descubrí que el endpoint sobre el que se apoyaba la mitad de mis decisiones no devolvía lo que yo daba por hecho. Tiré el documento entero.

La spec no estaba mal escrita. Estaba escrita antes de tiempo.

Escribí el libro de Spec-Driven Development. Lo uso casi todos los días y sigo pensando que es la diferencia entre dirigir a un agente y rezarle. Por eso mismo puedo decirte esto sin que suene a excusa: hay trabajo donde SDD no compensa, y confundir "el método funciona" con "el método aplica siempre" te cuesta más horas de las que te ahorra.

Una spec es un seguro, y a veces la prima cuesta más que el siniestro

Escribir una spec tiene dos costes.

El obvio es el tiempo. Ese lo ves y lo aceptas, porque sabes que la vas a recuperar en el primer malentendido que no ocurre.

El segundo no lo ve casi nadie: una spec fija decisiones. Ese es su trabajo. Y fijar decisiones es fantástico cuando tienes la información para tomarlas, y carísimo cuando no la tienes, porque conviertes una suposición en un contrato y luego construyes encima.

Todo el debate se reduce a comparar dos cantidades: lo que cuesta el error que la spec previene, y lo que cuesta escribirla ahora, con la información que tienes ahora. Cuando el error es caro e irreversible, la prima es barata a cualquier precio. Cuando el error se arregla con un git revert y un café, estás pagando un seguro contra un rasguño.

La regla, en una frase: no escribas una spec cuando el coste de deshacer el error sea menor que el coste de escribirla; escríbela siempre que el error no se deshaga con un comando.

Si has llegado aquí sin el contexto previo, en Spec-Driven Development: evita el caos de la IA está el método entero. Este post es la otra mitad: los seis sitios donde estuve pagando de más hasta que aprendí a mirar la factura.

1. Cuando todavía no sabes lo que quieres

Una spec responde a "qué vamos a construir". Un spike responde a "¿esto es siquiera posible?".

Son preguntas distintas, y la segunda no se contesta escribiendo. Se contesta ejecutando. Cuando estás evaluando si una librería aguanta tu caso, si esa API devuelve lo que promete o si el modelo entiende tus documentos, el código no es la implementación de la decisión: es el instrumento de medida.

Especificar ahí es adivinar con formato de documento. Y un documento bien maquetado tiene un efecto raro sobre el cerebro: le da a una suposición el aspecto de un hecho.

Lo que sí necesita un spike son guardarraíles, y son tres:

1. Una pregunta concreta escrita antes de empezar ("¿puedo procesar 500 facturas en menos de un minuto con este proveedor?"). Si no sabes formularla, no es un spike, es procrastinación con IDE.
2. Una caja de tiempo. Cuatro horas, un día. Lo que quieras, pero decidido antes.
3. El compromiso de tirar el código. Rama aparte, sin tests, sin abstracciones. Es YAGNI aplicado al documento: no especifiques por si acaso.

El peligro real de un spike nunca fue no tener spec. Es que el prototipo se quede. El prototipo demuestra, no se promociona.

Cuando llega la respuesta, escribes la spec. La exploración no sustituye a la spec: la alimenta. Ese salto del prototipo que demuestra al producto que se sostiene es justo lo que trabajamos en Construye con IA.

2. Cuando el cambio cabe en tu cabeza y git revert lo deshace

Subir un timeout. Añadir un índice. Cambiar el copy de un botón. Un campo más en un formulario que ya existe.

Un diff de veinte líneas, un archivo, reversible en un comando. Escribir spec.md + plan.md + tasks.md para eso no es rigor. Es ceremonia.

Y la ceremonia hace un daño que no se contabiliza: enseña a todo el mundo —incluido tú— que el proceso es un trámite. En cuanto una spec se percibe como trámite, todas las specs pierden autoridad. También las que sí importaban.

El test que uso es de tres preguntas. ¿Puedes describir el cambio completo en una frase, sin "y" ni "además"? ¿El diff cabe en una pantalla? ¿Deshacerlo es un comando? Tres síes: abre el editor y hazlo.

3. Cuando el código no va a sobrevivir a la semana

Un script para limpiar una tabla una vez. Un notebook para sacar un número que te ha pedido alguien. Un endpoint de debug que borras el viernes.

Una spec sirve para que otra persona —o tú dentro de seis meses— entienda una decisión. Si no va a haber ni otra persona ni dentro de seis meses, el documento no tiene a quién servir. El criterio de aceptación es ejecutarlo y mirar el resultado.

La trampa está en otro sitio: el código temporal tiene la mala costumbre de volverse permanente. En cuanto ese script se ejecuta una segunda vez, deja de ser desechable y entra en el caso contrario.

Mi regla: si dudo, la escribo. La duda ya es la señal de que la tarea es más grande de lo que parecía. Y si escribir la spec te está costando de verdad, echa un vistazo a la anatomía de una spec, porque a lo mejor el problema no es la tarea, es que estás escribiendo cuarenta líneas donde bastaban seis.

4. Los bugs no se especifican, se reproducen

Un bug no es una funcionalidad que falta. Es una diferencia entre lo que el sistema hace y lo que ya estaba dicho que tenía que hacer.

O sea: la especificación ya existe. La escribiste cuando construiste la feature, o vive implícita en el comportamiento que todo el mundo daba por bueno hasta el martes pasado. Escribir un documento nuevo para describir algo que ya está descrito es duplicar la verdad, no aclararla.

El artefacto correcto es un test que falla.

Reproduce, aísla, escribe el test en rojo, arréglalo, deja el test dentro. Ese test es la spec de ese bug, con una ventaja que ningún markdown te da: es ejecutable, y cuando envejece te avisa el CI. Si alguien vuelve a romper eso dentro de seis meses, se entera antes que tú. Cómo se combina eso con dejar que la IA escriba la implementación lo desarrollé en TDD y spec-first con IA.

Hay dos excepciones. La primera: nadie sabe decirte cuál sería el comportamiento correcto. Eso no es un bug, es un requisito sin decidir disfrazado de bug, y sí se especifica. La segunda: sabes perfectamente qué tiene que pasar, pero el arreglo es más grande que el fallo —rehacer la caché, tocar el modelo de concurrencia, cambiar un contrato que ya consume alguien—. El test sigue siendo obligatorio, pero describe el síntoma, no el rediseño. Eso se especifica igual.

5. Cuando el dominio cambia bajo tus pies

Si el requisito muda cada semana, la spec envejece más rápido de lo que tardas en ejecutarla. Y entonces tienes dos verdades: el documento y el código.

Cuando hay dos verdades, los humanos resuelven el conflicto solos: dejan de leer el documento. Molesto, pero se sobrevive.

El problema es el agente. Un agente no distingue una spec vigente de una obsoleta. No tiene forma de saber que ese párrafo lo invalidó una llamada del jueves. La lee, la trata como fuente de verdad y construye encima con toda la seguridad del mundo.

La salida no es abandonar el método, es acortar el alcance. Specs de una semana en vez de specs de un trimestre. Especifica la parte del dominio que ya está congelada y deja explícitamente marcado lo que sigue en discusión. Una sección de "esto todavía no está decidido" vale más que tres páginas de decisiones falsas.

6. Cuando la spec se ha convertido en teatro

El síntoma es fácil de reconocer: escribes la spec después de tener el código.

Eso no es Spec-Driven Development. Es documentación retroactiva, que no tiene nada de malo salvo el nombre que le pongas. El valor de la spec está en el orden, no en el archivo. Si el código ya existe, el documento no puede cambiar ni una sola decisión, que era exactamente para lo que servía.

Hay dos síntomas más. El primero: nadie la lee, y lo sabes porque nadie te ha discutido nunca una línea. El segundo: las specs se copian de la anterior cambiando los nombres.

Cuando aparece cualquiera de los tres, el problema no es el método. Es que lo estás aplicando en tareas donde no aportaba, y la gente lo ha notado antes que tú.

Cuándo usar Spec-Driven Development y cuándo no: la tabla

Tipo de trabajo	¿Spec?	Por qué
Spike para saber si algo es viable	No — pregunta y caja de tiempo	El código es la investigación; la spec fijaría decisiones sin información
Cambio pequeño y reversible	No — el propio diff	Revertirlo cuesta menos que documentarlo
Bug reproducible	No — un test en rojo	El test fija el comportamiento y además lo vigila el CI
Código que no sobrevive a la semana	No — el propio código	El documento no tiene a quién servir
Spec escrita después del código	No — llámalo documentación	Ya no puede cambiar ninguna decisión, que era su único trabajo
Requisito que cambia cada semana	Corta y con caducidad	La spec envejece más rápido de lo que se ejecuta
Feature nueva en un producto vivo	Sí	Otra persona la va a tocar y el error se paga meses después
Migración o cambio del modelo de datos	Sí, siempre	El error no se deshace con git
Trabajo que cruza servicios o equipos	Sí, siempre	La spec es el punto de sincronización, no el papeleo
Tarea que delegas entera a un agente	Sí, siempre	Lo que no escribas, lo rellena inventando
Auth, pagos, datos personales	Sí, siempre	El coste del fallo no es técnico

Bajar de artefacto no es dejar de pensar

La alternativa a una spec no es el caos: es un artefacto más barato. Hay cinco niveles, y solo el primero es una spec completa.

1. Spec completa — spec, plan y tareas. Para trabajo caro, compartido o delegado entero.
2. Spec corta — tres párrafos: objetivo, criterio de aceptación y qué queda fuera. El escalón que más uso.
3. Un plan — el modo plan de Claude Code, leído y aprobado antes de que toque nada. Treinta segundos de lectura que evitan revisar un diff de novecientas líneas, como conté en cómo usar Claude Code a diario.
4. Un test que falla — para bugs y para cualquier cosa con un criterio binario.
5. Nada — y el diff es toda la conversación.

La pregunta buena nunca fue "¿spec sí o spec no?". Es: ¿cuál es el artefacto más barato que evita que esto salga mal?

Dónde Spec-Driven Development gana siempre

La tabla ya dice dónde la spec no se discute: migraciones, modelo de dominio, auth, dinero. Nada de eso es nuevo. Lo que ha cambiado la ecuación, desde que los agentes de código empezaron a ejecutar tareas de varias horas sin supervisión, es la última fila: el trabajo que delegas entero a un agente.

Antes la spec competía contra "lo hago yo, que ya me entiendo". Ahora compite contra revisar cuatrocientas líneas que alguien escribió interpretando lo que tú no llegaste a decir. Cuando delegas, cada hueco de la especificación se rellena con una invención plausible, y las invenciones plausibles son las más caras de detectar. Lo desarrollé en qué pasa cuando pides código sin spec.

En ese escenario la spec deja de ser documentación. Es el prompt más caro que vas a escribir, y el único que se amortiza.

Lo que haría yo mañana

Coge la siguiente tarea de tu lista y hazte una sola pregunta antes de abrir el editor:

Si esto sale mal, ¿cuánto cuesta deshacerlo?

Si la respuesta es "un git revert", empieza a picar. Si la respuesta es "una migración de datos", "una llamada con otro equipo" o "un incidente en producción", escribe la spec antes de tocar una línea.

No necesitas más criterio que ese. Los seis casos de este post son solo ejemplos de esas dos respuestas.

El libro de Spec-Driven Development va justo de esto: hay un capítulo entero sobre la spec más corta que puedes escribir, además de las plantillas, el flujo con el agente y qué hacer cuando la spec y el código se separan. Si prefieres ver cómo lo aplica gente que ya lo tiene metido en su día a día, esa conversación pasa en Dominicode Labs.

Saber cuándo no usar un método es la parte que nadie te enseña, y es la que separa aplicarlo de entenderlo.

Preguntas frecuentes

¿Entonces Spec-Driven Development no sirve para proyectos pequeños?

Sirve, pero el tamaño del proyecto no es la variable correcta. La variable es cuánto cuesta deshacer la tarea si sale mal y cuánta gente toca ese código. Un proyecto pequeño con una migración de datos y un cobro de por medio necesita spec. Un proyecto enorme donde vas a cambiar el texto de un botón, no. Y si dudas, escríbela: la duda suele significar que la tarea es más grande de lo que parecía.

¿Qué escribo en lugar de una spec cuando la tarea no la necesita?

Bajas un escalón de artefacto, no bajas a cero. Hay cinco: spec completa, spec corta (objetivo, criterio de aceptación y qué queda fuera), un plan aprobado antes de tocar código, un test que falla, y nada. La mayoría del trabajo diario vive en los escalones dos y tres, no en el uno. La pregunta útil no es "¿spec sí o no?" sino cuál es el artefacto más barato que evita que eso salga mal.

¿Qué escribo en lugar de una spec cuando arreglo un bug?

Un test que falla. Reproduce el fallo, aísla el caso mínimo, escribe el test en rojo, arregla el código y deja el test dentro del repositorio. Ese test cumple la misma función que una spec —fijar el comportamiento esperado— con dos ventajas: es ejecutable y el CI lo comprueba solo. La excepción es cuando nadie sabe cuál debería ser el comportamiento correcto; eso no es un bug, es un requisito sin decidir, y ese sí se especifica.

¿Puedo escribir la spec después de tener el código?

Puedes, pero llámalo por su nombre: documentación. El valor de una spec está en el orden, porque su trabajo es cambiar decisiones antes de que se conviertan en código. Escrita después, no puede cambiar ninguna. Sirve para onboarding y para dejar constancia, y eso tiene su utilidad, pero no está gobernando nada.

¿Qué hago si los requisitos cambian cada semana?

Acorta el alcance de la spec en lugar de abandonarla. Especifica solo la parte del dominio que ya está cerrada, marca de forma explícita lo que sigue en discusión y ponle caducidad al documento. El riesgo grande no es no tener spec, es tener una obsoleta: un agente no sabe distinguirla de una vigente y construirá encima con total seguridad.

¿Y si voy a delegar la tarea completa a un agente de código?

Entonces escribe la spec aunque la tarea parezca pequeña. Cuando delegas, cada hueco que dejes sin especificar lo rellena el modelo con una suposición razonable, y esas suposiciones son las más difíciles de detectar revisando el diff. Ahí la spec no compite contra tu tiempo de escribir código: compite contra tu tiempo de revisar código ajeno, que siempre es más caro.

---

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.