Spec-Kit: cuando la spec es el código

Llevamos un par de años viendo pasar frameworks de “AI-assisted development”. La mayoría son wrappers elegantes sobre un prompt, un par de plantillas, y mucha expectativa. Spec-Kit es distinto por una razón concreta: lo mantiene GitHub. No es un proyecto de laboratorio con 300 estrellas que va a morir en seis meses.

La premisa es fuerte, casi incómoda: la especificación es el código. El archivo .py o .ts que ves en el repo es un artefacto derivado, regenerable. Lo que importa, lo que versionas con cariño, lo que revisas en PR, es la spec en markdown.

Antes de entrar a si esa premisa se sostiene, los números para ubicarnos.

· github/spec-kit · MIT · GitHub oficial

Qué hace realmente

Spec-Kit formaliza una práctica que llamaba Spec-Driven Development (SDD). La idea cabe en una oración: si el LLM puede generar código desde una descripción, entonces la descripción — y no el código — es el activo que vale la pena mantener.

Las consecuencias son las interesantes. Mantener software ya no es editar archivos fuente, es evolucionar la spec y regenerar. Debuggear no es rastrear una variable, es encontrar el requisito mal escrito que produjo ese bug. Refactorizar es reordenar la spec, no mover funciones entre módulos.

Dicho así suena a ciencia ficción organizacional. En la práctica, el código sigue ahí, sigue commiteado, sigue en producción. Pero el flujo de trabajo gira alrededor de los archivos spec.md, plan.md y tasks.md que Spec-Kit genera y versiona. El equipo discute la spec. El agente discute con la spec. El código aparece al final.

Cómo funciona por dentro

El flujo tiene siete pasos, pero de verdad son cuatro fases que importan: specify, plan, tasks, implement. El resto son soporte.

Arrancas con specify init, que crea un directorio .specify/ con la estructura base y una constitución — principios del proyecto, tipo “nada se despliega sin tests”, “APIs siempre REST”. Después, para cada feature, invocas /speckit.specify en tu agente (Claude, Copilot, Cursor, lo que uses) y describes el requisito en lenguaje natural. El agente devuelve un spec.md estructurado. Revisas, corriges, aceptas.

Luego /speckit.plan convierte la spec en plan técnico: stack, data model, contratos de API. /speckit.tasks desglosa ese plan en tareas con dependencias. /speckit.implement las ejecuta.

Así se ve una spec mínima generada tras /speckit.specify "búsqueda facetada en el buscador interno":

# Feature: Búsqueda facetada

## User story
Como operador interno, quiero filtrar resultados por
categoría, estado y fecha para encontrar registros sin
recordar IDs exactos.

## Criterios de aceptación
- Facetas: categoria, estado, rango_fecha
- Múltiples facetas combinables con AND
- Respuesta < 300ms p95 sobre 100k registros
- Facetas vacías no aparecen en la UI

## Fuera de alcance
- Búsqueda full-text (existe en /search/fulltext)
- Persistencia de filtros entre sesiones

Diez líneas. Lo suficiente para que el plan técnico tenga donde agarrarse y para que un humano, en una revisión, entienda qué se está pidiendo sin leer una sola línea de código.

Pros

• Respaldo de GitHub. No es un side-project. Tiene equipo, roadmap y va a seguir existiendo el año que viene.
• Trazabilidad nativa. Cada pieza de código tiene una tarea, cada tarea un plan, cada plan una spec. Para software regulado esto es oro puro, especialmente con la extensión V-Model.
• Agnóstico del agente. Funciona con Claude, Copilot, Gemini, Codex, Cursor, Windsurf y varios más. No te amarra a un proveedor de LLM.
• Ecosistema de extensiones real. Hay CI Guard, Security Review, Brownfield Bootstrap, Jira sync. No todas son útiles, pero varias resuelven problemas que en proyectos grandes aparecen rápido.
• Las specs son legibles por humanos. A diferencia de DSLs propietarios, sigues usando markdown. Un PM puede leer y comentar una spec sin formación especial.

Contras

• Overhead real en proyectos chicos. Para un script de 200 líneas, escribir constitución, spec, plan y tasks es absurdo. El framework asume cierta escala.
• taskstoissues solo habla GitHub. Si tu equipo vive en Gitea, GitLab o Jira con flujos raros, la integración más jugosa se queda corta.
• Sistema de presets con curva. Las capas de prioridad (overrides locales > presets > extensiones > core) son potentes pero se enredan rápido cuando alguien nuevo intenta entender por qué un comando se comporta distinto en su máquina.
• Aún no llega a 1.0. Versión 0.7.5. Para un proyecto oficial de GitHub con 90k estrellas, eso dice algo: el diseño sigue moviéndose. Si adoptas hoy, cuenta con reajustar en seis meses.
• La spec mal escrita genera código mal escrito, pero más lento. SDD no te protege de requisitos malos. Te obliga a formalizarlos, lo cual es bueno, pero el trabajo de pensar no desaparece — se mueve a otra fase.

Cuándo sí, cuándo no

Tiene sentido cuando el proyecto es lo suficientemente grande para que la trazabilidad pague el overhead: software regulado, equipos distribuidos, sistemas donde “quién decidió esto” es una pregunta real y frecuente. También para greenfield con stakeholders no técnicos que necesitan ver y aprobar lo que se va a construir antes de que exista.

No tiene sentido para scripts, prototipos, herramientas internas de un solo desarrollador, ni proyectos donde el código cambia más rápido que cualquier spec podría seguirle el paso. Tampoco si tu equipo no vive en GitHub: perderías la mitad del valor. Si leíste los dos párrafos anteriores y ninguno te describe, probablemente no es para ti — y está bien.

Veredicto

En el lab lo estamos mirando con interés pragmático, no con fervor. Para un cliente con auditorías regulares, trazabilidad obligatoria y equipos de cinco o más personas trabajando con agentes AI, Spec-Kit es probablemente la opción más seria que existe hoy. La extensión V-Model sola justifica evaluarlo en cualquier proyecto que toque ISO o FDA.

Para nuestro trabajo interno — proyectos chicos, decisiones rápidas, mucho código desechable — el overhead no paga. Seguimos usando flujos más ligeros: prompts bien escritos, revisión humana agresiva, y commits chicos.

¿Metodología base o herramienta de nicho? Hoy es nicho con ambición de metodología. Si llega a 1.0 sin traicionar su diseño actual, en un par de años podría ser la forma por defecto de construir software en equipos medianos y grandes con asistencia AI. Pero “podría” hace mucho trabajo en esa frase. Por ahora, lo tratamos como lo que es: una apuesta bien fundada, oficial, con tracción real, que conviene entender antes de que el cliente nos pregunte si lo usamos.

TL;DR — Spec-Kit convierte la spec en la fuente de verdad y el código en artefacto regenerable; vale la pena si tu proyecto necesita trazabilidad auditada, sobra si solo quieres entregar rápido.