Si ha pasado tiempo utilizando agentes de codificación de IA (GitHub Copilot, Claude Code, Gemini CLI), probablemente se haya encontrado con esta situación: usted describe lo que desea, el agente genera un bloque de código que parece correcto, lo compila y luego pasa por alto sutilmente la intención real. Este enfoque de “codificación por vibración” puede funcionar para prototipos rápidos, pero se vuelve menos confiable cuando se crean aplicaciones de misión crítica o se trabaja con bases de código existentes. El problema, tal como lo plantea GitHub, no es la capacidad del agente codificador, sino el enfoque. Los desarrolladores han estado tratando a los agentes de codificación como motores de búsqueda, cuando deberían ser tratados más como programadores de mentalidad literal que destacan en el reconocimiento de patrones pero que aún necesitan instrucciones inequívocas.
Para abordar esto, GitHub tiene Spec-Kit de código abierto, un conjunto de herramientas diseñado para llevar el desarrollo basado en especificaciones (SDD) a los flujos de trabajo de codificación de IA. El proyecto cuenta actualmente con más de 90.000 estrellas y más de 8.000 bifurcaciones en GitHub, y se ha convertido en uno de los repositorios de herramientas para desarrolladores de más rápido crecimiento en la memoria reciente.
¿Qué es el desarrollo basado en especificaciones?
El desarrollo basado en especificaciones invierte la estructura de poder tradicional del desarrollo de software. Las especificaciones no sirven al código: el código sirve a las especificaciones. El Documento de Requisitos del Producto (PRD) no es una guía de implementación; es la fuente que genera la implementación.
En la práctica, esto significa que primero se escribe una especificación estructurada (describiendo lo que se desea construir y por qué, sin especificar la pila tecnológica) y luego se introduce eso en un agente de codificación de IA como documento de base. La especificación se convierte en la fuente de verdad que las herramientas y los agentes de IA utilizan para generar, probar y validar código. El resultado es menos conjeturas, menos sorpresas y un código de mayor calidad.
Esto es distinto de “la documentación primero” como se practica tradicionalmente. SDD no se trata de redactar documentos de requisitos exhaustivos y aburridos que nadie lee. No se trata de una planificación en cascada ni de intentar predecir el futuro mediante extensos ejercicios de planificación. Y no se trata de crear más burocracia que ralentice a los equipos de ingeniería. La especificación sigue siendo un artefacto vivo: se actualiza a medida que evolucionan los requisitos, en lugar de archivarse después del inicio del proyecto.
Lo que realmente incluye el Spec-Kit
Spec-Kit tiene dos componentes clave: Specify CLI, una herramienta auxiliar de línea de comandos que inicia proyectos para SDD descargando plantillas oficiales para el agente de codificación y la plataforma de su elección; y un conjunto de plantillas y scripts de ayuda que establecen las bases para la experiencia SDD: definen cómo se ve una especificación, qué abarca un plan técnico y cómo todo se divide en tareas individuales que un agente de IA puede ejecutar.
La CLI está escrita en Python y requiere Python 3.11+. La instalación vía uv es el método recomendado:
Una vez inicializado, el agente tiene acceso a un conjunto de comandos de barra diagonal que se asignan directamente al flujo de trabajo de SDD. Los comandos principales son:
/speckit.constitution: establece los principios rectores no negociables del proyecto. /speckit.specify: captura lo que desea construir, centrado en el “qué” y el “por qué” sin detalles de la pila tecnológica. /speckit.plan: genera el plan de implementación técnica dada la pila elegida. /speckit.implement: ejecuta esas tareas utilizando el agente de codificación de IA
También hay tres comandos opcionales para mejorar la calidad y la validación:
/speckit.clarify: muestra áreas poco especificadas a través de preguntas estructuradas y secuenciales antes de crear un plan técnico (recomendado antes de /speckit.plan para reducir el retrabajo posterior) /speckit.analyze: ejecuta análisis de cobertura y coherencia entre artefactos después de /speckit.tasks y antes de /speckit.implement /speckit.checklist: genera listas de verificación de calidad personalizadas que validan la integridad, claridad y coherencia de los requisitos
Una adición importante es Constitution.md. En el contexto de SDD, un documento de constitución establece un conjunto de principios no negociables para un proyecto: convenciones de prueba, requisitos de CLI primero, estándares de sistemas de diseño organizacional. Estos se capturan una vez y se hace referencia a ellos en cada fase de desarrollo posterior.
Cómo utilizar el kit de especificaciones de GitHub: una guía paso a paso
Desarrollo basado en especificaciones (SDD) con agentes de codificación de IA, desde la instalación de la CLI hasta la ejecución de su primera implementación. Sigue el flujo de trabajo oficial del repositorio github/spec-kit.
Paso 1: requisitos previos
Asegúrese de tener las herramientas adecuadas instaladas
Antes de instalar Specify CLI, necesita cuatro cosas en su máquina. Spec Kit es multiplataforma y funciona en Linux, macOS y Windows.
Python 3.11+: descargar desde python.org uv (recomendado) o pipx para administración de paquetes: instale uv desde docs.astral.sh/uv Git: descargar desde git-scm.com Un agente de codificación de IA compatible: Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf, Codex CLI o cualquiera de las 29 integraciones compatibles.
¿Por qué ultravioleta? Gestiona las instalaciones de herramientas globalmente, las mantiene en su RUTA y facilita la actualización con la lista de herramientas uv, la actualización de herramientas uv y la desinstalación de herramientas uv. Es el método recomendado oficialmente.
Paso 2: instalación
Instale la CLI especificada desde GitHub
El único paquete oficial de Spec Kit se publica directamente desde el repositorio de GitHub. No lo instale desde PyPI: el equipo del kit de especificaciones no mantiene ningún paquete allí con el mismo nombre.
herramienta uv instalar especificar-cli –desde git+https://github.com/github/spec-kit.git @vX.YZ pipx instalar git+https://github.com/github/spec-kit.git @vX.YZ especificar versión
Paso 3: inicializar
Arranca tu proyecto con especifica init
Navegue a la carpeta de su proyecto y ejecute especificar init. La CLI detecta qué agente de codificación de IA ha instalado y configura automáticamente la estructura de directorios, las plantillas y los comandos correctos.
especifique init my-photo-app especifique init . –integración claude especifica init . –códice de integración –opciones-integración =”–habilidades” especificar verificación
Después de esto, su proyecto contendrá un directorio .specify/ con subdirectorios memoria/, scripts/, especificaciones/ y plantillas/.
Modo de habilidades: Claude Code, Codex CLI, Kimi Code, Devin y varios otros agentes utilizan una instalación basada en habilidades: los archivos van a directorios específicos del agente (por ejemplo, .claude/skills/) en lugar de archivos de símbolo del sistema con barra diagonal. Ejecute la lista de integración específica para ver qué modo utiliza cada agente.
Paso 4: Constitución
Establezca los principios del proyecto con /speckit.constitution
El primer comando que ejecuta dentro de su agente es /speckit.constitution. Esto crea un archivo Constitution.md que contiene principios rectores no negociables que el agente sigue en cada fase posterior. Ejecute esto una vez por proyecto.
/speckit.constitution Cree principios centrados en: – Calidad del código y estándares de cobertura de pruebas – Coherencia en la experiencia del usuario en todas las pantallas – Requisitos de rendimiento para interfaces con muchas imágenes – Sin servicios de carga de imágenes de terceros: solo almacenamiento local
Esto escribe en .specify/memory/constitution.md. Piense en ello como instrucciones permanentes: cosas como "use siempre TypeScript", "nunca introduzca cambios importantes en la API" o "siga nuestro sistema de diseño interno".
Paso 5: Especificación
Describe qué construir con /speckit.specify
Ahora describe lo que quieres construir; concéntrate completamente en el "qué" y el "por qué". No menciones la pila tecnológica en esta etapa. El agente produce un spec.md con historias de usuarios y requisitos funcionales.
/speckit.specify Cree una aplicación que organice fotografías en álbumes. Los álbumes están agrupados por fecha y se pueden reorganizar arrastrándolos y soltándolos en la página principal. Los álbumes nunca se anidan dentro de otros álbumes. Dentro de cada álbum, las fotos se obtienen una vista previa en una interfaz similar a un mosaico. Los usuarios pueden cambiar el nombre y eliminar álbumes, pero no pueden eliminar fotos individuales desde una vista de álbum.
No menciones la pila tecnológica aquí. Mezclar “qué construir” con “cómo construirlo” en esta etapa conduce a especificaciones demasiado restringidas. La pila tecnológica viene en el Paso 7.
La salida va a .specify/specs/001-photo-app/spec.md y se crea automáticamente una nueva rama de Git.
Paso 6: Comandos de calidad opcionales
Aclare y valide sus especificaciones antes de planificar
Antes de generar el plan técnico, dos comandos opcionales ayudan a resaltar las lagunas y validar sus especificaciones. Se recomiendan ambos y se pueden omitir para obtener picos rápidos o prototipos exploratorios.
/speckit.aclarar
Preguntas estructuradas y secuenciales que registran las respuestas directamente en una sección de Aclaraciones de la especificación. Reduce el retrabajo posterior. Ejecutar antes de /speckit.plan.
/speckit.lista de verificación
Genera listas de verificación de calidad personalizadas que validan la integridad, claridad y coherencia de los requisitos, descritas en el README como "pruebas unitarias para inglés". Corre después de la aclaración.
/speckit.clarificar /speckit.lista de verificación
Durante la aclaración, el agente podría preguntar cosas como:
¿Los álbumes deberían admitir la selección múltiple para operaciones por lotes? ¿Hay un número máximo de fotos por álbum? ¿La función arrastrar y soltar debería funcionar solo en dispositivos móviles o en computadoras de escritorio?
Si omite intencionalmente una aclaración, infórmeselo explícitamente al agente; de lo contrario, puede bloquear la espera de aclaraciones faltantes antes de permitirle continuar con la planificación.
Paso 7: Plan técnico
Definir la pila con /speckit.plan
Ahora especifique la arquitectura y la pila tecnológica. El agente genera un plan.md, un data-model.md, un research.md y un quickstart.md.
/speckit.plan Utilice Vite con HTML, CSS y JavaScript básicos. Mantenga las bibliotecas de terceros al mínimo. Las imágenes no se cargan en ningún lugar: los metadatos se almacenan en una base de datos SQLite local a través de un backend Express liviano. Arrastrar y soltar utiliza la API nativa HTML5 de arrastrar y soltar.
Su directorio después de este paso:
.specify/specs/001-photo-app/ ├── spec.md ├── plan.md ├── data-model.md ├── research.md └── quickstart.md
Consulte research.md para verificar que se haya elegido la pila tecnológica correcta. Si se trata de un marco que cambia rápidamente, solicite al agente que investigue la versión instalada específica antes de seguir adelante.
Paso 8: Desglose de tareas
Generar tareas con /speckit.tasks y /speckit.taskstoissues
Ejecute /speckit.tasks para generar un task.md con la hoja de ruta de implementación completa. Las tareas están organizadas por historia de usuario, ordenadas por dependencia y anotadas con marcadores de ejecución paralela.
/speckit.tasks ## Historia de usuario: Gestión de álbumes – [ ] Crear esquema SQLite: álbumes, tablas de fotos – [ ] [P] Build Express GET /albums endpoint – [ ] [P] Build Express POST /albums endpoint – [ ] [P] Implementar el cambio de nombre del álbum PUT /albums/:id ## Punto de control: validar el álbum CRUD de forma independiente
El marcador [P] indica tareas que se pueden ejecutar en paralelo. Cada sección de historia de usuario termina con un punto de control para validar que la funcionalidad de esa fase funcione de forma independiente antes de que comience la siguiente. Opcionalmente, convierta tareas en GitHub Issues:
/speckit.taskstoissues
Paso 9: Análisis de artefactos cruzados
Validar la coherencia con /speckit.analyze
Después de generar tareas y antes de ejecutar la implementación, ejecute el comando opcional /speckit.analyze. Realiza una verificación de cobertura y coherencia entre artefactos en todas las especificaciones, el plan, el modelo de datos y las tareas para garantizar que todo esté alineado.
/speckit.analizar
El agente señalará problemas como:
Una historia de usuario en spec.md sin tarea correspondiente en task.md El plan que hace referencia a una tabla de base de datos que no está definida en el modelo de datos. Un comportamiento descrito en la especificación que no tiene ninguna tarea asignada para implementarlo.
Este es un comando de solo lectura: produce un informe de hallazgos sin modificar ningún archivo. Solucione los problemas marcados antes de ejecutar /speckit.implement para evitar errores en cascada durante la generación de código.
Paso 10: Implementación
Ejecutar con /speckit.implement
Con todos los artefactos en su lugar, ejecute /speckit.implement. El agente primero valida que constitution.md, spec.md, plan.md y task.md estén presentes, luego ejecuta las tareas en orden, respetando las dependencias y los marcadores paralelos [P].
/speckit.implementar
Se deben instalar herramientas CLI locales. El agente ejecutará comandos como npm, dotnet o python directamente en su máquina. Asegúrese de que todos los tiempos de ejecución necesarios estén disponibles antes de ejecutar este comando.
¿Agregar una nueva característica? Omita /speckit.constitution (se ejecuta una vez por proyecto) y comience desde /speckit.specify para cada característica posterior.
✅ Flujo de trabajo del kit de especificaciones completo: referencia rápida
Instalar: herramienta uv instalar speckit-cli –from git+https://github.com/github/[email protected] Iniciar proyecto: especificar init –integration Establecer principios: /speckit.constitution: ejecutar una vez por proyecto Escribir especificaciones: /speckit.specify: describir qué construir, no cómo Aclarar brechas: /speckit.clarify (opcional, recomendado antes del plan) Validar especificaciones: /speckit.checklist (opcional, después de aclarar) Generar plan: /speckit.plan: especificar pila tecnológica y arquitectura Divida las tareas: /speckit.tasks + opcional /speckit.taskstoissues Verifique la coherencia: /speckit.analyze (opcional, después de las tareas, antes de la implementación) Compílelo: /speckit.implement
Las fases de desarrollo
Spec-Kit admite tres amplios escenarios de desarrollo. Para proyectos totalmente nuevos, se comienza con requisitos de alto nivel, se generan especificaciones y se planifica la implementación antes de escribir cualquier código. Para una mejora iterativa en bases de código existentes ("brownfield"), agrega características de forma incremental sin descartar el contexto anterior. Para la modernización heredada, donde la intención original a menudo se pierde en el tiempo, se captura la lógica empresarial esencial en una especificación moderna, se diseña una nueva arquitectura en el plan y se deja que la IA reconstruya el sistema sin arrastrar la deuda técnica heredada.
El comando /speckit.tasks produce un archivo task.md con desgloses de tareas organizados por historia de usuario, orden de dependencia (para que los modelos se implementen antes que los servicios, los servicios antes que los puntos finales), marcadores de ejecución paralela etiquetados [P], especificaciones de ruta de archivo exactas y validación de puntos de control entre fases.
Compatibilidad y extensibilidad de agentes
La CLI de Specify admite una amplia gama de agentes de codificación de IA. Cuando ejecuta spec init, la CLI configura los archivos de comando, las reglas de contexto y las estructuras de directorio apropiados para el agente de codificación AI elegido. Spec-Kit actualmente admite 29 integraciones con nombre, incluidas Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf, Codex CLI, Qwen Code, Kiro CLI, Goose, Mistral Vibe, Devin for Terminal, Roo Code e IBM Bob, junto con una integración genérica para cualquier agente que no esté en la lista.
Una distinción importante: para varios agentes, Spec-Kit instala habilidades del agente en lugar de archivos de símbolo del sistema con barra diagonal. Claude Code, por ejemplo, utiliza una integración basada en habilidades que coloca archivos en .claude/skills/. Codex CLI usa de manera similar habilidades invocadas como $speckit-. Para estas integraciones, pase –integration-options="–skills" durante el inicio especificado para instalar en modo skills.
El conjunto de herramientas también se puede ampliar mediante dos mecanismos. Las extensiones introducen nuevos comandos y plantillas, por ejemplo, integración de Jira o Azure DevOps, revisión de código posterior a la implementación, modelado de amenazas OWASP LLM o trazabilidad de pruebas de V-Model. Los ajustes preestablecidos anulan las plantillas y comandos existentes para hacer cumplir los estándares organizacionales o regulatorios sin agregar nuevas capacidades. Actualmente hay más de 70 extensiones aportadas por la comunidad en el catálogo, que cubren categorías que incluyen documentos, código, proceso, integración y visibilidad, cada una marcada como de solo lectura o lectura+escritura vigente.
Conclusiones clave
Spec-Kit de GitHub es un conjunto de herramientas de código abierto que presenta un flujo de trabajo estructurado de desarrollo basado en especificaciones (SDD) para agentes de codificación de IA, alejándose de las indicaciones ad-hoc. El flujo de trabajo principal se ejecuta a través de seis comandos: /speckit.constitution → /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.taskstoissues → /speckit.implement, con tres comandos opcionales adicionales para la validación. Spec-Kit admite 29 integraciones de agentes de codificación de IA con nombre más una opción genérica; algunos agentes (incluidos Claude Code y Codex CLI) utilizan un modo de instalación basado en habilidades en lugar de comandos de barra diagonal. Un ecosistema en crecimiento de más de 70 extensiones comunitarias agrega integraciones con herramientas como Jira, Azure DevOps y GitHub Issues, además de puertas de calidad para seguridad, pruebas y detección de derivas. El proyecto se describe a sí mismo como un experimento y es más adecuado para compilaciones nuevas y trabajos de funciones grandes en lugar de pequeñas correcciones de errores.
Consulte el repositorio de GitHub aquí. Además, no dude en seguirnos en Twitter y no olvide unirse a nuestro SubReddit de más de 150.000 ML y suscribirse a nuestro boletín. ¡Esperar! estas en telegrama? Ahora también puedes unirte a nosotros en Telegram.
¿Necesita asociarse con nosotros para promocionar su repositorio de GitHub O su página principal de Hugging O su lanzamiento de producto O seminario web, etc.? Conéctate con nosotros