Spec-driven development con Claude Code: ejemplo paso a paso
Una feature pequeña, de la idea al código con Spec Kit y Claude Code: spec, plan, tareas, implementación y qué hacer si el agente se desvía.
Spec-driven development con Claude Code consiste en escribir primero qué tiene que hacer la feature, dejar que el agente te pregunte lo que hayas dejado ambiguo y solo entonces planificar, desglosar en tareas y programar. Este tutorial en español recorre el proceso con GitHub Spec Kit y un ejemplo pequeño: etiquetas en una lista de tareas.
Necesitas saber qué es un repositorio de git y haber pedido alguna vez a un asistente que te escriba una función. La definición completa está en qué es spec-driven development y la comparativa de herramientas en OpenSpec vs Spec Kit vs BMAD; aquí no las repetimos.
Una advertencia de honestidad: los comandos, ficheros y carpetas son los reales, comprobados leyendo la documentación y las plantillas del repositorio oficial[1], pero no los hemos ejecutado. La feature, la spec, el plan y las tareas son un escenario ilustrativo construido a partir de esas plantillas; el texto que genere tu agente será distinto, aunque la forma del proceso se repite.
Tutorial de Spec Kit con Claude Code: de la idea al código
Primero, preparar el proyecto.
Spec Kit es una CLI (specify) más un conjunto de comandos que, tras specify init, quedan disponibles en tu agente de código. Un agente, como Claude Code, es un programa que lee tus ficheros y escribe cambios por su cuenta; de aquí en adelante, “el agente”.
Necesitas Python 3.11 o superior y uv, un instalador de herramientas de Python[1]:
uv tool install specify-cli
specify init mis-tareas --integration claude
cd mis-tareas
claude
La opción --integration claude hace que los comandos se instalen como skills de Claude Code, en .claude/skills/speckit-<comando>/SKILL.md[2]. Una skill es un fichero de instrucciones que el agente carga cuando lo invocas. La documentación escribe los comandos con punto (/speckit.specify), pero en Claude Code se invocan con guion, /speckit-specify[2][3].
Esos comandos se escriben en el chat de Claude Code, no en la terminal, y se lanzan de uno en uno, revisando el resultado antes de pasar al siguiente[9]. Esa pausa es lo que te deja corregir antes de que el agente acumule decisiones por ti.
La constitución: reglas que valen para todas las features
Se ejecuta una vez por proyecto y fija los principios contra los que se evalúa todo lo demás:
/speckit-constitution Código simple y legible. Cada comportamiento nuevo lleva un test. Sin dependencias nuevas si la librería estándar basta.
El resultado se guarda en .specify/memory/constitution.md[4]. Lo que pongas aquí se aplica a todas las features futuras, así que conviene que sea breve.
La spec y la pregunta que no se te había ocurrido
Ahora la feature, en lenguaje natural, centrada en el qué y sin tecnología[3]:
/speckit-specify Quiero poder poner etiquetas a las tareas ("casa", "trabajo") y filtrar la lista por etiqueta.
Spec Kit crea una carpeta numerada dentro de specs/ y escribe ahí spec.md[5], con historias de usuario priorizadas, escenarios Given/When/Then y requisitos numerados (FR-001…)[6]. Un extracto ilustrativo:
### User Story 1 - Etiquetar una tarea (Priority: P1)
**Acceptance Scenarios**:
1. **Given** una tarea sin etiquetas, **When** añado "casa",
**Then** la tarea muestra la etiqueta "casa".
2. **Given** una tarea con la etiqueta "casa", **When** añado "Casa",
**Then** [NEEDS CLARIFICATION: ¿es la misma etiqueta o una distinta?]
- **FR-003**: El usuario MUST poder filtrar la lista por una etiqueta.
- **FR-004**: [NEEDS CLARIFICATION: con dos etiquetas seleccionadas,
¿se muestran las tareas que tienen ambas o cualquiera de las dos?]
Mira el segundo escenario: no habías pensado en mayúsculas. Si le pides el código directamente, el agente decide por su cuenta, y lo más probable es que compare cadenas tal cual: “Casa” y “casa” serían dos etiquetas y el filtro tendría duplicados raros que solo descubrirías con la app ya en uso.
Aquí no puede decidir en silencio: la plantilla del comando marca como [NEEDS CLARIFICATION] las decisiones que cambian el alcance o la experiencia, con un máximo de tres marcadores, y te pide las respuestas antes de seguir[5]. Ese es el momento que justifica el método: responder una pregunta ahora cuesta casi nada, y descubrir la misma decisión con el código hecho obliga a rehacerlo.
Respondes: misma etiqueta sin distinguir mayúsculas ni espacios, y el filtro múltiple muestra las tareas que las tienen todas. Los criterios quedan verificables:
- **FR-002**: "Casa", "casa" y " casa " MUST ser la misma etiqueta;
se muestra con la grafía con la que se creó la primera vez.
- **FR-004**: Filtrar por varias etiquetas MUST mostrar solo las tareas
que tienen todas las seleccionadas.
Si quieres afinar más, /speckit-clarify hace hasta cinco preguntas sobre lo que siga flojo y las vuelca en spec.md[3]. Antes de seguir, lee la spec entera con calma: corregirla ahora es mucho más barato que corregir plan, tareas y código que cuelgan de ella.
El plan: aquí sí entra la tecnología
Con la spec cerrada se decide el cómo; aquí, y solo aquí, nombras el stack[3]:
/speckit-plan La app es TypeScript con React y guarda los datos en localStorage. Los tests con Vitest.
Se genera plan.md en la misma carpeta, con un contexto técnico (lenguaje, dependencias, almacenamiento, testing) y una comprobación contra la constitución[7]. Revísalo con una pregunta concreta: ¿contradice algo de la spec? Por ejemplo, que el plan guarde las etiquetas como un string[] sin normalizar chocaría directamente con FR-002.
La plantilla prevé también ficheros auxiliares (research.md, data-model.md, contracts/…); en una feature tan pequeña es normal que sobren varios.
Las tareas y la última revisión antes de programar
/speckit-tasks
Genera tasks.md, ordenado por dependencias, con un identificador y la ruta del fichero en cada tarea[8]:
- [ ] T001 Crear tipo Tag y función normalizeTag en src/lib/tags.ts
- [ ] T002 [P] [US1] Test: "Casa" y " casa " son la misma etiqueta en src/lib/tags.test.ts
- [ ] T003 [US1] Añadir etiquetas a la tarea en src/lib/tasks.ts
- [ ] T004 [US1] Filtrar por varias etiquetas con semántica "todas" en src/lib/filter.ts
[P] marca una tarea paralelizable[8]. Fíjate en que T002 sale directamente del escenario ambiguo: la pregunta que respondiste ya es un test.
Antes de implementar queda una puerta opcional, /speckit-analyze: de solo lectura, cruza spec, plan y tareas y señala conflictos y huecos[3]. Si encuentra algo, arréglalo en el paso que lo originó y regenera lo que cuelga de él.
Implementar, converger y qué hacer cuando el agente se desvía
/speckit-implement
Ejecuta las tareas en orden de dependencia[3]. Tu papel es comprobar que lo que sale cumple los escenarios de aceptación: corre los tests y prueba a mano “Casa” contra “casa”.
Supongamos que el agente normaliza al guardar pero no al filtrar, y el filtro por “casa” no encuentra las tareas guardadas como “Casa”. Nos pasa que la primera reacción es pedirle por el chat “arregla el filtro” y seguir, pero así la corrección solo vive en esa conversación. Mejor mirar dónde está el fallo:
- Si la spec ya decía lo correcto (aquí sí:
FR-002), el fallo es de implementación. Apunta al requisito y comprueba queT002o un test nuevo lo cubre. - Si la spec no lo decía, el fallo es tuyo y se corrige primero en
spec.md, después en el plan o las tareas si cambian, y solo entonces se vuelve a implementar.
Para saber si queda algo sin cubrir está /speckit-converge, que compara el código con la spec, el plan y las tareas y solo puede añadir tareas nuevas a tasks.md. Si no hay huecos responde Converged; si los hay, vuelves a ejecutar /speckit-implement y repites hasta que converja[3].
| Comando | Qué escribe | Cuándo lo usas |
|---|---|---|
/speckit-constitution | .specify/memory/constitution.md | Una vez por proyecto |
/speckit-specify | spec.md en la carpeta de la feature | Al empezar cada feature |
/speckit-clarify | Respuestas dentro de spec.md | Opcional, si la spec sigue floja |
/speckit-plan | plan.md (y auxiliares) | Cuando la spec está cerrada |
/speckit-tasks | tasks.md | Cuando el plan te convence |
/speckit-analyze | Nada (solo informa) | Antes de implementar, si hay riesgo |
/speckit-implement | El código de las tareas | Tras revisar spec, plan y tareas |
/speckit-converge | Tareas nuevas en tasks.md | Después de implementar, hasta Converged |
Cuándo spec-driven development no compensa
Para corregir una errata, renombrar una variable o montar un prototipo que vas a tirar, la spec cuesta más que el cambio: se pide directamente y se revisa en el diff.
Una regla útil: si no puedes imaginar una pregunta ambigua que el agente tendría que responder por ti, no necesitas spec. Las etiquetas la necesitaban porque escondían decisiones de producto (mayúsculas y filtro combinado, para empezar) que nadie había tomado todavía. Y si el proceso entero te parece mucha ceremonia, existe la versión corta: specify, plan, tasks, implement y converge, sin las puertas opcionales[9]. La completa, para lo que vaya a producción.
Fuentes
- Spec Kit: README oficial, GitHub: requisitos e instalación con
uv. - Spec Kit: Claude Code, documentación oficial:
--integration claudey la ruta de las skills. - Spec Kit: referencia de Agentic SDD, GitHub: qué hace cada comando.
- Spec Kit: plantilla del comando constitution, GitHub: ruta de la constitución.
- Spec Kit: plantilla del comando specify, GitHub: carpeta
specs/y límite de tres marcadores. - Spec Kit: plantilla de spec, GitHub: historias, escenarios y requisitos
FR-###. - Spec Kit: plantilla de plan, GitHub: contexto técnico y ficheros auxiliares.
- Spec Kit: plantilla de tareas, GitHub: identificadores y marca
[P]. - Spec Kit: guía de inicio rápido de SDD, GitHub: caminos corto y completo, y el orden de los comandos.
Preguntas Frecuentes
¿Necesito Spec Kit para hacer spec-driven development con Claude Code?
No. Puedes escribir un spec.md a mano y pedirle a Claude Code que lo lea antes de programar; Spec Kit automatiza el flujo y aporta plantillas. Para elegir, está la comparativa de OpenSpec, Spec Kit y BMAD.
¿Hace falta pasar por todos los comandos en una feature pequeña?
No. La documentación propone un camino corto para features pequeñas y uno completo para producción, y los pasos extra solo compensan cuando la feature esconde decisiones sin tomar.
¿Por qué /speckit-specify en Claude Code y /speckit.specify en la documentación?
Es el mismo comando: la documentación usa punto como notación general y Claude Code lo instala como skill con guion. Si no aparece, mira el nombre de la carpeta en .claude/skills/.
¿Hay un tutorial de GitHub Spec Kit en español con un ejemplo completo?
Este mismo post: recorre la constitución, la spec, el plan, las tareas y la implementación con un ejemplo pequeño, y avisa de qué partes son ilustrativas. Para la referencia exacta de cada comando, la fuente es la documentación oficial.
¿Qué hago si el agente ignora la spec?
Comprueba primero que la spec dice lo que crees. Si estaba clara, señala el requisito concreto (FR-002) y pide un test que falle antes de arreglarlo; si no lo cubría, corrígela y regenera plan y tareas.
¿Spec-driven development sustituye a los tests?
No: la spec dice qué tiene que pasar y los tests comprueban que pasa, como el escenario de “Casa” contra “casa” que se convierte en la tarea T002; la diferencia entre ambos enfoques la explica la guía de spec-driven development.
Si quieres aprender a dirigir agentes con este mismo criterio, de la spec a la verificación, lo trabajamos paso a paso en el curso de patrones agénticos.