Spec-Kit: la guía para dejar de vibe-codear a ciegas

Tu IA programa genial el primer día. A las dos semanas se vuelve tonta: pierde el hilo, rehace código que ya existía, contradice lo que ella misma escribió. No es que el modelo haya empeorado. Es que nunca le diste una especificación — vas picando código a ciegas y esperas que ella adivine el resto.

Spec-Kit es el toolkit open-source de GitHub para arreglar justo eso. Antes de tocar una línea de código, escribes qué quieres construir y por qué. Sin hablar de stack todavía. La IA convierte eso en un plan técnico, luego en tareas, y solo entonces implementa. Lo anunció GitHub en septiembre y superó las 16.000 estrellas en la primera semana — lleva desde entonces con tracción sostenida.

El flujo completo

Spec-Kit son 7 fases, cada una con su comando slash. No te saltas ninguna a la primera:

Fase	Comando	Qué haces
Constitución	`/speckit.constitution`	Defines los principios fijos del proyecto (qué NO va a cambiar)
Especificación	`/speckit.specify`	Qué quieres construir y por qué. Cero stack.
Clarificación	(preguntas de la IA)	La IA te pregunta lo ambiguo antes de seguir
Plan	`/speckit.plan`	Cómo se construye: stack, arquitectura, decisiones técnicas
Análisis	(revisión cruzada)	Comprueba que plan y especificación no se contradicen
Tareas	`/speckit.tasks`	Rompe el plan en tareas concretas y ordenadas
Implementación	`/speckit.implement`	Aquí, y solo aquí, se escribe código

La clave está en el orden: especificación antes que plan, plan antes que tareas, tareas antes que código. Cada fase se apoya en la anterior. Si saltas directo a implementar, estás otra vez vibe-codeando — solo que ahora con más pasos por delante.

Constitución: los principios que no cambian

/speckit.constitution es el primer comando, y se corre una sola vez por proyecto (o cada vez que cambien las reglas del juego). Aquí fijas cosas como “siempre TDD”, “nunca tocar la carpeta de pagos sin confirmación”, “el stack es X y no se negocia”. Es el documento que la IA respeta en cada fase siguiente.

Especificación: qué y por qué, nunca cómo

/speckit.specify es donde describes la funcionalidad: qué problema resuelve, quién la usa, qué comportamiento espera el usuario. Ni una palabra de framework, librería o base de datos. Si te pillas escribiendo “usando React” en la especificación, te has adelantado de fase.

La IA te lanza preguntas de clarificación antes de dar la especificación por cerrada — ambigüedades que si no resuelves ahora, las vas a arrastrar hasta el código.

Plan: ahora sí, el cómo

/speckit.plan coge la especificación ya cerrada y decide el stack, la arquitectura, las dependencias. Aquí es donde entra React, Postgres, o lo que uses. Antes de generar tareas, hay una fase de análisis que cruza plan contra especificación para pillar contradicciones antes de que lleguen al código.

Tareas e implementación

/speckit.tasks trocea el plan en una lista de tareas ejecutables, ordenadas y con dependencias claras entre ellas. /speckit.implement las va resolviendo una a una. Este es el único momento del flujo en el que se escribe código de verdad.

Instalación

Spec-Kit se instala como CLI vía uv:

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

Y arrancas un proyecto nuevo con:

specify init <nombre-proyecto> --integration claude

El flag --integration le dice a Specify con qué agente vas a trabajar. Funciona con Claude Code, GitHub Copilot, Gemini CLI, Codex y más de 30 agentes distintos — no está atado a ninguno. specify init te genera la carpeta con la estructura y los comandos slash ya listos para usar dentro de tu agente.

Si ya tienes un proyecto en marcha y solo quieres añadir Spec-Kit encima, puedes correr specify init en el directorio actual en vez de crear uno nuevo — revisa las opciones con specify init --help.

Cuándo merece la pena

No hace falta para un script de 20 líneas. Merece la pena en cuanto el proyecto tiene más de una feature en marcha, más de una persona tocando el código (tú incluido, en distintos días), o cuando llevas dos semanas notando que tu IA “ya no se entera”. Ese síntoma es exactamente el que Spec-Kit ataca: le da a la IA un documento de referencia en vez de dejar que improvise sobre la marcha.

La regla de oro

Si tu IA se pierde cuando el proyecto crece, el problema no es el modelo: es que nunca le diste un mapa. Escribe la especificación antes que el código, y deja de vibe-codear a ciegas.

Repo oficial → github.com/github/spec-kit

Sígueme para más trucos con Claude Code e IA → @pabloinpublic

Únete a la comunidad → pabloinpublic.com