01 Qué es Spec Kit y qué problema resuelve
Cuando le pides a un agente de código «hazme una app de reservas», tiene que adivinar decenas de decisiones: quién se registra, qué pasa si se cancela una cita, qué base de datos usar. Si adivina mal, lo descubres tarde y con mucho código ya escrito. Spec Kit es un kit de código abierto (licencia MIT) mantenido por GitHub que cambia el orden: primero se escribe una especificación en Markdown, después un plan técnico, luego una lista de tareas y, por último, la implementación.
Todo queda como archivos dentro de tu repositorio, así que se revisa en un pull request, se comparte con el equipo y sobrevive a que cierres la conversación. Funciona con Claude Code y con muchos otros agentes (Copilot, Gemini CLI, Codex, Cursor…), por lo que no te ata a una herramienta.
Constitución
Los principios del proyecto: calidad, tests, rendimiento, restricciones. Se define una vez y todo lo demás se evalúa contra ella.
Especificación
Qué hay que construir y para quién, en lenguaje de negocio. Sin hablar todavía de frameworks.
Plan
El cómo: stack, modelo de datos, APIs y decisiones de arquitectura.
Tareas
El plan troceado en pasos pequeños, ordenados por dependencias, que el agente va completando.
02 Instalación paso a paso
- ✓Python 3.11 o superior (compruébalo con python3 --version).
- ✓uv, el gestor de paquetes de Python que recomienda el proyecto.
- ✓Claude Code funcionando en tu terminal o en la app de escritorio.
- ✓Git, solo si vas a activar la extensión de ramas por funcionalidad.
-
1
Instala uv si no lo tienes
En macOS y Linux basta con el instalador oficial de una línea (abajo). En Windows, uv tiene su propio instalador para PowerShell en su documentación.
-
2
Instala la CLI specify
Se publica en PyPI como specify-cli. Con uv queda instalada de forma global y disponible en cualquier carpeta.
-
3
Comprueba la instalación
Ejecuta specify version. Si la terminal no encuentra el comando, cierra y vuelve a abrirla para que recargue el PATH.
-
4
Crea el proyecto con la integración de Claude
specify init con --integration claude genera la carpeta .specify/ y copia las skills de Spec Kit en .claude/skills.
-
5
Abre Claude Code dentro del proyecto
Escribe /speckit en el chat y deberían aparecer las skills: speckit-constitution, speckit-specify, speckit-plan, etc.
# 1. uv (si no lo tienes)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. CLI de Spec Kit
uv tool install specify-cli
specify version
# 3. Proyecto nuevo preparado para Claude Code
specify init mi-proyecto --integration claude
cd mi-proyecto
claude03 El flujo de trabajo, comando a comando
Las órdenes no se ejecutan en la terminal, sino en el chat de Claude Code. Lanza una, lee lo que ha generado, corrige si hace falta y pasa a la siguiente. La constitución se hace una vez por proyecto; el resto se repite para cada funcionalidad.
| Skill | Para qué sirve | ¿Obligatoria? |
|---|---|---|
| /speckit-constitution | Fija los principios del proyecto | Una vez por proyecto |
| /speckit-specify | Escribe la especificación de la funcionalidad | Sí |
| /speckit-clarify | Te hace hasta cinco preguntas sobre lo que quedó ambiguo y anota tus respuestas en la spec | Recomendable |
| /speckit-plan | Genera el plan técnico a partir del stack que le indiques | Sí |
| /speckit-checklist | Crea una lista de control para revisar la calidad de los requisitos | Opcional |
| /speckit-tasks | Divide el plan en tareas ordenadas por fases | Sí |
| /speckit-analyze | Revisa, sin modificar nada, que spec, plan y tareas sean coherentes | Opcional |
| /speckit-implement | Ejecuta las tareas y escribe el código | Sí |
| /speckit-converge | Compara lo construido con los documentos y añade tareas pendientes | Sí, hasta que diga Converged |
04 Prompts listos para cada fase
/speckit-constitution Este proyecto es la web de reservas de una clínica. Principios: accesibilidad AA en todas las pantallas, tests automáticos para cualquier lógica de negocio, ningún dato personal en los logs, cumplimiento del RGPD, dependencias mínimas y código legible por un desarrollador junior. Si una decisión choca con estos principios, debe señalarse en el plan./speckit-specify Los pacientes deben poder reservar una cita eligiendo profesional, servicio y hueco libre. Reciben confirmación por correo y pueden cancelar hasta 24 horas antes. Recepción ve la agenda del día, puede mover citas y marcar ausencias. No hace falta pago online en esta versión. Describe usuarios, historias, casos límite y criterios de aceptación; no menciones tecnologías./speckit-plan Usa Laravel con MySQL y Blade, sin frameworks de JavaScript pesados. El correo se envía con la cola de Laravel. Las horas se guardan en UTC y se muestran en Europe/Madrid. Indica el modelo de datos, las rutas, cómo se evitan reservas dobles y qué tests cubren cada historia./speckit-implement Empieza solo por las fases de preparación y fundamentos. Al terminar cada fase, ejecuta los tests, marca las tareas completadas en tasks.md y para para que lo revise antes de continuar con la primera historia de usuario.05 Errores habituales y cómo evitarlos
Meter tecnología en la spec
La especificación habla del qué y el porqué. Si escribes «con React y Firebase», mezclas decisiones y luego cuesta cambiarlas. Guárdalo para /speckit-plan.
Encadenar fases sin leer
El valor está en revisar cada documento. Si apruebas todo sin mirar, obtienes lo mismo que pidiendo el código directamente, pero más lento.
Una constitución inventada
Pon reglas que de verdad se cumplen o que el equipo ha acordado. Normas irreales solo generan avisos que acabarás ignorando.
Funcionalidades enormes
«Toda la plataforma» no es una funcionalidad. Divide en piezas que se puedan revisar en un único pull request.
Dar por buena la checklist
Las listas de /speckit-checklist son para que tú revises los requisitos. Una casilla marcada no significa que el código esté hecho.
06 Cuándo compensa y cuándo no
El modo plan de Claude Code ya hace que el agente piense antes de escribir, pero ese plan vive en la conversación. Spec Kit compensa cuando necesitas documentos persistentes que se versionan con el código, varias personas (o varios agentes) trabajando sobre las mismas reglas, o un rastro de por qué se tomó cada decisión, algo muy útil en proyectos para clientes.
Para un script de una tarde o un prototipo desechable es excesivo: el modo plan y un buen prompt bastan. Además del flujo de especificaciones, el kit trae extensiones opcionales para corregir errores (specify extension add bug) y para evaluar ideas antes de construirlas (specify extension add assess).
Preguntas frecuentes
No. Es código abierto con licencia MIT. Lo único que pagas es el uso del agente que elijas, en este caso tu plan de Claude o tu consumo de API.
Sí. Funciona en Linux, macOS y Windows; en Windows usa scripts de PowerShell y no necesita WSL. Instala uv con su instalador para Windows y el resto de comandos son iguales.
Sí. Las skills generan los documentos a partir de lo que tú describes, y Claude responde en el idioma en el que le escribes. Mantén un mismo idioma en todo el proyecto para que los documentos sean coherentes.
Ejecuta specify self check para saber si hay versión nueva; es de solo lectura. Después sigue la guía de actualización de la documentación oficial, que explica cómo actualizar la CLI y los archivos del proyecto.
Los documentos de .specify/ y de cada funcionalidad son Markdown normal. Puedes inicializar otra integración en el mismo repositorio y seguir trabajando con los mismos artefactos.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.