Spec Kit de GitHub: desarrollar software de alta calidad más rápido

• Desarrollo guiado por especificaciones (Spec-Driven Development): un enfoque que eleva la especificación (Spec), que en el desarrollo tradicional era un recurso auxiliar, a una especificación ejecutable, con el objetivo de generar directamente una implementación funcional a partir de ella
  • Cambia la práctica centrada en el código para definir primero el qué y el por qué, y luego concretar el cómo, enfatizando un desarrollo centrado en la intención
  • La idea central es crear entregables consistentes mediante especificaciones y automatizar las tareas repetitivas para que los desarrolladores puedan concentrarse en los problemas del producto
• Spec Kit es un conjunto de herramientas que ayuda a convertir estas especificaciones en entregables ejecutables para automatizar la implementación
• Después de instalarlo, se describe el qué/por qué con /specify, se declara el stack/arquitectura con /plan y se generan las unidades de trabajo con /tasks
• El objetivo es ayudar a las organizaciones a dejar de escribir código común no diferenciador y enfocarse en los escenarios del producto; es un framework experimental que busca elevar tanto la calidad como la velocidad mediante un enfoque guiado por especificaciones

Filosofía central: Core philosophy

• Una mentalidad de especificación primero basada en desarrollo centrado en la intención, donde se prioriza el qué y el cómo se detalla después
• Se redactan especificaciones ricas con guardrails y principios organizacionales, y se sigue un proceso de refinamiento en múltiples etapas en lugar de una generación de código de una sola vez
• Se orienta a un uso que depende activamente de la capacidad de interpretación de modelos avanzados de IA para transformar especificaciones en resultados ejecutables

Proceso guiado por especificaciones con Spec Kit

• Spec Kit coloca las especificaciones en el centro del proceso de ingeniería para guiar la implementación, los checklists y la descomposición del trabajo, mientras que el desarrollador cumple principalmente un rol de dirección
  • El agente de codificación se encarga de la mayor parte de la escritura
• El proceso consta de 4 etapas, cada una con checkpoints claros, y no se avanza a la siguiente hasta que el trabajo actual esté completamente validado
• Etapa Specify: al proporcionar una descripción de alto nivel, el agente de codificación genera una especificación detallada enfocada en el recorrido del usuario, la experiencia y las métricas de éxito, no en el stack técnico
  • Mapea quién es el usuario, qué problema se resuelve, cómo interactúa y cuáles son los resultados importantes
  • Esto toma la forma de un artefacto vivo que evoluciona según lo aprendido del usuario
• Etapa Plan: al proporcionar el stack deseado, la arquitectura y las restricciones, el agente de codificación genera un plan técnico integral
  • Incluye tecnologías estándar de la empresa, integración con sistemas legacy, cumplimiento normativo, objetivos de rendimiento, etc.
  • Se pueden solicitar varias versiones del plan para compararlas, y si se aporta documentación interna, integra directamente los patrones de arquitectura
• Etapa Tasks: a partir de la especificación y el plan, el agente de codificación descompone el trabajo en bloques pequeños y revisables
  • Cada tarea puede implementarse y probarse de manera independiente, y está diseñada para que la IA pueda validarla y darle seguimiento
  • Por ejemplo, en lugar de "construir autenticación", sería algo como "crear un endpoint de registro de usuarios que valide el formato del correo electrónico"
• Etapa Implement: el agente de codificación procesa las tareas una por una o en paralelo, y el desarrollador revisa cambios acotados y enfocados
  • La especificación indica qué construir, el plan cómo construirlo y las tareas sobre qué trabajar
• En cada etapa, el desarrollador reflexiona y refina, verificando si la especificación captura la intención, si el plan considera las restricciones reales y si hay omisiones o casos límite, cumpliendo un rol de validación

Cómo usar Spec Kit en un flujo de trabajo agéntico

• Spec Kit funciona con agentes de codificación como GitHub Copilot, Claude Code y Gemini CLI, y guía al agente mediante una serie simple de comandos para generar artefactos
  • Esto convierte prompts ambiguos en intenciones claras para una ejecución confiable
• Después de inicializar el proyecto, al dar un prompt de alto nivel con el comando /specify, el agente de codificación genera la especificación completa enfocada en el "qué" y el "por qué" del proyecto
• Con el comando /plan, al proporcionar una dirección técnica de alto nivel, el agente de codificación genera un plan detallado que respeta la arquitectura y las restricciones
• Con el comando /tasks, descompone la especificación y el plan en una lista de tareas ejecutables, a partir de la cual el agente de codificación implementa los requisitos del proyecto

Fases de desarrollo: Development phases

• Etapa 0-to-1 (greenfield): soporta un flujo de generación de especificación → planificación → creación de una app lista para producción a partir de requisitos de alto nivel
• Etapa de exploración creativa: enfatiza un proceso para experimentar con diversos stacks/arquitecturas y patrones de UX mediante implementación en paralelo
• Etapa de mejora gradual (brownfield): desarrollo evolutivo que itera sobre agregar funciones, modernizar sistemas legacy y adaptar procesos

Tres escenarios donde este enfoque funciona bien

• Greenfield (zero-to-one): al iniciar un proyecto nuevo, en lugar de comenzar a programar de inmediato, se crean primero la especificación y el plan para asegurar que la IA construya lo realmente buscado, ofreciendo resultados personalizados en lugar de soluciones genéricas basadas en patrones comunes
• Trabajo de funciones en sistemas existentes (N-to-N+1): al agregar funciones a una base de código compleja, la especificación aclara cómo interactúa la nueva función con el sistema existente, y el plan codifica las restricciones arquitectónicas para generar código que se sienta nativo
  • Esto hace que el desarrollo continuo sea más rápido y seguro, aunque puede requerir técnicas avanzadas de ingeniería de contexto
• Modernización legacy: al reconstruir sistemas legacy donde se perdió la intención original, el proceso de Spec Kit captura la lógica de negocio esencial en una especificación moderna y planifica una arquitectura nueva para que la IA lo reconstruya sin deuda técnica

Prerequisites

• Se requiere Linux/macOS o WSL2 de Windows
• Elegir como agente de IA entre Claude Code, GitHub Copilot, Gemini CLI y Cursor

[edunga1]

Me recuerda a Copilot Workspace.

[cocofather]

Parece que se convertirá en la base de la programación con IA basada en lenguaje natural.

[tested]

La ventaja de Spec Kit de GitHub es que también se puede usar en GitHub Copilot.
Como lo hizo GitHub, supongo que era de esperarse, pero muchas de las otras herramientas estaban basadas en Claude.

[skageektp]

Me recuerda a Kiro IDE

[kandk]

Está interesante. Y también tiene sentido.

[xguru]

El enlace de presentación detallada de SDD en medio del texto está muy bueno. Abajo va un resumen hecho con IA.

Desarrollo guiado por especificaciones (Specification-Driven Development, SDD)

The Power Inversion

• Invierte el flujo donde el PRD y los documentos de diseño giraban alrededor del código: la especificación es la fuente original y el código es una expresión implementada en un lenguaje o framework específico
  • Se plantea el diagnóstico de que la brecha permanente entre especificación e implementación era difícil de cerrar solo reforzando documentación o procesos
  • Si las especificaciones ejecutables y el plan de implementación generan el código, la brecha desaparece y solo queda la transformación
• La IA hace posible interpretar especificaciones complejas y elaborar planes de implementación, pero como la generación sin estructura provoca caos, SDD asegura la calidad con estructura precisa y guardrails
• El mantenimiento es una acción de evolución de la especificación; la intención de desarrollo se expresa con lenguaje natural, activos de diseño y principios clave, y el código ocupa la posición de la última milla
• El debugging prioriza corregir la especificación y el plan de implementación antes que arreglar código incorrecto, y el refactoring se redefine como reconstrucción de claridad

The SDD Workflow in Practice

• La idea se refina en un PRD mediante interacción conversacional con la IA, y la IA concreta preguntas, casos límite y criterios de aceptación
  • Convierte requisitos y diseño en una actividad continua, y soporta trabajo de especificación basado en branches a nivel de equipo, además de revisión y versionado
• Un agente de investigación explora compatibilidad de librerías, performance, seguridad y restricciones organizacionales (estándares de DB, autenticación, políticas de despliegue) y lo refleja automáticamente en la especificación
• A partir del PRD genera un plan de implementación que mapea de forma trazable los requisitos y las decisiones técnicas, mientras la IA valida continuamente contradicciones, ambigüedades y omisiones
• Cuando la especificación y el plan están lo suficientemente estables, comienza la generación de código, pero al inicio se usa generación exploratoria para validar la viabilidad
  • Los conceptos de dominio se convierten en modelos de datos, las user stories en endpoints de API y los escenarios de aceptación en tests
• En operación, las métricas e incidentes actualizan la especificación para reflejarse en la siguiente regeneración; los cuellos de botella de performance se elevan a requisitos no funcionales y las vulnerabilidades a restricciones globales

Why SDD Matters Now

• Punto de inflexión en capacidades de IA: ya puede generar de forma confiable código funcional desde especificaciones en lenguaje natural, y automatiza la parte mecánica de la traducción a implementación para potenciar exploración y creatividad
• Explosión de complejidad: con muchos servicios, frameworks y dependencias, mantener la alineación entre intención e implementación se vuelve difícil, por lo que se necesita la alineación impulsada por especificaciones de SDD
• Aceleración del cambio: en contextos de pivotes frecuentes, SDD maneja los cambios mediante regeneración sistemática en lugar de propagación manual entre documento, diseño y código
  • Como ejemplo, permite simulaciones what-if e implementación en paralelo, aportando agilidad en la toma de decisiones

Core Principles

• Especificación = lenguaje común: la especificación es un artefacto de primer nivel, el código es una expresión de un stack específico y el mantenimiento es evolución de la especificación
• Especificaciones ejecutables: con especificaciones precisas, completas y no ambiguas se genera un sistema funcional
• Refinamiento continuo: no es una compuerta única, sino una verificación permanente de consistencia
• Contexto basado en investigación: se recopilan de forma continua performance, seguridad y restricciones organizacionales para inyectarlas en la especificación
• Feedback bidireccional: la realidad operativa se convierte en entrada para actualizar la especificación
• Branching para explorar: desde una misma especificación se soporta generar múltiples implementaciones según objetivos de optimización como performance, mantenibilidad, UX o costo

Implementation Approaches

• La práctica actual se centra en combinar herramientas existentes y mantener disciplina, y puede implementarse con los siguientes elementos
  • Asistente de IA para refinamiento iterativo de especificaciones
  • Agente de investigación para recopilar contexto técnico
  • Herramienta de generación de código para la transformación especificación→implementación
  • Control de versiones adaptado a un flujo de trabajo spec-first
  • Verificación basada en análisis de consistencia con IA sobre los documentos de especificación
• El principio común es tratar la especificación como única fuente de verdad y el código como resultado exigido por la especificación

Streamlining SDD with Commands

• /specify: convierte la descripción de una funcionalidad en una especificación estructurada y automatiza numeración automática, creación de branch y estructura de directorios basada en templates
• /plan: analiza la especificación → revisa cumplimiento de la constitución → hace la traducción técnica → documenta modelo de datos, contrato de API y escenarios de prueba → genera validación quickstart
• /tasks: lee plan.md y diseños relacionados para producir una lista de tareas ejecutables, además de marcar tareas paralelizables y agrupar paralelismo seguro
• Ejemplo: funcionalidad de chat
  • Se presenta un flujo de ejemplo donde unas ~12 horas de trabajo documental en el enfoque tradicional se reducen a unos 15 minutos de configuración mediante automatización de especificación, plan y tareas
  • Entre los entregables se versionan en el branch la especificación, el plan de implementación y su fundamento, el contrato de API y modelo de datos, los escenarios quickstart y tasks.md

The Power of Structured Automation

• Evita omisiones: los templates abarcan incluso requisitos no funcionales y manejo de errores
• Trazabilidad de decisiones: toda elección técnica queda conectada a requisitos concretos
• Documentación viva: como la especificación genera el código, es más fácil mantener la sincronización
• Iteración rápida: ante cambios de requisitos, la regeneración del plan permite responder en minutos u horas

Template-Driven Quality

• Evita la intrusión prematura de detalles de implementación: al enfocarse en WHAT/WHY y excluir HOW, induce a mantener el nivel de abstracción
• Obliga a marcar incertidumbre: el marcador [NEEDS CLARIFICATION] impulsa no adivinar y formular preguntas explícitas
• Autorrevisión basada en checklist: implementa una compuerta de calidad verificando completitud, claridad y criterios de aceptación medibles
• Constitution gate: aplica checks de etapa previa (-1) como compuerta de simplicidad (≤3 proyectos), compuerta antiabstracción (uso directo del framework) y compuerta de integración primero (contratos y pruebas de contrato antes de implementar)
• Gestión de detalle por capas: separa código o detalles excesivos en implementation-details/ para mantener legibilidad
• Prioridad de testing: asegura verificabilidad con la regla de crear archivos y tests primero en el orden contrato → integración → E2E → unitario
• Contención de supuestos y funciones especulativas: refuerza el control de alcance prohibiendo funcionalidades especulativas y explicitando precondiciones por etapa

The Constitutional Foundation

• Adopta una constitución de desarrollo en memory/constitution.md con principios inmutables para mantener todas las implementaciones consistentes, simples y de alta calidad
  • Article I: Library-First — toda funcionalidad empieza como librería independiente para asegurar modularidad
  • Article II: CLI Mandate — toda librería expone una interfaz CLI con soporte para entrada/salida de texto y JSON, garantizando observabilidad y facilidad de prueba
  • Article III: Test-First — prohibido implementar antes de aprobar tests y confirmar fallo (red), bajo el principio de definir primero el comportamiento
  • Articles VII & VIII: simplicidad y antiabstracción — minimizar la cantidad de proyectos y confiar directamente en el framework para evitar sobreingeniería
  • Article IX: pruebas de integración primero — prioriza tests cercanos al entorno real y obliga a implementar pruebas de contrato antes de la implementación
• Con la Phase -1 gate del template, el cumplimiento constitucional se vuelve una checklist, y las excepciones registran su justificación explícita en Complexity Tracking
• Mediante el procedimiento de enmienda, la forma de aplicar los principios puede evolucionar, pero la filosofía central se mantiene

The Transformation

• El objetivo no es reemplazar desarrolladores, sino potenciar la capacidad humana y mantener la alineación entre intención e implementación automatizando la traducción mecánica
• SDD pone a la especificación a generar código, haciendo que especificación, investigación y código coevolucionen en un feedback loop cerrado como una transformación continua

[amoplan]

¿Con qué IA lo resumiste?

[xguru]

Lo hice con GPT-5. Uso un prompt bastante largo que preparé para resumir.

[heycalmdown]

Estoy muy de acuerdo con el concepto, así que hice algunas pruebas este fin de semana en un proyecto nuevo, pero no funcionó tan bien como esperaba. Creo que todavía necesita muchas mejoras. Por ahora, el flujo general parece ser más o menos el siguiente, como ya se ha explicado varias veces:
redactar la constitución → redactar la especificación → redactar las tareas → implementar

El problema es que

• el archivo constitution.md es una guía clave sobre "cómo desarrollar", pero no contiene "en qué se convertirá finalmente esta app"
• spec.md es un documento que describe una sola funcionalidad
• no existe un documento maestro sobre "qué es esta app"
• leyendo las discusiones en GitHub, parece que la chain of specs terminará siendo la source of truth. Me deja con dudas, pero más o menos lo pude entender.
• mediante los comandos /specify y /tasaks se generan muchos documentos como entregables (que era lo que quería), pero por eso mismo consume contexto rápidamente (estoy usando Claude Code)
• una vez que entro en la implementación, me alejo un poco de Spec Kit y termino completándola como siempre, conversando con Claude Code
• cuando se consume todo el contexto y se hace compaction o se inicia una sesión nueva, se olvida de la existencia de los documentos generados por Spec Kit
• mientras avanzo con las tareas definidas en tasks.md, a veces termino sobrescribiendo cosas que antes había hecho bien, y en el proceso de corregir bugs también acabo creando nuevas funcionalidades, así que cada vez se aleja más de tasks.md. No entiendo qué sentido tiene conservar tasks.md de forma permanente.

Por ahora, mi conclusión es la siguiente

• aunque el resultado termine siendo distinto de lo que pensé al principio, primero hay que cerrar la especificación y luego crear una nueva para ir corrigiendo poco a poco
• la especificación inicial inevitablemente crecerá, así que para las funcionalidades de la app quizá sea mejor no explicarlas en absoluto y limitarse a crear solo el boilerplate
• para algo hecho a nivel PoC, es mejor no usar Spec Kit