Workshop · La IA construye, tú pones los planos

Tabla de contenido

Basado en el artículo La IA construye. Tú pones los planos. Guía práctica para hacer desde tu máquina. No necesitas conocer OpenSpec ni haber usado Spec-Driven Development antes.

Qué vas a tener funcionando al terminar
#

Un mini editor web con un botón “Copiar como Markdown” que la IA implementó a partir de una spec que tú revisaste y corregiste a mano, con esa spec guardada en tu repositorio como la fuente de la verdad de tu sistema.

Vas a poder comprobarlo con tres cosas:

El botón funciona y cumple exactamente lo que escribiste en la spec.
La spec vive en tu repo, en openspec/specs/, y cualquiera puede leerla sin abrir el código.
El commit lleva la spec y el código juntos.

Y, más importante que el botón, vas a haber recorrido el ciclo completo una vez: proponer, revisar, implementar, archivar. Eso es lo que te llevas.

La feature es deliberadamente pequeña. La lección no es el botón, es el ciclo.

Paso 0 · Requisitos
#

Haz esto con calma antes del workshop, en tu propia máquina. Es lo que más falla (versiones, instalaciones, sesiones) y no queremos resolverlo durante la sesión. Nada de lo que sigue funciona sin este paso.

0.1 · Node y git
#

node -v      # necesitas 20 o superior
git --version

Si no los tienes: nodejs.org y git-scm.com.

0.2 · OpenSpec
#

npm install -g @fission-ai/openspec@latest
openspec --version

Si imprime un número de versión, está listo.

0.3 · Kiro
#

Instala Kiro, inicia sesión y abre un chat. Escríbele “hola”. Si responde, está listo.

0.4 · El proyecto base
#

Crea una carpeta nueva y dentro un único archivo index.html:

mkdir sdd-workshop
cd sdd-workshop
git init

Contenido de index.html:

<!doctype html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <title>Mini editor</title>
  <style>
    body { font-family: sans-serif; max-width: 600px; margin: 40px auto; }
    textarea { width: 100%; height: 120px; }
    #salida { border: 1px solid #ccc; padding: 12px; margin-top: 12px; min-height: 40px; }
  </style>
</head>
<body>
  <h1>Mini editor</h1>
  <textarea id="entrada" placeholder="Escribe algo..."></textarea>
  <div id="salida"></div>
  <script>
    const entrada = document.getElementById('entrada');
    const salida = document.getElementById('salida');
    entrada.addEventListener('input', () => { salida.textContent = entrada.value; });
  </script>
</body>
</html>

Guarda y haz el primer commit:

git add index.html
git commit -m "proyecto base: mini editor sin botón de copiar"

Abre index.html en el navegador (doble clic o npx serve .). Debes ver un textarea y, al escribir, el texto repetido abajo. No hay botón de copiar. Eso es lo que vamos a construir.

✅ Checkpoint 0 · “Estoy listo”
#

openspec --version responde
Kiro responde a un mensaje
index.html abre en el navegador y repite lo que escribes
git log muestra tu primer commit

Parte 1 · Siente el problema: pedir por prompt
#

Antes de usar OpenSpec, vamos a hacer lo que hace todo el mundo: pedirle a la IA por chat y aceptar lo que salga. A esto se le llama vibe coding.

Paso 1.1 · Crea una rama descartable
#

git checkout -b vibe

Paso 1.2 · Pídelo como lo pedirías un martes a las seis de la tarde
#

Abre la carpeta sdd-workshop en Kiro y escribe en el chat, solo esto:

agrega un botón de copiar

Acepta lo que proponga. Recarga el navegador.

Paso 1.3 · Observa qué salió
#

Responde para ti mismo:

¿Copia texto plano o Markdown?
¿El botón está deshabilitado cuando el textarea está vacío?
Si otra persona hiciera este mismo paso, ¿le saldría el mismo botón?

Ahora mira tu repositorio:

git status

Solo cambió index.html. Ninguna decisión quedó escrita en ningún lado. Nadie sabe qué pediste ni qué se esperaba. Si cierras el chat, se perdió.

Paso 1.4 · Descarta y vuelve al inicio
#

git checkout -- .
git checkout main
git branch -D vibe

✅ Checkpoint 1
#

Deberías estar en main, con el proyecto base limpio corriendo en el navegador y habiendo visto los tres problemas del prompt: el pedido vive en el chat, cada vez sale distinto, la memoria se borra.

Es como remodelar tu casa mandándole audios de WhatsApp al maestro de obra. La casa queda parecida a la que pediste. Pero no es la que pediste.

Parte 2 · Pon los planos: OpenSpec
#

Ahora vamos a pedir lo mismo, pero escribiendo primero qué queremos, revisándolo, y recién después dejando que la IA construya.

Paso 2.1 · Conecta OpenSpec con Kiro
#

En la carpeta del proyecto:

openspec init

Te preguntará qué asistente de IA usas. Elige Kiro. Esto crea la carpeta openspec/ y configura los comandos para que Kiro sepa cómo trabajar con ella.

Comprueba:

openspec list

Debe responder que no hay cambios activos. Correcto: aún no propusimos nada.

Si Kiro no muestra los comandos /openspec-... en el siguiente paso, abre la carpeta openspec/ y busca el archivo de instrucciones que generó el init para Kiro. Puedes pegar su contenido como mensaje en el chat junto con tu pedido. El resultado es el mismo.

Nota: ¿por qué OpenSpec si Kiro ya es spec-first? Kiro trae su propia forma de trabajar con specs (requirements, design y tasks dentro de .kiro/specs/), y funciona bien. La diferencia es dónde viven los planos. Las specs de Kiro son de Kiro. Las de OpenSpec son Markdown en tu repo, en un formato que entienden más de 25 asistentes: Claude Code, Cursor, Copilot, Codex, Gemini CLI, Windsurf y el propio Kiro. Si mañana el equipo cambia de IDE, o cada persona usa uno distinto, la carpeta openspec/ sigue siendo la misma verdad del sistema para todos. Hoy usamos Kiro porque es la herramienta del workshop, pero todo lo que hagas en las Partes 2 y 3 lo podrías repetir tal cual en cualquier otro IDE agéntico con un openspec init que apunte a ese asistente.

Paso 2.2 · Propón el cambio (todavía sin código)
#

En el chat de Kiro:

/openspec-propose Agregar un botón que copie el contenido del textarea como Markdown. Si el textarea está vacío, el botón debe estar deshabilitado.

La IA va a crear una carpeta dentro de openspec/changes/ con cuatro cosas:

openspec/changes/agregar-boton-copiar/
├── proposal.md   → qué vamos a hacer y por qué
├── design.md     → decisiones técnicas (por ejemplo, usar la Clipboard API)
├── tasks.md      → checklist de implementación, en orden
└── specs/        → el DELTA: qué requisitos se agregan al sistema

Fíjate en algo: todavía no hay una sola línea de código nueva. Eso es a propósito. Es el momento de revisar.

Paso 2.3 · Revisa y corrige a mano
#

Abre el archivo dentro de openspec/changes/agregar-boton-copiar/specs/. Vas a encontrar algo parecido a esto:

## ADDED Requirements

### Requirement: Botón de copiar
El resultado MUST poder copiarse como Markdown.

#### Scenario: textarea vacío
WHEN el input está vacío, THEN el botón se deshabilita.

Ahora tú haces dos cosas:

Agrega un escenario que la IA no puso. Por ejemplo:

#### Scenario: confirmación visual
WHEN se copia con éxito, THEN el botón muestra "Copiado" durante 2 segundos.

Borra algo que la IA agregó de más. Casi siempre agrega algo que no pediste: un atajo de teclado, un toast, soporte para algo que no existe. Quítalo.

Guarda el archivo.

Acabas de revisar unas doce líneas de Markdown en lugar de doscientas de código. Si la spec estaba mal, la corregiste antes de que exista el código. Este es el paso que hace que todo lo demás funcione.

Paso 2.4 · Deja que la IA construya
#

En Kiro:

/openspec-apply

La IA implementa siguiendo tasks.md y el delta que acabas de revisar. Verás cómo las tareas se van marcando como completadas.

Paso 2.5 · Verifica contra la spec, no contra tu gusto
#

Recarga el navegador y comprueba exactamente lo que dice la spec:

Con el textarea vacío, el botón está deshabilitado.
Escribes algo, pulsas el botón, pegas en un editor: es Markdown.
Al copiar, el botón muestra “Copiado” durante 2 segundos (lo que tú agregaste).

Si el “Copiado” no aparece: no es un fracaso, es la lección más importante del workshop. La spec reduce el riesgo, no lo hace desaparecer. Pídele a Kiro que complete la tarea que falta en tasks.md y vuelve a verificar.

✅ Checkpoint 2
#

El botón funciona en tu navegador, generado desde una spec que tú revisaste. tasks.md está todo tachado. Y si corres git status, verás que la spec y el código cambiaron juntos, en el mismo repo.

Parte 3 · Haz que la spec sea la verdad
#

Hasta aquí tienes una propuesta implementada. Falta que se convierta en la descripción oficial de cómo funciona tu sistema.

Paso 3.1 · Archiva el cambio
#

En Kiro:

/openspec-archive

Mira qué pasó con la carpeta:

ANTES                                DESPUÉS
openspec/                            openspec/
├── specs/         (vacío)           ├── specs/
└── changes/                         │   └── .../spec.md   ← la verdad, actualizada
    └── agregar-boton-copiar/        └── changes/          ← vacío

El delta se fusionó en openspec/specs/. Esa carpeta ahora responde a la pregunta "¿qué hace mi sistema hoy?". La próxima feature no arranca de cero: arranca de aquí.

Comprueba:

openspec list                  # sin cambios activos
cat openspec/specs/*/spec.md   # ahí está tu requisito, con el escenario que agregaste

Paso 3.2 · Guarda spec y código juntos
#

git add -A
git commit -m "feat: botón copiar como Markdown (spec + código)"

Si tienes un remoto configurado, haz git push. Un compañero podrá entender el cambio leyendo la spec, sin bucear en el código.

✅ Checkpoint 3 · El resultado final
#

Tienes:

Un botón funcionando que cumple lo que tú especificaste.
Una spec en openspec/specs/ que describe tu sistema y que cualquiera puede leer.
Un commit con la spec y el código juntos.
Y el ciclo completo hecho una vez: proponer → revisar → implementar → archivar.

Y del otro lado: Spec Kit
#

OpenSpec no es la única opción. Spec Kit es la propuesta de GitHub para lo mismo, con una filosofía distinta. No lo vamos a ejecutar aquí, pero conviene que sepas en qué se diferencia para elegir en tu próximo proyecto.

Si hubieras hecho esta misma feature con Spec Kit, la carpeta se vería así:

OpenSpec (lo que acabas de hacer)     Spec Kit (misma feature)
changes/agregar-boton-copiar/          specs/001-boton-copiar/
├── proposal.md                        ├── spec.md
├── design.md                          ├── plan.md
├── tasks.md                           ├── research.md
└── specs/… (delta, ~12 líneas)        ├── data-model.md
                                       ├── quickstart.md
                                       ├── contracts/
                                       └── tasks.md
                                       + memory/constitution.md
                                       + una rama de git creada automáticamente

Spec Kit sigue un pipeline fijo 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.

La diferencia en una frase: Spec Kit responde “qué construimos para la feature 001”; 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

Elige OpenSpec si trabajas sobre código existente, quieres una spec viva que crezca cambio a cambio, prefieres ciclos cortos y menos ceremonia.

Elige Spec Kit si arrancas desde cero, tu equipo recién empieza con esto y agradece un pipeline fijo con menos decisiones, 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.

Para cerrar
#

Responde esta pregunta con tu propio caso. Es lo que decide todo lo demás:

Mi próximo proyecto es ___ (existente / desde cero). Mi equipo ___ (ya usa SDD / recién empieza). Elegiría ___ porque ___.

Y tres cosas para llevarte:

specs/ es la verdad. changes/ es el delta.
El flujo es proponer → revisar → implementar → archivar.
Lo único innegociable: revisar antes de que exista código.

Una advertencia honesta: no uses esto para todo. Si la spec tiene más líneas que el cambio, el flujo es demasiado pesado para ese caso. Un bug de una línea no necesita una propuesta.

Tu tarea para esta semana: elige una feature pequeña y real de tu proyecto, haz openspec init y repite el ciclo completo una vez. Toma menos de una hora y vas a saber si te sirve mejor que cualquier artículo.

Si algo falla
#

Problema	Qué hacer
Kiro no reconoce `/openspec-propose`	Abre `openspec/` y busca el archivo de instrucciones que generó `openspec init` para Kiro. Pega su contenido en el chat junto con tu pedido.
`openspec init` no muestra Kiro en la lista	Actualiza: `npm install -g @fission-ai/openspec@latest`. Si sigue sin aparecer, elige la opción genérica de `AGENTS.md`, que Kiro también lee.
El `apply` implementó algo distinto a la spec	Es normal y es la lección. Dile a Kiro qué tarea de `tasks.md` no cumple la spec y que la corrija.
El botón no copia en el navegador	La Clipboard API necesita `https://` o `localhost`. Sirve el archivo con `npx serve .` en vez de abrirlo con doble clic.
`openspec list` sigue mostrando el cambio después de archivar	Revisa que el `archive` terminó sin errores. Puedes correr `openspec archive agregar-boton-copiar` desde la terminal.

Referencias
#

openspec.dev · github.com/Fission-AI/OpenSpec
github.com/github/spec-kit
kiro.dev
Birgitta Böckeler, Understanding Spec-Driven Development (martinfowler.com)
Artículo base: La IA construye. Tú pones los planos

Qué vas a tener funcionando al terminar#

Paso 0 · Requisitos#

0.1 · Node y git#

0.2 · OpenSpec#

0.3 · Kiro#

0.4 · El proyecto base#

✅ Checkpoint 0 · “Estoy listo”#

Parte 1 · Siente el problema: pedir por prompt#

Paso 1.1 · Crea una rama descartable#

Paso 1.2 · Pídelo como lo pedirías un martes a las seis de la tarde#

Paso 1.3 · Observa qué salió#

Paso 1.4 · Descarta y vuelve al inicio#

✅ Checkpoint 1#

Parte 2 · Pon los planos: OpenSpec#

Paso 2.1 · Conecta OpenSpec con Kiro#

Paso 2.2 · Propón el cambio (todavía sin código)#

Paso 2.3 · Revisa y corrige a mano#

Paso 2.4 · Deja que la IA construya#

Paso 2.5 · Verifica contra la spec, no contra tu gusto#

✅ Checkpoint 2#

Parte 3 · Haz que la spec sea la verdad#

Paso 3.1 · Archiva el cambio#

Paso 3.2 · Guarda spec y código juntos#

✅ Checkpoint 3 · El resultado final#

Y del otro lado: Spec Kit#

Para cerrar#

Si algo falla#

Referencias#