Spec Kit: usa el SDD de GitHub para no improvisar con IA

Le dices a tu agente de IA “hazme una app del tiempo” y te genera algo que compila, se ve bonito y hasta te muestra la temperatura de tu ciudad. Pruebas a cambiar la ubicación y no funciona. Miras el código y descubres que la API key está hardcodeada, no hay manejo de errores y los tests brillan por su ausencia.

Bienvenido al vibe coding.

Spec Kit es la respuesta de GitHub a ese problema. Un toolkit open source que pone la especificación en el centro y convierte tus intenciones en software a través de un flujo de trabajo que cualquier agente de IA puede seguir. Tiene más de 126.000 estrellas en GitHub, soporta más de 30 agentes de IA y su versión más reciente (v0.16.1) se publicó el 7 de agosto de 2026.

En este artículo vamos a construir algo concreto: una webapp que te diga si necesitas paraguas antes de salir de casa, usando la API de Open-Meteo. Pero no lo haremos al estilo “escríbeme esto, a ver qué sale”. Lo haremos con Spec Kit, paso a paso.

Post actualizado el 10 de agosto de 2026. Escribí la versión original con la v0.3.1 y desde entonces Spec Kit ha cambiado lo suficiente como para que los comandos de aquel artículo ya no funcionen tal cual. Esto es lo que ha cambiado, por si vienes de la versión antigua:

• El flag --ai ya no existe: ahora es --integration, y hay un specify integration list para ver las disponibles
• La CLI está publicada en PyPI: uv tool install specify-cli funciona sin el --from git+...
• Ya no son 8 comandos slash, son 10: entran /speckit.taskstoissues y /speckit.converge en el núcleo
• Los comandos slash ya no son universales: hay un modo skills, Codex CLI usa $speckit-* y GitHub Copilot CLI usa /agents
• Dos primitivas nuevas: workflows (automatización multi-paso con checkpoints) y bundles (setups por rol)
• Autoactualización: specify self check y specify self upgrade
• Extensión bug incluida y triaje en tres pasos bajo .specify/bugs/
• Brownfield ya es una fase oficial (“Iterative Enhancement”) con su propia guía

Esto es lo que vas a encontrar:

• Qué es el Spec Driven Development (SDD) y por qué necesitas conocerlo
• Qué es Spec Kit y qué lo diferencia de otras herramientas como OpenSpec
• Cómo instalar y configurar Spec Kit con tu agente favorito
• Caso práctico completo: “¿Me llevo el paraguas?” con la API de Open-Meteo
• Los 10 comandos slash y cuándo usar cada uno
• Qué es la constitución de un proyecto y por qué cambia las reglas del juego
• Workflows y bundles: automatizar el flujo y provisionar setups por rol
• Limitaciones y críticas que deberías conocer antes de adoptarlo

¿Qué es el Spec Driven Development (y por qué importa)? ¶

Si has leído mi guía sobre OpenSpec y Spec Driven Development, ya sabes de qué va esto. Si no, te lo resumo rápido.

El Spec Driven Development (SDD) es una forma de trabajar donde escribes primero lo que tiene que hacer el software antes de que la IA genere una sola línea. La especificación no es un documento que se queda en un cajón. Es la fuente de verdad que el agente usa para planificar, implementar y validar.

¿Por qué necesitas esto? Porque el 41% del código que se genera a nivel global ya sale de una IA (Second Talent, Vibe Coding Statistics 2026). Y cuando le das instrucciones vagas, el resultado es un software que “funciona” pero que no cubre los casos extremos, ignora la seguridad y acumula deuda técnica como si no hubiera mañana. Un informe de Veracode de 2025 encontró que el código generado por IA introduce vulnerabilidades del OWASP Top 10 en el 45% de los casos (Awesome Agents, Vibe Coding Security Report).

El SDD invierte la relación: el código sirve a la especificación, no al revés. Mantienes el software evolucionando las specs, no parcheando el código. No es una idea nueva — la ingeniería de software lleva décadas predicando “especifica antes de construir” — pero ahora el ejecutor es un agente de IA que trabaja a una velocidad sin precedentes y que necesita ese plano más que cualquier programador humano.

🔑 Si quieres profundizar en las bases del SDD, las diferencias con TDD y BDD, y cómo funciona OpenSpec, tengo una guía completa de Spec Driven Development con OpenSpec que lo cubre en detalle. Aquí nos vamos directo a la práctica con Spec Kit.

¿Qué es Spec Kit y de dónde sale? ¶

Spec Kit es el toolkit open source de GitHub para Spec Driven Development. Lo presentaron en septiembre de 2025 y desde entonces ha crecido a un ritmo que pocos proyectos alcanzan: más de 126.000 estrellas en GitHub, más de 11.200 forks, contribuidores en más de 50 países y desarrollo activo con varias releases por semana — la última, la v0.16.1, publicada el 7 de agosto de 2026 (GitHub Spec Kit Releases). Según un análisis de Ry Walker Research, Spec Kit es una de las herramientas de desarrollo con crecimiento más rápido de 2026 (Ry Walker Research).

No es un editor, no es un agente de IA, no es un IDE. Es una estructura que se integra con el agente que ya usas — Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex CLI, OpenCode, Cline, Antigravity, Kimi Code, Grok Build y una lista que ya pasa de 30 integraciones — y le da un flujo de trabajo con pasos claros.

La filosofía de Spec Kit se resume en una frase que su creador, Den Delimarsky, repite en cada presentación: las especificaciones dejan de ser scaffolding que descartas y se convierten en artefactos ejecutables que generan el código.

¿Qué significa “artefacto ejecutable”? Que la spec no es un PDF que nadie lee. Es un documento Markdown versionado en tu repo que el agente de IA consume, interpreta y transforma en código, tests y tareas.

El flujo tiene cinco fases:

1. Constitution — Defines los principios inamovibles del proyecto
2. Specify — Describes qué quieres construir y por qué
3. Plan — Eliges el stack técnico y la arquitectura
4. Tasks — El agente descompone el plan en tareas ejecutables
5. Implement — El agente implementa las tareas siguiendo el plan

Cada fase produce un artefacto que alimenta la siguiente. Si cambias la spec, el plan se actualiza. Si cambias el plan, las tareas se regeneran.

A ese esqueleto de cinco pasos se le han añadido después dos comandos que cierran el círculo: /speckit.taskstoissues, que convierte la lista de tareas en issues de GitHub, y /speckit.converge, que compara el código real contra la spec, el plan y las tareas, y añade lo que falta como tareas nuevas. Volvemos a ellos en la referencia de comandos.

El método paso a paso

Antes de comparar herramientas, asegúrate de tener el método SDD claro

Spec Kit es una herramienta para aplicar SDD. La guía premium te lleva por el método entero en una tarde: cinco fases con ejemplo guiado real y plantilla para empezar hoy.

Abrir la guía →

Incluye autodiagnóstico + plantilla descargable

¿En qué se diferencia Spec Kit de OpenSpec? ¶

Si ya conoces OpenSpec, te preguntarás: ¿por qué necesito otra herramienta? La respuesta corta: Spec Kit apunta a proyectos nuevos y OpenSpec a evolucionar los que ya existen. Son primas hermanas pero con personalidades distintas — aunque la frontera se ha ido difuminando, como verás justo debajo de la tabla.

📌 Matiz importante desde la versión original de este post. La fila de “enfoque principal” ya no es tan tajante. Spec Kit tiene hoy una fase Iterative Enhancement (Brownfield) documentada de forma explícita y una guía oficial, Evolving Specs, con el bucle recomendado para proyectos que ya existen. Sigue siendo cierto que OpenSpec nació para eso y que su modelo de delta specs encaja mejor, pero ya no es un “Spec Kit no sirve para legacy”.

OpenSpec brilla cuando ya tienes un proyecto con código y quieres añadir funcionalidades sin romper nada. Spec Kit es más ambicioso: quiere que la especificación sea la fuente de verdad de la que todo se genera.

💡 No tienes que elegir uno para siempre. Puedes usar OpenSpec para mantener un proyecto legacy y Spec Kit para arrancar uno nuevo. Lo que importa es que dejes de improvisar con prompts sueltos.

¿Cómo instalar Spec Kit? ¶

Necesitas tres cosas en tu máquina: Python 3.11 o superior, uv (el gestor de paquetes de Astral; pipx también vale) y Git. Si ya tienes un agente de IA configurado — Claude Code, Copilot, Cursor, lo que sea — estás listo.

La instalación persistente es la recomendada. Desde hace unas cuantas versiones, specify-cli está publicado en PyPI, así que ya no necesitas el --from git+...:

# Instalar Spec Kit desde PyPI
uv tool install specify-cli

# Verificar que tus agentes CLI están disponibles
specify check

Si prefieres fijar una versión concreta — que es lo que recomienda el README oficial, porque el proyecto se mueve muy rápido — instala desde Git apuntando al tag de release, con la v delante:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.16.1

Y para no quedarte atrás, Spec Kit trae ahora sus propios comandos de autoactualización:

# ¿Hay una versión más nueva? (solo lectura, no toca nada)
specify self check

# Ver qué haría el upgrade sin ejecutarlo
specify self upgrade --dry-run

# Actualizar en el sitio (detecta si usaste uv tool o pipx)
specify self upgrade

# O fijar un tag concreto
specify self upgrade --tag v0.16.1

El flag --ai ya no existe: ahora es --integration ¶

Este es el cambio que más rompe si vienes de un tutorial antiguo (incluida la primera versión de este mismo post). El flag que le dice a Spec Kit qué agente usas pasó de --ai a --integration:

# Inicializar un proyecto nuevo
specify init mi-proyecto --integration claude

# Ver todas las integraciones disponibles en tu versión
specify integration list

Si omites --integration en una terminal interactiva, la CLI te pregunta. En entornos no interactivos (CI, ejecución con pipe) el valor por defecto es GitHub Copilot, y puedes cambiarlo con la variable SPECKIT_INTEGRATION_DEFAULT.

Las claves que más te van a sonar: claude, copilot, cursor-agent, gemini, codex, opencode, cline, agy (Antigravity), kimi, grok, droid, devin, hermes, junie, zed. La lista completa pasa de 36 integraciones y sale en specify integration list.

⚠️ Los comandos slash ya no son universales. La mayoría de agentes exponen Spec Kit como /speckit.*, pero Codex CLI en modo skills usa $speckit-* y GitHub Copilot CLI usa /agents para seleccionar el agente (o te diriges a él directamente en el prompt). Hay integraciones que instalan agent skills en vez de ficheros de prompt: se activa con --integration-options="--skills", y en el caso de Copilot ese ya es el comportamiento por defecto desde la v0.16.0 (pasa --integration-options="--commands" si quieres el layout antiguo).

Una vez ejecutas specify init, tu proyecto tendrá una carpeta .specify/ con las plantillas, los scripts de automatización y la estructura para empezar a trabajar. Ojo con un detalle que la primera versión de este post contaba mal: las specs viven en specs/ en la raíz del proyecto, no dentro de .specify/.

mi-proyecto/
├── .specify/
│   ├── memory/
│   │   └── constitution.md    # Principios del proyecto
│   ├── scripts/               # Scripts de automatización
│   ├── templates/             # Plantillas para spec, plan y tareas
│   │   └── overrides/         # Ajustes puntuales de este proyecto
│   ├── extensions/            # Extensiones instaladas
│   └── .gitignore             # Gestionado por Spec Kit
├── specs/                     # ← Especificaciones por feature (raíz)
│   └── 001-mi-feature/
│       ├── spec.md
│       ├── plan.md
│       └── tasks.md
└── .claude/                   # Varía según la integración
    └── skills/                # (o commands/, o .github/skills/…)

A partir de aquí, todo ocurre dentro del chat con tu agente de IA.

Caso práctico: “¿Me llevo el paraguas?” ¶

Vamos a lo que nos gusta. Construir algo. La idea es sencilla: una webapp que consulta la previsión meteorológica y te dice si necesitas paraguas. Usaremos la API gratuita de Open-Meteo, que no requiere API key y procesa más de 30.000 millones de solicitudes al mes según sus propias estadísticas (Open-Meteo, documentación oficial).

Paso 1: la constitución del proyecto ¶

La constitución es el concepto más potente de Spec Kit. Es un documento donde defines las reglas que todo el código debe cumplir, sin excepción. Es como los principios SOLID pero para tu proyecto concreto.

En el chat de tu agente:

/speckit.constitution Este proyecto sigue estos principios:
1. Sin API keys: usamos solo APIs públicas sin autenticación
2. Responsive first: la interfaz debe funcionar en móvil
3. Accesibilidad: cumplimos WCAG 2.1 nivel AA como mínimo
4. Tests obligatorios: no se implementa nada sin test previo
5. Sin frameworks pesados: vanilla HTML, CSS y JavaScript

El agente crea el archivo constitution.md en .specify/memory/. A partir de ahora, cada vez que genere código, plan o tareas, consultará esta constitución para asegurarse de que no viola ningún principio.

¿Parece exagerado para un proyecto pequeño? Puede ser. Pero piensa en lo que pasa cuando le dices a tu agente “añade autenticación con Google” y la constitución dice “sin API keys”. El agente te va a avisar del conflicto en lugar de generar código que no encaja con lo que decidiste al principio. Según la investigación de Den Delimarsky para el blog de GitHub, los equipos que trabajan sin principios compartidos producen código donde cada agente toma decisiones conflictivas sobre estructura, convenciones y patrones (GitHub Blog, SDD announcement).

⚠️ La constitución no es un documento flexible. Es tu línea roja. Si un requisito futuro la contradice, lo que toca es actualizar la constitución con una justificación, no ignorarla.

Paso 2: especificar qué queremos construir ¶

Aquí es donde describes el qué y el por qué, sin entrar en tecnología:

/speckit.specify Construir una aplicación web que muestre si el usuario
necesita paraguas hoy. La app detecta la ubicación del usuario mediante
geolocalización del navegador (con fallback a introducción manual de ciudad).
Consulta la previsión meteorológica de las próximas 12 horas. Si la
probabilidad de precipitación supera el 30% en cualquier franja horaria,
muestra "Llévate el paraguas" con los detalles de cuándo lloverá.
Si no, muestra "Hoy no necesitas paraguas". La interfaz es una sola
pantalla, limpia, con un icono animado que cambia según la previsión.

Spec Kit genera automáticamente una rama de Git (algo como 001-umbrella-checker) y crea el archivo spec.md en specs/001-umbrella-checker/, en la raíz del repositorio.

La spec que genera el agente incluye user stories, criterios de aceptación y — esto es lo bueno — marca con [NEEDS CLARIFICATION] todo lo que no le queda claro. Por ejemplo:

### User story: location fallback
As a user without geolocation enabled,
I want to enter my city manually,
So that I can still check the weather forecast.

#### Acceptance criteria:
- [NEEDS CLARIFICATION: ¿Autocompletado de ciudades o texto libre?]
- The system must validate the city exists before querying the API
- Error message shown for invalid locations

Esas marcas de clarificación son una de las grandes ventajas sobre el vibe coding. En lugar de inventar una respuesta (que es lo que hace un LLM cuando le falta contexto), te pregunta. Investigadores de la Universidad de Columbia documentaron que los agentes de IA tienden a eliminar validaciones de seguridad o relajar políticas de base de datos con tal de que el error de consola desaparezca (Towards Data Science, The Reality of Vibe Coding, 2026). Las marcas [NEEDS CLARIFICATION] atacan ese problema de raíz: obligan a resolver la ambigüedad antes de que el agente tome una decisión por ti.

Paso 3: clarificar las ambigüedades ¶

Antes de pasar al plan técnico, resolvemos las preguntas abiertas:

/speckit.clarify El campo de ciudad será texto libre con validación
contra la API de geocoding de Open-Meteo. No necesitamos autocompletado.
La app debe mostrar la previsión hora a hora en una lista sencilla
debajo del mensaje principal. El icono animado será un SVG inline,
sin dependencias externas.

El agente actualiza la spec con las aclaraciones y elimina las marcas [NEEDS CLARIFICATION]. Ahora tienes un documento limpio, sin ambigüedades, listo para planificar.

Paso 4: crear el plan técnico ¶

Ahora sí, hablamos de tecnología:

/speckit.plan La aplicación usa Vite como bundler con vanilla JavaScript.
No usamos frameworks de UI. Los estilos van con CSS nativo y custom properties.
Consultamos la API de Open-Meteo (https://api.open-meteo.com/v1/forecast)
con los parámetros latitude, longitude y hourly=precipitation_probability.
Los tests usan Vitest. El despliegue será estático en cualquier hosting.

Spec Kit genera varios archivos:

• plan.md — El plan técnico con decisiones de arquitectura
• research.md — Investigación sobre la API de Open-Meteo, límites de rate, formato de respuesta
• contracts/ — Definición de los endpoints y el formato de datos esperado
• quickstart.md — Escenarios de validación rápida

Aquí un fragmento de lo que podría generar en contracts/:

{
  "endpoint": "https://api.open-meteo.com/v1/forecast",
  "method": "GET",
  "params": {
    "latitude": 41.65,
    "longitude": -4.72,
    "hourly": "precipitation_probability",
    "forecast_hours": 12,
    "timezone": "auto"
  },
  "response_format": {
    "hourly": {
      "time": ["2026-03-20T08:00", "..."],
      "precipitation_probability": [10, 25, 45, "..."]
    }
  }
}

El plan también referencia la constitución. Si habías dicho “sin API keys”, el agente verifica que Open-Meteo no requiere autenticación y lo documenta. Si hubieras elegido una API de pago, te habría avisado del conflicto.

Según la documentación de Spec Kit, un enfoque tradicional de documentación para un proyecto equivalente (PRD + diseño técnico + plan de tests) puede llevar unas 12 horas de trabajo. Con SDD y los comandos automatizados, ese mismo proceso se comprime a unos 15 minutos (GitHub Spec Kit, spec-driven.md). La diferencia es que los artefactos que genera Spec Kit no son documentos estáticos: son inputs ejecutables para el agente.

Paso 5: generar las tareas ¶

/speckit.tasks

Este comando lee el plan, los contratos y la spec para generar un archivo tasks.md con la lista de tareas en el orden correcto:

1. Crear la estructura del proyecto con Vite
2. Escribir los tests de contrato para la API de Open-Meteo
3. Implementar el módulo de llamada a la API
4. Escribir los tests para la lógica de decisión (paraguas sí/no)
5. Implementar la lógica de decisión
6. Escribir los tests para la geolocalización
7. Implementar la geolocalización con fallback manual
8. [P] Crear los componentes de UI (paralelizable)
9. [P] Crear las animaciones SVG del icono (paralelizable)
10. Integrar todos los módulos
11. Tests end-to-end

Las tareas marcadas con [P] son paralelizables. Si tienes un agente que soporta tareas paralelas, puede trabajar en la UI y las animaciones al mismo tiempo.

🛡️ Fíjate en el orden: los tests siempre van antes que la implementación. No es casualidad. La constitución dijo “tests obligatorios” y la plantilla de Spec Kit refuerza el enfoque TDD. La IA no puede saltarse ese paso.

Paso 6: implementar ¶

/speckit.implement

El agente recorre las tareas una a una, genera el código y lo valida contra los tests. Si algo falla, ajusta. Si un test no pasa, no avanza a la siguiente tarea. Ese ciclo de validación es clave: si quieres profundizar en cómo hacer testing con IA de forma que los tests no sean una capa más de alucinación, merece la pena entender la trampa de la tautología.

El resultado es un proyecto con esta estructura:

src/
├── api/
│   └── weather.js          # Módulo de llamada a Open-Meteo
├── logic/
│   └── umbrella-decision.js # Lógica de decisión
├── geo/
│   └── location.js          # Geolocalización + fallback
├── ui/
│   ├── app.js               # Componente principal
│   └── icons.js              # SVG animados
├── styles/
│   └── main.css
└── index.html

Con tests en:

tests/
├── api/
│   └── weather.test.js
├── logic/
│   └── umbrella-decision.test.js
├── geo/
│   └── location.test.js
└── e2e/
    └── app.test.js

El módulo de decisión tendría algo como esto:

// Determina si necesitas paraguas en las próximas horas
export function shouldTakeUmbrella(precipitationData, threshold = 30) {
  const { time, precipitation_probability } = precipitationData;

  const rainyHours = time
    .map((t, i) => ({ time: t, probability: precipitation_probability[i] }))
    .filter(entry => entry.probability >= threshold);

  return {
    needsUmbrella: rainyHours.length > 0,
    rainyHours,
    maxProbability: Math.max(...precipitation_probability),
  };
}

Y su test correspondiente:

import { describe, it, expect } from 'vitest';
import { shouldTakeUmbrella } from '../src/logic/umbrella-decision.js';

describe('shouldTakeUmbrella', () => {
  it('devuelve true cuando alguna hora supera el umbral', () => {
    const data = {
      time: ['08:00', '09:00', '10:00'],
      precipitation_probability: [10, 45, 20],
    };

    const result = shouldTakeUmbrella(data);

    expect(result.needsUmbrella).toBe(true);
    expect(result.rainyHours).toHaveLength(1);
    expect(result.maxProbability).toBe(45);
  });

  it('devuelve false cuando ninguna hora supera el umbral', () => {
    const data = {
      time: ['08:00', '09:00'],
      precipitation_probability: [10, 20],
    };

    const result = shouldTakeUmbrella(data);

    expect(result.needsUmbrella).toBe(false);
  });
});

¿Qué es la constitución y por qué cambia las reglas del juego? ¶

La constitución es un documento que establece los principios técnicos inamovibles de tu proyecto, y es el concepto que más separa a Spec Kit de cualquier otra herramienta SDD del mercado. Cada comando de Spec Kit la consulta antes de generar cualquier artefacto.

Ya la hemos usado en el ejemplo, pero merece un apartado propio.

Imagina que tienes un equipo de cinco personas, cada una usando un agente de IA distinto. Sin constitución, cada agente toma decisiones diferentes sobre estructura de carpetas, convenciones de código, patrones de testing y estilo de API. El resultado es un Frankenstein arquitectónico.

La constitución resuelve esto. Es un documento que vive en .specify/memory/constitution.md y define los “artículos” que gobiernan todo el desarrollo. Si ya conoces el concepto de harness engineering — diseñar el entorno que rodea al modelo — la constitución es la capa de restricciones del harness aplicada al nivel de proyecto. El documento original de Spec Kit propone nueve artículos, pero puedes adaptarlos a tu realidad:

• Library-First: cada feature empieza como librería independiente
• CLI obligatorio: toda funcionalidad debe ser accesible por línea de comandos
• Test-First: no se escribe implementación sin tests previos aprobados
• Simplicidad: máximo 3 proyectos para la implementación inicial
• Anti-abstracción: usa el framework tal cual, sin wrappers innecesarios
• Integration-First: los tests usan entornos reales, no mocks

No tienes que aplicar los nueve. Elige los que tengan sentido para tu contexto y añade los tuyos. Lo que no puedes hacer es ignorar la constitución una vez definida: si el agente detecta que una tarea la viola, se detiene y te avisa.

Modificar la constitución es posible, pero exige documentar el motivo y evaluar el impacto en el código existente. No es “borro esta línea y listo”.

¿Funciona Spec Kit para proyectos que ya existen? ¶

Sí, y cada vez con menos matices. Spec Kit nació con mentalidad greenfield — proyectos que empiezan de cero — pero hoy el brownfield es una fase de primera clase en la documentación oficial, bautizada como Iterative Enhancement, con tres actividades declaradas: añadir features de forma iterativa, modernizar sistemas legacy y adaptar procesos.

Además, la comunidad lleva tiempo demostrándolo en bases de código grandes. Uno de los walkthroughs más impresionantes extiende un CMS open source de más de 307.000 líneas de C# con dos features nuevas. Otro añade una consola de administración a un runtime Jakarta EE de 420.000 líneas de Java repartidas en 180 módulos Maven (GitHub Spec Kit README, Community Walkthroughs).

La clave sigue siendo el flag --here, que permite inicializar Spec Kit en un directorio que ya tiene código (con el nombre de flag nuevo, ojo):

specify init --here --integration claude --force

El bucle brownfield recomendado ¶

La guía oficial Evolving Specs insiste en separar dos cosas que la gente mezcla: actualizar los ficheros de Spec Kit (comandos, scripts, plantillas) y hacer evolucionar los artefactos de specs/. Son dos mantenimientos distintos y conviene no cruzarlos.

Para lo segundo, la documentación propone tres modelos de persistencia y te deja elegir, en vez de imponer uno:

• Flow-forward: cada carpeta de feature es un registro histórico inmutable. Cuando algo cambia, creas una feature nueva en lugar de tocar la anterior. Bueno para auditoría y trazabilidad.
• Living spec: spec.md es el contrato y plan.md y tasks.md se derivan de él. Cuando cambia el comportamiento previsto, primero revisas la spec y luego regeneras lo de abajo.
• Flow-back: los cuatro artefactos (spec, plan, tasks y el código) se informan mutuamente y el equipo reconcilia a mano. Rápido, pero con riesgo real de divergencia silenciosa.

En cualquiera de los tres, el paso que cierra el bucle es /speckit.converge: le pides que compare el código con la spec, el plan y las tareas, y te añade como tareas nuevas lo que falte. Repites implement + converge hasta que la feature está completa de verdad.

Dicho esto, si tu caso de uso principal es evolucionar un proyecto existente, OpenSpec sigue estando más afinado gracias a su sistema de delta specs. Spec Kit ya puede hacerlo con soltura, pero el modelo de OpenSpec sigue siendo más natural para cambios incrementales sobre código que ya vive en producción.

OpenSpec en tu proyecto de verdad

Te quedas con OpenSpec para legacy: ahora llévalo a fondo

Acabas de ver que OpenSpec sigue siendo el más natural para código que ya existe. La guía a fondo te lleva justo ahí: el flujo completo explore→propose→apply→verify→archive, el esquema research para meter specs en legacy sin romperlo y cómo forkear tu propio flujo.

Ver el método a fondo →

Semáforo interactivo + prompt de arranque copiable · Web Reactiva Premium · 15€/mes

¿Cómo personalizar Spec Kit con extensiones y presets? ¶

Spec Kit se puede adaptar a cualquier equipo mediante dos sistemas complementarios: extensiones (que añaden funcionalidad nueva) y presets (que cambian cómo funciona lo existente). Es una de las adiciones más recientes al toolkit y una de las que más potencial tiene para equipos con requisitos específicos.

Con extensiones puedes añadir comandos al flujo de trabajo — integración con Jira, revisiones de código post-implementación, trazabilidad de tests según el modelo V. Con presets puedes cambiar las plantillas, la terminología y hasta el idioma de todo el sistema.

Hay un ejemplo que me encanta: un preset de “habla pirata” donde las especificaciones se llaman “Manifiestos de Viaje”, los planes son “Planes de Batalla” y las tareas son “Asignaciones de Tripulación”. Parece broma, pero demuestra que puedes personalizar cada aspecto del flujo sin tocar el código del toolkit.

# Buscar extensiones disponibles
specify extension search

# Instalar una extensión
specify extension add jira-integration

# Buscar presets
specify preset search

# Instalar un preset
specify preset add enterprise-compliance

La prioridad de resolución tiene cuatro niveles, no tres. Se ha formalizado uno nuevo arriba del todo — los overrides de proyecto — para cuando quieres tocar una plantilla en un solo repo sin montarte un preset entero:

Las plantillas se resuelven en tiempo de ejecución: Spec Kit recorre la pila de arriba abajo y usa la primera coincidencia. Los comandos de extensiones y presets, en cambio, se aplican en tiempo de instalación (se escriben en el directorio del agente cuando ejecutas extension add o preset add). Si no personalizas nada, Spec Kit usa sus valores por defecto.

La extensión bug: triaje en tres pasos ¶

Spec Kit trae extensiones incluidas que no se instalan solas. La más útil para el día a día es bug, que añade un flujo de triaje de bugs en tres pasos:

specify extension add bug

Cada bug vive en su propio directorio bajo .specify/bugs/<slug>/ con un informe en Markdown por etapa:

• /speckit.bug.assess — lee el reporte (texto pegado o una URL), juzga si es un bug real, localiza las rutas de código sospechosas y propone remediación → assessment.md
• /speckit.bug.fix — aplica la remediación y registra exactamente qué cambió → fix.md
• /speckit.bug.test — re-ejecuta la reproducción y los tests añadidos, y registra el resultado → test.md

Es el mismo principio del flujo principal aplicado a los bugs: el artefacto de cada etapa es el input de la siguiente, y queda por escrito.

🔁 Si vienes de una versión antigua, atención a agent-context. La actualización del fichero de contexto del agente (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md…) se extrajo a una extensión opt-in. specify init ya no la instala, así que si notas que ese bloque dejó de sincronizarse, es esto: specify extension add agent-context.

¿Qué son los workflows y los bundles? ¶

Estas dos primitivas no existían cuando escribí la primera versión del post, y son las que más cambian el techo de lo que puedes hacer con Spec Kit.

Workflows: automatizar el flujo completo ¶

Un workflow encadena comandos, prompts, pasos de shell y checkpoints humanos en un proceso repetible. No es una macro tonta: soporta lógica condicional, bucles y fan-out/fan-in, y puede pausarse y reanudarse desde el punto exacto de interrupción.

Los tipos de paso disponibles:

• command — invoca un comando de Spec Kit (speckit.plan, por ejemplo)
• prompt — manda un prompt arbitrario al agente
• shell — ejecuta un comando de shell y captura la salida
• gate — se para y espera aprobación humana
• init — arranca un proyecto
• if / switch — ramificación condicional y despacho multi-rama
• while / do-while — bucles
• fan-out / fan-in — reparte pasos sobre una lista y agrega los resultados

Cuando un workflow llega a un gate, se detiene y guarda el estado en .specify/workflows/runs/<run_id>/. Puedes volver días después y continuar exactamente donde lo dejaste:

# Lanzar un workflow
specify workflow run <source> -i clave=valor

# Ver en qué punto está
specify workflow status <run_id>

# Reanudar desde el paso pausado
specify workflow resume <run_id>

# Descubrir, instalar y gestionar
specify workflow search
specify workflow add <source>
specify workflow list

Aquí es donde el “mar de Markdown” del que se quejaba la crítica original empieza a tener respuesta: si el flujo entero está automatizado con checkpoints en los puntos que de verdad requieren criterio humano, dejas de teclear seis comandos y de vigilar cada artefacto a mano.

Bundles: un setup por rol, en un comando ¶

Extensiones y presets son piezas sueltas. Un bundle empaqueta un conjunto curado de extensiones, presets, steps y workflows en un setup versionado y orientado a un rol, para que puedas provisionar a una persona entera con una sola orden. El repo trae cuatro manifiestos de ejemplo listos para leer: product manager, business analyst, security researcher y developer.

# Descubrir bundles disponibles
specify bundle search

# Ver EXACTAMENTE qué componentes añadiría (es lo mismo que instala)
specify bundle info <bundle-id>

# Instalar el conjunto completo de una vez
specify bundle install <bundle-id>

# Gestionar lo instalado
specify bundle list
specify bundle update <bundle-id>
specify bundle remove <bundle-id>

Un bundle se describe con un manifiesto bundle.yml escrito a mano que fija la versión de cada componente. Si no declara integración, es agnóstico y hereda la que ya use el proyecto. Los bundles se resuelven desde una pila de catálogos con prioridad (proyecto > usuario > incluido), y las garantías están bien pensadas: info muestra exactamente lo que install añade, las instalaciones son idempotentes y confinadas a la raíz del proyecto, y remove nunca toca componentes que otro bundle instalado siga necesitando.

Si trabajas en un equipo donde el product manager, el de seguridad y los devs necesitan flujos distintos sobre el mismo repo, esto es lo que te ahorra la tarde de configuración manual.

¿Cuáles son las limitaciones de Spec Kit? ¶

Spec Kit no es perfecto y tiene críticas legítimas que deberías conocer antes de adoptarlo. Según un análisis publicado en el blog técnico de Scott Logic tras probar Spec Kit en un proyecto real, la experiencia fue “un mar de documentos Markdown, tiempos de ejecución largos del agente y fricción inesperada” (Scott Logic, Putting Spec Kit Through Its Paces, 2025). Birgitta Böckeler, en un artículo para martinfowler.com, señala que el workflow puede ser excesivo para problemas pequeños — como “usar una apisonadora para partir una nuez” (martinfowler.com, Exploring Gen AI: SDD 3 Tools).

El problema del “mar de Markdown”: un proyecto complejo puede terminar con decenas de archivos .md en la carpeta de specs. La constitución, las specs, el plan, los contratos, la investigación, las tareas… todo es Markdown. Para proyectos pequeños, la cantidad de documentación puede superar al código generado.

El “efecto waterfall”: algunos desarrolladores argumentan que Spec Kit se parece demasiado a un proceso waterfall disfrazado. Defines todo antes de escribir código, y si la realidad te obliga a cambiar algo a mitad de camino, tienes que retroceder y actualizar toda la cadena de documentos. Si esta crítica te resuena pero quieres seguir poniendo la spec en el centro, una alternativa interesante es SPDD (Structured Prompt-Driven Development), que mantiene un único prompt vivo sincronizado con el código en ambos sentidos en lugar de propagar cambios por cinco artefactos.

Es justo decir que esta crítica ha envejecido algo mejor que peor para Spec Kit: el modelo flow-back de la guía de persistencia acepta explícitamente que las ediciones empiecen en cualquier artefacto, y /speckit.converge existe precisamente para reconciliar código y spec sin volver al principio de la cadena. No es que la objeción desaparezca, pero ya no puedes decir que el proyecto la ignore.

El contexto se agota: los agentes de IA tienen un límite de contexto. Para proyectos grandes, la constitución + spec + plan + tareas puede superar ese límite, lo que degrada la calidad del código generado. La documentación de Spec Kit recomienda implementar en fases para evitarlo, pero es un problema real.

La calidad depende del agente: Spec Kit es agnóstico — funciona con más de 30 integraciones — pero la calidad del resultado varía. Lo que Claude Code genera a partir de la misma spec puede ser muy diferente de lo que produce Copilot o Gemini CLI. La estructura ayuda, pero no es magia. Como explica Dax Raad, la calidad del código base que genera el agente depende también de la calidad del código que ya existe.

💡 Mi recomendación: empieza con un proyecto pequeño, como el del paraguas. Haz el flujo completo una vez. Evalúa cuánto valor aporta la estructura frente al tiempo que inviertes en escribir las specs. Si el balance es positivo, escala a proyectos mayores.

Si prefieres una alternativa sin frameworks cerrados, el workflow de Matt Pocock aplica los mismos principios — alineamiento previo, PRD como documento de destino, subdivisión en tareas pequeñas — con skills que controlas tú desde el principio. Y si dudas entre Spec Kit, OpenSpec, BMAD, GSD o PAUL, esta comparativa de frameworks SDD los pone cara a cara.

¿Qué comandos tiene Spec Kit y cuándo usar cada uno? ¶

Spec Kit expone 10 comandos slash — 7 del flujo principal y 3 opcionales — que cubren desde la definición de principios hasta la verificación de que el código cumple lo que dice la spec. Eran 8 en la primera versión de este post; los dos nuevos van marcados.

Comandos del flujo principal:

• /speckit.constitution — Define o actualiza los principios del proyecto
• /speckit.specify — Describe qué quieres construir (sin stack técnico)
• /speckit.plan — Genera el plan técnico con tu stack elegido
• /speckit.tasks — Descompone el plan en tareas ejecutables
• /speckit.taskstoissues — (nuevo) Convierte la lista de tareas en issues de GitHub para seguimiento y ejecución
• /speckit.implement — Ejecuta las tareas y genera el código
• /speckit.converge — (nuevo) Evalúa el código contra spec, plan y tareas, y añade el trabajo pendiente como tareas nuevas

Comandos opcionales (pero muy útiles):

• /speckit.clarify — Resuelve ambigüedades antes de planificar
• /speckit.analyze — Verifica consistencia entre spec, plan y tareas
• /speckit.checklist — Genera checklists de calidad para las specs

El flujo recomendado: constitution → specify → clarify → plan → tasks → analyze → implement → converge. Puedes saltarte clarify y analyze, pero no lo recomiendo para proyectos que vayan más allá de un prototipo.

De los dos nuevos, el que de verdad cambia cosas es /speckit.converge. Es el comando que responde a la pregunta incómoda de todo flujo SDD: vale, el agente dice que ha terminado, pero ¿ha implementado lo que ponía en la spec? En lugar de fiarte, le pides que audite el código contra los tres artefactos y te devuelva las tareas que faltan. Si aparecen tareas nuevas, vuelves a implement y repites hasta que converge no encuentre nada.

💡 Recuerda que el prefijo depende de la integración. Si usas Codex CLI en modo skills serán $speckit-constitution, $speckit-specify y compañía. Si usas GitHub Copilot CLI, entras con /agents y seleccionas el agente. En la mayoría de los demás, /speckit.* tal cual.

¿Cuándo usar Spec Kit y cuándo no? ¶

Spec Kit es la opción más estructurada para equipos que quieren dejar atrás el vibe coding sin atarse a un IDE o agente concreto. Con el 92% de los desarrolladores en EE.UU. usando ya herramientas de IA a diario (Second Talent, Vibe Coding Statistics 2026), la pregunta no es si necesitas estructura, sino cuánta.

Spec Kit merece tu atención si:

• Estás arrancando un proyecto nuevo y quieres que la IA trabaje con estructura
• Tu equipo usa agentes de IA diferentes y necesitas consistencia
• Quieres que los tests, la seguridad y la arquitectura queden definidos antes de que nadie toque código
• Te interesa experimentar con SDD sin atarte a un IDE o agente concreto
• Necesitas provisionar a varios roles distintos sobre el mismo repo (ahí entran los bundles)

No es la mejor opción si:

• Tu proyecto ya existe y solo necesitas añadir features puntuales (mira OpenSpec)
• Estás haciendo un prototipo de 30 minutos donde la velocidad importa más que la estructura
• Tu agente de IA tiene un contexto muy limitado

El SDD en general — y Spec Kit en particular — no es una bala de plata. Conviene conocer los errores más comunes al hacer Spec-Driven Development antes de adoptarlo. Es una herramienta que te obliga a pensar antes de ejecutar. Y en un mundo donde la IA puede generar miles de líneas de código en segundos, pensar antes de ejecutar es más valioso que nunca. Una vez generado el código, herramientas como Expect verifican en un navegador real que lo que ha generado tu agente funciona de verdad.

¿Vas a probarlo? El comando es uno:

uv tool install specify-cli

A partir de ahí, la especificación manda.

Preguntas frecuentes ¶

¿Spec Kit es gratuito?
Sí. Es open source con licencia MIT. No tiene coste, no requiere cuenta y no envía datos a ningún servidor.

¿Necesito saber Python para usarlo?
No. Python es solo un requisito para instalar la CLI specify. Todo el trabajo se hace a través de tu agente de IA con comandos slash.

¿Puedo usar Spec Kit con Cursor?
Sí. Usa specify init mi-proyecto --integration cursor-agent. Ojo: el flag --ai de versiones antiguas ya no existe, ahora es --integration.

¿Spec Kit funciona en Windows?
Sí. Desde las primeras versiones incluye scripts tanto en Bash como en PowerShell. El CLI detecta tu sistema operativo y elige el adecuado. También puedes forzarlo con specify init mi-proyecto --integration copilot --script ps.

¿Cómo actualizo Spec Kit?
Con specify self check compruebas si hay versión nueva sin tocar nada, y con specify self upgrade actualizas en el sitio (detecta si instalaste con uv tool o con pipx). Añade --dry-run para ver qué haría antes de ejecutarlo, o --tag v0.16.1 para fijar una versión concreta.

¿Puedo combinar Spec Kit con OpenSpec?
No hay integración directa, pero nada impide usar Spec Kit para proyectos nuevos y OpenSpec para evolucionar proyectos existentes. Son complementarios.

¿Qué pasa si cambio de agente de IA a mitad del proyecto?
Las specs, planes y tareas son archivos Markdown en tu repo. Son independientes del agente. Solo necesitas reinicializar con specify init --here --integration nuevo-agente, o usar directamente specify integration switch.

¿Spec Kit genera tests automáticos?
Sí, si tu constitución y plan lo exigen. Las plantillas fuerzan el enfoque test-first: el agente escribe los tests antes de la implementación.

¿Cuántos agentes soporta Spec Kit?
Más de 30 integraciones, incluyendo Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex CLI, OpenCode, Cline, Antigravity, Amp, Kilo Code, Kimi Code, Qwen Code, Grok Build, Factory Droid, Devin, Hermes, Zed y más. Ejecuta specify integration list para ver las de tu versión. También soporta un modo genérico para agentes no listados.

¿Dónde se guardan las specs?
En specs/ en la raíz del repositorio, una carpeta por feature (specs/001-mi-feature/). Dentro de .specify/ viven la constitución, las plantillas, los scripts y las extensiones, pero no las especificaciones.

¿Qué son los workflows de Spec Kit?
Automatizaciones que encadenan comandos, prompts, pasos de shell y checkpoints humanos en un proceso repetible, con condicionales, bucles y fan-out/fan-in. Se pausan en los pasos gate y se reanudan desde el punto exacto con specify workflow resume <run_id>.

¿Y los bundles?
Paquetes que agrupan extensiones, presets, steps y workflows en un setup versionado por rol (product manager, business analyst, security researcher, developer), instalable de una vez con specify bundle install.

¿Puedo usar Spec Kit para proyectos en cualquier lenguaje?
Sí. La especificación es independiente del lenguaje. En la fase de /speckit.plan es donde eliges el stack técnico: puede ser JavaScript, Python, Go, .NET, Java o cualquier otro.

¿Hay riesgo de que las specs queden desactualizadas?
Menos que con documentación tradicional, porque las specs generan el código. Pero si modificas el código a mano sin actualizar la spec, se desincronizarán. La disciplina de “spec primero” es clave.

Fuentes ¶

• Repositorio oficial de Spec Kit en GitHub
• Metodología Spec-Driven Development completa
• Anuncio oficial en el blog de GitHub
• Guía en el blog de Microsoft para desarrolladores
• Integraciones soportadas — referencia oficial
• Workflows — referencia oficial
• Bundles — guía de la comunidad
• Evolving Specs — la guía brownfield oficial
• Modelos de persistencia de specs
• Extensión bug — triaje en tres pasos
• API de Open-Meteo — documentación oficial
• Guía de Spec Driven Development con OpenSpec en Web Reactiva
• Second Talent — Vibe Coding Statistics 2026
• Awesome Agents — Vibe Coding Security Report
• Towards Data Science — The Reality of Vibe Coding, 2026
• Scott Logic — Putting Spec Kit Through Its Paces, 2025
• martinfowler.com — Exploring Gen AI: SDD 3 Tools
• Ry Walker Research — GitHub Spec Kit

🧨 Última oportunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter