GitHub Spec Kit con Claude Code: specs que el agente cumple
GitHub Spec Kit con Claude Code: user stories P1/P2/P3, Given/When/Then, [NEEDS CLARIFICATION] y analyze para que el agente no contradiga tu especificación.

La spec decía 200 caracteres. El código dice 500.
En septiembre de 2026, un developer abrió el issue #4383 en el repo de Spec Kit. Había hecho todo bien: constitution, specify, plan, tasks, implement, usando GitHub Spec Kit con Claude Code. El PRD fijaba en 200 la longitud máxima de dos campos. spec.md lo decía. data-model.md también: SuspendReason nvarchar(200).
Y Claude implementó SuspendReasonMaxLength = 500.
Nadie le había dado mal la regla al agente. La regla se había perdido por el camino: tasks.md mencionaba el límite de un campo y no el del otro. Para el campo sin límite, el agente puso uno por su cuenta.
En corto: GitHub Spec Kit no impide que Claude Code contradiga tu spec, pero hace visible dónde se rompe el hilo. Su plantilla te obliga a escribir historias priorizadas que se prueban por separado, escenarios Given/When/Then, requisitos numerados y criterios medibles. Sus comandos clarify, checklist, analyze y converge detectan las contradicciones antes de implementar y después.
¿Qué es GitHub Spec Kit?
GitHub Spec Kit es un toolkit open source de GitHub que instala en tu agente de código (Claude Code, Copilot, Codex y otros) un proceso de Spec-Driven Development con plantillas y comandos que van de la especificación al plan, las tareas, el código y la verificación.
No es un modelo ni un servicio. Es un CLI en Python (specify) que copia plantillas Markdown y skills a tu proyecto. Todo lo demás lo hace el agente siguiendo esas instrucciones.
Va rápido. La última release cuando escribo esto es la v1.3.2, del 6 de noviembre de 2026, y el repo pasa de 148.000 estrellas (dato de la API de GitHub, 7 de noviembre de 2026).
Los tres errores que hacen que el agente contradiga la spec
Un agente contradice una spec por tres motivos que el formato de Spec Kit ataca de frente: la ambigüedad, la falta de slices verticales y los criterios de aceptación débiles.
El resto de fallos lo tienes en los siete fallos de una spec que rompen a un agente de IA, y lo de los slices, en el post sobre spec global y slices verticales en un proyecto greenfield.
La tesis es simple: un agente no contradice una spec por rebeldía. La contradice cuando la spec deja un hueco y él lo rellena. Spec Kit no hace al agente más obediente. Te deja menos huecos que rellenar.
Cómo instalar GitHub Spec Kit en Claude Code
Necesitas Python 3.11+, uv y Claude Code instalado. La página de la integración con Claude da la clave claude:
uv tool install specify-cli
specify init mi-proyecto --integration claude
cd mi-proyecto
En un proyecto que ya existe, la guía de proyectos existentes indica specify init --here --force --integration claude. Haz commit antes: --force puede sobrescribir archivos en las rutas que gestiona Spec Kit.
Spec Kit instala sus comandos como skills en .claude/skills/speckit-<comando>/SKILL.md. En el chat de Claude Code se invocan con guion:
/speckit-constitution Prioriza la exactitud fiscal y los tests de integración.
/speckit-specify Exportación trimestral de facturas para la gestoría.
/speckit-clarify
/speckit-plan Next.js, Postgres y generación del CSV en el servidor.
/speckit-checklist
/speckit-tasks
/speckit-analyze
/speckit-implement
/speckit-converge
Si ves /speckit.specify con punto en la documentación, es la notación genérica: en Claude Code va con guion.
El formato de spec de Spec Kit, sección a sección
La plantilla spec-template.md tiene tres secciones obligatorias (User Scenarios & Testing, Requirements y Success Criteria), una condicional (Key Entities, si la feature maneja datos) y una sección final de Assumptions. Así se mapea cada error a un mecanismo concreto:
| Error en la spec | Mecanismo de Spec Kit | Qué lo detecta |
|---|---|---|
| Ambigüedad | Marcadores [NEEDS CLARIFICATION: …] (máximo 3 por spec) y sección Assumptions |
/speckit-clarify: hasta 5 preguntas y las respuestas se escriben en spec.md |
| Sin slices verticales | User stories con prioridad (P1, P2, P3) y un Independent Test cada una |
/speckit-tasks agrupa las tareas por historia |
| Criterios débiles | Escenarios Given/When/Then y Success Criteria medibles (SC-001…) |
/speckit-checklist, "unit tests for English" |
| Spec, plan y tareas que no cuadran | Requisitos numerados FR-001… para trazar cada uno |
/speckit-analyze, de solo lectura |
| Código que no cumple la spec | spec.md, plan.md y tasks.md como referencia |
/speckit-converge añade tareas por lo que falta |
| Principios del proyecto ignorados | .specify/memory/constitution.md |
/speckit-analyze marca cualquier conflicto con la constitución como CRITICAL |
Fuente: plantillas y comandos en templates/commands/, consultados el 7 de noviembre de 2026.
La plantilla exige que cada historia sea "INDEPENDENTLY TESTABLE": si implementas solo una, sigues teniendo un MVP viable. Es un slice vertical con otro nombre.
Ejemplo: de spec mala a spec en formato Spec Kit
Caso: un SaaS de facturación para autónomos. Los usuarios quieren mandar sus facturas a la gestoría cada trimestre sin descargarlas una a una.
La spec que suele llegar al agente:
# Exportación para la gestoría
Añadir exportación de facturas para la gestoría.
Tiene que ser rápida y fácil de usar.
Formato CSV o Excel.
Opción de enviarlo por email automáticamente.
Gestionar bien los errores.
Cada línea es un hueco. "Rápida" no se puede medir. "CSV o Excel" deja la decisión al agente. "Gestionar bien los errores" no dice qué es un error. Y no hay orden: el agente puede empezar por el envío automático, la parte más difícil, sin que exista la exportación básica.
La misma spec en el formato de Spec Kit:
# Feature Specification: Exportación trimestral para la gestoría
**Status**: Draft
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Descargar el CSV del trimestre (Priority: P1)
El autónomo elige un trimestre y descarga un CSV con todas sus
facturas emitidas en ese periodo.
**Why this priority**: sin esto no hay nada que enviar. Es el
mínimo que ya ahorra el trabajo manual.
**Independent Test**: con 3 facturas en el T2 y 1 en el T3,
exportar el T2 devuelve un CSV con exactamente 3 filas.
**Acceptance Scenarios**:
1. **Given** un usuario con 3 facturas emitidas en el T2 de 2026,
**When** exporta el T2 de 2026, **Then** descarga un CSV con
3 filas y las columnas número, fecha, NIF del cliente, base
imponible, tipo de IVA, cuota de IVA y total.
2. **Given** una factura rectificativa en el T2, **When** exporta
el T2, **Then** la rectificativa aparece con importes negativos.
3. **Given** un trimestre sin facturas, **When** lo exporta,
**Then** ve el mensaje "No hay facturas en este trimestre"
y no se descarga ningún archivo.
---
### User Story 2 - Enviar el CSV al email de la gestoría (Priority: P2)
El autónomo guarda el email de su gestoría y envía el CSV del
trimestre con un botón.
**Why this priority**: elimina el paso de adjuntar el archivo,
pero depende de que la US1 funcione.
**Independent Test**: con un email de gestoría guardado, pulsar
"Enviar" genera un único email con el CSV del trimestre adjunto.
**Acceptance Scenarios**:
1. **Given** un email de gestoría guardado, **When** pulsa
"Enviar T2", **Then** se envía un email con el CSV adjunto
y el envío queda registrado con fecha y destinatario.
2. **Given** que el T2 ya se envió, **When** pulsa "Enviar T2"
otra vez, **Then** se le pide confirmación antes de reenviar.
---
### User Story 3 - Envío automático al cerrar el trimestre (Priority: P3)
[...]
### Edge Cases
- ¿Qué pasa con una factura con fecha del último día del trimestre
a las 23:59 en otra zona horaria?
- ¿Qué pasa si el email de la gestoría rebota?
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST incluir solo facturas emitidas, nunca
borradores.
- **FR-002**: System MUST asignar el trimestre por la fecha de
emisión, no por la fecha de cobro.
- **FR-003**: System MUST usar [NEEDS CLARIFICATION: ¿separador
decimal coma o punto? Depende del programa de la gestoría].
- **FR-004**: System MUST NOT modificar ninguna factura al exportar.
### Key Entities
- **Factura**: número, fecha de emisión, cliente, base, IVA, total.
- **Envío**: trimestre, destinatario, fecha y archivo enviado.
## Success Criteria *(mandatory)*
### Measurable Outcomes
- **SC-001**: un usuario con 500 facturas en un trimestre obtiene
el CSV en menos de 5 segundos.
- **SC-002**: la suma de la columna total del CSV coincide al
céntimo con el total facturado del trimestre en la app.
## Assumptions
- La exportación a Excel queda fuera de esta versión.
- Las facturas recibidas (gastos) no entran en esta feature.
Fíjate en lo que cambió. El orden ya no es cosa del agente: P1 se puede terminar, probar y desplegar sin tocar P2. "Rápida" ahora es SC-001, con un número. "CSV o Excel" se convirtió en una decisión escrita en Assumptions. Y lo que de verdad no sabes, el separador decimal, queda marcado en vez de inventado.
Ojo: una spec mejor no habría evitado por sí sola el bug del issue #4383. Allí la spec ya decía 200; el límite se perdió al pasar a tasks.md. Lo que lo atrapa es una restricción escrita como escenario (Given un motivo de 201 caracteres, When se guarda, Then se rechaza) más un comando que compare el código con ella. Un escenario se convierte en un test que falla, y un test que falla no deja pasar un 500 donde ponía 200.
Cómo detecta Spec Kit las contradicciones antes de implementar
Spec Kit detecta las contradicciones con cuatro comandos: clarify y checklist revisan la spec, analyze cruza spec, plan y tareas antes de implementar, y converge compara el código con los tres después. Es justo el punto donde falló el issue: algo se perdió entre spec.md y el código.
/speckit-clarify revisa la spec por categorías y te hace como máximo cinco preguntas, de una en una, con opciones cerradas o respuestas de cinco palabras como mucho. Cada respuesta se escribe en spec.md. Pásalo antes de plan: es más barato resolver el separador decimal ahí que en un PR.
/speckit-checklist genera lo que el propio comando llama "Unit Tests for English": comprueba si los requisitos están completos, son claros y no se contradicen. No prueba el código. Prueba la spec.
/speckit-analyze cruza spec.md, plan.md y tasks.md y saca una tabla de hallazgos con severidad. Es estrictamente de solo lectura: no toca ningún archivo. Y la constitución manda: según el propio comando, un conflicto con ella es "automatically CRITICAL" y se arregla cambiando la spec, el plan o las tareas, no el principio.
/speckit-converge va después de implementar. Compara el código con los tres artefactos y añade a tasks.md el trabajo que falta, sin tocar el código. Repites implement y converge hasta que el comando informa Converged.
El issue #4383 acabó en un cambio a la plantilla de tasks. Desde el PR #4430, fusionado el 8 de septiembre de 2026, el comando pide citar literalmente en cada tarea las restricciones de campo de data-model.md: longitudes máximas, nullables, enums, reglas de validación. Aun así, el bot del repo, que clasificó el issue como "likely valid, needs reproduction", avisa de que el arreglo es solo de prompt y de que distintos agentes pueden seguir parafraseando las restricciones en vez de citarlas. Por eso no te fíes de un solo comando: analyze antes de implementar y converge después.
La constitución: lo que ningún feature puede saltarse
/speckit-constitution escribe .specify/memory/constitution.md, que se crea una vez por proyecto. La plantilla trae huecos para cinco principios, con ejemplos como "Test-First (NON-NEGOTIABLE)".
Para el SaaS de facturas, uno de los principios sería este:
### I. Exactitud fiscal (NON-NEGOTIABLE)
Los importes se calculan en céntimos enteros, nunca en coma flotante.
Toda exportación tiene un test que compara su suma con el total del sistema.
Ese principio no vive en ninguna spec concreta. Vive por encima de todas. Si mañana un plan propone calcular con number de JavaScript, analyze debería marcarlo como CRITICAL antes de que se escriba una línea.
Spec Kit, un spec.md propio u OpenSpec
No todo proyecto necesita Spec Kit:
| Criterio | GitHub Spec Kit | spec.md propio | OpenSpec |
|---|---|---|---|
| Instalación | uv + Python 3.11+ |
Ninguna | npm (Node 22.12+), Homebrew o script |
| Formato de spec | Plantilla fija: user stories P1-P3, Given/When/Then, FR, SC | El que tú decidas | Requisitos y escenarios en Markdown, por cambio |
| Detección de contradicciones | clarify, checklist, analyze, converge |
Depende de tu disciplina y tus prompts | /opsx:verify en el perfil ampliado |
| Specs a largo plazo | Una carpeta por feature en specs/ |
Lo que mantengas a mano | openspec/specs/ vivas; los cambios se archivan y las actualizan |
| Limitación o riesgo | Mucho Markdown y ceremonia; las specs por feature envejecen | Nada te obliga a escribir criterios medibles | Menos puertas de calidad; su README llama a Spec Kit "Thorough but heavyweight" |
Fuentes: README de Spec Kit, README de OpenSpec, consultados el 7 de noviembre de 2026. Si ya usas OpenSpec, tienes el paso a paso en cómo integrar OpenSpec con Claude Code.
Mi opinión: el formato es lo mejor del paquete y te lo puedes llevar sin el CLI. Si copias la plantilla a tu spec.md propio, ya ganas la mitad; la otra mitad, analyze y converge, es lo que justifica instalarlo en proyectos medianos o grandes.
Cuándo NO usar Spec Kit
Para cambios pequeños. El proceso completo genera spec, plan, tareas, checklists y varios artefactos más. Para un bug de tres líneas es ceremonia pura. En este hilo de Hacker News, a raíz del análisis de Birgitta Böckeler sobre Kiro, Spec Kit y Tessl, un usuario contaba que lo dejó porque "Always made it too complex, and at some point it wasn't worth correcting it anymore". Para bugs, Spec Kit tiene ahora una extensión aparte (specify extension add bug); úsala en vez de pasar el bug por el flujo de features.
Cuando esperas que la spec garantice el resultado. En el mismo hilo, otro usuario cuenta que usó Spec Kit con Claude Code durante dos semanas. Tras unos diez días de flujo, tenía tests fallando y un build que no salía. En el siguiente proyecto dejó de lado parte del flujo: montó sus propios comandos por sprint y revisaba cada sprint antes de seguir. Ese comentario es de octubre de 2025, antes de converge, pero la lección no caduca: la spec reduce los huecos, no sustituye la revisión.
Cuando tus specs tienen que vivir años. Spec Kit crea una carpeta por feature. Si la feature 009 cambia lo que definió la 001, nada fusiona las dos automáticamente. Es lo que se preguntaba en el issue #620, "How to keep specs consistent and up-to-date with spec-kit?". Existe una guía para hacer evolucionar specs, pero el mantenimiento sigue siendo tuyo.
Cuando no vas a leer lo que genera. Una spec sin revisar es un prompt vago convertido en Markdown largo; el README pide ejecutar los comandos de uno en uno y revisar cada resultado.
Por dónde empezar a escribir specs para agentes de IA con Spec Kit
Coge la última feature que le pediste a Claude Code y reescribe su spec con la plantilla: dos o tres historias con prioridad, un Independent Test por historia, escenarios Given/When/Then y al menos un criterio con número. Después pasa /speckit-clarify y mira qué te pregunta. Esas preguntas son los huecos que el agente iba a rellenar por ti.
Si quieres el método completo detrás de este formato, está en el libro Spec-Driven Development. Y si prefieres verlo aplicado de la idea al producto con Claude Code, es lo que hacemos en el curso Construye con IA. Para la parte de revisar lo que genera el agente contra la spec, el workshop SDD + Agentic Engineering va justo de eso.
Preguntas frecuentes
¿Cómo se instala GitHub Spec Kit en Claude Code?
Con uv tool install specify-cli y specify init mi-proyecto --integration claude (en un repo existente, specify init --here --force --integration claude). Necesitas Python 3.11+, uv y Claude Code.
¿Los comandos de Spec Kit se escriben /speckit.specify o /speckit-specify?
En Claude Code, /speckit-specify, con guion: Spec Kit los instala como skills en .claude/skills/. La documentación de referencia usa /speckit.specify como notación genérica, y cada agente tiene su propia forma de invocarlos.
¿Qué diferencia hay entre /speckit-clarify y /speckit-analyze?
clarify resuelve dudas de la spec antes del plan y escribe las respuestas en spec.md. analyze cruza spec, plan y tareas después de tasks y no modifica ningún archivo.
¿Cómo se escriben criterios de aceptación para un agente de IA con Spec Kit?
Con escenarios Given/When/Then en cada user story y Success Criteria numerados (SC-001…) con una cifra. Cada escenario fija un estado inicial, una acción y un resultado comprobable; cada criterio, un número que un test puede medir, como "menos de 5 segundos con 500 facturas". Si no se puede comprobar con un test, no es un criterio de aceptación: es un hueco que el agente rellenará por su cuenta.
¿Cuántos [NEEDS CLARIFICATION] puede tener una spec de Spec Kit?
Como máximo tres. El comando specify está escrito para suponer con criterio y anotar esas suposiciones en Assumptions, y para marcar solo las decisiones críticas sin un valor razonable por defecto: alcance, seguridad o experiencia de usuario.
¿Spec Kit sirve para proyectos existentes o solo para empezar de cero?
Sirve para los dos, pero en un proyecto existente no genera specs del comportamiento que ya tienes: empiezan con la siguiente feature que definas.
¿Puedo usar el formato de Spec Kit sin instalar el CLI?
Sí. La plantilla templates/spec-template.md es Markdown público en el repo. Copiarla a tu propio spec.md te da las historias priorizadas, Given/When/Then, FR y SC. Lo que pierdes son los comandos que comprueban la coherencia entre spec, plan, tareas y código.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
¿Quieres construir con agentes en serio?
Curso «Construye con IA» con Claude Code, de la idea al producto.
Developer con más de 15 años en frontend y creador de Dominicode. Escribe sobre IA aplicada al desarrollo de software.
¿Te resultó útil este artículo?
Compártelo con tu comunidad y ayuda a otros desarrolladores.