Aprenderemos sobre SDD – Spec Driven Development instrumentalizado sobre OpenSpec. Haremos un primer acercamiento usando ClaudeCode con Sonnet, para luego, en un artículo posterior pasarnos a la versión gratuita de OpenCode con Gemma4
Índice de contenidos
- 1. Introducción a Spec Driven Development (SDD)
- 2. SDD con OpenSpec y ClaudeCode
- 3. Cómo funciona OpenSpec
- 4. Aplicando las Specs
- 5. Archivando las Specs
- 6. Añadiendo modo oscuro a nuestra web
- 7. La fuente de la verdad ya no es el código
- 8. Conclusiones
- 9. Enlaces y referencias
1. Introducción a Spec Driven Development (SDD)
No hará ni seis meses que escuché el término SDD y realmente es un cambio de paradigma. La idea es desarrollar a través de las especificaciones. Si, sí. Eso está muy guay, pero todos fuimos a la universidad, estudiamos precondiciones, invariante, postcondiciones, etc… Lo cierto es que es un poco más complejo. Tú le dices a la IA lo que quieres hacer, las especificaciones, la IA te entiende y las enriquece con lo que ella cree que tú quieres, detallándolo a niveles muy muy precisos. Tú lo revisas, y puedes modificar y añadir por ejemplos test, reglas de cómo debe comportarse. Al final aplicas y te genera el código en base a esas especificaciones.
Si están bien hechas, son tan importantes, que podrías borrar el código y pedir a la IA que lo regenerara en base a las especificaciones, y el resultado no debería cambiar demasiado. Ante este nuevo paradigma han aparecido una serie de herramientas que nos ayudan en el flujo de SDD. Por ejemplo, SpecKit. Aquí vamos a analizar el flujo simple de OpenSpec.
2. SDD con OpenSpec y ClaudeCode
OpenSpec no es una IA. Se apoya en una interfaz y en un LLM para generar sus specs. El interfaz puede ser ClaudeCode y el LLM puede ser Sonnet o Opus.
En el fondo es un conjunto de herramientas de código abierto. Su objetivo principal es servir como la fuente de verdad compartida entre humanos y agentes de Inteligencia Artificial antes de escribir código. Las specs sirven para no perder el contexto entre sesiones. Obliga al agente a leer un documento de especificaciones versionado y a trabajar estrictamente bajo ese marco. A través de comandos, genera un plan con dependencias (propuesta, especificaciones, diseño y lista de tareas). Una vez que el agente completa el código, las modificaciones se integran en la especificación, manteniendo un histórico de qué se construyó y por qué.
La instalación es muy sencilla.
npm install -g @fission-ai/openspec@latest
Una vez instalado, nos vamos hacia una carpeta donde queremos probarlo y ejecutamos el comando
openspec init
Nos preguntará con qué agente queremos interactuar.
3. Cómo funciona OpenSpec
Lo primero es arrancar ClaudeCode en ese directorio.
Una vez entramos en el cliente de Claude podemos ejecutar comandos de openspec. En el flujo básico nos vienen cuatro.
- /opsx:explore Explora el código que hay, matiza ideas, clarifica requerimientos, etc…
- /opsx:propose Propones una nueva funcionalidad. OpenSpec la enriquecerá y generará todos los ficheros con las specs
- /opsx:apply Se aplican los cambios propuestos una vez revisados y generaran el código.
- /opsx:archive Los cambios los archivará y volvemos al proceso iterativo con la siguiente historia de usuario.
Vamos a verlo en funcionamiento y le hacemos la siguiente propuesta.
/opsx:propose Quiero una web con la tabla periódica. 1) Con fondo claro y los elementos en color pastel 2) Que funcione sin necesidad de un servidor web, usando solo estándares HTML, CSS3 y JavaScript (Vainilla) 3) Que tenga un buscador 4) Que cuando selecciones un elemento muestre los detalles, sin que la tabla periódica reescale de tamaño. 5) Que los lantánidos y actínidos estén separados de la tabla periódica por al menos una fila
Ha creado varios ficheros.
proposal.md
design.md
tasks.md
Y las specs de los distintos componentes.
Vamos a ver el del buscador, por ejemplo
4. Aplicando las specs
Bien, ya tenemos los archivos generados con las especificaciones detalladas. Hemos dedicado un rato a leerlas y a comprobar que, en efecto, es lo que queremos. Podemos enriquecerlas con ejemplos y casos de uso, o con otros detalles. Una vez lo hayamos hecho estamos en condiciones de aplicarlas y ahí, ahí es donde sucede la magia.
/opsx:apply
Al aplicar los cambios se han generado los ficheros y, en efecto, se ha generado la página web que queríamos y se muestra sin necesidad de tener un servidor web.
No me gusta mucho el panel ese que dice «Haz click en un elemento para ver sus propiedades»
5. Archivando las specs
Cuando archivamos mediante el comando archive se mueven los cambios activos a la carpeta «archive». Y nos preguntas si queremos sincronizar el cambio a archivar con los specs del proyecto, que ahora mismo están vacíos. Decimos que sí, y se crearán las specs centrales del proyecto. Y ya estamos en condiciones de comenzar el ciclo proponiendo un nuevo cambio.
/opsx:archive
/opsx:propose no me gusta mucho el panel blanco que dice «Haz click en un elemento para ver sus propiedades». Prefiero que no se muestre y cuando se haga click en un elemento para ver el detalle del mismo aparezca el panel de detalle
Lo aplicamos, que ejecutará los cambios necesarios para que se comporte como queremos. Tras eso, lo archivamos, que moverá la carpeta de «changes» a «archive», y nos pedirá sincronizar, que mezclará las nuevas specs con las specs centrales del proyecto, aplicando los deltas.
6. Añadiendo el modo oscuro
Ya le estamos pillando el tranquillo a esto. Cada cambio debe ir acompañado de una nueva prouesta:
/opsx:propose quiero añadir un botón arriba que alterne entre modo oscuro y modo claro.
Y la plicamos
/opsx:apply
La página web ahora tiene modo claro y modo oscuro.
Archivamos el resultado y sincronizamos para que añada el delta spec del modo oscuro a los specs centrales del proyecto.
7. La fuente de la verdad ya no es el código
Pero, ¿y qué pasaría si borrase el código e hiciera una propuesta de que me lo regenerase en base a los specs? Bueno, los LLMs no son deterministas. Con mucha probabilidad no saldría exactamente igaul, pero el funcionamiento y lo programado cumpliría las especificaciones.
Hasta ahora repositábamos solo los cambios en el código, pero es legítimo preguntarse si deberíamos repositas las specs y la realidad es que sí.
Y, claro, poco a poco, según vamos trabajando vamos dándonos cuenta de sus ventajas:
1) podemos seguir trabajando en el mismo proyecto en diferentes sesiones.
2) podemos trabajar en equipo, y las specs son como una memoria del contexto compartida.
Se me antoja que GitFlow será complejo de gestionar con SDD. Seguramente haya que ir a estrategias de ramas de Trunk Base Development y hacer integraciones frecuentes, acercándonos a un despliegue contínuo de verdad.
8. Conclusiones
Es muy fácil acomodarse a OpenSpec. Aquí lo hemos usado con ClaudeCode y el modelo que he utilizado es Sonnet 4.6. No hemos usado el Opus que se habría fundido los tokens en un pis-pas. Tenemos que prestar atención a estas cosas. Probablemente no necesitamos el modelo más potente.
Creo que es muy fácil ser complaciente y acabar confiando en que lo que nos propone es suficientemente bueno y acabar por no revisarlo. Y de ahí pueden venir efectos laterales. Voy a proponer tres buenas prácticas que creo fundamentales para reducir la entropía de trabajar con SDD.
- Hacer una buena propuesta.
Cuanto mejor y más detallada sea la especificación de lo que queremos, más concreta y precisa será su propuesta. - Revisar y ampliar las specs
Debemos revisar con detalle todo lo que nos propone. El proposal.md, el design.md, tasks.md y los specs.md - Añadir test antes del apply
Si de verdad queremos que algo se comporte de una forma determinada, debemos escribir los nombres de los test de forma que reflejen ese comportamiento. Por ejemplo, «comprueba que cuando el usuario hace esto entonces pasa esto otro». En el fondo estos tests, que si hicieras TDD los harías antes de programar, aquí los sumas como validaciones del comportamiento que se espera.
9. Enlaces y referencias
- El código fuente de este tutorial en GitHub
https://github.com/eContento/lab/tree/main/tablaperiodica-con-claude-y-openspec - La tabla periódica funcionando
- ClaudeCode
- OpenSpec
