Spec-kit: el kit de desarrollo de GitHub
En esta serie de publicaciones sobre Spec Driven Development, abordaremos varios frameworks que implementan el concepto de Spec Kit de maneras diferentes. Hoy comenzamos con el spec-kit de GitHub, uno de los más conocidos.
En constante evolución, lanzado a mediados de agosto de 2025, hoy cuenta con alrededor de 9k forks, más de 145 releases y más de 101k estrellas en GitHub. Este kit SDD es un caso de éxito.
Puedes instalarlo localmente con uv, un gestor de paquetes de Python, con un solo comando:
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v[tag release]
Hecho esto, inicializa el proyecto indicando el nombre y el agente que usarás:
specify init my-project --integration copilot
cd my-project
Antes de empezar a desarrollar, la documentación sugiere definir los principios del proyecto creando una especie de constitución. El comando /speckit.constitution crea un archivo con ese nombre, que contiene guías sobre cómo debe estructurarse el proyecto, reglas de gobernanza con restricciones, principios y todo lo relevante para considerar durante el desarrollo. Este archivo se crea una sola vez.
Después, especifica lo que necesitas crear en esta spec con /speckit.specify. El objetivo aquí no es cómo hacerlo, sino qué y por qué. Se crea una carpeta con el número de la spec y el nombre, y dentro se genera un archivo .spec.md junto con requirements.md.
Archivos creados:
spec.md/checklists/requirements.md
La spec contiene información como requisitos funcionales, entidades clave, casos límite, user stories y otros detalles inferidos por el agente. Este documento es muy valioso y debe leerse con calma para refinar el problema. Además, se genera requirements.md.
Ese otro archivo es más directo: documenta lo que se hará y lo que se entendió en forma de lista, definiendo lo que falta y lo que ya se completó en el proceso de la spec.
Tras esta primera etapa, es momento de documentar cómo resolveremos técnicamente el problema: qué tecnologías, librerías, frameworks y stack usaremos.
Usando /speckit.plan, en este momento se generan varios documentos:
data-model.mdquickstart.mdresearch.mdResearch.mdplan.md
El data model sirve para mapear los modelos utilizados en este proceso y el flujo de uso de esos datos. El quickstart ayuda a entender los archivos clave, comandos y prerequisitos.
El research es un documento que actúa como la “investigación del agente”: documenta cómo y por qué se eligió cada tecnología, la arquitectura, estrategias de testing, insights y más. También registra dudas o ambigüedades sin resolver.
El plan registra el contexto técnico, resumen, branch, verificación de compatibilidad con la constitución y deja justificaciones técnicas. Posee información valiosa sobre implementación, performance, alcance y limitaciones.
Después de planificar, debemos dividir el plan en tareas. Usamos /speckit.tasks para que el agente divida la implementación en tareas por fases, categorizando infra, proyecto, user stories, dependencias y orden. Es un archivo detallado para seguir el progreso.
Si durante el proceso hay algo que deba corregirse o revisarse, podemos usar
speckit.clarify.
Luego implementamos con /speckit.implement. Idealmente se recomienda usar diferentes ventanas de contexto: un modelo más potente para generar planes y otro más simple para implementar. Con un plan claro y sin ambigüedades, el agente implementador tendrá menos margen para alucinar o desviarse. El desarrollo será predecible, claro y transparente.
Problemas
Este Spec Kit es extremadamente completo y deja el proyecto muy bien documentado y fácil de compartir con otros desarrolladores, pero consume muchos tokens. No lo recomiendo para cosas muy pequeñas o tareas rápidas.
Al tener muchas etapas, la velocidad inicial puede verse afectada. Si necesitas algo estructurado pero rápido, quizás no sea la mejor opción. El proceso puede sentirse algo burocrático, y no todos los documentos generados tendrán sentido según el tamaño del proyecto.
