Probablemente ya te pasó: le pides algo a la IA, recibes el resultado en diez segundos y descubres media hora después que entendió otra cosa.
La IA es un excelente equipo de obra: rapidísimo e incansable. Pero nadie deja que un equipo de obra decida solo cómo va a quedar tu casa. Alguien tiene que poner los planos. A eso, en software, se le llama Spec-Driven Development (SDD), y este artículo es lo que aprendí usándolo a diario.
El problema: remodelar la casa por audios de WhatsApp#
Un amigo decidió remodelar su casa. En vez de sentarse con un arquitecto, le fue mandando audios al maestro de obra: “tumba esa pared”, “mejor la cocina abierta”, “un enchufe ahí donde va la refri”.
Cuando hacemos eso con la IA se llama vibe coding: programar a sensación. Pides por chat, aceptas lo que salga y vas ajustando. Y falla igual que la remodelación por audios, por tres razones:
- Los pedidos viven en el chat. Nadie más los ve, nadie los guarda, nadie los puede revisar.
- Cada vez sale distinto. Pides lo mismo dos veces y salen dos cosas diferentes.
- La memoria se borra. Se cierra el chat o alguien deja el equipo, y nadie sabe por qué esa pared está ahí.
¿El final? La casa quedó parecida a la que pidió. Pero no es la que pidió. Con el software pasa exactamente igual.
El giro: deja de escribir prompts, empieza a escribir specs#
Un prompt es privado, temporal y difícil de revisar. Una spec es lo mismo que le pedirías a la IA, pero escrito como un requisito con nombre y un criterio de aceptación verificable, guardado en el repositorio junto al código:
## Requirement: Botón de copiar
El resultado MUST poder copiarse como Markdown.
WHEN el input está vacío, THEN el botón se deshabilita.
Cualquiera del equipo puede leerla, discutirla y mejorarla, hoy o dentro de seis meses.
El prompt-first es rápido. El spec-first es repetible. Y en proyectos grandes, lo que escala no es la velocidad de arranque: es la repetibilidad.
De “prompt and pray” (pides, rezas, revisas 800 líneas de código) a “specify and verify” (acuerdas el QUÉ en una o dos páginas, la IA implementa, verificas contra la spec). La calidad de lo que produce la IA es proporcional a la calidad de lo que le das.
El modelo mental: la spec es el contrato#
Nadie construye sin normas, planos, ingeniería y cronograma. Con la IA, tampoco:
| Capa | En la obra | En software |
|---|---|---|
| Constitución | Normas de construcción | Seguridad, pruebas, pautas del equipo |
| Spec | Los planos | QUÉ construimos. Cero detalle técnico |
| Plan | La ingeniería | Stack, frameworks, decisiones técnicas |
| Tareas | El cronograma | Bloques manejables, en orden |
| Código | La obra | Recién aquí se construye |
Y el paso que hace que todo funcione o no: revisar lo que la IA genera antes de que exista código. Si tú y tu equipo están de acuerdo con la spec y el plan, el contrato garantiza el resultado. Si nadie los lee, volvimos al vibe coding con más carpetas.
Mi camino: de Spec Kit a OpenSpec#
Hasta 2025 desarrollaba todo por prompts. Cuando apareció SDD, lo primero que probé fue Spec Kit, la herramienta de GitHub, en un proyecto personal. Seamos justos: ordenaba. Pero lo sentí engorroso, con muchos archivos y mucha ceremonia, y consumía muchos tokens. Entonces los tokens no dolían. Hoy sí.
Después apareció OpenSpec, con una filosofía más ligera, y ahí sentí la diferencia. Me agilizó de verdad tres cosas que hago todo el tiempo: los evolutivos de mis aplicativos, la modernización de aplicaciones existentes y la creación de apps nuevas. Hoy es mi framework del día a día.
OpenSpec en dos ideas#
Idea 1 · Dos carpetas: la verdad y lo que cambia.
openspec/
├── specs/ ← cómo funciona el sistema HOY (fuente de la verdad)
└── changes/ ← propuestas en curso, una carpeta por cambio
└── agregar-poliza-vida/
├── proposal.md qué y por qué
├── design.md decisiones técnicas
├── tasks.md checklist de implementación
└── specs/ el DELTA: qué requisitos cambian
En la analogía: specs/ son los planos actualizados de la casa; changes/ son los permisos de obra en trámite. Por eso funciona tan bien en sistemas que ya existen: no dibujas los planos de toda la casa el día uno, dibujas la habitación que vas a tocar.
Idea 2 · Delta specs: describe solo lo que cambia. Como un adéndum a un contrato: no se reescribe todo, solo se firma qué se agrega, qué se modifica y qué se elimina. Un revisor entiende el cambio leyendo doce líneas de Markdown, sin bucear en el código. Si el delta está mal, se corrige antes de que exista una sola línea.
El flujo, en cuatro comandos desde tu asistente de IA:
/opsx:explore— piensas el problema con la IA, sin comprometerte (opcional)./opsx:propose "idea"— la IA genera propuesta, delta, diseño y tareas. Tú revisas. Aún no hay código./opsx:apply— la IA implementa guiada por la spec./opsx:archive— el delta se fusiona enspecs/: la verdad queda actualizada.
El punto de control está entre el 2 y el 3: revisas unas pocas páginas de Markdown, no cientos de líneas generadas. El setup toma dos minutos (npm install -g @fission-ai/openspec@latest y openspec init), funciona con más de 25 asistentes (Claude Code, Cursor, Copilot, Codex, Gemini CLI…) y no necesita API keys ni servidores: es puro Markdown en tu repo.
Y del otro lado: Spec Kit#
Spec Kit es la propuesta de GitHub. Su filosofía es opuesta en algo clave: un pipeline fijo y secuencial de siete pasos (constitution → specify → clarify → plan → tasks → analyze → implement), gobernado por una constitución que todo agente lee primero. Cada feature genera su carpeta completa con siete o más archivos, crea una rama de git automáticamente, y tiene el respaldo, la documentación y los tutoriales de GitHub.
Una frase que resume la diferencia: Spec Kit responde “qué construimos para la feature 003”; OpenSpec responde “qué hace nuestro sistema”. Con el tiempo, uno te deja una colección de features; el otro, un documento vivo del sistema.
| OpenSpec | Spec Kit | |
|---|---|---|
| Filosofía | Fluido, iterativo, sin fases obligatorias | Estructurado, pipeline fijo |
| Specs | Una del sistema + deltas por cambio | Una completa por feature |
| Archivos por cambio | ~4 compactos | 7+ verbosos |
| Ideal para | Código existente (brownfield) | Proyectos desde cero (greenfield) |
| Reglas del proyecto | config.yaml | constitution.md (más central) |
| Git | Tú controlas las ramas | Rama por feature automática |
¿Cuándo usar cuál?#
OpenSpec si trabajas sobre código existente, quieres una spec viva que crezca cambio a cambio, prefieres ciclos cortos y menos ceremonia, y quieres controlar tú la estrategia de ramas.
Spec Kit si arrancas desde cero, el equipo recién empieza con SDD y agradece un pipeline fijo con menos decisiones, quieres una constitución fuerte y valoras el ecosistema de GitHub.
Spec Kit es la rampa de entrada al SDD; OpenSpec es el destino cuando las specs tienen que vivir y crecer con el sistema.
Lo que hay que decir con honestidad#
Esto no es magia. Quienes lo probaron en código real reportan cosas incómodas:
- Martillo para una nuez. Un bug pequeño puede convertirse en cuatro user stories con dieciséis criterios. OpenSpec ayuda con un flujo sin fases obligatorias, pero la disciplina de no sobre-especificar sigue siendo tuya. Regla práctica: si la spec tiene más líneas que el cambio, el flujo es demasiado pesado para ese caso.
- Falsa sensación de control. Con plantillas y constituciones, el agente igual puede ignorar instrucciones. Ninguna herramienta lo elimina: la revisión humana entre proponer e implementar sigue siendo obligatoria. La spec reduce el riesgo; no lo hace desaparecer.
- Puede volverse waterfall si haces mucho diseño por adelantado. La respuesta es mantener cambios pequeños e iterativos.
Y un matiz para los modelos de 2026: las guías oficiales de OpenAI y Anthropic coinciden en describir el destino, no el camino. Los modelos actuales planifican y se corrigen solos. Una spec bien hecha es exactamente eso: objetivo, criterios de éxito, restricciones y hasta dónde llega el agente antes de volver a ti. Por eso funciona.
El volante es tuyo#
De “prompt and pray” a specs que viven en el repo y se revisan antes del código. Lo que me llevo:
specs/es la verdad.changes/es el delta.- El flujo es proponer → implementar → archivar.
- Lo único innegociable: revisar antes.
$ git commit -m "este artículo"
Author: humano <yo>
Co-authored-by: IA — implementó la spec, no la decidió.
Ese reparto de roles es todo el punto.
Mi recomendación: elige una feature pequeña y real de tu proyecto, haz openspec init y prueba el ciclo completo una vez. Toma menos de una hora y sabrás si te sirve mejor que cualquier artículo, incluido este.
Referencias#
- openspec.dev · github.com/Fission-AI/OpenSpec
- github.com/github/spec-kit
- Birgitta Böckeler, Understanding Spec-Driven Development (martinfowler.com)