Spec-Kit y agentes de IA en proyectos reales: especificaciones, gobernanza y código mantenible.
La primera semana programando con un agente de IA parece magia. El mes seis, alguien tiene que mantener lo que generó. Este libro trata de ese mes seis.
El problema
Servicios duplicados porque cada sesión con el agente creó el suyo. Un patrón de manejo de errores que cambia cada dos archivos. Un endpoint que llama directamente al proveedor de correo cuando ya existía un despachador de mensajes que hacía exactamente eso.
Nada de eso es culpa de los modelos: programan bien. Ocurre porque el agente toma decisiones allí donde nadie le dio instrucciones, y esas decisiones —razonables una a una— se acumulan sesión tras sesión hasta construir una arquitectura que nadie diseñó pero que todo el equipo hereda.
Lo descubres el día que intentas un cambio transversal y lo que creías que eran cuatro módulos resultan ser quince.
Qué es el desarrollo guiado por especificaciones
El Spec-Driven Development (SDD) invierte la relación entre especificación y código. En el desarrollo tradicional, escribes código y luego lo documentas; la documentación envejece y acaba mintiendo. En el SDD, la especificación es la representación primaria del sistema y el código ejecutable es un artefacto derivado de ella.
Mantener software deja de ser mantener código: pasa a ser mantener especificaciones.
Eso no es una idea filosófica, es un flujo operativo. Cada funcionalidad recorre un ciclo: se especifica qué hace y por qué, se traduce en un plan técnico, se descompone en tareas atómicas y solo entonces se implementa. Por encima de todo el proyecto hay una constitución con las reglas que el agente no puede saltarse. La herramienta de referencia del libro es Spec-Kit, el conjunto de herramientas de código abierto de GitHub que implementa este ciclo e integra con Claude Code, GitHub Copilot, Cursor y Gemini CLI.
Qué hay dentro
El libro tiene cuatro partes y unas 330 páginas.
Parte I — Fundamentos. Por qué la generación de código sin especificación se derrumba a escala, qué convierte a una especificación en el código fuente real de un sistema, y en qué se diferencia el SDD del TDD, el BDD o el desarrollo en cascada.
Parte II — Inmersión en Spec-Kit. El manual operativo: instalación de la CLI, redacción de la constitución del proyecto y el ciclo completo, fase por fase, hasta el código generado.
Parte III — El crisol corporativo. El núcleo del libro. Cómo aplicar todo lo anterior sobre bases de código que ya existen: políticas restrictivas que impiden al agente duplicar lo existente, curación del contexto disperso entre tickets y documentos, y descomposición de tareas que no deja margen a la interpretación.
Parte IV — Gobernanza, seguridad y ecosistema. Extensiones de la comunidad, el marco OWASP para LLM aplicado a los artefactos del ciclo, control del gasto y despliegue en entornos aislados.
Por qué la Parte III importa
Casi todo lo que se ha escrito sobre agentes de IA asume un repositorio nuevo y vacío. Es donde las demos lucen y donde la documentación oficial se detiene.
Pero los proyectos nuevos son la minoría. El entorno real es un repositorio con historia, convenciones que nadie escribió y decisiones técnicas heredadas. Ahí es donde el comportamiento del agente cambia, y donde la disciplina deja de ser opcional. Cuatro capítulos completos están dedicados a ese escenario.
Para quién es
Para desarrolladores con experiencia que ya usan agentes de IA a diario y han empezado a ver el patrón de degradación. Y para tech leads y arquitectos que deben introducir la IA en su equipo sin que el repositorio se resienta.
No es un tutorial de introducción a la IA, ni un libro sobre el futuro del oficio, ni una colección de prompts. Da por sentado que ya sabes programar y que ya tienes un agente instalado.
El repositorio
El libro incluye un repositorio con todo el código, las constituciones de ejemplo, los specs y las plantillas, organizado por capítulos. Es también donde publico correcciones y actualizaciones: el ecosistema se mueve rápido y el libro lo asume.
Preguntas frecuentes
¿Qué es exactamente el Spec-Driven Development?
Un paradigma en el que la especificación es la representación primaria del sistema y el código se deriva de ella. Se opera mediante un ciclo de especificación, planificación, descomposición e implementación, gobernado por una constitución de proyecto.
¿En qué se diferencia del vibe coding?
El vibe coding genera código a partir de instrucciones breves e informales, sin contrato previo. Es rápido en prototipos y frágil en proyectos con recorrido, porque deja que el agente decida todo lo que no se le dijo.
¿Necesito conocer Spec-Kit antes de leerlo?
No. La Parte II parte de la instalación y recorre el ciclo completo. Si ya lo usas, puedes ir directo a la Parte III.
¿Sirve si uso Copilot o Cursor en lugar de Claude Code?
Sí. Spec-Kit se integra con los principales agentes del mercado, y las prácticas del libro son independientes del agente que utilices.
¿Sirve para proyectos que ya existen?
Es precisamente su foco diferencial: cuatro capítulos dedicados a bases de código legadas.
¿Está disponible en papel?
Sí, en tapa blanda y en formato digital, en Amazon.
Sobre el autor
Joaquín Ruiz Lite es ingeniero informático y Director de Innovación e IA. Integra modelos de lenguaje y arquitecturas RAG en entornos empresariales, imparte formación profesional y universitaria, y comparte su trabajo en el canal de YouTube @jokioki.