Software Crafters® 2026 | Creado con 🖤 para elevar el nivel de la conversación sobre programación en español | Legal
Hay una pregunta que llevo encontrándome una y otra vez en los últimos meses: ¿cómo le describes al agente exactamente lo que tiene que construir?
Los prompts largos no escalan. No hay un estándar de cómo hacerlo. Cada developer le pasa al agente lo que buenamente puede, con el nivel de detalle que buenamente le sale, y el agente lo interpreta como puede. Cuanto más compleja es la feature, más se desvía el resultado de lo que tenías en mente.
Tienes el agente bien configurado. Sabe cómo programar, cómo testear, cómo revisar. Pero falta una pieza: definir de manera exhaustiva qué quieres construir y cómo quieres que se construya.
Esa es la pieza que añade Spec Driven Development.
Y no es vibe coding. No es promptear y rezar. Es ingeniería de software.
Los datos dicen que la deuda técnica se ha multiplicado por cuatro desde 2022. No es casualidad. Es el resultado de usar la IA sin proceso. Lo que voy a contar aquí es el proceso.
Spec Driven Development es desarrollo guiado por especificaciones claras y formales que actúan como fuente de verdad para diseñar, implementar y validar el sistema.
Dicho de otra forma: antes de que el agente toque una línea de código, tiene que existir un documento que defina exactamente qué se va a construir, cómo se va a construir y cómo se va a validar que está bien hecho.
Ese documento es la spec. Y la spec es el contrato.
Hasta ahora, la fuente de verdad en la mayoría de equipos era el código. Y el código sigue siendo la fuente de verdad. Eso no cambia. Lo que cambia es que ahora podemos complementarlo con documentación en lenguaje natural que se genera muy rápido. Decisiones de arquitectura, requisitos no funcionales, criterios de aceptación, alternativas que se descartaron y por qué. Todo eso no vive bien en el código. Y ahora tenemos herramientas que nos permiten generarlo y mantenerlo actualizado sin esfuerzo.
Para que una spec funcione de verdad, tiene que cumplir dos cosas.
La primera es que sea exhaustiva. Tiene que cubrir todo lo que tiene que pasar para que esa tarea pueda darse como realizada. No es el definition of done que muchas veces se queda en el imaginario colectivo del equipo, en la wiki que nadie actualiza, en la conversación del standup. Es la spec real, con todos los casos cubiertos.
¿Por qué la mayoría no las hace? Porque describir con detalle lo que vamos a hacer cuesta. Es tedioso. Pero ahora tenemos una máquina que lo hace por nosotros. No hay excusa para no decirle a la máquina cómo nos gusta trabajar y pedirle: oye, aplicando esto, sabiendo que lo que quiero construir es esto, dame una tarea mucho más exhaustiva que cubra criterios de aceptación, requisitos funcionales, no funcionales y todo lo demás.
La segunda es que todo sea validable. Si no, lo único que vamos a hacer es desplazar el cuello de botella. Pasamos de tenerlo en desarrollo (traducir de lenguaje humano a lenguaje máquina) a tenerlo en validación. Porque ahora el agente genera código muy rápido, pero si no tenemos un proceso de validación automático que verifique rápidamente que está bien hecho, el problema es incluso mayor que el que teníamos antes.
Y no vas a subir directamente a producción sin revisarlo antes. ¿Verdad?
Con estas dos variables, lo que te da Spec Driven Development es un contrato. Con mayúsculas. Un outcome claro que se espera de ti como developer.
Igual que en otros departamentos donde está muy claro en qué consiste el trabajo de cada persona: tantas llamadas, tanto impacto en redes, tantas conversiones. Métricas claras y tarea clara. En desarrollo no hemos tenido eso. Tradicionalmente, un developer recibía un ticket que decía "quiero que el usuario pueda exportar los datos a CSV" y con eso se iba a programar. Y cada uno interpretaba el alcance como podía.
Hay que traer esa claridad al mundo de la ingeniería.
Y antes de que nadie lo piense: esto no mata la artesanía del software. Al contrario. La artesanía está en refinar el contexto que le das al agente. En que haga TDD paso a paso. En la calidad de las guidelines de diseño, de arquitectura, de testing. En definir qué es código bien hecho para tu equipo y tu proyecto. El agente ejecuta, pero tú defines y validas el estándar del código. Y definir y validar qué es código sostenible y qué no, requiere criterio, experiencia y oficio. Más que nunca.
Seguro que alguno acostumbrado al agilismo está pensando: si tienes que definir totalmente la tarea desde el principio para poder desarrollarla, ¿no estamos volviendo al modelo cascada?
No. Lo único que estamos haciendo es decir: lo que quiero hacer, lo voy a detallar al máximo y lo voy a validar con unos criterios de aceptación al final. Nada más. Es pensar antes de programar y plasmarlo por escrito.
Si la primera entrega de valor es un endpoint sencillo con un frontend mínimo, puedo especificar esa tarea con todo el detalle y entregarla mañana. La granularidad la decides tú.
La diferencia con antes es que ahora, por el mismo coste de picar la idea directamente al código, tienes la documentación clara de lo que vas a hacer. No solo se acelera el desarrollo: la IA deja una traza de lo que se hizo, por qué se hizo y qué decisiones se tomaron. Lejos de perder agilidad, la motiva. Porque deja claras las decisiones para saber qué no funcionó y qué sí. Y si ese prototipo que ibas a tirar resulta que funciona, probablemente no haya que tirarlo abajo: por el mismo tiempo puede ser más seguro, más modular, más escalable, más testable. En definitiva, más sostenible.
Esto no es la última moda de Silicon Valley, ni lo ha inventado nadie recientemente. La idea tiene más de 20 años.
Está basado en los principios de BDD, Behavior Driven Development. Dan North empezó a trabajar en estas ideas en 2003 y publicó su famoso artículo "Introducing BDD" en 2006.
La clave de BDD no es el Given-When-Then. Eso es solo el formato. La clave es el proceso que hay detrás. Y son tres pasos:
Discovery. Conversaciones para descubrir los escenarios. ¿Qué tiene que pasar? ¿Qué casos límite hay? ¿Qué pasa si el usuario mete un campo vacío? ¿Qué pasa si no tiene permisos? Es la parte que más valor aporta y la que más se salta la gente. Porque requiere sentarse a pensar.
Formulation. Formular esos escenarios en un formato concreto y no ambiguo. Given-When-Then. "Dado que el carrito tiene 3 productos, cuando el usuario aplica un cupón de descuento válido, entonces el precio total se reduce un 20%." Sin margen de interpretación. El escenario dice exactamente qué tiene que pasar y con un ejemplo concreto.
Automation. Convertir esos escenarios en tests ejecutables que validen que el sistema hace lo que dice la spec. No antes. Primero Discovery, luego Formulation, luego Automation.
Estos tres pasos son la esencia de BDD. No Cucumber. No Gherkin. No testing end-to-end. Discovery, Formulation, Automation.
¿Y qué tiene que ver esto con Spec Driven Development?
Todo.
Discovery es lo que pasa cuando detallas la historia de usuario. Formulation es lo que genera el agente en las specs con escenarios BDD. Y Automation es lo que hace el agente cuando implementa y crea los tests.
Los tres pasos de BDD que casi nadie hacía porque costaban demasiado. Demasiada ceremonia. Los equipos no tenían tiempo. Acababan en la wiki que nadie actualizaba.
Ahora la IA los hace en minutos. Y luego implementa ella misma.
Si te interesa profundizar en BDD, dos libros cortos y prácticos de Seb Rose y Gáspár Nagy: Discovery y Formulation. Y un clásico que complementa muy bien: Specification by Example de Gojko Adzic (2011). La tesis central de este último es usar ejemplos concretos para definir requisitos, de forma que esos ejemplos se conviertan en la especificación del sistema y en los tests que lo validan. Misma filosofía, otro ángulo.
La idea tiene más de 20 años. Lo nuevo es que ahora es viable.
Vale, ya sabemos qué es. Ahora la pregunta es: ¿cómo lo implemento?
Han surgido varios frameworks que te dan el proceso listo para usar. Yo traigo cinco, pero hay más y cada semana aparece alguno nuevo.
Kiro es el IDE de Amazon. Amazon ha sacado su propio IDE agentico con Spec Driven Development integrado de serie. No es un plugin, no es un framework que instalas. Es un entorno completo. Cuando creas una tarea, te genera automáticamente una spec con requisitos, diseño y plan de implementación.
El enfoque es interesante porque apuesta por que el SDD sea el flujo por defecto, no algo opcional. Pero tiene una limitación clara: estás atado a su ecosistema. Si usas otro editor, no te vale.
SpecKit está muy pensado para proyectos que empiezan de cero, para greenfield. Te da una estructura para definir specs y generar código a partir de ellas. Fácil de arrancar.
El problema es que cuando tu proyecto ya tiene una codebase grande, con sus convenciones, con su deuda técnica, con sus formas de trabajar, SpecKit se queda corto. No está diseñado para eso.
GSD va por otro camino. Es más pragmático, menos ceremonia. La idea es que definas lo mínimo necesario para que el agente trabaje bien y ya. Sin artefactos de más.
Funciona bien para tareas puntuales, pero cuando necesitas trazabilidad y documentación que se mantenga en el tiempo, se queda algo justo.
B-MAD es el más complejo de todos. Tiene un sistema de artefactos muy elaborado, con múltiples fases y niveles de detalle. Si lo que buscas es el máximo rigor y tu equipo tiene la madurez para adoptarlo, es muy potente.
Pero esa complejidad tiene un coste. Arrancarlo es difícil. Entenderlo lleva tiempo. Y si no tienes un equipo comprometido con el proceso, se convierte en burocracia.
Y luego está OpenSpec. Que es el que yo uso.
Los asistentes de IA son muy potentes pero impredecibles cuando los requisitos viven solo en el historial del chat. OpenSpec añade una capa de especificación ligera para que tú y la IA estéis de acuerdo en qué se va a construir antes de que se escriba una línea de código.
Te permite acordar antes de construir. Mantenerte organizado, porque cada cambio tiene su propia carpeta con propuesta, specs, diseño y tareas. Trabajar de forma fluida, sin puertas rígidas entre fases: puedes actualizar cualquier artefacto en cualquier momento. Y funciona con más de 20 agentes de IA mediante comandos.
En proyectos brownfield donde ya hay una codebase, donde ya hay convenciones y formas de trabajar, OpenSpec brilla. Y la configuración no es complicada: se puede montar bastante rápido.
Un punto importante: todo esto es agnóstico del agente que uses. Claude Code, Codex, GitHub Copilot, Cursor, Antigravity. Todos son compatibles con OpenSpec porque los frameworks son archivos markdown y comandos. No dependen de ningún editor concreto.
Si mañana cambias de herramienta, tu proceso de SDD sigue funcionando. Y eso es muy potente. Porque tus specs, tu contexto, tus flujos de trabajo, todo se queda en el repo. No se queda en un plugin propietario que desaparece cuando cambia el viento.
OpenSpec trabaja con tres pasos básicos. Bueno, tres más uno.
El primero es Propose. Preparar muy bien la propuesta. Definir qué quieres construir con el máximo detalle. Aquí hay un paso previo opcional que se llama Explore: cuando tienes una idea vaga y necesitas pensarla antes de comprometerte, Explore te guía en una conversación para aclarar requisitos, identificar riesgos y llegar a una comprensión clara de lo que quieres construir. No se crean artefactos. Es Discovery puro. Casi siempre empiezo por aquí.
Cuando la idea está clara, Propose genera todos los artefactos de planificación.
El segundo es Apply. Aquí es cuando realmente se programa. El agente implementa todo lo que se ha definido en la propuesta. Crea los tests (si se lo has indicado en el contexto), escribe el código, actualiza la documentación.
Y el tercero es Archive. Cuando la tarea está terminada, la archivas. Lo que hasta ahora estaba viviendo como un cambio dentro del código pasa a ser documentación formal del proyecto. De manera que cuando pidas un nuevo cambio, OpenSpec va a revisar todo lo que está archivado y va a saber si lo que pides es una funcionalidad nueva o un delta sobre algo que ya existe.
Eso es todo. Explore, Propose, Apply, Archive. Olvídate de hacer prompts. Olvídate de las técnicas de prompt engineering para las tareas del día a día. Esas técnicas son para preparar tu contexto, para personalizar los pasos. Pero para que el proceso sea sistemático y lo haga igual el junior que el senior, son comandos o acciones en formato skills.
Cuando lanzas el Propose, OpenSpec te genera cuatro artefactos:
La propuesta: el por qué. Define por qué quieres hacer esto, qué es lo que quieres construir. Es la visión desde producto.
Las specs: los requerimientos y los escenarios. Esto sí que es el ticket técnico súper exhaustivo. Con escenarios en formato BDD Given-When-Then, para todos los casos que tienen que pasar.
El diseño: la aproximación técnica. Qué decisiones de arquitectura se toman, qué alternativas se han descartado y por qué. No es solo "lo voy a hacer así". Es "lo voy a hacer así por tal y tal razón, y se ha descartado hacerlo de esta otra manera". Muy interesante desde el punto de vista de arquitectura.
Y las tareas: la checklist de implementación. Hiper exhaustiva. 95, 130 tareas una a una. Porque cada test unitario es una tarea. Mockear las variables de base de datos es otra tarea. Crear la rama de la funcionalidad es otra tarea. Todo es una tarea.
OpenSpec tiene dos perfiles.
El Core tiene cuatro workflows: Explore, Propose, Apply y Archive. Es simple y rápido. Para la mayoría de casos es suficiente.
El Expanded añade workflows adicionales para control granular: New (crea una carpeta de cambio vacía sin generar artefactos), Continue (genera el siguiente artefacto uno a uno para que lo revises antes de pasar al siguiente), Fast-forward (genera todos los artefactos pendientes de golpe), Sync specs (sincroniza los delta specs con la fuente de verdad sin necesidad de archivar el cambio), Verify (comprueba que todos los artefactos estén completos y sean coherentes entre sí) y Bulk archive (archiva múltiples cambios a la vez).
Mi recomendación: empieza con los cuatro del perfil Core. Tienes todo lo que necesitas. Si más adelante necesitas más control, puedes añadir pasos extra en cualquier momento.
Instalar OpenSpec es muy sencillo. Requiere Node.js 20 o superior.
npm install -g @fission-ai/openspec@latest
Luego, en tu proyecto:
cd tu-proyecto openspec init
El setup interactivo te pregunta dos cosas: qué herramientas IA quieres configurar (Claude Code, Cursor, Copilot, lo que uses) y qué perfil (Core o Expanded). Para empezar rápido con Claude Code:
openspec init --tools claude --profile core
¿Qué crea esto?
tree openspec
Una carpeta openspec/ con tres subcarpetas: specs/ (la fuente de verdad del comportamiento de tu sistema), changes/ (donde viven los cambios activos y archivados) y config.yaml (el contexto de tu proyecto y las reglas de cada artefacto).
Y además crea las skills correspondientes en .claude/skills/ para que los comandos funcionen directamente en Claude Code.
OpenSpec puede entregar sus workflows como commands (slash commands que invocas explícitamente) o como skills (se cargan automáticamente por contexto y también las puedes invocar manualmente). Mi recomendación: usa skills. Te dan lo mejor de ambos mundos.
openspec config profile # Elige: "Change delivery only" → "Skills only" openspec update
Con esto, cuando estés en un contexto relevante, el agente sabe que tiene OpenSpec disponible. Y tú puedes invocar /openspec-propose o /openspec-apply cuando quieras.
OpenSpec está instalado. Pero todavía no conoce tu proyecto. Vamos a configurar el contexto para que cuando genere artefactos, los genere acorde a cómo trabajas.
Todo se configura en un solo archivo: openspec/config.yaml. Tiene dos secciones.
La sección context se muestra a la IA cada vez que genera artefactos. Es lo primero que lee antes de crear una propuesta, una spec, un diseño o una tarea. Aquí le cuentas tu stack, tu arquitectura, tus prácticas, tu dominio.
La forma más directa es escribirlo en texto plano:
context: | Tech stack: TypeScript, Bun, React 19, Hono 4, MongoDB 7 Architecture: Hexagonal with vertical slicing Practices: TDD (red-green-refactor), conventional commits Domain: e-commerce platform
Pero hay una forma mejor. Si ya tienes guidelines documentadas como skills (arquitectura hexagonal, estándares de testing, prácticas de TDD), en vez de duplicar esa información en el config.yaml, puedes referenciarlas directamente:
context: | Project guidelines (source of truth): Read and follow: - .claude/skills/guidelines/architecture-hexagonal - .claude/skills/guidelines/testing-standards - .claude/skills/guidelines/xp-tdd-practices
¿Qué ganamos? Que la información vive en un solo sitio. Si actualizas una guideline, OpenSpec lo ve automáticamente la próxima vez que genere artefactos. No tienes que acordarte de actualizar el config.yaml cada vez que cambia algo en el proyecto.
La segunda sección es rules. Aquí defines cómo quieres que OpenSpec genere cada tipo de artefacto. Es como darle instrucciones específicas para cada paso del proceso.
Por ejemplo, puedes decirle que las propuestas siempre incluyan una sección de Non-goals para delimitar el alcance. Que las specs usen formato Given-When-Then para los escenarios. Que el diseño siga las capas de tu arquitectura hexagonal. Y que las tareas apliquen TDD con el ciclo red-green-refactor:
rules: proposal: - Keep proposals concise and focused on the "why" - Always include a "Non-goals" section specs: - Write scenarios in Given/When/Then format - Include edge cases and error scenarios design: - Follow hexagonal architecture layers - Specify testing strategy per layer tasks: - "Tasks with behavior use TDD format: RED → GREEN → REFACTOR" - "Order tasks inside-out: domain → application → infrastructure" - Keep tasks small enough for one TDD cycle
Sin estas reglas, cada artefacto sale genérico. Las specs no tienen escenarios BDD. El diseño no sigue tu arquitectura. Las tareas no aplican TDD. Con las reglas, OpenSpec genera exactamente como quieres.
Un detalle sobre la versión actual: las rules del apply todavía no se leen directamente del config.yaml. Pero hay un workaround sencillo: si embedes las instrucciones TDD en las rules de tasks, cuando el agente lea el tasks.md para implementar, las instrucciones están ahí dentro de cada tarea. Funciona bien.
Hasta ahora, el grueso del trabajo de un developer estaba en el medio: programar. Recibías un ticket, te ponías a picar código y cuando terminabas lo subías a revisión.
Con Spec Driven Development, el trabajo se desplaza a los extremos.
Al principio: en definir con precisión qué se va a construir.
Y al final: en verificar que lo que ha salido es lo que se pidió y que el código sigue siendo sostenible.
Cuanto más sostenible sea el código, más rápido irás con la IA y menos bugs se introducirán en el sistema. Esto no quiere decir que la calidad del código importe menos, al contrario. Lo que cambia es quién la sostiene y desde dónde.
El esfuerzo que antes suponía tener documentación actualizada, tests con buena cobertura, buena arquitectura, trazabilidad de las decisiones que se tomaron, tareas bien definidas con un contrato claro, todo eso tendía a infinito. Era caro. Era tedioso. Por eso la mayoría de equipos no lo hacía.
Ahora tiende a cero. Y el valor que aporta es muy alto.
Coge un proyecto en el que estés trabajando ahora mismo. Elige una tarea pendiente. Instala OpenSpec, configura el config.yaml con tu contexto y tus skills, y haz el flujo completo: explore, propose, apply, archive.
Verás la diferencia.
Por cierto, todo esto lo veo en detalle en una masterclass de la mentoría: la plantilla, el config.yaml real, una demo completa end-to-end y soporte por email para resolver dudas mientras lo aplicas en tu proyecto.
Si te interesa, suscríbete a la newsletter aquí debajo y responde a cualquier email.
¿Quiéres leer más artículos como éste? Pues suscríbete a la newsletter