Cupón activo 
Llevo un tiempo trabajando con Claude Code y hay un patrón que se repite. Le pido algo amplio — "hazme un Arkanoid con power-ups y niveles" — y en 30 segundos tengo 400 líneas de código. Funciona. Más o menos. Pero cuando lo abro con calma, me doy cuenta de que Claude tomó 50 decisiones de diseño que yo nunca vi: cómo estructurar las clases, dónde vive el estado, qué formato usar para los niveles, cómo nombrar las entidades. Decisiones razonables, pero invisibles. Y caras de revertir.
Ese es el problema que el spec-driven design intenta resolver.
Qué es spec-driven design
La idea es simple: el spec es el artefacto principal del trabajo, no el código. El código es la consecuencia.
Suena obvio, y suena a "documentar antes de programar de toda la vida". La diferencia real está en que el spec no es decorativo ni opcional: es el contrato que guía la ejecución, vive en git, y se mantiene actualizado. Si el código diverge del spec, uno de los dos está mal.
Cada feature tiene su propio spec — un archivo markdown numerado en specs/ — y juntos forman el registro de decisiones de diseño del proyecto.
Por qué con un LLM se nota más
Los humanos también improvisamos cuando programamos sin plan. La diferencia con un LLM es la velocidad. Cuando un humano tarda dos horas en escribir un módulo, tiene tiempo de pensar. Cuando Claude lo hace en 30 segundos, las decisiones pasan invisibles.
Hay otros dos factores que lo agravan:
Cada conversación arranca de cero. Sin un spec, en la siguiente sesión Claude no sabe qué decidiste antes y va a improvisar otra vez, posiblemente en dirección contraria.
El contexto se llena rápido. Sin un documento estable al que referirse, terminas pegando contexto a mano en cada prompt.
El spec resuelve los tres problemas: hace explícitas las decisiones, persiste entre sesiones, y se carga una vez como referencia.
La parte aburrida
Aquí está la trampa: aunque entiendas el valor del método, planear es aburrido. Sentarte a escribir el alcance, el modelo de datos, los pasos numerados, los criterios de aceptación — todo eso es exactamente el tipo de trabajo que el cerebro quiere saltarse para llegar a "lo divertido", que es ver código corriendo.
Y esa pereza es la razón por la que mucha gente abandona spec-driven design después de intentarlo dos veces. No porque no funcione, sino porque la fricción inicial es alta y los beneficios se ven a mediano plazo.
Cuándo SÍ y cuándo NO usar specs
No todo merece un spec. La regla mental que uso:
Escribe un spec cuando:
La tarea tocará más de dos archivos.
Hay decisiones caras de revertir (esquemas, formatos, APIs).
La feature ocupará más de una sesión de Claude Code.
Es algo que vas a olvidar en una semana.
Usa un prompt directo cuando:
Es un bug fix puntual.
Es un refactor mecánico.
La tarea cabe en un prompt y se entiende a la primera.
Si te tienta abrir plan mode, probablemente lo necesites. Si la feature te aburre planearla, probablemente no.
Los skills que armé para esto
Para reducir la fricción de la parte aburrida, creé dos skills para ClaudeCode pero ya están funcionando para otros agentes que automatizan el ciclo completo: fernando-skills.
Son dos comandos:
/spec— Diseña el documento de la feature. Claude lee el contexto del proyecto, hace preguntas de clarificación en bloques, desarrolla el spec sección por sección, y al final lo guarda enspecs/NN-slug.mdcon estadoBorrador./spec-impl <NN-slug>— Implementa el spec. Valida que esté aprobado, crea una rama git, y arranca la implementación paso a paso con pausas para revisar diffs entre cada paso.
El gap entre los dos skills es deliberado: cambiar el estado del spec de Borrador a Aprobado lo haces tú a mano, fuera del chat. Es el único momento donde solo el humano puede actuar. Sin ese gap, el método se degrada a "Claude escribe documentación bonita y luego escribe el código que se le ocurra de todos modos".
La instalación es de una línea:
npx skills@latest add Klerith/fernando-skillsEl repo está en github.com/Klerith/fernando-skills con la documentación completa, el flujo de seis pasos, y los detalles de qué hace cada skill.
Cierre
Spec-driven design no es una bala de plata. Es un enfoque que cambia dónde inviertes el esfuerzo: más al principio, menos al final. La promesa es que las decisiones quedan capturadas, las sesiones largas se vuelven manejables, y el código que produce Claude deja de sorprenderte (en mal sentido).
Los skills que armé no inventan el método — solo le quitan la fricción de implementarlo. Que es, al final, la diferencia entre un método que usas y uno que abandonas.